Streamline Python launchfiles to promote best practices (ros2#5413)

Signed-off-by: Emerson Knapp <[email protected]>

Author: emersonknapp

source/How-To-Guides/launch/different_formats_launch.py

@@ -1,96 +1,84 @@
-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.actions import DeclareLaunchArgument, GroupAction, IncludeLaunchDescription
+from launch.substitutions import LaunchConfiguration, PathJoinSubstitution
+from launch_ros.actions import Node, PushROSNamespace
+from launch_ros.substitutions import FindPackageShare
 
 
 def generate_launch_description():
+    launch_dir = PathJoinSubstitution([FindPackageShare('demo_nodes_cpp'), 'launch', 'topics'])
+    return LaunchDescription([
+        # args that can be set from the command line or a default will be used
+        DeclareLaunchArgument('background_r', default_value='0'),
+        DeclareLaunchArgument('background_g', default_value='255'),
+        DeclareLaunchArgument('background_b', default_value='0'),
+        DeclareLaunchArgument('chatter_ns', default_value='my/chatter/ns'),
 
-    # 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_ns_launch_arg = DeclareLaunchArgument(
-        'chatter_ns', default_value=TextSubstitution(text='my/chatter/ns')
-    )
+        # include another launch file
+        IncludeLaunchDescription(
+            PathJoinSubstitution([launch_dir, 'talker_listener.launch.py'])
+        ),
 
-    # 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 another launch file in the chatter_ns namespace
-    launch_include_with_namespace = GroupAction(
-        actions=[
-            # push_ros_namespace to set namespace of included nodes
-            PushRosNamespace('chatter_ns'),
-            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
+        GroupAction(
+            actions=[
+                # push_ros_namespace first to set namespace of included nodes for following actions
+                PushROSNamespace(LaunchConfiguration('chatter_ns')),
+                IncludeLaunchDescription(
+                    PathJoinSubstitution([launch_dir, 'talker_listener_launch.py'])),
+            ]
+        ),
 
-    # start a turtlesim_node in the turtlesim1 namespace
-    turtlesim_node = Node(
-        package='turtlesim',
-        namespace='turtlesim1',
-        executable='turtlesim_node',
-        name='sim'
-    )
+        # include a xml launch file in the chatter_xml_ns namespace
+        GroupAction(
+            actions=[
+                # push_ros_namespace first to set namespace of included nodes for following actions
+                PushROSNamespace('chatter_xml_ns'),
+                IncludeLaunchDescription(
+                    PathJoinSubstitution([launch_dir, 'talker_listener_launch.xml'])),
+            ]
+        ),
 
-    # 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'),
-        }]
-    )
+        # include a yaml launch file in the chatter_yaml_ns namespace
+        GroupAction(
+            actions=[
+                # push_ros_namespace first to set namespace of included nodes for following actions
+                PushROSNamespace('chatter_yaml_ns'),
+                IncludeLaunchDescription(
+                    PathJoinSubstitution([launch_dir, 'talker_listener_launch.yaml'])),
+            ]
+        ),
 
-    # 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'),
-        ]
-    )
+        # start a turtlesim_node in the turtlesim1 namespace
+        Node(
+            package='turtlesim',
+            namespace='turtlesim1',
+            executable='turtlesim_node',
+            name='sim'
+        ),
 
-    return LaunchDescription([
-        background_r_launch_arg,
-        background_g_launch_arg,
-        background_b_launch_arg,
-        chatter_ns_launch_arg,
-        launch_include,
-        launch_include_with_namespace,
-        turtlesim_node,
-        turtlesim_node_with_parameters,
-        forward_turtlesim_commands_to_second_turtlesim_node,
+        # start another turtlesim_node in the turtlesim2 namespace
+        # and use args to set 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
+        Node(
+            package='turtlesim',
+            executable='mimic',
+            name='mimic',
+            remappings=[
+                ('/input/pose', '/turtlesim1/turtle1/pose'),
+                ('/output/cmd_vel', '/turtlesim2/turtle1/cmd_vel'),
+            ]
+        ),
     ])

