Basic Grammar of ROS Launch

Definition

• roslaunch is a tool for easily launching multiple ROS nodes locally and remotely via SSH.
• As well as setting parameters on the Parameter Server.
• Include options to automatically respawn processes that have already died.

Many ROS packages come with launch files, which you can run with:

roslaunch package_name file.launch

Basic Grammar

• roslaunch uses XML¹ files describe:
  • the nodes that should be run.
  • the parameters that should be set.
  • other attributes of launching a collection of ROS nodes.
• roslaunch will automatically start roscore if it detects that the roscore is not already running.

Substitution args

• roslaunch tag attributes can make use of substitution args.
• roslaunch will resolve prior to launching nodes.

$(env ENVIRONMENT_VARIABLE)

• Substitute the value of a variable from the current environment.
• The launch will fail if the environment variable is not set.
• This value cannot be overridden by tags.

$(optenv ENVIRONMENT_VARIABLE default_value)

• Substitute the value of an environment variable if it is set.
• If default_value is provided, it will be used if the environment variable is not set.
• If default_value is not provided, an empty string will be used.
• default_value can be multiple words separated by spaces.

<param name="foo" value="$(optenv NUM_CPUS 1)" />
<param name="foo" value="$(optenv CONFIG_PATH /home/marvin/ros_workspace)" />
<param name="foo" value="$(optenv VARIABLE ros rocks)" />

$(find pkg)

• Specifies a package-relative path.
• The filesystem path to the package directory will be substituted inline.
• Use of package-relative paths is highly encouraged as hard-coded paths inhibit the portability of the launch configuration.

$(find rospy)/manifest.xml

$(anon name)

• Generate an anonymous ID based on the name.
• Multiple uses of $(anon name) will create the same anonymized name.
• ROS requires nodes to have unique names.

<node name="$(anon foo)" pkg="rospy_tutorials" type="talker.py" />

$(arg value)

• Evaluate to the value specified by an <arg> tag.
• There must be a corresponding <arg> tag in the same launch file that declares the arg.

<param name="foo" value="$(arg my_foo)" />

<node name="add_two_ints_client" pkg="beginner_tutorials" type="add_two_ints_client" args="$(arg a) $(arg b)" />
roslaunch beginner_tutorials launch_file.launch a:=1 b:=5

$(eval )

• New in Kinetic.
• Evaluate arbitrary complex python expressions.

<param name="circumference" value="$(eval 2.* 3.1415 * arg('radius'))"/>

$(dirname)

• New in Lunar.
• Return the absolute path to the directory of the launch file in which it appears.
• This can be used in conjunction with eval and if/unless to modify behaviour based on the installation path.
• As a convenience for referencing launch or yaml files relative to the current file rather than relative to a package root as with $(find pkg).

<include file="$(dirname)/other.launch" />

if and unless attributes

• All tags support if/unless attributes.
• 1 and ture are considered as true values.
• 0 and false are considered as false values.
• if=value(optional): if value evaluates to true, include tag and its contents.
• unless=value(optional): unless value evaluates to true, include tag and its contents.

<group if="$(arg foo)">
  <!-- stuff that will only be evaluated if foo is true -->
</group>

<param name="foo" value="bar" unless="$(arg foo)" />
<!-- This param will not be set unless foo is true -->

Tag

<launch>

• <launch> tag is the root element of any roslaunch file.
• Its sole purpose is to act as a container for the other elements.

<launch>
  <node name="talker" pkg="rospy_tutorials" type="talker" />
</launch>

<group>

• <group> tag makes it easier to apply settings to a group of nodes.
• ns="namespace": assign the group of nodes to the specified namespace.
• clear_params="true|false": delete all parameters in the group’s namespace before launch.
  • This feature is very dangerous and should be used with caution, ns must be specified.
• if="0 or 1".
• unless="0 or 1".

