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, including a c++ source file. Each action is implemented as a ROS package.
roslaunch <my_temoto_config> action_assistant.launchThis should bring up the start screen of the action assistant, depicted in Fig. 1.
Figure 1: Start screen of the TeMoto Action Assistant
Click on "Create New TeMoto Action Package".
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
Each action is represented with an interactive circle in the canvas, that you can drag $ drop, or simply select to change its parameters in the Item Editor section.
- 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 selecting "ADD parameter".
Figure 3: UMRF Editor Adding parameters
There is a dropdown menu with a list of pre-defined parameters that you can use, or it is also possible to create your own parameter structure in the custom tab. For now, select "my_number (number)" and click "ok".
- Select the newly created parameter and change it's name to "input_1" and make sure the type is "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 4: UMRF Done
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
Now navigate to the generated package and open the action source file with your favorite editor. For example:
cd YOUR_TEMOTO_WORKSPACE/temoto_actions/ta_add_numbers/src
gedit ta_add_numbers.cppThe 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.
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 original terminal from within which TeMoto was launched:
[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'
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).
There are two ways to insert actions to the UMRF Graph:
- Right click on the UMRF Editor canvas and press ADD Action
- 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
- 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
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.
Once you finish the graph, hit the generate button under the "Generate Actions" tab, which creates a json file in the umrf_graphs folder.
*** Note: For testing purposes: Fill the input parameters in the ".umrfg.json" file and run the graph using the following command:
rosrun temoto_action_engine parser_node <path_to_umrfg.json> <temoto_namespace>