Rearranging ros2#863 YAML parameters content (ros2#887)

* Add tutorial YAML files parameters

Signed-off-by: Jorge Perez <[email protected]>

* Update source/Contributing/Migration-Guide.rst

Co-authored-by: Marya Belanger <[email protected]>

* Update source/Tutorials/Parameters-YAML-files-migration-guide.rst

Co-authored-by: Marya Belanger <[email protected]>

* Update source/Tutorials/Parameters-YAML-files-migration-guide.rst

Co-authored-by: Marya Belanger <[email protected]>

* Update source/Tutorials/Parameters-YAML-files-migration-guide.rst

Co-authored-by: Marya Belanger <[email protected]>

* Update source/Tutorials/Parameters-YAML-files-migration-guide.rst

Co-authored-by: Marya Belanger <[email protected]>

* Update source/Tutorials/Parameters-YAML-files-migration-guide.rst

Co-authored-by: Marya Belanger <[email protected]>

* Update source/Tutorials/Parameters-YAML-files-migration-guide.rst

Co-authored-by: Marya Belanger <[email protected]>

* Update source/Tutorials/Parameters-YAML-files-migration-guide.rst

Co-authored-by: Marya Belanger <[email protected]>

* Update source/Contributing/Migration-Guide.rst

Co-authored-by: Jacob Perron <[email protected]>

* Update source/Tutorials/Parameters-YAML-files-migration-guide.rst

Co-authored-by: Jacob Perron <[email protected]>

* Update source/Contributing/Migration-Guide.rst

Co-authored-by: Jacob Perron <[email protected]>

* Use cross reference to YAML extra document

Signed-off-by: Jorge Perez <[email protected]>

* rearranging Blast545's YAML parameters content

Signed-off-by: maryaB-osr <[email protected]>

* fix link

Signed-off-by: maryaB-osr <[email protected]>

* Refactor 'concept' page

Refactored the concept page to keep it high-level without details and referenced other pages containing details.

Signed-off-by: Jacob Perron <[email protected]>

* minor typo

Signed-off-by: Jacob Perron <[email protected]>

* Refactor migration guide

Signed-off-by: Jacob Perron <[email protected]>

Co-authored-by: Jorge Perez <[email protected]>
Co-authored-by: Jacob Perron <[email protected]>

Author: 3 people

source/Concepts.rst

@@ -15,6 +15,7 @@ Concept overviews will help you understand the "big picture" idea of ROS 2 syste
    Concepts/About-Topic-Statistics
    Concepts/ROS-2-Client-Libraries
    Concepts/Logging
+   Concepts/About-ROS-2-Parameters
 
 See https://docs.ros2.org/ for more high-level ROS 2 documentation.
 

source/Concepts/About-ROS-2-Parameters.rst

@@ -0,0 +1,45 @@
+.. _AboutParameters:
+
+.. redirect-from::
+
+    About-ROS-2-Parameters
+
+About parameters in ROS 2
+=========================
+
+.. contents:: Table of Contents
+   :local:
+
+Overview
+--------
+
+ROS parameters are associated with ROS nodes.
+Parameters are used to externally configure nodes at runtime (and during runtime).
+The lifetime of a parameter is tied to the lifetime of the node (though the node could implement some sort of persistence to reload values after restart).
+
+Parameters are addressed by node name, node namespace, parameter name, and parameter namespace.
+Providing a parameter namespace is optional.
+
+Each parameter consists of a key and a value, where the key is a string and the value could be one of the following types: bool, int64, float64, string, byte[], bool[], int64[], float64[] or string[]
+
+For an hands-on tutorial with ROS parameters see :ref:`ROS2Params`.
+
+Setting parameters
+------------------
+
+Parameters can be set in many different ways.
+They can be set from the command-line, from launch files, or programmatically.
+They can be set individually or together in a parameters file.
+
+In order to set a parameter on a node, the node must first *declare* that it has that parameter.
+See :ref:`CppParamNode` or :ref:`PythonParamNode` for tutorials on declaring and using parameters from a node.
+These tutorials also demonstrate how to dynamically set a parameter with the ``ros2 param`` tool and from a launch file.
+
+For examples on setting parameters from the command-line or from a parameters file, see :ref:`NodeArgsParameters`.
+
+Migrating from ROS 1
+--------------------
+
+The :ref:`Launch file migration guide <MigratingLaunch>` explains how to migrate ``param`` and ``rosparam`` launch tags from ROS 1 to ROS 2.
+
+The :ref:`YAML parameter file migration guide <yaml-ros1-ros2>` explains how to migrate parameter files from ROS 1 to ROS 2.

