From 0ddf2b2eead46c4584914eef781aad2f4d6624a5 Mon Sep 17 00:00:00 2001 From: Kacper Bojakowski Date: Tue, 4 Aug 2026 02:30:02 +0200 Subject: [PATCH] Backport learning about parameters tutorial. Adapt the rewritten parameters tutorial to the Beginner-CLI-Tools layout used on this distribution. --- .../Understanding-ROS2-Parameters.rst | 170 +++++++++++------- 1 file changed, 107 insertions(+), 63 deletions(-) diff --git a/source/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters.rst b/source/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters.rst index 4c0791135f0..60d41b5dff5 100644 --- a/source/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters.rst +++ b/source/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters.rst @@ -4,42 +4,44 @@ .. _ROS2Params: -Understanding parameters -======================== +Learning about parameters - tutorial +===================================== -**Goal:** Learn how to get, set, save and reload parameters in ROS 2. +Parameters are configuration values stored by each node in the ROS graph. +This article walks you through using the ``ros2 param`` command-line tools to inspect, change, save, and reload parameters. +A hands-on exercise with Turtlesim shows how parameters control node behaviour at runtime. -**Tutorial level:** Beginner - -**Time:** 5 minutes +**Area: Framework | Content-type: tutorial | Experience: beginner** .. contents:: Contents :depth: 2 :local: -Background ----------- +Summary +------- -A parameter is a configuration value of a node. -You can think of parameters as node settings. -A node can store parameters as integers, floats, booleans, strings, and lists. -In ROS 2, each node maintains its own parameters. -For more background on parameters, please see :doc:`the concept document <../../../Concepts/Basic/About-Parameters>`. +Each node in the ROS graph stores its own set of configuration values, called parameters. +Use the ``ros2 param`` commands to get, set, save, and reload parameter values at runtime. + +For more information, see :doc:`About parameters <../../../Concepts/Basic/About-Parameters>`. Prerequisites ------------- -This tutorial uses the :doc:`turtlesim package <../Introducing-Turtlesim/Introducing-Turtlesim>`. - -As always, don't forget to source ROS 2 in :doc:`every new terminal you open <../Configuring-ROS2-Environment>`. +You will need the :doc:`turtlesim package <../Introducing-Turtlesim/Introducing-Turtlesim>`. -Tasks +Steps ----- +.. note:: + Do not forget to source ROS in every new terminal you open. + + For more information, see :doc:`Configuring environment <../Configuring-ROS2-Environment>`. + 1 Setup ^^^^^^^ -Start up the two turtlesim nodes, ``/turtlesim`` and ``/teleop_turtle``. +Start up the two Turtlesim nodes, ``/turtlesim`` and ``/teleop_turtle``. Open a new terminal and run: @@ -54,14 +56,19 @@ Open another terminal and run: $ ros2 run turtlesim turtle_teleop_key -2 ros2 param list -^^^^^^^^^^^^^^^^^ +2 View the list of parameters for your nodes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To see the parameters belonging to your nodes, open a new terminal and enter the command: +To see the parameters belonging to your nodes, open a new terminal and run: .. code-block:: console $ ros2 param list + +You should see output similar to: + +.. code-block:: console + /teleop_turtle: qos_overrides./parameter_events.publisher.depth qos_overrides./parameter_events.publisher.durability @@ -80,76 +87,92 @@ To see the parameters belonging to your nodes, open a new terminal and enter the qos_overrides./parameter_events.publisher.reliability use_sim_time -You see the node namespaces, ``/teleop_turtle`` and ``/turtlesim``, followed by each node's parameters. +The output groups the parameters under each node name, ``/teleop_turtle`` and ``/turtlesim``. +The namespace and name of a parameter are separated by dots, as in ``parameter_events.publisher.depth``. -Every node has the parameter ``use_sim_time``; it's not unique to turtlesim. +Before you continue, notice the following parameters: -Based on their names, it looks like ``/turtlesim``'s parameters determine the background color of the turtlesim window using RGB color values. +* ``use_sim_time``: Specifies whether the node uses simulated time or the computer's clock. +* ``background_r``, ``background_g``, and ``background_b``: Define the RGB values for the background colour of the Turtlesim window -To determine a parameter's type, you can use ``ros2 param get``. +3 Identify the type and value of a parameter +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -3 ros2 param get -^^^^^^^^^^^^^^^^ - -To display the type and current value of a parameter, use the command: +To display the type and current value of a parameter, use the following command: .. code-block:: console $ ros2 param get -Let's find out the current value of ``/turtlesim``'s parameter ``background_g``: +To find out the current value of ``/turtlesim``'s parameter ``background_g``, run: .. code-block:: console $ ros2 param get /turtlesim background_g + +The terminal returns: + +.. code-block:: console + Integer value is: 86 -Now you know ``background_g`` holds an integer value. +This tells you ``background_g`` holds an integer value. -If you run the same command on ``background_r`` and ``background_b``, you will get the values ``69`` and ``255``, respectively. +Running the same command on ``background_r`` and ``background_b`` should return the values ``69`` and ``255``, respectively. -4 ros2 param set -^^^^^^^^^^^^^^^^ +4 Change a parameter value at runtime +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To change a parameter's value at runtime, use the command: +To change a parameter's value at runtime, use the following command: .. code-block:: console $ ros2 param set -Let's change ``/turtlesim``'s background color: +Change ``/turtlesim``'s background colour: .. code-block:: console $ ros2 param set /turtlesim background_r 150 + +The terminal returns: + +.. code-block:: console + Set parameter successful -The background of your turtlesim window should change colors: +The background of the Turtlesim window should change colour, like this: .. image:: images/set.png Setting parameters with the ``set`` command will only change them in your current session, not permanently. However, you can save your settings and reload them the next time you start a node. +See :ref:`dumping parameters ` and :ref:`loading a parameter file on node startup `. + +.. _DumpNodeParameters: -5 ros2 param dump -^^^^^^^^^^^^^^^^^ +5 Save the parameters of a node to a file +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -You can view all of a node's current parameter values by using the command: +You can save parameters of a node to a file. +This comes in handy if you want to reload the node with the same parameters in the future. +Use the following command: .. code-block:: console $ ros2 param dump -The command prints to the standard output (stdout) by default but you can also redirect the parameter values into a file to save them for later. -To save your current configuration of ``/turtlesim``'s parameters into the file ``turtlesim.yaml``, enter the command: +The command prints to the standard output (stdout) by default, but you can also redirect the parameter values into a file to save them for later. +To save your current configuration of ``/turtlesim``'s parameters into the file ``turtlesim.yaml``, run: .. code-block:: console $ ros2 param dump /turtlesim > turtlesim.yaml -You will find a new file in the current working directory your shell is running in. -If you open this file, you'll see the following content: +A new file is created in the current working directory. + +Open the file to view the following content: .. code-block:: YAML @@ -167,22 +190,25 @@ If you open this file, you'll see the following content: reliability: reliable use_sim_time: false -Dumping parameters comes in handy if you want to reload the node with the same parameters in the future. - -6 ros2 param load -^^^^^^^^^^^^^^^^^ +6 Load node parameters from a file +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -You can load parameters from a file to a currently running node using the command: +You can load parameters from a file to a currently running node using the following command: .. code-block:: console $ ros2 param load -To load the ``turtlesim.yaml`` file generated with ``ros2 param dump`` into ``/turtlesim`` node's parameters, enter the command: +To load the ``turtlesim.yaml`` file generated with ``ros2 param dump`` into ``/turtlesim`` node's parameters, run: .. code-block:: console $ ros2 param load /turtlesim turtlesim.yaml + +The terminal returns: + +.. code-block:: console + Set parameter background_b successful Set parameter background_g successful Set parameter background_r successful @@ -194,7 +220,9 @@ To load the ``turtlesim.yaml`` file generated with ``ros2 param dump`` into ``/t .. note:: - Read-only parameters can only be modified at startup and not afterwards, that is why there are some warnings for the "qos_overrides" parameters. + Read-only parameters can only be modified at startup and not afterwards, which is why there are some ``failed`` warnings for the ``qos_overrides`` parameters. + +.. _LoadParameterFileOnNodeStartup: 7 Load parameter file on node startup ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -205,28 +233,44 @@ To start the same node using your saved parameter values, use: $ ros2 run --ros-args --params-file -This is the same command you always use to start turtlesim, with the added flags ``--ros-args`` and ``--params-file``, followed by the file you want to load. +This is the same command used to start Turtlesim, with the added flags ``--ros-args`` and ``--params-file``, followed by the file you want to load. -Stop your running turtlesim node, and try reloading it with your saved parameters, using: +Stop your running Turtlesim node, and try reloading it with your saved parameters: .. code-block:: console $ ros2 run turtlesim turtlesim_node --ros-args --params-file turtlesim.yaml -The turtlesim window should appear as usual, but with the purple background you set earlier. +The Turtlesim window should appear as usual, but with the purple background you set earlier. .. note:: - When a parameter file is used at node startup, all parameters, including the read-only ones, will be updated. + When a parameter file is used at node startup, all parameters are updated, including the read-only ones. -Summary -------- +Related content +--------------- + +More articles: + +* :doc:`Learning about nodes <../Understanding-ROS2-Nodes/Understanding-ROS2-Nodes>` +* :doc:`Learning about services <../Understanding-ROS2-Services/Understanding-ROS2-Services>` +* :doc:`About parameters <../../../Concepts/Basic/About-Parameters>` + +FAQs +---- + +What types can a parameter hold? + Parameters can be integers, floats, booleans, strings, and lists. -Nodes have parameters to define their default configuration values. -You can ``get`` and ``set`` parameter values from the command line. -You can also save the parameter settings to a file to reload them in a future session. +Do parameter changes persist after a node is restarted? + No. + Changes made with ``ros2 param set`` apply only to the current session. + To persist them, use ``ros2 param dump`` to save the values to a YAML file and load that file when starting the node. -Next steps ----------- +Why do some parameters fail to load with ``ros2 param load``? + Parameters marked as read-only can only be set at node startup, not at runtime. + The ``qos_overrides`` parameters are read-only, which is why they show ``failed`` messages when loading a parameter file into a running node. -Jumping back to ROS 2 communication methods, in the next tutorial you'll learn about :doc:`actions <../Understanding-ROS2-Actions/Understanding-ROS2-Actions>`. +What is the difference between ``ros2 param dump`` and ``ros2 param load``? + ``ros2 param dump`` saves a node's current parameter values to a YAML file. + ``ros2 param load`` reads a YAML file and applies the values to a currently running node.