Feature: Combined Parameter Substitution

[DLu]

Description

I am proposing a new launch_ros.Substitution that takes multiple yaml paths as a parameter, and returns one unified (temporary) yaml path as the result.

Motivation

YAML files are getting mighty unwieldy these days. Check out all 600 lines of this navigation config. It is easy enough to load multiple parameter files into a Node when you are writing the launch file directly, i.e.

    Node(...
        parameters=[yaml_path1, yaml_path2],
    )

However, there are scenarios where you might want to load those yaml files into one single LaunchConfiguration. Consider nav2_bringup / navigation_launch.py. The above navigation configuration is declared as a launch argument

declare_params_file_cmd = DeclareLaunchArgument(
        'params_file',
        default_value=os.path.join(bringup_dir, 'params', 'nav2_params.yaml'),
        description='Full path to the ROS2 parameters file to use for all launched nodes',
    )

and then passed to multiple nodes (after some processing).

I want to be able to specify multiple yaml files to replace the single nav2_params.yaml WITHOUT having to rewrite the entire launch file.

Design / Implementation Considerations

One option is to just copy/paste the launch file and rewrite the parameters as needed, which is valid, and many people have done just that.

I have implemented a proof-of-concept approach (that I call MultiYaml) wherein multiple yaml files are passed in, and a new temporary yaml file is returned as the result of the substitution. The contents of the new temporary yaml file are merged into one large dictionary.

nav2_common / RewrittenYaml and nav2_common / ReplaceString already read a yaml file and write a temporary yaml file as a result. #258 exists to port that behavior to launch_ros.

I see three potential paths forward.

• Implement MultiYaml, RewrittenYaml and ReplaceString as independent substitutions.
• Implement all three with some common inherited infrastructure for "Substitutions that write to a temporary yaml file"
• Implement a CombinedConfiguration substitution that writes to a temporary yaml but operates in a more extensible way, i.e.
  • Starts with a single base yaml path
  • Takes a list of "Yaml Operations" in as a parameter that could include
    • Combine with another yaml (for MultiYaml)
    • Perform a string replacement (for ReplaceString natch)
    • Perform param, key, value rewrites (for RewrittenYaml)
    • Change the root key (for RewrittenYaml)
  • Returns the resulting dictionary as a temporary yaml path

I am open to discussion of the proper level of over-engineering for this problem. For reference, here is my initial unpolished MultiYaml implementation.

from launch import Substitution, LaunchContext, SomeSubstitutionsType
from launch.utilities import normalize_to_list_of_substitutions, perform_substitutions

from collections.abc import Mapping
import tempfile
from typing import List, Text
import yaml


def recursive_update(d, u):
    for k, v in u.items():
        if isinstance(v, Mapping):
            d[k] = recursive_update(d.get(k, {}), v)
        else:
            d[k] = v
    return d


class MultiYaml(Substitution):
    def __init__(
        self,
        source_files: List[SomeSubstitutionsType],
    ) -> None:
        super().__init__()

        self.__source_files = source_files

    def perform(self, context: LaunchContext) -> Text:
        output_file = tempfile.NamedTemporaryFile(mode='w', delete=False)

        d = {}

        for raw_source_file in self.__source_files:
            source_list = normalize_to_list_of_substitutions(raw_source_file)
            source_file = perform_substitutions(context, source_list)

            new_d = yaml.safe_load(open(source_file))
            recursive_update(d, new_d)

        yaml.dump(d, output_file)

        return output_file.name

and its usage

    navigation_launch = IncludeLaunchDescription(
        PathJoinSubstitution([nav_config_path, 'launch', 'nav_core.launch.py']),
        launch_arguments={
            'params_file': MultiYaml([
                PathJoinSubstitution([nav_config_path, 'config', 'nav2_params_core.yaml']),
                PathJoinSubstitution([nav_config_path, 'config', 'nav2_params_mppi.yaml']),
            ]),
        }.items(),
    )

Other approach: I briefly considered trying to return an array of yaml files from a substitution but that would have required more work from the evaluate_parameters code to theoretically get to work.

Additional Information

I'd wager @SteveMacenski has feelings on this, and maybe @adamsj-ros @leander-dsouza

[mjcarroll]

Thanks for proposing! I'm sure that @SteveMacenski has some good thoughts on this, but here is some early feedback.

I would lean towards approach 1, this feels like the more "ROS" approach that fits in with launch as it already exists. The config pipeline approach seems more or less what launch is already intended to do. Distinct substitutions that can be composed make the most sense to me.

As for the proof of concept, we should make sure that the YAML merging matches what we do in other places, just so it isn't surprising. You may have already done this check, if so, great!

We should probably also pay attention to those temporary files and make sure that we clean them up eventually at the end of execution.

