SMACHA

SMACHA is a YAML and Jinja2-based meta-scripting, templating, and code generation engine for SMACH.

SMACH is an exceptionally useful and comprehensive task-level architecture for state machine construction in ROS-based robot control systems. However, while it provides much in terms of power and flexibility, its overall task-level simplicity can often be obfuscated at the script-level by boilerplate code, intricate structure and lack of code reuse between state machine prototypes.

SMACHA (short for “State Machine Assembler”, pronounced “smasha”) aims at distilling the task-level simplicity of SMACH into compact YAML-based scripts in the foreground, while retaining all of its power and flexibility in Jinja2-based templates and a custom code generation engine in the background.

Overview

SMACHA Scripts

SMACHA scripts are YAML files that describe how SMACHA should generate SMACH code. Here is the “Nesting State Machines” example from the SMACH Tutorials described in a SMACHA script:

--- # Nesting State Machines Tutorial SMACHA script.
name: sm_top
template: Base
manifest: smach_tutorials
node_name: smach_example_state_machine
outcomes: [outcome5]
states:
  - BAS:
      template: Bas
      transitions: {outcome3: SUB}
  - SUB:
      template: StateMachine
      outcomes: [outcome4]
      transitions: {outcome4: outcome5}
      states:
        - FOO:
            template: Foo
            transitions: {outcome1: BAR, outcome2: outcome4}
        - BAR:
            template: Bar
            transitions: {outcome1: FOO}

This demonstrates a reduction from 80 lines of raw SMACH code to 20 lines of SMACHA script. Nice.

Base Variables

The base of the script specifies the following variables:

• name: a name for the overall state machine,
• template: the name of its base template,
• manifest (optional): a name for an optional ROS manifest,
• node_name: a name for its associated ROS node,
• outcomes: a list of its possible outcomes,
• states: list of its constituent states.

Each of the states in the base script may, in turn, specify similar variables of their own, as discussed in the following sub-sections.

States

Each state, including the base, must specify a template from which its respective code should be generated. States may be specified as lists specifying their transition order and may also be nested as described in the SMACH tutorials using appropriate combinations of template and state specifications as seen in the example above.

Outcomes

Possible state outcomes may be specified as a list in the base state machine and in each container state.

Transitions

Possible state transitions may be specified as an associative array (hash/dictionary) in each state.

Remappings

Input and output remappings of user data (not shown in the above example; see the SMACH User Data Tutorial for more details) may be specified as an associative array in each state.

Jinja2 Templating

Jinja2 is a powerful template engine for Python. Jinja2 templates are used to specify how code should be generated from SMACHA scripts. The Base template from the above example is specified in a Base.tpl file and looks like this:

```python {% from “Utils.tpl” import render_userdata %} {% set defined_headers = [] %} {% block base_header %} #!/usr/bin/env python {{ base_header }} {% endblock base_header %}

File truncated at 100 lines see the full file

Changelog for package smacha

0.5.0

• First release
• Removes all ROS related content from the core 'smacha' library
• Contributors: Barry Ridge, Timotej Gašpar