ROS Launch Files in Sailbot Workspace¶

ROS 2 Launch files allow us to programatically start up and configure multiple ROS nodes.¹ Within Sailbot Workspace, ROS launch files are used to start up our ROS packages with ease. Additionally, we take advantage of the hierarchical properties of launch files by defining a global entry point that invokes the launch files of all ROS packages in the system.

Tutorial¶

Launch File Architecture¶

There are two launch processes that we utilize: namely the Package Launch Process and the Global launch process.

The Package Launch Process¶

The package launch process is intended to start up a specific ROS package by directly using the package launch file. The process is as follows:

The package launch file is invoked with the user passing arguments via the CLI and specifying a configuration file.
Global argument declarations and environment variables are loaded into the launch process.
Local arguments, specific to the package, are declared.
Both global and local arguments are parsed based on the argument declarations and are set for use upon start up.
The ROS nodes belonging to the package begin execution, utilizing the ROS parameters from the configuration file.

When launching individual packages, be aware of dependencies between ROS packages

Some packages rely on the data produced by other packages in the system. This may cause only partial functionality of the ROS node(s) that are running inside the launched package. Therefore, it may be necessary to launch multiple packages manually to get the desired functionality.

The Global Launch Process¶

The global launch process is intended to start up the entire system (both the development and production environments). This process invokes the package launch files for each ROS package used in the system through a global launch file. The process is as follows:

The global launch file is invoked with the user passing arguments via the CLI and specifying a configuration file.
Environment variables common to all ROS packages are declared. In addition, the global arguments common across all ROS packages are declared.
For each package launch file:
- The CLI arguments, global argument declarations, and environment variables are passed into the package launch file.
- Local arguments, specific to the package, are declared. Both the global and local arguments are parsed based on the argument declarations and are set for use upon start up.
- The ROS nodes belonging to the package begin execution, utilizing the ROS parameters from the configuration file.

Invoking Launch Files¶

Stopping the execution of a launch file

Entering Ctrl+C in the terminal where the launch file was invoked will stop all associated ROS packages from running.

Use Cmd+C for Mac OS

Package Launch¶

At the bare minimum, the following packages need to be built with the Build or Build All VS Code task before launching:

custom_interfaces
The package you want to launch

Packages only need to be rebuilt either when the workspace is first set up, or if any changes are made to the ROS package. Once built, the package launch file can be invoked either in the CLI or using a VS Code command:

CLI VS Code

Either the package and launch file name, or the path to the launch file can be used:

Method 1: ros2 launch <package> <launch file>. This method can only be used when a launch file is part of a built ROS package.
Method 2: ros2 launch <path to launch file>. This method can be used regardless if a launch file is in a ROS package or not.

Launch via CLI Examples

Let's launch local pathfinding using both CLI methods:

Method 1

ros2 launch local_pathfinding main_launch.py

Method 2

ros2 launch $ROS_WORKSPACE/src/local_pathfinding/launch/main_launch.py

Run the following VS Code command from the Run and Debug tab: ROS: Launch (workspace)

There will be a prompt to select which launch file to run. Select the desired launch file.

Global Launch¶

Before running the system, be sure to run the Build All VS Code task to build all ROS packages. If the ROS launch debug configuration is being used, then this step is not necessary as the Build All task is ran automatically before launch.

CLI VS Code

Run the entire system with the following CLI command:

ros2 launch $ROS_WORKSPACE/src/global_launch/main_launch.py

Run the following VS Code command from the Run and Debug tab: ROS: Launch (workspace)

There will be a prompt to select which launch file to run. Select the desired launch file.

Remember to that you need to potentially reload the window if the nodes are not being detected by VS Code. This usually happens when somebody build for the first time. Also, note that the global launch file is not part of a ROS package, so the path to the global launch file always must be provided. This is not always the case when a launch file is contained within a ROS package.

Using CLI Arguments¶

Invoking the launch files as is will provide the system with the default CLI arguments. As an example, the following command will launch local pathfinding while setting the log level to "debug":

ros2 launch local_pathfinding main_launch.py log_level:=debug

It can also be ran with the VS Code command named ROS: Launch.

Passing arguments takes the form of <arg name>:=<arg value>. To list the arguments that a launch file takes, simply add the -s flag at the end of the launch command.

Example using the -s flag in a launch command

Let's add the -s flag after the global launch command to see the list of arguments:

ros2 launch $ROS_WORKSPACE/src/global_launch/main_launch.py -s

The following output is observed in the terminal (as of September 2023):

Arguments (pass arguments as '<name>:=<value>'):

'config':
    Path to ROS parameter config file. Controls ROS parameters passed into ROS nodes
    (default: '/workspaces/sailbot_workspace/src/global_launch/config/globals.yaml')

'log_level':
    Logging severity level. A logger will only process log messages with severity levels at or higher than the
    specified severity. Valid choices are: ['debug', 'info', 'warn', 'error', 'fatal']
    (default: 'info')

'mode':
    System mode. Decides whether the system is ran with development or production interfaces. Valid choices are:
    ['production', 'development']
    (default: 'development')

Example using multiple CLI arguments

ros2 launch local_pathfinding main_launch.py log_level:=debug mode:=production

Example passing local launch arguments to the global launch file

As long as an argument is valid inside one of the package launch files, it may be passed to the global launch file without generating any errors. This is valid even though the argument doesn't show up in the argument list for the global launch file. For example, the following will run:

ros2 launch $ROS_WORKSPACE/src/global_launch/main_launch.py enable_sim_multithreading:=true

Compare the argument list between the global launch file and the package launch file for the boat_simulator package. It will be observed that the argument enable_sim_multithreading shows up in the boat_simulator package argument list, but not for the global launch file.

ROS Parameter Config File¶

All launch files in Sailbot Workspace accept a configuration file, which controls the ROS parameters that the ROS nodes in the system have access to. This makes our system highly configurable and customizable during development and testing. See more about ROS parameters.

ROS Launch File Documentation ↩