= 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:

* *Eval*: Evaluates commands in runtime, supporting file-level variables, environment variables, math expressions, ROS package paths, and more.
* *From*: Retrieves values from other YAML files.
* *Include*: Fully includes another configuration file
* *Merge*: Merges multiple key-value pairs to be under a single key

// 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:

* Device level
* Model level
* ROS Package level

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:

[source]
----
export PARAM_CONFIG_DIR=/home/user/config_dir
----

// This is used to generate the image for folder structure. GitHub doesn't support this format directly.
////
[plantuml, format=svg, opts="inline"]
----
skinparam Legend {
	BackgroundColor transparent
	BorderColor transparent
	FontName "Noto Serif", "DejaVu Serif", serif
	FontSize 17
}
legend
config_dir
|_ model
  |_ <ros-pkg-name>
    |_ <param_file_1>.yaml
    |_ <param_file_2>.yaml
    |_ ...
|_ device
  |_ <ros-pkg-name>
    |_ <param_file_1>.yaml
    |_ ...
end legend
----
////

== 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: