ros2-launch-system

Purpose: Generate accurate, educational ROS 2 Python launch files and multi-node configurations following official ROS 2 Humble patterns for the Physical AI textbook.

When to Use

• Creating lessons in Chapter 6 (Building Robot Systems)
• Writing multi-node deployment exercises
• Generating worked examples for system startup
• Teaching parameter configuration and node composition
• Chapter 7 capstone project integration

Live Documentation Access

CRITICAL: Before generating any code, fetch current ROS 2 documentation using Context7 MCP:

Tool: mcp__context7__resolve-library-id
libraryName: "ros2 launch"

Then:
Tool: mcp__context7__get-library-docs
context7CompatibleLibraryID: [resolved ID]
topic: "launch file python"

This ensures launch patterns match current ROS 2 Humble API.

Launch File Patterns

Basic Launch File (Canonical)

# File: launch/robot_system.launch.py

from launch import LaunchDescription
from launch_ros.actions import Node

def generate_launch_description():
    return LaunchDescription([
        Node(
            package='my_robot_pkg',
            executable='publisher_node',
            name='sensor_publisher',
            output='screen',
        ),
        Node(
            package='my_robot_pkg',
            executable='subscriber_node',
            name='data_processor',
            output='screen',
        ),
    ])

Launch File with Parameters

from launch import LaunchDescription
from launch_ros.actions import Node

def generate_launch_description():
    return LaunchDescription([
        Node(
            package='my_robot_pkg',
            executable='configurable_node',
            name='robot_controller',
            output='screen',
            parameters=[{
                'robot_name': 'my_robot',
                'update_rate': 10.0,
                'max_speed': 1.5,
                'enabled_sensors': ['lidar', 'camera', 'imu'],
            }],
        ),
    ])

Launch File with Parameter File (YAML)

import os
from ament_index_python.packages import get_package_share_directory
from launch import LaunchDescription
from launch_ros.actions import Node

def generate_launch_description():
    config = os.path.join(
        get_package_share_directory('my_robot_pkg'),
        'config',
        'robot_params.yaml'
    )

    return LaunchDescription([
        Node(
            package='my_robot_pkg',
            executable='robot_node',
            name='robot_controller',
            output='screen',
            parameters=[config],
        ),
    ])

Parameter File (YAML)

# File: config/robot_params.yaml
robot_controller:
  ros__parameters:
    robot_name: "physical_ai_bot"
    update_rate: 20.0
    max_linear_speed: 2.0
    max_angular_speed: 1.57
    sensors:
      lidar:
        enabled: true
        topic: "/scan"
      camera:
        enabled: true
        topic: "/image_raw"

Launch File with Arguments

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

def generate_launch_description():
    # Declare launch arguments
    robot_name_arg = DeclareLaunchArgument(
        'robot_name',
        default_value='default_robot',
        description='Name of the robot'
    )

    sim_mode_arg = DeclareLaunchArgument(
        'sim_mode',
        default_value='true',
        description='Run in simulation mode'
    )

    return LaunchDescription([
        robot_name_arg,
        sim_mode_arg,
        Node(
            package='my_robot_pkg',
            executable='robot_node',
            name='robot_controller',
            output='screen',
            parameters=[{
                'robot_name': LaunchConfiguration('robot_name'),
                'simulation': LaunchConfiguration('sim_mode'),
            }],
        ),
    ])

Package Structure for Launch Files

my_robot_pkg/
├── my_robot_pkg/
│   ├── __init__.py
│   ├── publisher_node.py
│   └── subscriber_node.py
├── launch/
│   ├── robot_system.launch.py
│   └── debug_system.launch.py
├── config/
│   ├── robot_params.yaml
│   └── debug_params.yaml
├── package.xml
├── setup.py
└── setup.cfg

setup.py (Essential Parts for Launch)

from setuptools import setup
import os
from glob import glob

package_name = 'my_robot_pkg'

setup(
    name=package_name,
    version='0.1.0',
    packages=[package_name],
    data_files=[
        ('share/ament_index/resource_index/packages',
            ['resource/' + package_name]),
        ('share/' + package_name, ['package.xml']),
        # Include launch files
        (os.path.join('share', package_name, 'launch'),
            glob('launch/*.launch.py')),
        # Include config files
        (os.path.join('share', package_name, 'config'),
            glob('config/*.yaml')),
    ],
    install_requires=['setuptools'],
    entry_points={
        'console_scripts': [
            'publisher_node = my_robot_pkg.publisher_node:main',
            'subscriber_node = my_robot_pkg.subscriber_node:main',
        ],
    },
)

Debugging Multi-Node Systems

Using ros2doctor

# Check system health
ros2 doctor

# Verbose output
ros2 doctor --report

Using rqt_graph

# Visualize node graph
ros2 run rqt_graph rqt_graph

Logging Levels

# In node code
self.get_logger().debug('Detailed debug info')
self.get_logger().info('Normal operation')
self.get_logger().warn('Warning condition')
self.get_logger().error('Error occurred')
self.get_logger().fatal('Fatal error')

# Set log level at runtime
ros2 run my_pkg my_node --ros-args --log-level debug

Educational Requirements

Layer 1 (Manual Foundation)

• Explain launch file structure and purpose
• Walk through LaunchDescription components
• Demonstrate parameter passing patterns

Layer 2 (AI Collaboration)

• Generate launch files from system requirements
• Debug multi-node communication issues with AI
• Optimize node configuration (Three Roles INVISIBLE)

Layer 3 (Intelligence Design)

• System architecture patterns
• Configuration management strategies
• Reusable launch file components

Layer 4 (Spec-Driven)

• Design system from specification
• Multi-node integration testing
• Capstone project orchestration

Hardware Tier Compatibility

All launch files MUST work on:

• Tier 1: Cloud ROS 2 (TheConstruct) with turtlesim
• Tier 2+: Local ROS 2 Humble with physical robots

Launch commands:

# Build and source
cd ~/ros2_ws
colcon build --packages-select my_robot_pkg
source install/setup.bash

# Launch
ros2 launch my_robot_pkg robot_system.launch.py

# Launch with arguments
ros2 launch my_robot_pkg robot_system.launch.py robot_name:=my_bot sim_mode:=false

Common Mistakes to Prevent

1. Missing data_files in setup.py: Launch files won't be installed
2. Wrong path in get_package_share_directory: Package name must match
3. Forgetting to rebuild: Changes require colcon build
4. Parameter type mismatches: YAML types must match node expectations

Integration with Other Skills

• ros2-publisher-subscriber: Nodes to launch
• ros2-service-pattern: Service nodes in system
• ros2-custom-interfaces: Interface packages as dependencies
• lesson-generator: For full lesson structure

Authoritative Source

All patterns verified against:

• https://docs.ros.org/en/humble/Tutorials/Intermediate/Launch/Creating-Launch-Files.html
• https://docs.ros.org/en/humble/Tutorials/Beginner-Client-Libraries/Using-Parameters-In-A-Class-Python.html