Edit on Github

Passing ROS arguments to nodes via the command-line

All ROS nodes take a set of arguments that allow various properties to be reconfigured. Examples include configuring the name/namespace of the node, topic/service names used, and parameters on the node. All ros specific arguments have to be specified after a --ros-args flag:

ros2 run my_package node_executable --ros-args ...

For more details, see this design doc.

Note

Before Eloquent, --ros-args wasn’t needed.

Note: all features on this page are only available as of the ROS 2 Bouncy release.

Name remapping

Names within a node (e.g. topics/services) can be remapped using the syntax -r <old name>:=<new name>. The name/namespace of the node itself can be remapped using -r __node:=<new node name> and -r __ns:=<new node namespace>.

Note

Before Eloquent, remapping rules were specified directly using <old name>:=<new name>, __node:=<new node name>, __ns:=<new node namespace>.

Note that these remappings are “static” remappings, in that they apply for the lifetime of the node. “Dynamic” remapping of names after nodes have been started is not yet supported.

See this design doc for more details on remapping arguments (not all functionality is available yet).

Example

The following invocation will cause the talker node to be started under the node name my_talker, publishing on the topic named my_topic instead of the default of chatter. The namespace, which must start with a forward slash, is set to /demo, which means that topics are created in that namespace (/demo/my_topic), as opposed to globally (/my_topic).

ros2 run demo_nodes_cpp talker --ros-args -r __ns:=/demo -r __node:=my_talker -r chatter:=my_topic

Note

Before Eloquent, run ros2 run demo_nodes_cpp talker __ns:=/demo __node:=my_talker chatter:=my_topic.

Passing remapping arguments to specific nodes

If multiple nodes are being run within a single process (e.g. using Composition), remapping arguments can be passed to a specific node using its name as a prefix. For example, the following will pass the remapping arguments to the specified nodes:

ros2 run composition manual_composition --ros-args -r talker:__node:=my_talker -r listener:__node:=my_listener

The following example will both change the node name and remap a topic (node and namespace changes are always applied before topic remapping):

Note

Before Eloquent, run ros2 run composition manual_composition talker:__node:=my_talker listener:__node:=my_listener.

ros2 run composition manual_composition --ros-args -r talker:__node:=my_talker -r my_talker:chatter:=my_topic -r listener:__node:=my_listener -r my_listener:chatter:=my_topic

Note

Before Eloquent, run ros2 run composition manual_composition talker:__node:=my_talker my_talker:chatter:=my_topic listener:__node:=my_listener my_listener:chatter:=my_topic.

Logger configuration

See --log-level argument usage in the logging page.

Parameters

Note

The behavior of parameters changed for Dashing and newer, so if you’re using Crystal or older, see the sections below.

Setting parameters directly in the command line

Note

Supported since Eloquent.

You can set parameters directly from the command line using the following syntax:

ros2 run package_name executable_name --ros-args -p param_name:=param_value

As an example, you can run:

ros2 run demo_nodes_cpp parameter_blackboard --ros-args -p some_int:=42 -p "a_string:=Hello world" -p "some_lists.some_integers:=[1, 2, 3, 4]" -p "some_lists.some_doubles:=[3.14, 2.718]"

Other nodes will be able to retrieve the parameter values, e.g.:

$ ros2 param list parameter_blackboard
a_string
some_int
some_lists.some_doubles
some_lists.some_integers

Setting parameters from YAML files

Parameters can be set from the command-line in the form of yaml files.

See here for examples of the yaml file syntax.

As an example, save the following as demo_params.yaml:

parameter_blackboard:
    ros__parameters:
        some_int: 42
        a_string: "Hello world"
        some_lists:
            some_integers: [1, 2, 3, 4]
            some_doubles : [3.14, 2.718]

Then either declare the parameters within your node with declare_parameter or declare_parameters (see documentation for function signatures), or set the node to automatically declare parameters if they were passed in via a command line override.

Then run the following:

ros2 run demo_nodes_cpp parameter_blackboard --ros-args --params-file demo_params.yaml

Note

In dashing, use ros2 run demo_nodes_cpp parameter_blackboard __params:=demo_params.yaml.

Other nodes will be able to retrieve the parameter values, e.g.:

$ ros2 param list parameter_blackboard
a_string
some_int
some_lists.some_doubles
some_lists.some_integers

Crystal and Older

Parameters support for Python nodes was added in Crystal. In Bouncy only C++ nodes are supported.

Setting parameters from the command-line is currently supported in the form of yaml files.

See here for examples of the yaml file syntax.

As an example, save the following as demo_params.yaml:

talker:
    ros__parameters:
        some_int: 42
        a_string: "Hello world"
        some_lists:
            some_integers: [1, 2, 3, 4]
            some_doubles : [3.14, 2.718]

Then run the following:

ros2 run demo_nodes_cpp talker __params:=demo_params.yaml

Other nodes will be able to retrieve the parameter values, e.g.:

$ ros2 param list talker
a_string
some_int
some_lists.some_doubles
some_lists.some_integers