simple_launch

This package provides a Python class to help writing ROS 2 launch files.

The motivation behind this package is that the ROS 2 launch Python syntax may not be suited for many simple cases such as running basic nodes, spawning a robot_state_publisher, and grouping nodes in namespaces or components.

Thanks: this package is inspired by ros2_launch_util.

The entry point is the SimpleLauncher class, which has several capabilities.

Basic syntax

Namespace and argument parser initialization

sl = SimpleLauncher(namespace = '', use_sim_time = None, scope_included_files = False)

• will initialize all nodes relative to the given namespace
• if use_sim_time is a Boolean, creates a use_sim_time launch argument with this value as the default and forwards it to all nodes, unless explicitely specified when running the node
• if use_sim_time is 'auto', then SimpleLauncher will set it to True if the /clock topic is advertized (case of an already running simulation). This may have side effects if the /clock topic is advertized but you want to use this launch file with system clock.
• if use_sim_time is None (default) then no particular value is forwarded to the nodes
• if scope_included_files is False (default) then including another launch file that shares the same argument but while passing another value for this argument, will also modify the value of this argument after the inclusion. This is the default behavior of launch but can be undesired. Inside an OpaqueFunction the behavior is to be scoped anyway (the argument value is resolved) and scope_included_files has no effect.

Node registration

sl.node(package, executable, **node_args) where

• package is the node package
• executable is the name of the executable
• node_args are any additional Node arguments

Launch file include

sl.include(package, launch_file, launch_dir = None, launch_arguments=None) where

• package is the package of the included launch file
• launch_file is the name of the launch file
• launch_dir is its directory inside the package share (None to have it found)
• launch_arguments is a dictionary of arguments to pass to the included launch file

Call a service at launch

This line runs a temporary client that waits for a service and calls it when available:

sl.call_service(server, request = None, verbosity = '') where

• server is the path to some service (possibly namespaced). The service type is deduced when it becomes available.
• request is a dictionary representing the service request. If None or incomplete, will use the service request default values.
• verbosity let the underlying node describe what it is doing: 'req' for request info, 'res' for response info or both with 'reqres'

If any request parameter is __ns it will be changed to the current namespace.

Setting parameters

This line runs a temporary client that waits for a node and changes its parameters when available:

sl.set_parameters(node_name, parameters: dict = {}, verbosity = '') where

• node_name is the name of the node (possibly namespaced)
• parameters is a dictionary of (name, value) parameters to be set
• verbosity let the underlying node describe what it is doing: 'req' for request info, 'res' for response info or both with 'reqres'

This calls the set_parameters service of the node with the passed types. Possible errors may happen if the parameters do not exist or are of a different type.

Robust types for parameters

In the launch API, differents types are expected for:

• node parameters: a list of dictionaries
• node remappings: a list of (key, value) pairs
• included launch arguments: a list of (key, value) pairs
• xacro arguments: a concatenation of key:=value strings

The sl.include, sl.node and xacro_args calls allow using any type (the simplest being a single dictionary) and will convert to the one expected by the API.

Launch arguments

simple_launch allows declaring launch arguments and getting them in return.

Declare a launch argument

sl.declare_arg(name, default_value, description = None): declare and returns the argument

Contrary to the base API, the default value is a raw Python type.

Retrieve a launch argument

sl.arg(name): returns the argument name as a SimpleSubstitution

Retrieve several arguments as a dictionary

sl.arg_map('robot', 'x', 'y'): returns {'robot': <robot arg value>, 'x': <x arg value>, 'y': <y arg value>}

Typical when forwarding some launch arguments to a node or an included launch file.

Groups or scopes

Groups are created through the with sl.group(): syntax and accept, a namespace an if/unless condition and an event.

Actions that are added in a scope inherit from all previous defined groups.

File truncated at 100 lines see the full file

Changelog for package simple_launch

1.11.0 (2025-02-16)

• handle gz world export to SDF after some delay
• make gz_launch compatible with substitutions
• Contributors: Olivier Kermorgant

1.10.1 (2024-07-05)

• check for gz/ign executable being available
• gz_world_tf + better guess on Gz vs Ign
• Contributors: Olivier Kermorgant

1.10.0 (2024-06-16)

• scope_included_files to include other launch files in a Group and avoid changing my scope
• remove dead code about prefixing gz plugins
• forward sim_time even for nodes that load a parameter file
• lazy GazeboBridge
• Contributors: Olivier Kermorgant

1.9.2 (2024-03-25)

• Gazebo basic example: launch SDF world + spawn from xacro
• remove dead code related to Gazebo.
• sl.arg returns a SimpleSubstitution to allow concatenation
• auto-detect Gazebo world name, allows running the simulation + spawn models in the same launch file
• Type debug on String being Iterable
• better handling of non-string choices in argument declaration
• more robust to various gz/ros combinations
• Contributors: Olivier Kermorgant

1.9.1 (2024-02-20)

• simplify + debug logic of SimpleSubstitution divisions
• image instead of /image to be detected as an image topic
• remove auto_sim_time function
• more robust to various combinations of ROS and Gazebo
• default Gazebo is still ignition Fortress, better error message about GZ_VERSION
• add new bridges for Gazebo
• Contributors: Olivier Kermorgant

1.9.0 (2023-11-23)

• update documentation
• warnings/errors on misuse of GazeboBridge
• move example executable to share directory
• dict cannot be updated with | in Foxy, fallback to dict.update
• absolute container name when loading in existing container
• py_eval can now handle conditions
• Contributors: Olivier Kermorgant

1.8.0 (2023-11-20)

• sync documentation and examples
• when instead of after for events
• scoped events
• add event wrapper
• Contributors: Olivier Kermorgant

1.7.2 (2023-10-02)

• simplify logic of try_perform
• Merge pull request #5 from okvik/devel Fix string-valued launch argument substitution
• slight refactor to prepare wrapping Delays
• Contributors: Olivier Kermorgant, Viktor Pocedulic
• slight refactor to prepare wrapping Delays
• Contributors: Olivier Kermorgant

1.7.1 (2023-05-16)

• list[] -> List[] for type hints in 20.04
• detail on __ns for services
• add service call at launch
• Contributors: Olivier Kermorgant

1.7.0 (2023-02-22)

• GazeboBridge creates a camera_info topic for all bridged image topics
• Contributors: Olivier Kermorgant

1.6.2 (2023-01-23)

• add .rviz shortcut, clean Python scripts
• Contributors: Olivier Kermorgant

1.6.1 (2022-10-10)

• fix bug in robot_state_publisher with raw URDF
• Contributors: Olivier Kermorgant

1.6.0 (2022-10-06)

File truncated at 100 lines see the full file