source/Tutorials/Intermediate/Launch/Using-ROS2-Launch-For-Large-Projects.rst

@@ -125,7 +125,7 @@ Now let's create a new ``turtlesim_world_3_launch.py`` file similar to ``turtles
 
 .. literalinclude:: launch/turtlesim_world_3_launch.py
    :language: python
-   :emphasize-lines: 19
+   :emphasize-lines: 12
 
 Loading the same YAML file, however, will not affect the appearance of the third turtlesim world.
 The reason is that its parameters are stored under another namespace as shown below:
@@ -167,29 +167,25 @@ However, if the launch file contains a large number of nodes, defining namespace
 To solve that issue, the ``PushRosNamespace`` action can be used to define the global namespace for each launch file description.
 Every nested node will inherit that namespace automatically.
 
-To do that, firstly, we need to remove the ``namespace='turtlesim2'`` line from the ``turtlesim_world_2.launch.py`` file.
-Afterwards, we need to update the ``launch_turtlesim.launch.py`` to include the following lines:
+.. attention:: ``PushROSNamespace`` has to be the first action in the list for the following actions to apply the namespace.
+
+To do that, firstly, we need to remove the ``namespace='turtlesim2'`` line from the ``turtlesim_world_2_launch.py`` file.
+Afterwards, we need to update the ``launch_turtlesim_launch.py`` to change the ``IncludeLaunchDescription(... 'turtlesim_world_2_launch.py' ...)`` value to the following:
 
 .. code-block:: Python
 
    from launch.actions import GroupAction
    from launch_ros.actions import PushRosNamespace
 
       ...
-      turtlesim_world_2 = IncludeLaunchDescription(
-         PythonLaunchDescriptionSource([os.path.join(
-            get_package_share_directory('launch_tutorial'), 'launch'),
-            '/turtlesim_world_2.launch.py'])
-         )
-      turtlesim_world_2_with_namespace = GroupAction(
+      GroupAction(
         actions=[
-            PushRosNamespace('turtlesim2'),
-            turtlesim_world_2,
+            PushROSNamespace('turtlesim2'),
+            IncludeLaunchDescription(PathJoinSubstitution([launch_dir, 'turtlesim_world_2.launch.py'])),
          ]
-      )
+      ),
 
-Finally, we replace the ``turtlesim_world_2`` to ``turtlesim_world_2_with_namespace`` in the ``return LaunchDescription`` statement.
-As a result, each node in the ``turtlesim_world_2.launch.py`` launch description will have a ``turtlesim2`` namespace.
+As a result, each node in the ``turtlesim_world_2_launch.py`` launch description will have a ``turtlesim2`` namespace.
 
 4 Reusing nodes
 ^^^^^^^^^^^^^^^
@@ -215,7 +211,7 @@ In addition to that, we have passed it ``target_frame`` launch argument as shown
 
 .. literalinclude:: launch/launch_turtlesim_launch.py
    :language: python
-   :lines: 21-26
+   :lines: 16-19
 
 This syntax allows us to change the default goal target frame to ``carrot1``.
 If you would like ``turtle2`` to follow ``turtle1`` instead of the ``carrot1``, just remove the line that defines ``launch_arguments``.

source/Tutorials/Intermediate/Launch/Using-Substitutions.rst

@@ -185,14 +185,13 @@ To do this, create following file in the ``launch`` folder of the ``launch_tutor
 
     .. literalinclude:: launch/example_main_launch.py
       :language: python
-      :lines: 16-20
+      :lines: 14-18
 
     The ``launch_arguments`` dictionary with ``turtlesim_ns`` and ``use_provided_red`` arguments is passed to the ``IncludeLaunchDescription`` action.
-    The ``TextSubstitution`` substitution is used to define the ``new_background_r`` argument with the value of the ``background_r`` key in the ``colors`` dictionary.
 
     .. literalinclude:: launch/example_main_launch.py
       :language: python
