You're reading the documentation for a development version. For the latest released version, please have a look at Humble.

Integrating launch files into ROS 2 packages

Goal: Add a launch file to a ROS 2 package

Tutorial level: Intermediate

Time: 10 minutes

Prerequisites

You should have gone through the tutorial on how to create a ROS 2 package.

As always, don’t forget to source ROS 2 in every new terminal you open.

Background

In the previous tutorial, we saw how to write a standalone launch file. This tutorial will show how to add a launch file to an existing package, and the conventions typically used.

Tasks

1 Create a package

Create a workspace for the package to live in:

mkdir -p launch_ws/src
cd launch_ws/src
ros2 pkg create py_launch_example --build-type ament_python

2 Creating the structure to hold launch files

By convention, all launch files for a package are stored in the launch directory inside of the package. Make sure to create a launch directory at the top-level of the package you created above.

For Python packages, the directory containing your package should look like this:

src/
  py_launch_example/
    package.xml
    py_launch_example/
    resource/
    setup.py
    setup.cfg
    test/

In order for colcon to find the launch files, we need to inform Python’s setup tools of our launch files using the data_files parameter of setup.

Inside our setup.py file:

import os
from glob import glob
from setuptools import setup

package_name = 'py_launch_example'

setup(
    # Other parameters ...
    data_files=[
        # ... Other data files
        # Include all launch files.
        (os.path.join('share', package_name), glob('launch/*launch.[pxy][yma]*'))
    ]
)

3 Writing the launch file

Inside your launch directory, create a new launch file called my_script_launch.py. _launch.py is recommended, but not required, as the file suffix for Python launch files.

Your launch file should define the generate_launch_description() function which returns a launch.LaunchDescription() to be used by the ros2 launch verb.

import launch
import launch_ros.actions

def generate_launch_description():
    return launch.LaunchDescription([
        launch_ros.actions.Node(
            package='demo_nodes_cpp',
            executable='talker',
            name='talker'),
  ])

4 Building and running the launch file

Go to the top-level of the workspace, and build it:

colcon build

After the colcon build has been successful and you’ve sourced the workspace, you should be able to run the launch file as follows:

ros2 launch py_launch_example my_script_launch.py

Documentation

The launch documentation provides more details on concepts that are also used in launch_ros.

Additional documentation/examples of launch capabilities are forthcoming. See the source code (https://github.com/ros2/launch and https://github.com/ros2/launch_ros) in the meantime.