= Parameter configuration
Managing Node parameters in ROS 2 can be a daunting task, whether you're configuring a single robot or orchestrating a fleet. Parameter Configuration steps in to streamline this process, helping to avoid parameter duplication and easing the process of setting parameters by providing two main features: YAML placeholders and YAML file overlaying.
=== YAML placeholders YAML files natively lack support for placeholders, making dynamic parameter setting difficult. Parameter Configuration introduces "tags" that enable runtime evaluation of placeholders.
image::images/yaml_placeholders.drawio.png[Task and Mission setup used in Nav2 examples, width=600, align=center]
Available tags:
// Raw //// ros_node: ros__parameters: robot_base_frame: base_link scan_topic: /scan map_file: !eval join(env.HOME, "maps") bt_path: !eval path_to("behavior_trees_pkg") + "/bt/nav_to_pose.xml" robot_radius: !eval 0.6 / 2 ////
// Result //// ros_node: ros__parameters: robot_base_frame: base_link scan_topic: /scan map_file: /home/user/maps bt_path: /ros2_ws/src/behavior_trees_pkg/bt/nav_to_pose.xml" robot_radius: 0.3 ////
=== YAML file overlaying YAML overlaying allows to set parameter overrides per device and robot model. This will greatly reduce the parameter duplication, since only the overridden parameters need to be defined.
image::images/yaml_overlaying.drawio.png[Task and Mission setup used in Nav2 examples, width=600, align=center]
The overlaying will automatically look for parameter files across three different levels:
For example, any parameter that is set in Device level configuration, will override Model level and ROS Package level configurations. Overlaying files need to have !overlay tag in the beginning of the file, otherwise it won't be overlaid with a level below. Check out the tutorials in link:examples[examples] folder.
This level structure is also extendable, so that you can have your custom configuration for the overlaying levels.
== Setup [[setup]]
For YAML overlaying feature, the Device and Model layer parameters are automatically fetched from a preconfigured folder. To use the overlaying, follow these steps:
. Create a new config directory and device and model folders under it. Add your overlaying parameter files under ROS package folders. Names of the parameter files need to match the ROS package parameter file. Structure of the directory should be the following: + image::images/config_dir_structure.png[Task and Mission setup used in Nav2 examples, width=250, align=center]
. Set PARAM_CONFIG_DIR env variable to point to the folder from which the overlaying fetches the parameters. For example:
////
== Usage in launch files
To use these YAML files in ROS 2 launch files, get the configuration file in the following way with absolute path or with overlay syntax:
from param_configuration.configuration import get_resolved_yaml
# Absolute path
resolved_yaml = get_resolved_yaml("/home/user/config.yaml")
# Overlay syntax
resolved_yaml_2 = get_resolved_yaml("config://nav2_bringup/nav2_params.yaml")The overlay syntax is built as follows:
config:// tells parameter configuration to use the overlay files to resolve the configurationnav2_bringup tells the configuration to also use the ROS Package layer. If not set, uses only the Model and Device parameters.nav2_params.yaml is the name of the parameter file and is expected to be found in nav2_bringup ROS package. If a parameter files with a same name exist in device and/or model folders, we will use them to override the ROS-level parameters.NOTE:: The parameter files are expected to be in params folder within the ROS package, unlike within the device or model folders!
config. Validate a single configuration file by printing the evaluated version of it.
[source]If --config-directory is not given, uses the default PARAM_CONFIG_DIR directory.
More information with the command config --help
== Requirements
The package requires Python dependencies in the requirements.txt to be installed. Install them easily with
pip3 install -r requirements.txt== Examples and tutorials
Examples and tutorials can be found in link:examples[examples] folder.
== Supported Eval -commands [cols="1,1,1"] |=== |Command | Python function |Description
|!eval env.
|!eval m.
|!eval np.
|!eval round() |round() |Rounds to given decimals
|!eval path_to() |get_package_share_directory() |Path to ROS package share directory
|!eval join() |os.path.join() |Join two or more paths
|!eval get_resolved_yaml() |param_configuration.configuration.get_resolved_yaml |Resolves the given YAML file and returns a path to it.
|!eval to_string() |str() |Converts the given value to a string. Handy when using nested evaluations.
| !eval var. |
|---|
| Allows using variables which are defined in the beginning of the same file, under ".variables" -key. This key will be removed from the result file. |
| === |
== Disclaimer This package is under active development and changes. The usage and API may change rapidly and is not tied to ROS 2 release cycles, which is why we suggest to clone the stable release tag of this repository to avoid unintentional system breakdowns.
If you have feature requests or find any bugs or usability issues, please open a new issue with a low barrier. We are looking to solve them quickly.
== Known limitations
== Open questions Since the package is still in an experimental phase, there are still many open questions. For example:
== Acknowledgements
Current active maintainers:
https://www.linkedin.com/in/martmoerdijk/[Mart Moerdijk], Karelics Oy - Main author
https://www.linkedin.com/in/janne-karttunen-a22375209/[Janne Karttunen] - Secondary author
The initial version of the Parameter Configuration was developed at https://karelics.fi/[Karelics Oy]. This project came to life through the efforts of the following individuals, who contributed to its design, implementation, testing, reviewing and maintenance: https://www.linkedin.com/in/martmoerdijk/[Mart Moerdijk], https://www.linkedin.com/in/janne-karttunen-a22375209/[Janne Karttunen], https://www.linkedin.com/in/joni-p%C3%B6ll%C3%A4nen-a05378139/[Joni Pöllänen], https://www.linkedin.com/in/taneli-korhonen-669100177/[Taneli Korhonen], https://www.linkedin.com/in/lowellausen/[Leonardo Wellausen], and https://www.linkedin.com/in/pekka-myller-68a7301b9/[Pekka Myller].