<group ns="wg2">
  <node pkg="rospy_tutorials" type="listener" name="listener" args="--test" respawn="true" />
</group>

<group if="$(arg foo)">
  <!-- stuff that will only be evaluated if foo is true -->
</group>

<node>

• <node> tag specifies a ROS node that you wish to have launched.
• pkg="mypackage": package of the node.
• type="nodetype": must be a corresponding executable with the same name.
• name="nodename": the name of the node, which will overwrite the name in ros::init.
• args="arg1 arg2 arg3" (optional): arguments to the node.
• respawn="true" (optional): restart the node automatically if it quits.
• respawn_delay="30" (optional): if respawn is true, wait respawn_delay seconds after the node failure is detected before attempting restart. (New in ROS indigo)
• required="true" (optional): if node dies, kill entire roslaunch.
• ns="foo" (optional): start the node in the foo namespace.
• clear_params="true|false" (optional): delete all parameters in the node’s private namespace before launch.
• output="log|screen" (optional):
  • if screen, stdout/stderr from the node will be sent to the screen.
  • if log, stdout/stderr output will be sent to a log file in the $ROS_HOME/log, and the stderr will continue to be sent to screen.
• machine="machine_name" (optional): launch node on designated machine.
• cwd="ROS_HOME|node" (optional):
  • if node, the working directory of the node will be set to the same directory as the node’s executable.
  • The default is ROS_HOME.
• launch-prefix="prefix arguments" (optional): command/arguments to prepend to node’s launch arguments.
  • This is a powerful feature that enables you to enable gdb, valgrind, xterm, nice, or other handy tools.
  • launch-prefix="xterm -e": open a new terminal, and execute the following command lines.

<node name="listener1" pkg="rospy_tutorials" type="listener.py" args="--test" respawn="true" />
<node name="bar1" pkg="foo_pkg" type="bar" args="$(find baz_pkg)/resources/map.pgm" />

<include>

• <include> tag enables you to import another roslaunch file into current file.
• It will be imported within the current scope of the document, including <group> and <remap> tags.
• file="$(find pkg_name)/path/filename.launch": name of the file to include.
• ns="foo": import the file relative to the foo namespace.
• clear_params="true|false" (optional Default: false): delete all parameters before launch.
• pass_all_args="true|false" (optional Default: false): if true, then all args set in the current context are added to the child context that is created for processing the included file.

<remap>

• <remap> tag allows you to pass in name remapping arguments to the ROS node.
• It applies to all subsequent declarations in its scope (<launch>, <node>, <group>).
• from="original_name": name that remapping.
• to="new_name": target name.

<remap from="chatter" to="hello"/>

rosrun chatter chatter_node chatter:=hello

<rosparam>

• <rosparam> tag enables the use of rosparam file for loading and dumping parameters from the ROS parameter server.
• It can also be used to remove parameters.
• It can be put inside of a <node> tag.
• The delete and dump commands run (in the declared order) before the load command and before any other parameters are uploaded to the parameter server.
• It can either reference a YAML file or contain raw YAML text.
• command="load|dump|delete" (optional, default=load).
• file="$(find pkg_name)/path/foo.yaml" (load or dump commands).
• param="param_name": name of parameter.
• ns="namespace" (optional).
• subst_value=true|false (optional): allows use of substitution args in the YAML text.

<rosparam command="load" file="$(find rosparam)/example.yaml" />
<rosparam command="delete" param="my/param" />

<rosparam param="a_list">[1, 2, 3, 4]</rosparam>

<rosparam>
  a: 1
  b: 2
</rosparam>

<arg name="whitelist" default="[3, 2]"/>
<rosparam param="whitelist" subst_value="True">$(arg whitelist)</rosparam>

<param>