[SteveMacenski]

I do not have strong thoughts really.

One option is to just copy/paste the launch file and rewrite the parameters as needed, which is valid, and many people have done just that.

Users should be creating their own navigation configuration / launch packages and add/remove servers or parameter default values as they see fit for their applications. I actually tell people that they should create their own myrobot_navigation package based on nav2_bringup, so I think this is fully expected.

I don't see anything wrong here TBH but if people were rewriting them to allow for multiple parameter files, I 100% agree. I sampled a few but maybe that is a common modification that I just missed.

Implement MultiYaml, RewrittenYaml and ReplaceString

Anything you guys want to absorb into main launch-ros from nav2_common is A-OK by me. Just let me know when I can delete it from my repo 😆

---

What's wrong with simply having the launch configuration for params_file be params_files and provide an array of configuration files for sending over to the nodes? The Nav2 common substitutions would need o be updated to support multiple files rather than 1, but those are small updates.

[DLu]

As for the proof of concept, we should make sure that the YAML merging matches what we do in other places, just so it isn't surprising. You may have already done this check, if so, great!

My mind is blanking - can you give me an example of the other places, please?

What's wrong with simply having the launch configuration for params_file be params_files and provide an array of configuration files for sending over to the nodes? The Nav2 common substitutions would need o be updated to support multiple files rather than 1, but those are small updates.

I mentioned the array approach in my other approach, but didn't get a successful prototype initially. However, that may have also been with the base assumption of not changing the base nav launch files.

[SteveMacenski]

However, that may have also been with the base assumption of not changing the base nav launch files.

I'm open to it. Points if we can support both singular and multiple files from a single input, but I doubt that's actually wise.

We could either update params_files to be the new and only way to interact with it, or we have both params_file and params_files and we simply use both.

[DLu]

To get the ball rolling, see #518

[DLu]

I think passing an array of config files as a launch file will be straightforward.

I'm basing my example code here on the donatello package from rosetta_launch. Here is my test launch:

from launch import LaunchDescription
from launch.actions import DeclareLaunchArgument
from launch.substitutions import LaunchConfiguration
from launch.substitutions import PathJoinSubstitution
from launch_ros.substitutions import FindPackageShare
from launch_ros.actions import Node


def generate_launch_description():
    pkg = FindPackageShare('donatello')
    return LaunchDescription([
        DeclareLaunchArgument('params_files',
            default_value=[PathJoinSubstitution([pkg, 'config', 'params.yaml']),
                           PathJoinSubstitution([pkg, 'config', 'params2.yaml']),
            ]
        ),
        Node(name='does_machines',
             package='donatello',
             executable='donatello_node',
             parameters=[LaunchConfiguration('params_files')]),
    ])

List is a valid return type for a launch argument. However, the list is then wrapped as a ParameterFile in normalize_parameters, and the result is that the paths are concatenated together.

[WARNING] [launch_ros.actions.node]: Parameter file path is not a file: /path/to/ros2_ws/install/donatello/share/donatello/config/params.yaml/path/to/ros2_ws/install/donatello/share/donatello/config/params2.yaml

This makes sense, because lists are normally concatenated together, e.g.

from launch import LaunchDescription
from launch.actions import DeclareLaunchArgument
from launch.substitutions import LaunchConfiguration
from launch_ros.substitutions import FindPackageShare
from launch_ros.actions import Node


def generate_launch_description():
    pkg = FindPackageShare('donatello')
    return LaunchDescription([
        DeclareLaunchArgument('params_file',
            default_value=[FindPackageShare('donatello'), '/config', '/params.yaml']
        ),
        Node(name='does_machines',
             package='donatello',
             executable='donatello_node',
             parameters=[LaunchConfiguration('params_file')]),
    ])

The above approach should use PathJoinSubstitution instead, but this illustrates the point.

To get this to work, I think you would have to declare a new type in parameter_descriptions.py to handle merged parameter files, but that would result in having to change the typing in a number of places, and then the logic for expanding the parameters would need to be updated to pass multiple paths to the command line.

[ros-discourse]

This issue has been mentioned on Open Robotics Discourse. There might be relevant details there:

https://discourse.openrobotics.org/t/ros-news-for-the-week-of-february-23rd-2026/52787/1

[peci1]

In general this looks good to me. I'd vote for the option where yamls can be merged via a substitution as originally proposed. That wouldn't require any downstream changes and it would give everyone the freedom to split their configs as they wish.

The only problem I have with this approach is that it is always difficult to view the temporary merged files. It would be great if there were e.g. an env var that would disable deletion of these files.

Regarding the note that the merge behavior should be consistent with other places, I guess one example is loading several yamls sequentially via <param> tags in launch.

Last, similar to #518 , why does this target launch_ros and not launch?