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