• <param> defines a parameter to be set on the parameter server.
• It can be put inside of a <node> tag.
• name="namespace/name": parameter name.
• value="value"(optional): defines the value of the parameter.
• type="str|int|double|bool|yaml"(optional): specifies the type of the parameter.
  • If you don’t specify the type, roslaunch will attempt to automatically determine the type. These rules are very basic:
    • numbers with .s are floating point, integers otherwise.
    • true and false are boolean (not case-sensitive).
    • all other values are strings.
• textfile="$(find pkg-name)/path/file.txt"(optional): the contents of the file will be read and stored as a string.
• binfile="$(find pkg-name)/path/file"(optional): the contents of the file will be read and stored as a base64-encoded XML-RPC binary object.
• command="$(find pkg-name)/exe '$(find pkg-name)/arg.txt'"(optional): the output of the command will be read and stored as a string.

<param name="publish_frequency" type="double" value="10.0" />

<env>

• <env> tag allows you to set environment variables on the nodes that are launched.
• This tag may only be used within the scope of a <launch>, <include>, <node> or <machine> tag.
• When it is used inside of a <launch> tag, the <env> tag only applies to nodes declared after.
• name="environment_variable_name".
• value="environment_variable_value".

<env name="ENV_EXAMPLE" value="some value" />

<arg>

• Create more re-usable and configurable launch files by specifying values that are passed via the command-line.
• name="arg_name".
• default="default value" (optional): cannot be combined with value attribute.
• value="value" (optional): cannot be combined with default attribute.
• doc="description for this arg" (optional).

<include file="included.launch">
  <!-- all vars that included.launch requires must be set -->
  <arg name="hoge" value="fuga" />
</include>

<launch>
  <!-- declare arg to be passed in -->
  <arg name="hoge" /> 
  <!-- read value of arg -->
  <param name="param" value="$(arg hoge)"/>
</launch>

roslaunch my_file.launch hoge:=my_value

<machine>

• Declare a machine that you can run ROS nodes on.
• You do not need this tag if you are launching all the nodes locally.
• It is mainly used to declare SSH and ROS environment variable settings for remote machines, though you can also use it to declare information about the local machine.

<test>

• <test> tag is syntactically similar to the <node> tag.
• They both specify a ROS node to run, but the <test> tag indicates that the node is actually a test node to run.

<test test-name="test_1_2" pkg="mypkg" type="test_1_2.py" time-limit="10.0" args="--test1 --test2" />

Example

<launch>
  <!-- local machine already has a definition by default.
       This tag overrides the default definition with
       specific ROS_ROOT and ROS_PACKAGE_PATH values -->
  <machine name="local_alt" address="localhost" default="true" ros-root="/u/user/ros/ros/" ros-package-path="/u/user/ros/ros-pkg" />
  <!-- a basic listener node -->
  <node name="listener-1" pkg="rospy_tutorials" type="listener" />
  <!-- pass args to the listener node -->
  <node name="listener-2" pkg="rospy_tutorials" type="listener" args="-foo arg2" />
  <!-- a respawn-able listener node -->
  <node name="listener-3" pkg="rospy_tutorials" type="listener" respawn="true" />
  <!-- start listener node in the 'wg1' namespace -->
  <node ns="wg1" name="listener-wg1" pkg="rospy_tutorials" type="listener" respawn="true" />
  <!-- start a group of nodes in the 'wg2' namespace -->
  <group ns="wg2">
    <!-- remap applies to all future statements in this scope. -->
    <remap from="chatter" to="hello"/>
    <node pkg="rospy_tutorials" type="listener" name="listener" args="--test" respawn="true" />
    <node pkg="rospy_tutorials" type="talker" name="talker">
      <!-- set a private parameter for the node -->
      <param name="talker_1_param" value="a value" />
      <!-- nodes can have their own remap args -->
      <remap from="chatter" to="hello-1"/>
      <!-- you can set environment variables for a node -->
      <env name="ENV_EXAMPLE" value="some value" />
    </node>
  </group>
</launch>

References

• http://wiki.ros.org/roslaunch