From 095b1b1a7189bb13d2ec7a5cce619a48158dde2a Mon Sep 17 00:00:00 2001 From: Kacper Bojakowski Date: Sat, 1 Aug 2026 03:07:19 +0200 Subject: [PATCH] Learning about parameters - tutorial (#7031) * Draft Learning about parameters - tutorial * Implement peer review feedback * Created How ROS Works article and added to TOC * Update Understanding-ROS2-Parameters.rst * Update Understanding-ROS2-Parameters.rst * Update Understanding-ROS2-Parameters.rst * Remove trailing whitespace in How-ROS-Works stub --------- Co-authored-by: Denise Marshall Co-authored-by: Tomoya Fujita (cherry picked from commit a3e6767558ec88cf527d300c7647f855a7f0a834) # Conflicts: # source/Concepts/Basic/How-ROS-Works.rst # source/ROS-Framework.rst # source/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters.rst --- source/Concepts/Basic/How-ROS-Works.rst | 32 +++ source/ROS-Framework.rst | 15 ++ .../Understanding-ROS2-Parameters.rst | 191 +++++++++++++----- 3 files changed, 186 insertions(+), 52 deletions(-) create mode 100644 source/Concepts/Basic/How-ROS-Works.rst create mode 100644 source/ROS-Framework.rst diff --git a/source/Concepts/Basic/How-ROS-Works.rst b/source/Concepts/Basic/How-ROS-Works.rst new file mode 100644 index 00000000000..4e53021c749 --- /dev/null +++ b/source/Concepts/Basic/How-ROS-Works.rst @@ -0,0 +1,32 @@ +How ROS works +============= + +.. toctree:: + :maxdepth: 1 + :hidden: + +Coming Soon + +**[Area: Framework | Content-type: concept | Experience: beginner]** + +.. contents:: Table of Contents + :local: + +Summary +------- + + +ROS Graph +--------- + + +Related content +--------------- +* :doc:`nodes/About-Discovery` +* :doc:`About-Client-Libraries` +* :doc:`About-Parameters` +* :doc:`Interfaces-Topics-Services-Actions` +* :doc:`nodes/Working-with-nodes` + +FAQs +---- diff --git a/source/ROS-Framework.rst b/source/ROS-Framework.rst new file mode 100644 index 00000000000..6a4fb0373bf --- /dev/null +++ b/source/ROS-Framework.rst @@ -0,0 +1,15 @@ + + +ROS framework +============= + +Coming Soon + +.. toctree:: + :maxdepth: 3 + + ROS-Framework/How-ROS-Works + ROS-Framework/About-Nodes + ROS-Framework/Interfaces-Topics-Services-Actions + ROS-Framework/About-Parameters + ROS-Framework/About-Client-Libraries 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 82d32669351..2181253f913 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,60 @@ .. _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 +------- +<<<<<<< HEAD:source/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters.rst 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 <../../../About-Parameters>`. +>>>>>>> a3e6767 (Learning about parameters - tutorial (#7031)):source/ROS-Framework/parameters/Working-with-parameters/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters.rst Prerequisites ------------- +<<<<<<< HEAD:source/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters.rst 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>`. Tasks +======= +You will need the :doc:`turtlesim package <../../../../Get-Started/Introducing-Turtlesim/Introducing-Turtlesim>`. + +Steps +>>>>>>> a3e6767 (Learning about parameters - tutorial (#7031)):source/ROS-Framework/parameters/Working-with-parameters/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters.rst ----- +.. note:: + Do not forget to source ROS in every new terminal you open. + + For more information, see :doc:`Configuring environment <../../../../Get-Started/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 +72,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,79 +103,120 @@ To see the parameters belonging to your nodes, open a new terminal and enter the qos_overrides./parameter_events.publisher.reliability use_sim_time +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``. -You see the node namespaces, ``/teleop_turtle`` and ``/turtlesim``, followed by each node's parameters. +Before you continue, notice the following parameters: -The namespaces of the parameter and its name are separated using dots as you can see, for example, in ``parameter_events.publisher.depth``. +* ``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 -Every node has the parameter ``use_sim_time``; it's not unique to turtlesim. -Based on their names, it looks like ``/turtlesim``'s parameters determine the background color of the turtlesim window using RGB color values. +3 Identify the type and value of a parameter +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To determine a parameter's type, you can use ``ros2 param get``. +To display the type and current value of a parameter, use the following command: +.. code-block:: console -3 ros2 param get -^^^^^^^^^^^^^^^^ + $ ros2 param get -To display the type and current value of a parameter, use the command: +<<<<<<< HEAD:source/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters.rst +Let's find out the current value of ``/turtlesim``'s parameter ``background_g``: +======= +You can also query a parameter across all nodes by omitting the node name: .. code-block:: console - $ ros2 param get + $ 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: +>>>>>>> a3e6767 (Learning about parameters - tutorial (#7031)):source/ROS-Framework/parameters/Working-with-parameters/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters.rst .. 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. +<<<<<<< HEAD:source/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters.rst 4 ros2 param set ^^^^^^^^^^^^^^^^ +======= +You can also omit the node name. +As an example, you can try querying ``use_sim_time``, because every node has it: -To change a parameter's value at runtime, use the command: +.. code-block:: console + + $ ros2 param get use_sim_time + +The command displays the value for each node that has that parameter. + +.. note:: + Omitting the node name works only on Lyrical, Rolling, and later distributions. + On earlier distributions, ``ros2 param get`` requires both a node name and a parameter name. +>>>>>>> a3e6767 (Learning about parameters - tutorial (#7031)):source/ROS-Framework/parameters/Working-with-parameters/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters.rst + +4 Change a parameter value at runtime +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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 @@ -170,22 +234,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 Load node parameters from a file +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -6 ros2 param load -^^^^^^^^^^^^^^^^^ - -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 @@ -197,7 +264,7 @@ 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: @@ -210,28 +277,48 @@ 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 +--------------- -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. +More articles: -Next steps ----------- +* :doc:`Learning about nodes <../../../nodes/Working-with-nodes/Understanding-ROS2-Nodes/Understanding-ROS2-Nodes>` +* :doc:`Learning about services <../../../interfaces/services/Working-with-services/Understanding-ROS2-Services/Understanding-ROS2-Services>` +* :doc:`About parameters <../../../About-Parameters>` +<<<<<<< HEAD:source/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters.rst Jumping back to ROS 2 communication methods, in the next tutorial you'll learn about :doc:`actions <../Understanding-ROS2-Actions/Understanding-ROS2-Actions>`. +======= +FAQs +---- + +What types can a parameter hold? + Parameters can be integers, floats, booleans, strings, and lists. + +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. + +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. + +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. +>>>>>>> a3e6767 (Learning about parameters - tutorial (#7031)):source/ROS-Framework/parameters/Working-with-parameters/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters.rst