From 8a4a58003781b69074f5c1bbcbf167e8dde13aa5 Mon Sep 17 00:00:00 2001 From: Jan Kaniuka Date: Tue, 14 Jan 2025 01:26:38 +0100 Subject: [PATCH] shorter description of setting params via YAML file - added references instead --- .../Using-Parameters-In-A-Class-CPP.rst | 132 +---------------- .../Using-Parameters-In-A-Class-Python.rst | 136 +----------------- .../Using-ROS2-Launch-For-Large-Projects.rst | 2 + 3 files changed, 12 insertions(+), 258 deletions(-) diff --git a/source/Tutorials/Beginner-Client-Libraries/Using-Parameters-In-A-Class-CPP.rst b/source/Tutorials/Beginner-Client-Libraries/Using-Parameters-In-A-Class-CPP.rst index 24a9b2ec4b3..7b769768dc9 100644 --- a/source/Tutorials/Beginner-Client-Libraries/Using-Parameters-In-A-Class-CPP.rst +++ b/source/Tutorials/Beginner-Client-Libraries/Using-Parameters-In-A-Class-CPP.rst @@ -432,139 +432,17 @@ Further outputs should show ``[INFO] [minimal_param_node]: Hello world!`` every ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Instead of listing parameters and their values in launch file, you can create a separate YAML file that will be loaded in launch file. -First, you will need to add a config directory. -Inside the ``ros2_ws/src/cpp_parameters/`` directory, create a new directory called ``config``. -In there, create a new file called ``cpp_parameters_config.yaml``. +Placing parameters in a YAML file makes it easier to organize them, for example, by assigning them to different namespaces. +You can read more about it :ref:`here `. -.. code-block:: yaml - - custom_minimal_param_node: - ros__parameters: - my_parameter: "earth" - -Now, you will have to edit ``cpp_parameters_launch.py``. -Add the import statements to the top of the file and add a variable containing the path to the configuration file. -Then replace the dictionary containing the parameter name and value with a path to YAML file. - -.. code-block:: Python - - import os - from ament_index_python.packages import get_package_share_directory - # ... - - def generate_launch_description(): - config = os.path.join( - get_package_share_directory("cpp_parameters"), "config", "cpp_parameters_config.yaml" - ) - - return LaunchDescription( - [ - Node( - # ... - parameters=[config], - ) - ] - ) - -Now open the ``CMakeLists.txt`` file. Below the lines you added earlier, add the following lines of code. - -.. code-block:: console - - install( - DIRECTORY config - DESTINATION share/${PROJECT_NAME} - ) - -Open a console and navigate to the root of your workspace, ``ros2_ws``, and build the package: - -.. tabs:: - - .. group-tab:: Linux - - .. code-block:: console - - colcon build --packages-select cpp_parameters - - .. group-tab:: macOS - - .. code-block:: console - - colcon build --packages-select cpp_parameters - - .. group-tab:: Windows - - .. code-block:: console - - colcon build --merge-install --packages-select cpp_parameters - -Then source the setup files in a new terminal: - -.. tabs:: - - .. group-tab:: Linux - - .. code-block:: console - - source install/setup.bash - - .. group-tab:: macOS - - .. code-block:: console - - . install/setup.bash - - .. group-tab:: Windows - - .. code-block:: console - - call install/setup.bat - -Now run the node using the modified version of launch file: - -.. code-block:: console - - ros2 launch cpp_parameters cpp_parameters_launch.py - -The terminal should return the following message the first time: - -.. code-block:: console - - [INFO] [custom_minimal_param_node]: Hello earth! - -Further outputs should show ``[INFO] [minimal_param_node]: Hello world!`` every second. - -Parameter listed in ``cpp_parameters_config.yaml`` file will be set only for ``custom_minimal_param_node`` node. -If you want to indicate that the parameter ``my_parameter`` should be set on any node in any namespace, then you should use wildcards (``/**``). - -.. code-block:: yaml - - /**: - ros__parameters: - my_parameter: "earth" - -You can also use your parameter under namespace, but it will require some changes in ``cpp_parameters_node.cpp`` file. -First, edit config file to look like the one below. - -.. code-block:: yaml - - custom_minimal_param_node: - my_namespace: - ros__parameters: - my_parameter: "earth" - - -While declaring, getting and setting parameter value inside your C++ node, you should also add namespace to parameter name and use dot as a separator. -Modify ``cpp_parameters_node.cpp`` by changing all occurrences of ``"my_parameter"`` into ``"my_namespace.my_parameter"``. +.. note:: + While declaring, getting and setting parameter value inside your C++ node, you should use dot as a separator between parameter's namespace and name. 3.4 Change via passing YAML file as an argument at node startup ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -As a reminder from the :ref:`tutorial about parameters `, you can also load parameter file at node startup. - -.. code-block:: console - - ros2 run cpp_parameters minimal_param_node --ros-args --params-file ~/ros2_ws/src/cpp_parameters/config/cpp_parameters_config.yaml +Return to :ref:`tutorial about parameters ` to remind yourself, how to load parameters file at node startup using CLI. Summary ------- diff --git a/source/Tutorials/Beginner-Client-Libraries/Using-Parameters-In-A-Class-Python.rst b/source/Tutorials/Beginner-Client-Libraries/Using-Parameters-In-A-Class-Python.rst index 107101a99a5..326e205b7f7 100644 --- a/source/Tutorials/Beginner-Client-Libraries/Using-Parameters-In-A-Class-Python.rst +++ b/source/Tutorials/Beginner-Client-Libraries/Using-Parameters-In-A-Class-Python.rst @@ -438,143 +438,17 @@ Further outputs should show ``[INFO] [minimal_param_node]: Hello world!`` every ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Instead of listing parameters and their values in launch file, you can create a separate YAML file that will be loaded in launch file. -First, you will need to add a config directory. -Inside the ``ros2_ws/src/python_parameters/`` directory, create a new directory called ``config``. -In there, create a new file called ``python_parameters_config.yaml``. +Placing parameters in a YAML file makes it easier to organize them, for example, by assigning them to different namespaces. +You can read more about it :ref:`here `. -.. code-block:: yaml - - custom_minimal_param_node: - ros__parameters: - my_parameter: "earth" - -Now, you will have to edit ``python_parameters_launch.py``. -Add the import statements to the top of the file and add a variable containing the path to the configuration file. -Then replace the dictionary containing the parameter name and value with a path to YAML file. - -.. code-block:: Python - - from ament_index_python.packages import get_package_share_directory - # ... - - def generate_launch_description(): - config = os.path.join( - get_package_share_directory("python_parameters"), "config", "python_parameters_config.yaml" - ) - - return LaunchDescription( - [ - Node( - # ... - parameters=[config], - ) - ] - ) - -You have to also modify ``setup.py`` by adding new statement to the ``data_files`` parameter to include all YAML config files: - -.. code-block:: Python - - # ... - - setup( - # ... - data_files=[ - # ... - (os.path.join("share", package_name, "config"), glob("config/*.yaml")), - ] - ) - -Open a console and navigate to the root of your workspace, ``ros2_ws``, and build the package: - -.. tabs:: - - .. group-tab:: Linux - - .. code-block:: console - - colcon build --packages-select python_parameters - - .. group-tab:: macOS - - .. code-block:: console - - colcon build --packages-select python_parameters - - .. group-tab:: Windows - - .. code-block:: console - - colcon build --merge-install --packages-select python_parameters - -Then source the setup files in a new terminal: - -.. tabs:: - - .. group-tab:: Linux - - .. code-block:: console - - source install/setup.bash - - .. group-tab:: macOS - - .. code-block:: console - - . install/setup.bash - - .. group-tab:: Windows - - .. code-block:: console - - call install/setup.bat - -Now run the node using the modified version of launch file: - -.. code-block:: console - - ros2 launch python_parameters python_parameters_launch.py - -The terminal should return the following message the first time: - -.. code-block:: console - - [INFO] [custom_minimal_param_node]: Hello earth! - -Further outputs should show ``[INFO] [minimal_param_node]: Hello world!`` every second. - -Parameter listed in ``python_parameters_config.yaml`` file will be set only for ``custom_minimal_param_node`` node. -If you want to indicate that the parameter ``my_parameter`` should be set on any node in any namespace, then you should use wildcards (``/**``). - -.. code-block:: yaml - - /**: - ros__parameters: - my_parameter: "earth" - -You can also use your parameter under namespace, but it will require some changes in ``python_parameters_node.py`` file. -First, edit config file to look like the one below. - -.. code-block:: yaml - - custom_minimal_param_node: - my_namespace: - ros__parameters: - my_parameter: "earth" - - -While declaring, getting and setting parameter value inside your Python node, you should also add namespace to parameter name and use dot as a separator. -Modify ``python_parameters_node.py`` by changing all occurrences of ``'my_parameter'`` into ``'my_namespace.my_parameter'``. +.. note:: + While declaring, getting and setting parameter value inside your Python node, you should use dot as a separator between parameter's namespace and name. 3.4 Change via passing YAML file as an argument at node startup ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -As a reminder from the :ref:`tutorial about parameters `, you can also load parameter file at node startup. - -.. code-block:: console - - ros2 run python_parameters minimal_param_node --ros-args --params-file ~/ros2_ws/src/python_parameters/config/python_parameters_config.yaml +Return to :ref:`tutorial about parameters ` to remind yourself, how to load parameters file at node startup using CLI. Summary ------- diff --git a/source/Tutorials/Intermediate/Launch/Using-ROS2-Launch-For-Large-Projects.rst b/source/Tutorials/Intermediate/Launch/Using-ROS2-Launch-For-Large-Projects.rst index 8217cb76d74..cfa2d08b035 100644 --- a/source/Tutorials/Intermediate/Launch/Using-ROS2-Launch-For-Large-Projects.rst +++ b/source/Tutorials/Intermediate/Launch/Using-ROS2-Launch-For-Large-Projects.rst @@ -170,6 +170,8 @@ First, create a new file called ``turtlesim_world_1_launch.py``. This launch file starts the ``turtlesim_node`` node, which starts the turtlesim simulation, with simulation configuration parameters that are defined and passed to the nodes. +.. _LoadingParametersFromYAMLFile: + 2.2 Loading parameters from YAML file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~