YASMIN CLI

YASMIN CLI extends the ROS 2 command line with commands for inspecting plugins, printing XML state machines, validating factory files, opening the editor, running XML state machines, testing individual states, and starting the viewer.

The CLI is registered as a ROS 2 command extension, so all commands are available under: 

ros2 yasmin <verb> [options]

Available Verbs

  • list - list discovered YASMIN plugins and XML state machines
  • info - show detailed metadata for one plugin
  • print - print a YASMIN XML state machine in a readable form
  • validate - validate one XML state machine or all discovered XML files
  • edit - open a state machine in the YASMIN editor
  • run - run a state machine from an XML file
  • test - generate a temporary one-state XML and run a single plugin in isolation
  • viewer - start the YASMIN viewer

Plugin Identification

Several CLI verbs operate on a plugin identifier. The expected format depends on the plugin type:

  • Python plugins: module.submodule.ClassName
  • C++ plugins: package_name/ClassName
  • XML state machines: package_name/file.xml

Listing Plugins

The list verb shows all discovered plugins. You can filter by plugin type and search by substring. 

ros2 yasmin list
ros2 yasmin list --type cpp
ros2 yasmin list --type python --search monitor
ros2 yasmin list --type xml

The supported values for --type are:

all, cpp, python, xml

Inspecting Plugin Metadata

The info verb prints detailed metadata for one plugin, including its description, outcomes, parameters, input keys, and output keys. 

ros2 yasmin info yasmin_demo.monitor_state.MonitorState
ros2 yasmin info my_package/MyCppState

Printing XML State Machines

The print verb reads an XML state machine, validates the editor model, and prints the structure in a readable tree format. This includes containers, declared parameters, declared keys, remaps, parameter remaps, transitions, and final outcomes. 

ros2 yasmin print path/to/state_machine.xml
ros2 yasmin print path/to/state_machine.xml --validate-only

Validating XML State Machines

The validate verb uses YASMIN Factory to create the state machine from XML and then calls validate(). If no file is given, the CLI validates all XML state machines discovered by the plugin manager. 

ros2 yasmin validate path/to/state_machine.xml
ros2 yasmin validate path/to/state_machine.xml --no-strict
ros2 yasmin validate

Opening the Editor

The edit verb starts the YASMIN editor. If an XML file is provided, it is validated as a YASMIN state machine XML file and then opened directly. 

ros2 yasmin edit
ros2 yasmin edit path/to/state_machine.xml

Running an XML State Machine

The run verb launches a state machine through the YASMIN Factory node. It can override declared input keys and declared parameters from the root XML file before execution. 

ros2 yasmin run path/to/state_machine.xml
ros2 yasmin run path/to/state_machine.xml --input goal_pose=home
ros2 yasmin run path/to/state_machine.xml --input retries=3 --param mode=demo
ros2 yasmin run path/to/state_machine.xml --disable-viewer-pub
ros2 yasmin run path/to/state_machine.xml --py

Input and parameter overrides must be written as NAME=VALUE. In the current implementation, typed conversion for XML overrides supports the scalar default_type values str, int, float, and bool.

Testing a Single State

The test verb creates a temporary one-state XML state machine around a selected plugin and runs it through YASMIN Factory. This is useful for quickly testing one state with specific inputs or parameters without writing a full XML file manually. 

ros2 yasmin test my_package/MyCppState
ros2 yasmin test my_package/MyCppState --input goal=home
ros2 yasmin test my_package/MyCppState --param retries=3
ros2 yasmin test my_package/MyCppState --print-xml
ros2 yasmin test my_package/MyCppState --keep-temp-file
ros2 yasmin test my_package/MyCppState --disable-viewer-pub
ros2 yasmin test my_package/MyCppState --py

The test verb supports Python and C++ state plugins. It does not accept XML state machines as the selected plugin target.

Starting the Viewer

The viewer verb starts the YASMIN viewer node through ros2 run yasmin_viewer yasmin_viewer_node. 

ros2 yasmin viewer
ros2 yasmin viewer --host 127.0.0.1 --port 5000 --msg-per-second 30

Typical Workflow

A common workflow is to discover available states, inspect one plugin, test it in isolation, print or validate an XML state machine, and then run or edit it: 

ros2 yasmin list --search nav
ros2 yasmin info my_package/MyCppState
ros2 yasmin test my_package/MyCppState --print-xml
ros2 yasmin validate path/to/state_machine.xml
ros2 yasmin print path/to/state_machine.xml
ros2 yasmin run path/to/state_machine.xml
ros2 yasmin edit path/to/state_machine.xml