-      :lines: 22-26
+      :lines: 19-23
 
 
 3 Substitutions example launch file
@@ -290,37 +289,36 @@ Now create the substitution launch file in the same folder:
       :language: python
 
     The ``turtlesim_ns``, ``use_provided_red``, and ``new_background_r`` launch configurations are defined.
-    They are used to store values of launch arguments in the above variables and to pass them to required actions.
+    They are used to represent values of launch arguments in the above variables and to pass them to required actions.
     These ``LaunchConfiguration`` substitutions allow us to acquire the value of the launch argument in any part of the launch description.
 
     ``DeclareLaunchArgument`` is used to define the launch argument that can be passed from the above launch file or from the console.
 
     .. literalinclude:: launch/example_substitutions_launch.py
       :language: python
-      :lines: 13-24
+      :lines: 14-25
 
     The ``turtlesim_node`` node with the ``namespace`` set to ``turtlesim_ns`` ``LaunchConfiguration`` substitution is defined.
 
     .. literalinclude:: launch/example_substitutions_launch.py
       :language: python
       :lines: 26-31
 
-    Afterwards, the ``ExecuteProcess`` action called ``spawn_turtle`` is defined with the corresponding ``cmd`` argument.
-    This command makes a call to the spawn service of the turtlesim node.
+    The next action, ``ExecuteProcess``,  is defined with the corresponding ``cmd`` argument to call the spawn service of the turtlesim node.
 
-    Additionally, the ``LaunchConfiguration`` substitution is used to get the value of the ``turtlesim_ns`` launch argument to construct a command string.
+    Additionally, the ``LaunchConfiguration`` substitution is used to provide the value of the ``turtlesim_ns`` launch argument in the command string.
 
     .. literalinclude:: launch/example_substitutions_launch.py
       :language: python
       :lines: 32-41
 
     The same approach is used for the ``change_background_r`` and ``change_background_r_conditioned`` actions that change the turtlesim background's red color parameter.
-    The difference is that the ``change_background_r_conditioned`` action is only executed if the provided ``new_background_r`` argument equals ``200`` and the ``use_provided_red`` launch argument is set to ``True``.
+    The difference is that the next action is only executed if the provided ``new_background_r`` argument equals ``200`` and the ``use_provided_red`` launch argument is set to ``True``.
     The evaluation inside the ``IfCondition`` is done using the ``PythonExpression`` substitution.
 
     .. literalinclude:: launch/example_substitutions_launch.py
       :language: python
-      :lines: 42-67
+      :lines: 51-72
 
 4 Build the package
 ^^^^^^^^^^^^^^^^^^^

source/Tutorials/Intermediate/Launch/launch/example_main_launch.py

@@ -1,7 +1,6 @@
 from launch import LaunchDescription
 from launch.actions import IncludeLaunchDescription
-from launch.launch_description_sources import PythonLaunchDescriptionSource
-from launch.substitutions import PathJoinSubstitution, TextSubstitution
+from launch.substitutions import PathJoinSubstitution
 from launch_ros.substitutions import FindPackageShare
 
 
@@ -12,17 +11,15 @@ def generate_launch_description():
 
     return LaunchDescription([
         IncludeLaunchDescription(
-            PythonLaunchDescriptionSource([
-                PathJoinSubstitution([
-                    FindPackageShare('launch_tutorial'),
-                    'launch',
-                    'example_substitutions.launch.py'
-                ])
+            PathJoinSubstitution([
+                FindPackageShare('launch_tutorial'),
+                'launch',
+                'example_substitutions_launch.py'
             ]),
             launch_arguments={
                 'turtlesim_ns': 'turtlesim2',
                 'use_provided_red': 'True',
-                'new_background_r': TextSubstitution(text=str(colors['background_r']))
+                'new_background_r': colors['background_r'],
             }.items()
         )
     ])