Skip to content

[jazzy] Pull all example launchfiles into separate file with literalinclude (backport #5155) #5179

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Mar 28, 2025
Merged

[jazzy] Pull all example launchfiles into separate file with literalinclude (backport #5155) #5179

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cdca4af
Pull all example launchfiles into separate file with `literalinclude`…
emersonknapp Mar 26, 2025
41ef1f3
Resolve merge conflicts
emersonknapp Mar 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
289 changes: 9 additions & 280 deletions source/How-To-Guides/Launch-file-different-formats.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Guides/Launch-file-different-formats

Using Python, XML, and YAML for ROS 2 Launch Files
Using XML, YAML, and Python for ROS 2 Launch Files
==================================================

.. contents:: Table of Contents
Expand All @@ -29,290 +29,19 @@ Each launch file performs the following actions:

.. group-tab:: XML

.. code-block:: xml

<!-- example_launch.xml -->

<launch>

<!-- args that can be set from the command line or a default will be used -->
<arg name="background_r" default="0" />
<arg name="background_g" default="255" />
<arg name="background_b" default="0" />
<arg name="chatter_py_ns" default="chatter/py/ns" />
<arg name="chatter_xml_ns" default="chatter/xml/ns" />
<arg name="chatter_yaml_ns" default="chatter/yaml/ns" />

<!-- include another launch file -->
<include file="$(find-pkg-share demo_nodes_cpp)/launch/topics/talker_listener_launch.py" />
<!-- include a Python launch file in the chatter_py_ns namespace-->
<group>
<!-- push_ros_namespace to set namespace of included nodes -->
<push_ros_namespace namespace="$(var chatter_py_ns)" />
<include file="$(find-pkg-share demo_nodes_cpp)/launch/topics/talker_listener_launch.py" />
</group>
<!-- include a xml launch file in the chatter_xml_ns namespace-->
<group>
<!-- push_ros_namespace to set namespace of included nodes -->
<push_ros_namespace namespace="$(var chatter_xml_ns)" />
<include file="$(find-pkg-share demo_nodes_cpp)/launch/topics/talker_listener_launch.xml" />
</group>
<!-- include a yaml launch file in the chatter_yaml_ns namespace-->
<group>
<!-- push_ros_namespace to set namespace of included nodes -->
<push_ros_namespace namespace="$(var chatter_yaml_ns)" />
<include file="$(find-pkg-share demo_nodes_cpp)/launch/topics/talker_listener_launch.yaml" />
</group>

<!-- start a turtlesim_node in the turtlesim1 namespace -->
<node pkg="turtlesim" exec="turtlesim_node" name="sim" namespace="turtlesim1" />
<!-- start another turtlesim_node in the turtlesim2 namespace
and use args to set parameters -->
<node pkg="turtlesim" exec="turtlesim_node" name="sim" namespace="turtlesim2">
<param name="background_r" value="$(var background_r)" />
<param name="background_g" value="$(var background_g)" />
<param name="background_b" value="$(var background_b)" />
</node>
<!-- perform remap so both turtles listen to the same command topic -->
<node pkg="turtlesim" exec="mimic" name="mimic">
<remap from="/input/pose" to="/turtlesim1/turtle1/pose" />
<remap from="/output/cmd_vel" to="/turtlesim2/turtle1/cmd_vel" />
</node>
</launch>
.. literalinclude:: launch/different_formats_launch.xml
:language: xml

.. group-tab:: YAML

.. code-block:: yaml

# example_launch.yaml

launch:

# args that can be set from the command line or a default will be used
- arg:
name: "background_r"
default: "0"
- arg:
name: "background_g"
default: "255"
- arg:
name: "background_b"
default: "0"
- arg:
name: "chatter_py_ns"
default: "chatter/py/ns"
- arg:
name: "chatter_xml_ns"
default: "chatter/xml/ns"
- arg:
name: "chatter_yaml_ns"
default: "chatter/yaml/ns"


# include another launch file
- include:
file: "$(find-pkg-share demo_nodes_cpp)/launch/topics/talker_listener_launch.py"

# include a Python launch file in the chatter_py_ns namespace
- group:
- push_ros_namespace:
namespace: "$(var chatter_py_ns)"
- include:
file: "$(find-pkg-share demo_nodes_cpp)/launch/topics/talker_listener_launch.py"

# include a xml launch file in the chatter_xml_ns namespace
- group:
- push_ros_namespace:
namespace: "$(var chatter_xml_ns)"
- include:
file: "$(find-pkg-share demo_nodes_cpp)/launch/topics/talker_listener_launch.xml"

# include a yaml launch file in the chatter_yaml_ns namespace
- group:
- push_ros_namespace:
namespace: "$(var chatter_yaml_ns)"
- include:
file: "$(find-pkg-share demo_nodes_cpp)/launch/topics/talker_listener_launch.yaml"

# start a turtlesim_node in the turtlesim1 namespace
- node:
pkg: "turtlesim"
exec: "turtlesim_node"
name: "sim"
namespace: "turtlesim1"

# start another turtlesim_node in the turtlesim2 namespace and use args to set parameters
- node:
pkg: "turtlesim"
exec: "turtlesim_node"
name: "sim"
namespace: "turtlesim2"
param:
-
name: "background_r"
value: "$(var background_r)"
-
name: "background_g"
value: "$(var background_g)"
-
name: "background_b"
value: "$(var background_b)"

# perform remap so both turtles listen to the same command topic
- node:
pkg: "turtlesim"
exec: "mimic"
name: "mimic"
remap:
-
from: "/input/pose"
to: "/turtlesim1/turtle1/pose"
-
from: "/output/cmd_vel"
to: "/turtlesim2/turtle1/cmd_vel"
.. literalinclude:: launch/different_formats_launch.yaml
:language: yaml

.. group-tab:: Python

.. code-block:: python

# example_launch.py

import os

from ament_index_python import get_package_share_directory

from launch import LaunchDescription
from launch.actions import DeclareLaunchArgument
from launch.actions import GroupAction
from launch.actions import IncludeLaunchDescription
from launch.launch_description_sources import PythonLaunchDescriptionSource
from launch.substitutions import LaunchConfiguration
from launch.substitutions import TextSubstitution
from launch_ros.actions import Node
from launch_ros.actions import PushROSNamespace
from launch_xml.launch_description_sources import XMLLaunchDescriptionSource
from launch_yaml.launch_description_sources import YAMLLaunchDescriptionSource


def generate_launch_description():

# args that can be set from the command line or a default will be used
background_r_launch_arg = DeclareLaunchArgument(
"background_r", default_value=TextSubstitution(text="0")
)
background_g_launch_arg = DeclareLaunchArgument(
"background_g", default_value=TextSubstitution(text="255")
)
background_b_launch_arg = DeclareLaunchArgument(
"background_b", default_value=TextSubstitution(text="0")
)
chatter_py_ns_launch_arg = DeclareLaunchArgument(
"chatter_py_ns", default_value=TextSubstitution(text="chatter/py/ns")
)
chatter_xml_ns_launch_arg = DeclareLaunchArgument(
"chatter_xml_ns", default_value=TextSubstitution(text="chatter/xml/ns")
)
chatter_yaml_ns_launch_arg = DeclareLaunchArgument(
"chatter_yaml_ns", default_value=TextSubstitution(text="chatter/yaml/ns")
)

# include another launch file
launch_include = IncludeLaunchDescription(
PythonLaunchDescriptionSource(
os.path.join(
get_package_share_directory('demo_nodes_cpp'),
'launch/topics/talker_listener_launch.py'))
)
# include a Python launch file in the chatter_py_ns namespace
launch_py_include_with_namespace = GroupAction(
actions=[
# push_ros_namespace first to set namespace of included nodes for following actions
PushROSNamespace('chatter_py_ns'),
IncludeLaunchDescription(
PythonLaunchDescriptionSource(
os.path.join(
get_package_share_directory('demo_nodes_cpp'),
'launch/topics/talker_listener_launch.py'))
),
]
)

# include a xml launch file in the chatter_xml_ns namespace
launch_xml_include_with_namespace = GroupAction(
actions=[
# push_ros_namespace first to set namespace of included nodes for following actions
PushROSNamespace('chatter_xml_ns'),
IncludeLaunchDescription(
XMLLaunchDescriptionSource(
os.path.join(
get_package_share_directory('demo_nodes_cpp'),
'launch/topics/talker_listener_launch.xml'))
),
]
)

# include a yaml launch file in the chatter_yaml_ns namespace
launch_yaml_include_with_namespace = GroupAction(
actions=[
# push_ros_namespace first to set namespace of included nodes for following actions
PushROSNamespace('chatter_yaml_ns'),
IncludeLaunchDescription(
YAMLLaunchDescriptionSource(
os.path.join(
get_package_share_directory('demo_nodes_cpp'),
'launch/topics/talker_listener_launch.yaml'))
),
]
)

# start a turtlesim_node in the turtlesim1 namespace
turtlesim_node = Node(
package='turtlesim',
namespace='turtlesim1',
executable='turtlesim_node',
name='sim'
)

# start another turtlesim_node in the turtlesim2 namespace
# and use args to set parameters
turtlesim_node_with_parameters = Node(
package='turtlesim',
namespace='turtlesim2',
executable='turtlesim_node',
name='sim',
parameters=[{
"background_r": LaunchConfiguration('background_r'),
"background_g": LaunchConfiguration('background_g'),
"background_b": LaunchConfiguration('background_b'),
}]
)

# perform remap so both turtles listen to the same command topic
forward_turtlesim_commands_to_second_turtlesim_node = Node(
package='turtlesim',
executable='mimic',
name='mimic',
remappings=[
('/input/pose', '/turtlesim1/turtle1/pose'),
('/output/cmd_vel', '/turtlesim2/turtle1/cmd_vel'),
]
)

return LaunchDescription([
background_r_launch_arg,
background_g_launch_arg,
background_b_launch_arg,
chatter_py_ns_launch_arg,
chatter_xml_ns_launch_arg,
chatter_yaml_ns_launch_arg,
launch_include,
launch_py_include_with_namespace,
launch_xml_include_with_namespace,
launch_yaml_include_with_namespace,
turtlesim_node,
turtlesim_node_with_parameters,
forward_turtlesim_commands_to_second_turtlesim_node,
])
.. literalinclude:: launch/different_formats_launch.py
:language: python


Using the Launch files from the command line
--------------------------------------------
Expand Down Expand Up @@ -361,7 +90,7 @@ To test that the remapping is working, you can control the turtles by running th

.. _launch-file-different-formats-which:

Python, XML, or YAML: Which should I use?
XML, YAML, or Python: Which should I use?
-----------------------------------------

.. note::
Expand Down
Loading