(!) 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.

Writing Custom State Classes with User-defined Callbacks

Description: Sometimes you want to create a state class like smach.SimpleActionState which receives user callbacks as arguments. If these callbacks change the SMACH interface of a state (outcomes, userdata keys), then the callbacks need to be annotated with this information.

Tutorial Level: ADVANCED

SMACH provides a decorator which can attach a SMACH interface to a function. This includes user data input keys, output keys, and state outcomes. A common pattern for extensible state design is to use callback functions that are called on various events. For example, SimpleActionState can call callbacks for generating goal messages or processing result messages, and MonitorState calls a callback each time a message comes in on a specified topic.

If a state defines an interface that can take callback functions, it should support this decorator model. Doing so is as simple as checking for the existence of the SMACH interface methods. A single function is provided bu the smach.util module.

Single User Callback

The following code shows how to integrate the SMACH interface provided by a callback function into the interface of a state. This state simply receives a SINGLE callback function and calls it when the state is executing.

   1 class MyState(smach.State):
   2     def __init__(self, cb):
   3         smach.State.__init__(self, outcomes=['done'])
   4 
   5         self._cb = cb
   6         if cb and smach.has_smach_interface(cb):
   7             self.register_input_keys(cb.get_registered_input_keys())
   8             self.register_output_keys(cb.get_registered_output_keys())
   9             self.register_outcomes(cb.get_registered_outcomes())
  10     ...
  11     def execute(self, ud):
  12         # Call callback
  13         cb_outcome = self._cb(ud)
  14 
  15         # If callback returned an outcome, return it as the state outcome
  16         if cb_outcome:
  17             return cb_outcome 
  18         
  19         return 'done'

Multiple User Callbacks

If more than one callback is supplied, the state class implementer should ensure that no side-effects are caused by adding callbacks with different interfaces. This is done by using a userdata remapper when passing userdata to the callbacks.

The following state takes a list of callbacks as an argument, and stores each callback's input and output keys. Then, when each callback is called while this state is executing, they will receive access to only their declared input and output keys. This prevents accidental access to be granted to one callback by another callback.

   1 class MyState(smach.State):
   2     def __init__(self, cb_list):
   3         smach.State.__init__(self, outcomes=['done'])
   4 
   5         self._cbs = cb_list
   6         for cb in cb_list:
   7             if cb and smach.has_smach_interface(cb):
   8                 self._cb_input_keys.append(cb.get_registered_input_keys())
   9                 self._cb_output_keys.append(cb.get_registered_output_keys())
  10  
  11                 self.register_input_keys(self._cb_input_keys[-1])
  12                 self.register_output_keys(self._cb_output_keys[-1])
  13                 self.register_outcomes(self._cb_input_keys[-1])
  14     ...
  15     def execute(self, ud):
  16         # Call callbacks
  17         for (cb, ik, ok) in zip(self._cbs,
  18                                 self._cb_input_keys,
  19                                 self._cb_output_keys):
  20 
  21             # Call callback with limited userdata
  22             cb_outcome = self._cb(smach.Remapper(ud,ik,ok,{}))
  23 
  24             # If callback returned an outcome, return it as the state outcome
  25             if cb_outcome:
  26                 return cb_outcome 
  27         
  28         return 'done'

Wiki: smach/Tutorials/Writing Custom State Classes With User-defined Callbacks (last edited 2010-07-30 20:52:56 by wim)