source/Contributing/Migration-Guide.rst

@@ -395,6 +395,18 @@ Replace:
 * ``#include <boost/function.hpp>``  with ``#include <functional>``
 * ``boost::function`` with ``std::function``
 
+Parameters
+----------
+
+In ROS 1, parameters are associated with a central server that allowed retrieving parameters at runtime through the use of the network APIs.
+In ROS 2, parameters are associated per node and are configurable at runtime with ROS services.
+
+* See `ROS 2 Parameter design document <https://design.ros2.org/articles/ros_parameters.html>`_ for more details about the system model.
+
+* See `ROS 2 CLI usage <https://index.ros.org/doc/ros2/Tutorials/Parameters/Understanding-ROS2-Parameters/>`_ for a better understanding of how the CLI tools work and its differences with ROS 1 tooling.
+
+* See :ref:`yaml-ros1-ros2` to see how YAML parameter files are parsed in ROS 2 and their differences with ROS implementation.
+
 Launch files
 ------------
 

source/Tutorials.rst

@@ -117,6 +117,7 @@ Miscellaneous
    Tutorials/Eclipse-Oxygen-with-ROS-2-and-rviz2
    Tutorials/Building-ROS-2-on-Linux-with-Eclipse-Oxygen
    Tutorials/Building-Realtime-rt_preempt-kernel-for-ROS-2
+   Tutorials/Parameters-YAML-files-migration-guide
 
 Demos
 -----

source/Tutorials/Launch-files-migration-guide.rst

@@ -1,3 +1,5 @@
+.. _MigratingLaunch:
+
 Migrating launch files from ROS 1 to ROS 2
 ==========================================
 

source/Tutorials/Node-arguments.rst

@@ -115,6 +115,8 @@ See ``--log-level`` argument usage in `the logging page <Logging-and-logger-conf
 Parameters
 ----------
 
+.. _NodeArgsParameters:
+
 Setting parameters directly in the command line
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

source/Tutorials/Parameters-YAML-files-migration-guide.rst

@@ -0,0 +1,51 @@
+.. _yaml-ros1-ros2:
+
+Migrating YAML parameter files from ROS 1 to ROS 2
+==================================================
+
+This tutorial describes how to adapt ROS 1 parameters files for ROS 2.
+
+YAML file example
+-----------------
+
+YAML is used to write parameters files in both ROS 1 and ROS 2.
+The main difference in ROS 2 is that node names must be used to address parameters.
+In addition to the fully qualified node name, we use the key "ros__parameters" to signal the start of parameters for the node.
+
+
+For example, here is a parameters file in ROS 1:
+
+.. code-block:: yaml
+
+   lidar_name: foo
+   lidar_id: 10
+   ports: [11312, 11311, 21311]
+   debug: true
+
+Let's assume that the first two parameters are for a node named ``/lidar_ns/lidar_node_name``, the second parameter is for a node named ``/imu``, and the last parameter we want to set on both nodes.
+
+We would construct our ROS 2 parameters file as follows:
+
+.. code-block:: yaml
+
+   /lidar_ns:
+     lidar_node_name:
+       ros__parameters:
+         lidar_name: foo
+         id: 10
+   imu:
+     ros__parameters:
+       ports: [2438, 2439, 2440]
+   /**:
+     ros__parameters:
+       debug: true
+
+Note the use of wildcards (``/**``) to indicate that the parameter ``debug`` should be set on any node in any namespace.
+
+Feature parity
+--------------
+
+Some features of ROS 1 parameters files does not exist in ROS 2:
+
+- Mixed types in a list is not supported yet (`related issue <https://github.com/ros2/rcl/issues/463>`_)
+- ``deg`` and ``rad`` substitutions are not supported