(!) Please ask about problems and questions regarding this tutorial on answers.ros.org. Don't forget to include in your question the link to this page, the versions of your OS & ROS, and also add appropriate tags.

Viewing State Machines (ROS)

Description: This tutorial shows you how to use the smach viewer, a simple tool to monitor state machines and get introspection into the data flow between states.

Tutorial Level: BEGINNER

This is what you want to debug a running SMACH state machine:


The SMACH viewer shows a graphical representation of all the states in your (sub) state machines, the possible transitions between states, the currently active state, and the current values of the userdata. The SMACH viewer even allows you to set the initial state of your state machine. This tutorial teaches you how to start using the SMACH viewer.

Creating an Introspection Server

SMACH containers can provide a debugging interface (over ROS) which allows a developer to get full introspection into a state machine. The SMACH viewer can use this debugging interface to visualize and interact with your state machine. To add this debugging interface to a state machine, add the following lines to your code:

   1 # First you create a state machine sm
   2 # .....
   3 # Creating of state machine sm finished
   5 # Create and start the introspection server
   6 sis = smach_ros.IntrospectionServer('server_name', sm, '/SM_ROOT')
   7 sis.start()
   9 # Execute the state machine
  10 outcome = sm.execute()
  12 # Wait for ctrl-c to stop the application
  13 rospy.spin()
  14 sis.stop()
  • server_name: this name is used to create a namespace for the ROS introspection topics. You can name this anything you like, as long as this name is unique in your system. This name is not shown in the smach viewer.

  • SM_ROOT: your state machine will show up under this name in the smach viewer. So you can pretty much choose any name you like. If you have sub-state machines that are in different executables, you can make them show up as hierarchical state machines by choosing this name in a clever way: if the top level state machine is called 'SM_TOP', you can call the sub state machine 'SM_TOP/SM_SUB', and the viewer will recognize the sub state machine as being part of the top state machine.

For more details on the introspection server, see the API documentation.

The smach viewer will automatically traverse the child containers of sm, if any exist, and add ros hooks to each of them. So you only need to hook up one introspection server to the top level state machine, not to the sub state machines. Once the introspection server has been instantiated, it will advertise a set of topics with names constructed by appending to the server name given to it on construction. In this case three topics would be advertised:

  • /server_name/smach/container_structure

  • /server_name/smach/container_status

  • /server_name/smach/container_init

The first two publish heartbeat and event info regarding the structure and status of the SMACH containers served out by "server_name" The third is a topic for setting the configuration of the SMACH tree over ROS.

The "SM_ROOT" argument is simply used for visualization, and forced nesting of different servers.

Running SMACH viewer

Once you have one or more introspection servers running in your ROS system, you can start the smach viewer using:

  rosrun smach_viewer smach_viewer.py

The viewer will automatically connect to all running introspection servers.

Wiki: smach/Tutorials/Smach Viewer (last edited 2017-06-08 00:11:54 by IsaacSaito)