Relates #499

Being able to repeat entities (e.g., nodes) N times based on the value of a launch argument is a pretty commonly-requested feature. Example: #499 and https://discourse.ros.org/t/poll-interest-in-ros2-launch-action-to-support-for-loops-e-g-includenlaunchdescriptions/20026. Some current solutions/workarounds include:

1. OpaqueFunction: Launch Loop Support? [Feature Request] #499 (comment)
2. Recursion: https://github.com/MetroRobots/rosetta_launch#12---recursion

While these work, they involve some boilerplate code that has to be repeated in each launch file, and they make launch files more complex.

This PR aims to simplify this by adding a new ForEach action. It takes in sets of input values provided as a semicolon-separated list of string YAML structures, which can be a launch argument (LaunchConfiguration) or any other substitution. It also takes in a function that gets called with each set of input values. This function should return a list of entities using the input values to differentiate entities between each for-loop iteration.

This is basically a nicer alternative to using an OpaqueFunction directly in Python, and supports frontends, which OpaqueFunction doesn't/can't.

Example:

import launch


def for_each(id: int, name: str):
    return [
        launch.actions.LogInfo(msg=f"'{name}' id={id}"),
    ]


def generate_launch_description():
    return launch.LaunchDescription([
        launch.actions.DeclareLaunchArgument(
            'robots', default_value="{name: 'robotA', id: 1};{name: 'robotB', id: 2}"),
        launch.actions.ForEach(launch.substitutions.LaunchConfiguration('robots'), function=for_each),
    ])

Frontends are also supported, which isn't possible with OpaqueFunction. In this case, the callback function is created internally by the parser using the child entities. In the launch file, entities can use a $(for-var) substitution referencing a variable name:

<launch>
    <arg name="robots" default="{name: 'robotA', id: 1};{name: 'robotB', id: 2}" />
    <for_each values="$(var robots)" >
        <log message="'$(for-var name)' id=$(for-var id)" />
    </for_each>
</launch>

launch:
    - arg:
        name: robots
        default: "{name: 'robotA', id: 1};{name: 'robotB', id: 2}"
    - for_each:
        values: $(var robots)
        children:
            - log:
                message: "'$(for-var name)' id=$(for-var id)"

If any of these launch files were launched without any launch arguments, they would output the following log messages:

[INFO] [launch.user]: 'robotA' id=1
[INFO] [launch.user]: 'robotB' id=2

With robots:="{name: 'robotC', id: 3};{name: 'robotD', id: 4};{name: 'robotE', id: 5}", they would output:

[INFO] [launch.user]: 'robotC' id=3
[INFO] [launch.user]: 'robotD' id=4
[INFO] [launch.user]: 'robotE' id=5

In Python, default values can be defined through default values of callback function parameters, in which case they may be omitted from a set of values in the YAML string. For frontends, a default value can be provided to the $(for-var) substitution, e.g., $(for-var name 'default').

There's also a ForLoop action, which is a simpler version of ForEach with just an index value. It takes in something that defines the number of for-loop iterations and a function that gets called with each for-loop index value (0 to N, exclusive). For frontends, the callback function is created internally by the parser using the child entities and an $(index) substitution referencing the (index) name of the for-loop:

Examples:

import launch
import launch_ros


def for_i(i: int):
    return [
        launch_ros.actions.Node(
            package='test_tracetools',
            executable='test_ping',
            output='screen',
            namespace=['/pingpong_', str(i)],
        ),
        launch_ros.actions.Node(
            package='test_tracetools',
            executable='test_pong',
            output='screen',
            namespace=['/pingpong_', str(i)],
        ),
    ]


def generate_launch_description():
    return launch.LaunchDescription([
        launch.actions.DeclareLaunchArgument('num_robots', default_value='2'),
        launch.actions.ForLoop(launch.substitutions.LaunchConfiguration('num_robots'), function=for_i),
    ])

<launch>
    <arg name="num_robots" default="2" />
    <for len="$(var num_robots)" name="i" >
        <node pkg="test_tracetools" exec="test_ping" namespace="/pingpong_$(index i)" output="screen" />
        <node pkg="test_tracetools" exec="test_pong" namespace="/pingpong_$(index i)" output="screen" />
    </for>
</launch>

launch:
    - arg:
        name: num_robots
        default: '2'
    - for:
        len: $(var num_robots)
        name: i
        children:
            - node:
                pkg: test_tracetools
                exec: test_ping
                namespace: /pingpong_$(index i)
                output: screen
            - node:
                pkg: test_tracetools
                exec: test_pong
                namespace: /pingpong_$(index i)
                output: screen

If any of these launch files were launched without any launch arguments, they would create 2 pairs of ping & pong nodes, each pair in its own namespace. With num_robots:=5, they would create 5 pairs.

Bonus: you can even nest <for> loops:

<launch>
    <arg name="num_i" default="2" />
    <arg name="num_j" default="3" />
    <for len="$(var num_i)" name="i" >
        <for len="$(var num_j)" name="j" >
            <log message="i=$(index i), j=$(index j)" />
        </for>
    </for>
</launch>

[INFO] [launch.user]: i=0, j=0
[INFO] [launch.user]: i=0, j=1
[INFO] [launch.user]: i=0, j=2
[INFO] [launch.user]: i=1, j=0
[INFO] [launch.user]: i=1, j=1
[INFO] [launch.user]: i=1, j=2

Open questions:

1. Is this worth having in launch? I think so given that this is a common feature request (and undoubtedly a common Google search), but I'm open to other opinions.
   • We discussed this PR at a high level in the November 12th, 2024, ROS PMC meeting. In short, this is pushing us towards less declarative launch files, which makes writing potential linters/checkers harder. However, it was still possible to do this before using OpaqueFunction (only in Python), so this reduces boilerplate code, and it allows us to use this functionality from the XML & YAML frontends. Therefore, pragmatically, it was deemed to be acceptable.
2. For frontends, is there another mechanism (other than locals) for defining and using the index variable in each loop iteration?
   • I don't think so. And adding a suffix to the local name (see ForEachVar.get_local_arg_name()) makes it pretty robust.
3. Anything else? Any limitations or anything that would break this?

Also, once it looks good enough, I'd like to post on Discourse to request feedback from users. I posted here: https://discourse.ros.org/t/requesting-feedback-new-for-loop-action-for-ros-2-launch-files-to-repeat-entities/42021