Skip to content

Learning about parameters - tutorial (backport #7031) #7039

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
mergify wants to merge 1 commit into from
+186 −52
Closed

Learning about parameters - tutorial (backport #7031) #7039

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions source/Concepts/Basic/How-ROS-Works.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
----
15 changes: 15 additions & 0 deletions source/ROS-Framework.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
191 changes: 139 additions & 52 deletions ...inner-CLI-Tools/Understanding-ROS2-Parameters/Understanding-ROS2-Parameters.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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
Expand All @@ -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 <node_name> <parameter_name>

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 <node_name> <parameter_name>
$ ros2 param get <parameter_name>

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 <node_name> <parameter_name> <value>

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 <DumpNodeParameters>` and :ref:`loading a parameter file on node startup <LoadParameterFileOnNodeStartup>`.

.. _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 <node_name>

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

Expand All @@ -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 <node_name> <parameter_file>

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
Expand All @@ -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:

Expand All @@ -210,28 +277,48 @@ To start the same node using your saved parameter values, use:

$ ros2 run <package_name> <executable_name> --ros-args --params-file <file_name>

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
Loading