SMACHA ROS Documentation¶
SMACHA ROS is a package that provides ROS integration for SMACHA.
Its main component is a SMACHA server that allows for templates to be loaded from disparate packages and accessed from anywhere within the ROS network, loads template metadata onto the parameter server for use with, e.g. the ReconCell SMACHA GUI, and provides services for each of the main SMACHA functions.
SMACHA Server¶
Services¶
The SMACHA server provides a number of ROS services where, in each case, service requests may be handled in one of the following three ways:
- the request itself is a SMACHA script string,
- the request refers to a ROS parameter containing a SMACHA script string,
- the request refers to a ROS parameter containing a SMACHA script filename.
The currently available services are as follows:
- the
Generate
service: uses the SMACHA Generator to generate SMACH Python code from SMACHA scripts, - the
Contain
service: uses the SMACHA Contain tool to containerize linear state sequences in SMACHA scripts, - the
Extract
service: uses the SMACHA Extract tool to extract sub-scripts from super-scripts.
Template Metadata Parameters¶
Template metadata is automatically published to the ROS parameter server for
every template loaded by the parameter server (assuming a meta
block
is present in the template).
Installation¶
The smacha_ros
package forms a part of the main SMACHA stack, so it is installed alongside SMACHA by
following its installation instructions.
Usage¶
Launching a SMACHA Server¶
Launching a SMACHA server can be done as follows:
$ rosrun smacha_ros smacha_server -t `rospack find smacha`/test/smacha_templates/smacha_test_examples
Here, the -t
argument specifies directories containing additional templates that should be loaded by
the server outside of the core API templates
which are always loaded by default.
Further arguments and options may be explored by running
rosrun smacha_ros smacha_server -h
or rosrun smacha_ros smacha_server --help
.
Using Scripts with the ROS Parameter Server¶
Scripts may be used with the ROS parameter server in one of two ways, by either setting a parameter to hold the script filename:
$ rosparam set /seq_filename `rospack find smacha`/test/smacha_scripts/smacha_test_examples/seq.yml
or by loading the script itself (i.e. the contents of the file) onto a parameter:
$ rosparam load `rospack find smacha`/test/smacha_scripts/smacha_test_examples/seq.yml /seq_script
Since SMACHA scripts are written in YAML and the ROS parameter server is designed to handle YAML, this latter method is advantageous in that once the script has been loaded, different parts of the script, can be directly accessed, e.g.
$ rosparam get /seq_script/template
returns the name of the base template being used by the script:
$ rosparam get /seq_script/template
$ Base
Calling the Generate Service¶
Calling the Generate
service using the parameter containing the filename from the above example:
rosservice call /smacha/generate /seq_filename
of using the parameter containing the script itself:
rosservice call /smacha/generate /seq_script
will result in the same outcome, that is, the generated SMACH Python code string being returned.
Calling the Contain Service¶
The following command demonstrates how to call the contain service in order to replicate the example from the SMACHA Container States tutorial:
$ rosservice call /smacha/contain /seq_filename SUB StateMachine [FOO_0,FOO_1]
Calling the Extract Service¶
If we assign the output of the previous Contain
service call to an environment variable:
$ CONTAINED_SEQ=`rosservice call /smacha/contain /seq_filename SUB StateMachine [FOO_0,FOO_1]`
then we can load the generated script onto the parameter server:
$ rosparam set /contained_seq "$CONTAINED_SEQ"
before calling the Extract
service in order to extract the SUB
state from the script:
$ rosservice call /smacha/extract /contained_seq/script SUB
Templating¶
The SMACHA ROS package provides ROS state templates as well as other ROS templates in order to provide ROS integration and additional functionality, for example:
- Templates for publishing arbitrary messages to topics,
- Templates for performing TF transforms,
- Templates for parsing messages into selected types,
- Templates for recording ROS bags,
- etc.
Other SMACHA Packages¶
SMACHA¶
The SMACHA package contains all of the main SMACHA functionality.
SMACHA GUI¶
The SMACHA GUI package provides a visual programming interface for SMACHA for use within the ReconCell Project.
SMACHA ROS API¶
Templates¶
These are the core smacha_ros package templates:
State Templates¶
- PublishMsgState: used for publishing userdata ROS message entries to topics.
- PublishObserverMsgState: used for publishing userdata ROS message entries to topics using an observer pattern.
- ReadTopicState: used for reading ROS messages from topics to userdata.
- RecordROSBagState: used for recording topic data to ROS bags.
- ServiceState: used for inserting a ServiceState.
- SimpleActionState: used for inserting a SimpleActionState.
- TF2ListenerState: used for reading TF2 transforms.
- TransformMsgState: used for transforming userdata ROS messages from one tf frame to another.
Other Templates¶
- MsgPublisher: provides a helper class for the PublishMsgState template.
- MsgPublisherObserver: provides a helper class for the PublishObserverMsgState template.
- ParseJointTrajectoryPoint: provides a helper function for parsing trajectory_msgs/JointTrajectoryPoint types.
- ParsePointCloud: provides a helper function for parsing sensor_msgs/PointCloud types.
- ParsePointCloud2: provides a helper function for parsing sensor_msgs/PointCloud2 types.
- ParsePointStamped: provides a helper function for parsing geometry_msgs/PointStamped types.
- ParsePose: provides a helper function for parsing geometry_msgs/Pose types.
- ParsePoseArray: provides a helper function for parsing geometry_msgs/PoseArray types.
- ParsePoseStamped: provides a helper function for parsing geometry_msgs/PoseStamped types.
- ParseTransformStamped: provides a helper function for parsing geometry_msgs/TransformStamped types.
- ROSBagAPIThreadRecorder: provides a helper class for the RecordROSBagState template that allows for ROS bags to be recorded using the ROS bag Python application programming interface.
- ROSBagCLIProcessRecorder: provides a helper class for the RecordROSBagState template that allows for ROS bags to be recorded using the ROS bag command line interface.
- TF2ListenerSingleton: provides a helper class for the TF2ListenerState template.
- WaitForMsgState: provides a helper class for the ReadTopicState template.