Launchfiles

• ROS programs consist of many nodes communicating over topics and services
• For non-trivial programs, manually running nodes using ros2 run becomes tedious and hard to reproduce
• Launchfiles provide a method for having a single command start the robot and enable specifying
  • Which nodes are run
  • What parameters they use
  • What topics are named
  • and more!
• These Launchfile Tutorials will help get you started.

• The command-line tool for using launch files is ros2 launch
• There are two ways of invoking a launchfile:
  1. ros2 launch package file.launch.{xml,py} [arg_name:=value]...
     • Here, the launch file must be installed into the install space (e.g., by setting up setup.py)
  2. ros2 launch package /path/to/launch/file.launch [arg_name:=value...]
     • Here, the launch file at the given location is directly used.
     • The main advantage is that you do not need to rebuild the workspace when you change the launchfile.
• You can pass arguments to a launch file using the arg_name:=value syntax, which is shared with the remapping arguments syntax.

1. The ROS 1 Launchfile format relies on XML, along with a special enhanced substitution argument syntax.
   • Most easily understood in conjunction with ROS 2 Launchfile Migration Guide.
   • The launchfile system in ROS 2 is highly extendable
     • The basic launch functionality is implemented in the launch package. This repository contains generic tools for running processes on a system
     • ROS specific functionality is implemented in the launch_ros package.
       • For example, the Node launch action of launch_ros uses the ExecuteProcess launch action of launch.
     • The architecture of ROS 2 Launchfiles explains the concepts behind the design.
     • API Documentation contains XML examples for the python functions that have XML equivalents.
   • This Design Document lays out the format of ROS 2 XML launchfiles
2. Launchfiles should be installed by adding them to the data_files section of setup.py.
   • Install the files to share/package_name/launch.
3. Projects that use launchfiles should add ros2launch as an <exec_depend> in package.xml (because ros2 launch is required to use them).
4. Launchfiles list nodes to be launched; however, the order in which they start is non-deterministic.
5. Important Launchfile XML elements:
   • <launch> - the root element, every launchfile starts with this.
   • <node> - Used to run a node. Attributes:
     • pkg: the package the node is in.
     • exec (type in ROS 1): the name of the node executable file.
     • name: the basename of the node.
     • namespace (ns in ROS 1): the node's namespace.
     • output: determine where to send the output to (a log file or the screen).
     • required: if the node dies, the whole launch is terminated.
   • <include> - Lets you include a launchfile in another launchfile
   • <remap> - Used for Remapping arguments
   • <param> - Sets an individual parameter for a node (or on the parameter server in ROS 1).
     • In ROS 2 the "command" attribute does not exist. To set a parameter to the output of a command use the $(command) substitution.
   • <group> - Groups nodes together and allows you to easily apply common settings
     • To put all nodes within a group in the same namespace use the <push_ros_namespace namespace="ns"> tag
   • <arg> - Used to specify arguments which can be used to change the behavior of the launchfile from the command-line.
     • You should always provide documentation for Launchfile arguments using the description attribute (called doc in ROS 1).
   • <let> - used to define a constant (ROS 2 only, handled by <arg> in ROS 1)
   • <env> - Used to set environment variables for the underlying node
6. Conditionals:
   • Conditional Attributes All elements have attributes if and unless to be conditionally included.
7. Substitution arguments:
   • The following items can be used within attribute values to perform a computation and expand into the result of that computation
   • The general syntax uses $() (just like bash substitution arguments).
   • Within XML, a substitution argument would be used like <tag attribute ="$()" />.
   • A list of some possible substitution arguments is below:
     1. $(env ENVIRONMENT_VARIABLE) Expands into the value of the environment variable or is an error if that variable is not set.
     2. $(env ENVIRONMENT_VARIABLE default) Expands into the value of an environment variable or default if it is not set. (In ROS 1 this was $(optenv))
     3. $(find-pkg-share)$ expands to the location of a given package's share directory. Useful for finding configuration and data files associated with the package
     4. $(find-pkg-prefix)$ expands
     5. $(var myarg) expands into the value of myarg, as specified by an <arg> element and passed in on the call to roslaunch
     6. $(eval <expression>) Runs python code <expression> and expands to the result of the code evaluation
        • This does not yet behave exactly like the ROS 1 version:
          1. <expression> should be a single-quoted string
          2. If the expression itself uses single-quotes, those need to be escaped (e.g., 'mystring' becomes \'mystring\')
          3. Some ROS 1 shortcuts for accessing launchfile arguments are not supported: instead the substitution must be used: (e.g., $(var argname) will literally transform into the value of argname
     7. $(command '<expression>') runs a command and returns the output (ROS 2 only).
8. Loading Parameters from a file:

   1. In <pkg>/config, create a <myconfig>.yaml file

      • Each key at the top level is the name of a node (or a wildcard pattern for a node name)
      • The next subkey is ros__parameters (note the double _)
      • Then the next keys are parameters and their values

      node_name_here:
         ros__parameters:
             param1: value
             pram2: value
      

   2. ros2 param load can load these files

      1. You must install the data by editing setup.py and adding it to data_files in setup.py

      3.In an xml launchfile use <param from="$(find-pkg-share pkgname)/installed/path/to/configfile>

9. More information on how ROS handles .yaml files can be found in the rcl_yaml_param_parser library

Launchfile best practices in ROS 2 are still up in the air, the only "official" guidance I've found is here: Which Launch Format to Use?. So here are some opinions:

1. Prefer XML launch files in most cases
   • Closer to ROS 1 (so it will help you with ROS 1, which is still very much in use)
   • More declarative (that is no changing state) so it is easier to see what is going on and harder to make mistakes
   • Since ROS 2 Iron, we can do everything we do in this class with XML launchfiles
2. Use python launch files either when
   • Features are not yet in XML launch files (such as storing the value of a command in a parameter)
   • You begin doing lots of logic substitutions and if attributes in XML and need more code-reuse and more complex actions
3. In python launchfiles, stick to a declarative style as much as possible
   • generate_launch_description should ideally be a single return statement
   • No variables are used
   • Prefer substitution rules to python logic (for example FindPackageShare substitution rule rather than importing a function that finds the package share directory)
   • This declarative style makes it easier to see what the launchfile is doing (to experienced launchfile users) than needing to follow launchfile logic
   • The declarative style is also more directly translatable to an XML format, if the required features become available.
4. Remember that python launchfiles can include XML launchfiles and vice versa
5. I have yet to see a yaml launch file in the wild. As far as I can tell it has no features that XML does not have, other than it's not XML (and yaml is typically used as an alternative to XML).

• ROS 2 Launchfile Tutorials
• Migrating from ROS1
  • Contains useful information about ROS 2 Launchfiles that I have not found elsewhere.
• Launchfile XML Specification