Tutorial 3: Actions

Note: This tutorial assumes that you are familiar with the concept of Actions and UMRFs in TeMoto.

The basis for an action can be easily generated via TeMoto Action Assistant. Since the structure of an action is defined by its UMRF, the TeMoto Action Assistant provides the graphical interface for creating an UMRF. Once you are happy with the UMRF, a basis for action implementation package is generated, incuding a c++ source file. Each action is implemented as a ROS package.

Create a Temoto Action

1) Launch the TeMoto action assitant GUI

roslaunch <my_temoto_config> action_assistant.launch

This should bring up the start screen of the action assistant, depicted in Fig. 1.

Figure 1: Start screen of the TeMoto Action Assistant

2) Create your UMRF

Go to the "UMRF Editor" tab (depicted in Fig. 2). This tab consists of 2 main sections:

* UMRF Viewer section, which visually shows the structure of the UMRF.
* Item Editor section, which allows to edit the currently active item in the UMRF Viewer.

Figure 2: UMRF Editor tab

• Modify the name by clicking on the "Name:" item in the UMRF viewer and changing the name in the item editor. In the given example, let's call it "add numbers"
• Add new input parameter by right-clicking on the "Input Parameters" item and selecing "Add new parameter".
• Select the newly created parameter and change it's name to "input_1" and it's type to "number".
• Add another input parameter and change it's name to "input_2" and it's type to "number".
• Add an output parameter change it's name to "output_1" and it's type to "number".

The UMRF is now done (end result shown in Fig. 4).

Figure 3: UMRF Editor Adding parameters

Figure 4: UMRF Done

3) Generate the action package

Go to the "Generate Actions" tab (depicted in Fig. 5).

• Since this tutorial assumes that the Action Assistant was opened via TeMoto workspace (see the first step in this tutorial), then the directory where the action will be generated is automatically set. If that's not the case then select the directory where the action package is generated.
• Generate the package by clicking the "Generate" button.

Figure 5: Generate Action tab

4) Modify the autogenerated source

Now navigate to the generated package and open the action source file with your favourite editor. For example:

    cd YOUR_TEMOTO_WORKSPACE/actions/ta_add_numbers/src
    gedit ta_add_numbers.cpp

The action source file contains a bunch of things that are necessary for TeMoto, but we are going to focus on a executeTemotoAction() function. This function is invoked when the action is executed.

Locate the block comment which says "YOUR CODE HERE":

    void executeTemotoAction()
    {
      getInputParameters();

      /* * * * * * * * * * * * * * * * * * * * * * *
      *                          
      *         ===> YOUR CODE HERE <===
      *                          
      * * * * * * * * * * * * * * * * * * * * * * */

      setOutputParameters();
    }

    // Destructor
    ~TaAddNumbers()
    {
      TEMOTO_INFO("Action instance destructed");
    }

    // Loads in the input parameters
    void getInputParameters()
    {
      in_param_input_1 = GET_PARAMETER("input_1", double);
      in_param_input_2 = GET_PARAMETER("input_2", double);
    }

    // Sets the output parameters which can be passed to other actions
    void setOutputParameters()
    {
      SET_PARAMETER("output_1", "number", out_param_output_1);
    }

and replace it with code that adds up the numbers and puts the result to the output parameter out_param_output_1

    void executeTemotoAction()
    {
      getInputParameters();

      out_param_output_1 = in_param_input_1 + in_param_input_2;
      TEMOTO_INFO_STREAM("Adding numbers " 
        << in_param_input_1 << " and " 
        << in_param_input_2 << ". Result is " 
        << out_param_output_1);

      setOutputParameters();
    }

    // Destructor
    ~TaAddNumbers()
    {
      TEMOTO_INFO("Action instance destructed");
    }

    // Loads in the input parameters
    void getInputParameters()
    {
      in_param_input_1 = GET_PARAMETER("input_1", double);
      in_param_input_2 = GET_PARAMETER("input_2", double);
    }

    // Sets the output parameters which can be passed to other actions
    void setOutputParameters()
    {
      SET_PARAMETER("output_1", "number", out_param_output_1);
    }

Do not modify any of the autogenerated code. Otherwise your action will likely not work properly.

5) Build and test the action

   catkin build
   # (source your workspace)

   #In one terminal, run TeMoto 
   roslaunch <my_temoto_config> temoto.launch temoto_namespace:=<namespace>

Use another terminal to invoke the action.

Note that the wake_word must match the temoto_namespace defined when launched TeMoto, by default it is <my_temoto_config> (see Tutorial 2: "TeMoto Config" for more details).

   roslaunch ta_add_numbers invoke_action.launch wake_word:=<namespace>

If you followed this tutorial step-by-step, then you should see this in the terminal output:

   [my_temoto_config/action_engine/TaAddNumbers_0::executeTemotoAction] Adding numbers 0. and 0. Result is 0.

You can change the input values (denoted as pvf_value) by modifying the test/<name_temoto_action>.umrfg.json under your action package root folder like so:

   {
       "name": "TaAddNumbers",
       "package_name": "ta_add_numbers",
       "suffix": "0",
       "notation": "",
       "effect": "synchronous",
       "input_parameters": {
           "input_1": {
               "pvf_type": "number",
               "pvf_value": 8.4
           },
           "input_2": {
               "pvf_type": "number",
               "pvf_value": 1.2
           }
       },
       "output_parameters": {
           "output_1": {
               "pvf_type": "number"
           }
       }
   }

and terminal output should contain:

    [my_temoto_config/action_engine/TaAddNumbers_0::initializeTemotoAction] Action initialized
    [executeUmrfGraph] UMRF graph 'ta_add_numbers' invoked successfully.
    [my_temoto_config/action_engine/TaAddNumbers_0::executeTemotoAction] Adding numbers 8.4 and 1.2. Result is 9.6
    [my_temoto_config/action_engine/TaAddNumbers_0::~TaAddNumbers] Action instance destructed
    [monitoringLoop] Clearing umrf graph 'ta_add_numbers'

6) Create a UMRF Graph

You can also use the Action Assistant for creating UMRF graphs. You can create as many actions as needed, and connect them in different configurations (sequential, concurrent, cycle).

In order to connect the actions, select the parent node, then right click over the child node, and click connect. An arrow from the parent node pointing to the child should appear now.

6.1) Add a new action to the UMRF Editor canvas

There are two ways to insert actions to the UMRF Graph:

1. Right click on the UMRF Editor canvas and press ADD Action
2. Type a description on the Graph description field, then highlight the description and right click Annotate as action

Figure 6: Add action to UMRF Graph

6.2) Add an existing action

• Type a description on the Graph description field, highlight it and then right click to get the Annotate as Existing action option, and select the desired temoto action from the list.

Figure 7: UMRF Graph