Home

Introduction

An Executive is a software module that acts as the highest level behaviour planner. This means that it contains an overall plan and issues orders such as: "navigate to the dinner table", "move the arm to this position", "learn person name", among others. This page holds information on how to use and create executives.

One key thing to keep in mind is that every action can fail, either occasionally or frequently. States should return a transition such as "failed" when they do, and an executive should handle this correctly, and have a back-up plan.

Although you can create an Executive that doesn't interact with the ED world model, using it allows you to make a much smarter robot. Via the ED API, you can query where objects of a certain type and name are. You can use Designators to define what type of objects you want to use and resolve the exact position and ID of the object only at runtime.

Creating a SMACH Challenge Executive

Introduction

An Executive is a general name to the type of software module you are about to develop. You can use different languages and libraries to do this, in this example we will use Python and ROS Smach.

It is advisable to have some experience with both of these tools, therefore you should start by reading a simple tutorial on Python and the official tutorials from ROS Smach Tutorials (sections 1 and 2 should be enough to start with).

Preparations

In your user folder, create a new package called challenge_ and add robot_skills, robot_smach_states to the dependencies. For example:

roscreate-pkg <NAME OF PACKAGE> robot_skills robot_smach_states

In the package, create the following folders:

• src: this will hold the Python files
• launch: this will hold the launch files to start the executive

cd challenge_<NAME OF CHALLENGE>
mkdir src launch

An overview of the knowledge used in different environments for the various challenges can be found in Knowledge.

Then, in the src folder, create a Python file with the name of the challenge, e.g.:

cd src
touch challenge_<NAME OF CHALLENGE>.py

and make the file executable:

chmod +x challenge_<NAME OF CHALLENGE>.py

Base for a SMACH Executive

In order to sucessfuly run an Executive you first need to have a basic strucute that imports all necessary information and prepares the main state machine.

It is advisable that you use a good editor/IDE, such as Sublime or pyCharm, to edit your executioner, this will make it more readable and prevent confusions between spaces and tabs.

The following code snippet shows the essential things you will need to declare and prepare in order to create an executive for Amigo or Sergio. Most of the code shown bellow is not necessary on pure ROS Smach, but it is necessary in order to properly communicate with Amigo or Sergio.

This snippet of code shows the three main parts in which the skeleton of an executive should be divided: the imports and global variable definition (avoid globals...), the classes that will make up the state machine, and finally the main entry point.

#! /usr/bin/env python
import rospy

import robot_smach_states as states

from robot_smach_states.util.startup import startup #gives you some error handling, robot loading and introspection


class NameOfTheChallenge(smach.StateMachine):
    def __init__(self, robot):
        smach.StateMachine.__init__(self, outcomes=["Done", "Aborted", "Failed"])

        with self:
             smach.StateMachine.add("NAME_OF_STATE",
                                   states.Say(robot, "Hello world"),
                                   transitions={'spoken', 'Done'})
##
if __name__  '__main__':
    rospy.init_node('executioner')

    util.startup(NameOfTheChallenge)

Do Not Forget

• Do not forget to add an initial pose to your executive! Amigo needs an initial pose to know exactly where it is, e.g. in front of the door of the environment or arena. To set this, you can use the Set_initial_pose-state: Set_initial_pose(robot, ). It is included in the high-level state StartChallengeRobust

Tips and notes

• Remember that almost every state should have a fallback in case of failure, otherwise the challenge can fail.
• Avoid using global variables, its makes it much harder to debug
• To pass data between states, you an use Designators or pass around User Data
• Use SMACH Containers properly, since there are several types, and whenever possible encapsulate smaller machines inside bigger machines with the StateMachine container, this will make the code more readable and the visualization in ROS Smach Viewer more explicit
• The def init(...) in a class will only be executed once, while the def execute(...) will be executed everytime the class is called. So whenever possible declare queries and other variables that won't change over time in the def init(...)
• Avoid using sleeps (rospy.sleep()), whenever possible let the Executive run as fast as it can since the timming of actions, like moving or grasping, might change after improvements in outside code
• You should (bel able to) assume the robot is in a safe, default posture. If you put the robot in an unsafe posture, don't forget to reset it into a safe posture again so the assumption stays true.
• Re-use state( machine)s already available. For example, to learn the name of a person (which includes asking for the name, listening and requesting confirmation):

self.response = self.ask_user_service_get_learn_person_name('name', 3, rospy.Duration(60))

• It is preferable to have more states with less complexity than less states with more complexity:
• makes debugging easier
• allows for composition and reusability
• In order to make Amigo more empathic make him talk when taking some decisions (in moderation), it will help debugging whitout looking at the console and it will make him more predictable to the people watching.
• Avoid using blocking sentences when speaking:

self.robot.speech.speak("Going to the last place where I saw people.", block=False)

• Use standard names for the most common outcomes of states, e.g. Done, Aborted, Failed

Running a SMACH Executive

You can start an Executive in two ways, that are basically the same. You can execute it like you would any other ROS package:

rosrun challenge_<NAME OF PACKAGE> <NAME OF EXECUTIVE>

eg:

rosrun challenge_cocktail_party challenge_cocktail_party.py

Or you can directly execute the Python script (make sure that you either provide the complete path to the file or that you are in the src folder :

./challenge_<NAME OF EXECUTIVE>

Troubleshoot and Debugging

Amigo Console

Amigo Console is a powerful tool that allows you to issue commands to Amigo and query ED even while running a challenge. It depends on Amigo's Middleware (amiddle), so make sure it is running before starting it with:

amigo-console

Amigo Console is actually a Python interpreter, with some objects and functions already set up for you. This means so you can run queries live and see their output in the command window but also use any other Python stuff you'd like.