Launch Files Documentation

Complete Reference Guide for All Launch Files
ROS 2 Jazzy | Gazebo Harmonic
Last Updated: January 17, 2026

Overview
squarobot_gazebo Launch Files
squarobot_urdf Launch Files
Comparison Matrix
When to Use Which Launch File
Launch File Architecture

Overview

This document provides a comprehensive reference for all launch files in both the squarobot_gazebo and squarobot_urdf packages. Each launch file serves a specific purpose in the robot simulation, visualization, and navigation pipeline.

Package Purposes:

squarobot_gazebo: Production-ready simulation with Gazebo Harmonic, SLAM, and autonomous navigation
squarobot_urdf: Development, testing, and URDF visualization tools

squarobot_gazebo Launch Files

1. `navigation_with_map.launch.py` ⭐ RECOMMENDED

Purpose: Complete autonomous navigation system using a pre-saved map with AMCL localization.

Use Case:

Production navigation with known environment
Fastest and most reliable navigation setup
When you already have a mapped environment

Nodes Launched:

✓ robot_state_publisher      - Publishes robot TF tree
✓ gazebo (Harmonic)          - Simulation environment
✓ ros_gz_bridge              - Gazebo ↔ ROS 2 communication
✓ odom_to_tf                 - Odometry to TF broadcaster
✓ static_transform_publisher - Lidar frame transform
✓ map_server                 - Loads and serves saved map
✓ amcl                       - Localization (map→odom transform)
✓ controller_server          - Path following control
✓ planner_server            - Global path planning
✓ behavior_server           - Recovery behaviors
✓ bt_navigator              - Behavior tree navigation
✓ waypoint_follower         - Multi-waypoint navigation
✓ velocity_smoother         - Smooth velocity commands
✓ collision_monitor         - Dynamic obstacle avoidance
✓ smoother_server           - Path smoothing
✓ route_server              - Route planning
✓ lifecycle_manager (3x)    - Node lifecycle management
✓ rviz2                     - Visualization

Configuration Files:

config/nav2_params.yaml - All Nav2 parameters including AMCL
config/nav.rviz - RViz navigation layout
my_maze_map.yaml - Map metadata
my_maze_map.pgm - Map image

Launch Command:

ros2 launch squarobot_gazebo navigation_with_map.launch.py

Post-Launch Steps:

Wait 5-10 seconds for all nodes to initialize
Set initial pose in RViz using "2D Pose Estimate"
Set navigation goal using "Nav2 Goal"
Robot navigates autonomously

Key Features:

Complete Nav2 stack with all controllers
AMCL localization for accurate positioning
Global and local costmaps for obstacle avoidance
Recovery behaviors for stuck situations
No docking_server (excluded to avoid errors)
Proper frame configuration (base_link)

TF Tree:

map (from AMCL)
 └─ odom (from odom_to_tf)
     └─ base_link (from robot_state_publisher)
         ├─ lidar_1
         ├─ left_wheel_1
         └─ right_wheel_1

2. `slam_nav_simulation.launch.py`

Purpose: Simultaneous SLAM mapping and autonomous navigation - explore unknown environments while building a map.

Use Case:

First-time exploration of unknown environment
When you don't have a pre-existing map
Research and development scenarios
Dynamic environment mapping

Nodes Launched:

✓ robot_state_publisher      - Publishes robot TF tree
✓ gazebo (Harmonic)          - Simulation environment
✓ ros_gz_bridge              - Gazebo ↔ ROS 2 communication
✓ odom_to_tf                 - Odometry to TF broadcaster
✓ static_transform_publisher - Lidar frame transform
✓ slam_toolbox               - Real-time SLAM (lifecycle-managed)
✓ controller_server          - Path following control
✓ planner_server            - Global path planning
✓ behavior_server           - Recovery behaviors
✓ bt_navigator              - Behavior tree navigation
✓ waypoint_follower         - Multi-waypoint navigation
✓ velocity_smoother         - Smooth velocity commands
✓ collision_monitor         - Dynamic obstacle avoidance
✓ smoother_server           - Path smoothing
✓ lifecycle_manager (2x)    - Node lifecycle management
✓ rviz2                     - Visualization

Configuration Files:

config/nav2_params.yaml - Nav2 parameters
config/slam_params.yaml - SLAM Toolbox parameters
config/nav.rviz - RViz navigation layout

Launch Command:

ros2 launch squarobot_gazebo slam_nav_simulation.launch.py

Post-Launch Steps:

Activate SLAM Toolbox:

ros2 lifecycle set /slam_toolbox configure
ros2 lifecycle set /slam_toolbox activate

Set initial pose in RViz using "2D Pose Estimate"
Set navigation goals to explore environment
Map builds in real-time as robot moves

Save map when complete:

ros2 run nav2_map_server map_saver_cli -f ~/Final/my_map

Key Features:

Real-time SLAM mapping during navigation
Nav2 stack for autonomous navigation
Can save map for later use
Continuous map updates
Loop closure detection

TF Tree:

map (from SLAM Toolbox)
 └─ odom (from odom_to_tf)
     └─ base_link (from robot_state_publisher)
         └─ ... (other links)

Difference from navigation_with_map.launch.py:

Uses SLAM Toolbox instead of map_server + AMCL
Map is built in real-time, not pre-loaded
Requires SLAM activation via lifecycle commands
More computationally intensive

3. `slam_simulation.launch.py`

Purpose: Pure SLAM mapping with manual teleoperation - create maps by driving the robot manually.

Use Case:

Creating initial maps of environment
Testing SLAM performance
Manual map creation and refinement
No autonomous navigation needed

Nodes Launched:

✓ robot_state_publisher      - Publishes robot TF tree
✓ gazebo (Harmonic)          - Simulation environment
✓ ros_gz_bridge              - Gazebo ↔ ROS 2 communication
✓ odom_to_tf                 - Odometry to TF broadcaster
✓ static_transform_publisher - Lidar frame transform
✓ slam_toolbox               - SLAM mapping (lifecycle-managed)
✓ rviz2                      - Visualization

Configuration Files:

config/slam_params.yaml - SLAM Toolbox parameters
config/slam.rviz - RViz SLAM-focused layout

Launch Command:

ros2 launch squarobot_gazebo slam_simulation.launch.py

Post-Launch Steps:

Activate SLAM Toolbox:

ros2 lifecycle set /slam_toolbox configure
ros2 lifecycle set /slam_toolbox activate

Drive robot manually using keyboard teleop:

ros2 run teleop_twist_keyboard teleop_twist_keyboard

Watch map build in RViz

Save map when complete:

ros2 run nav2_map_server map_saver_cli -f ~/Final/my_map

Keyboard Controls (teleop_twist_keyboard):

i - Move forward
, - Move backward
j - Turn left
l - Turn right
k - Stop
q/z - Increase/decrease max speeds
w/x - Increase/decrease only linear speed
e/c - Increase/decrease only angular speed

Key Features:

Lightweight - only SLAM, no navigation
Full manual control
Real-time map building
Can serialize map for continued mapping later
Good for testing SLAM parameters

What's NOT included:

✗ No autonomous navigation
✗ No Nav2 stack
✗ No path planning
✗ No collision avoidance
✗ Manual control only

Save Map Options:

Standard map (PGM + YAML):
```
ros2 run nav2_map_server map_saver_cli -f ~/Final/my_map
```
Creates: my_map.pgm and my_map.yaml Use for: Navigation with AMCL
Serialized map (SLAM Toolbox format):
- In RViz → SLAM Toolbox panel → "Serialize Map"
- Creates: serialized.data and serialized.posegraph
- Use for: Continuing mapping later

4. `simulation.launch.py`

Purpose: Basic robot simulation in Gazebo - minimal setup for testing and development.

Use Case:

Testing robot URDF changes
Verifying sensor data
Development and debugging
Testing controllers without navigation
Learning ROS 2 basics

Nodes Launched:

✓ robot_state_publisher      - Publishes robot TF tree
✓ gazebo (Harmonic)          - Simulation environment
✓ ros_gz_bridge              - Gazebo ↔ ROS 2 communication
✓ static_transform_publisher - Lidar frame transform

Configuration Files:

None (uses default Gazebo world and URDF)

Launch Command:

ros2 launch squarobot_gazebo simulation.launch.py

Key Features:

Minimal overhead - fastest launch time
Basic sensor bridging (lidar, odom, cmd_vel)
No SLAM, no navigation, no RViz
Good starting point for development

Available Topics:

/scan           # Lidar data
/odom           # Odometry
/cmd_vel        # Velocity commands (input)
/joint_states   # Joint positions
/tf             # Transform tree
/tf_static      # Static transforms

What's NOT included:

✗ No SLAM
✗ No navigation
✗ No RViz (launch separately if needed)
✗ No autonomous features
✗ No map

Manual Control: You can control the robot by publishing to /cmd_vel:

# Move forward
ros2 topic pub /cmd_vel geometry_msgs/Twist "{linear: {x: 0.5}}"

# Rotate
ros2 topic pub /cmd_vel geometry_msgs/Twist "{angular: {z: 1.0}}"

# Stop
ros2 topic pub /cmd_vel geometry_msgs/Twist "{}"

Typical Workflow:

Launch simulation
Verify topics are publishing: ros2 topic list
Check lidar: ros2 topic echo /scan
Test odometry: ros2 topic echo /odom
Control robot manually or with your own node

squarobot_urdf Launch Files

These launch files are from the original development package and use older Gazebo Classic (not Gazebo Harmonic). They're primarily for URDF visualization and legacy support.

5. `display.launch.py`

Purpose: Visualize robot URDF in RViz without simulation - for URDF development and verification.

Use Case:

Developing and testing URDF/Xacro files
Visualizing robot model structure
Testing joint configurations
TF tree verification

Nodes Launched:

✓ robot_state_publisher       - Publishes robot description
✓ joint_state_publisher_gui   - GUI to control joints (if gui=True)
✓ joint_state_publisher       - Default joint positions (if gui=False)
✓ rviz2                       - Visualization

Configuration Files:

config/display.rviz - RViz layout for URDF visualization
urdf/squaroboturdf.xacro - Robot URDF model

Launch Command:

# With GUI (default)
ros2 launch squarobot_urdf display.launch.py

# Without GUI
ros2 launch squarobot_urdf display.launch.py gui:=False

Key Features:

Interactive joint control with GUI sliders
Real-time URDF visualization
No simulation - just visualization
Fast iteration for URDF development
TF tree visible in RViz

What you see in RViz:

Robot 3D model
TF frames
Joint axes
Link coordinate frames

Use this when:

✓ Modifying URDF structure
✓ Testing new links/joints
✓ Verifying collision geometry
✓ Checking visual vs collision meshes
✓ TF debugging

Don't use this for:

✗ Actual simulation (no physics)
✗ Sensor testing (no sensor data)
✗ Navigation (no environment)

6. `gazebo.launch.py`

Purpose: Launch robot in Gazebo Classic (old version) - legacy support.

Use Case:

Legacy projects using Gazebo Classic
Testing on systems without Gazebo Harmonic
Educational purposes

Nodes Launched:

✓ robot_state_publisher  - Publishes robot description
✓ joint_state_publisher  - Joint states
✓ gzserver              - Gazebo Classic server
✓ gzclient              - Gazebo Classic GUI
✓ spawn_entity          - Spawns robot in Gazebo

Configuration Files:

urdf/squaroboturdf.xacro - Robot URDF model

Launch Command:

ros2 launch squarobot_urdf gazebo.launch.py

Important Notes:

⚠️ Uses Gazebo Classic, not Gazebo Harmonic
⚠️ Different from squarobot_gazebo package
⚠️ May not work if Gazebo Classic not installed
⚠️ Consider using squarobot_gazebo packages instead

Key Differences from squarobot_gazebo:

Uses Gazebo Classic (older)
Different plugin architecture
Less reliable with ROS 2 Jazzy
No SLAM or navigation integration

Migration Note: If you're using this, consider migrating to:

ros2 launch squarobot_gazebo simulation.launch.py

7. `gz_sim.launch.py`

Purpose: Alternative Gazebo Harmonic launch (early development version).

Nodes Launched:

✓ robot_state_publisher
✓ gz_sim (Gazebo Harmonic)
✓ ros_gz_bridge

Note: This is a developmental launch file. For production use:

ros2 launch squarobot_gazebo simulation.launch.py

8. `squaro.launch.py`

Purpose: Custom launch file for specific testing scenarios.

Status: Development/testing file

Recommendation: Use squarobot_gazebo launch files for standard workflows.

9. `simulation.launch.py` (squarobot_urdf)

Purpose: Alternative simulation launcher.

Status: Development version

Recommendation: Use squarobot_gazebo/simulation.launch.py instead for better integration.

Comparison Matrix

Launch File	Package	SLAM	Navigation	Manual Control	RViz	Gazebo	AMCL	Purpose
`navigation_with_map.launch.py`	gazebo	✗	✓	✗	✓	Harmonic	✓	Production navigation ⭐
`slam_nav_simulation.launch.py`	gazebo	✓	✓	✗	✓	Harmonic	✗	Explore + navigate
`slam_simulation.launch.py`	gazebo	✓	✗	✓	✓	Harmonic	✗	Create maps manually
`simulation.launch.py`	gazebo	✗	✗	✓	✗	Harmonic	✗	Basic simulation
`display.launch.py`	urdf	✗	✗	GUI	✓	✗	✗	URDF visualization
`gazebo.launch.py`	urdf	✗	✗	✗	✗	Classic	✗	Legacy simulation

When to Use Which Launch File

Decision Tree

Do you need autonomous navigation?
├─ YES: Do you have a pre-existing map?
│   ├─ YES: Use navigation_with_map.launch.py ⭐
│   └─ NO: Use slam_nav_simulation.launch.py
│
└─ NO: Do you need to create a map?
    ├─ YES: Use slam_simulation.launch.py
    └─ NO: What do you need?
        ├─ Basic simulation: simulation.launch.py (gazebo)
        ├─ URDF visualization: display.launch.py
        └─ Legacy support: gazebo.launch.py (urdf)

By Use Case

🎯 Production/Deployment:

Use: navigation_with_map.launch.py
Why: Most reliable, fastest, complete Nav2 stack

🗺️ First-Time Mapping:

Use: slam_simulation.launch.py
Why: Manual control, focus on mapping quality

🔍 Exploration:

Use: slam_nav_simulation.launch.py
Why: Navigate while mapping

🔧 Development/Testing:

Use: simulation.launch.py (gazebo)
Why: Minimal overhead, fast iteration

📐 URDF Development:

Use: display.launch.py
Why: No simulation overhead, visual feedback

📚 Learning/Tutorial:

Start: simulation.launch.py → basics
Then: slam_simulation.launch.py → mapping
Finally: navigation_with_map.launch.py → navigation

Launch File Architecture

Common Components

All squarobot_gazebo launch files share these core components:

1. Robot Description (URDF/Xacro)

xacro_file = os.path.join(pkg_squarobot_gazebo, 'gazebo', 'squaroboturdf.xacro')
robot_description_config = xacro.process_file(xacro_file)
robot_urdf = robot_description_config.toxml()

Purpose: Loads and processes robot model

2. Robot State Publisher

robot_state_publisher = Node(
    package='robot_state_publisher',
    executable='robot_state_publisher',
    name='robot_state_publisher',
    parameters=[{'robot_description': robot_urdf}],
    output='screen'
)

Purpose: Publishes robot TF tree from URDF

3. Gazebo Simulation

gz_sim = IncludeLaunchDescription(
    PythonLaunchDescriptionSource(
        os.path.join(pkg_ros_gz_sim, 'launch', 'gz_sim.launch.py')
    ),
    launch_arguments={'gz_args': f'-r {world_file}'}.items(),
)

Purpose: Launches Gazebo Harmonic with specified world

4. ROS-Gazebo Bridge

bridge = Node(
    package='ros_gz_bridge',
    executable='parameter_bridge',
    arguments=[
        '/scan@sensor_msgs/msg/LaserScan@gz.msgs.LaserScan',
        '/cmd_vel@geometry_msgs/msg/Twist@gz.msgs.Twist',
        '/odom@nav_msgs/msg/Odometry@gz.msgs.Odometry',
        '/joint_state@...'
    ],
    ...
)

Purpose: Bridges topics between Gazebo and ROS 2

5. Odometry to TF

odom_to_tf = Node(
    package='squarobot_gazebo',
    executable='odom_to_tf.py',
    name='odom_to_tf',
    parameters=[{'use_sim_time': True}],
    output='screen'
)

Purpose: Broadcasts odom → base_link transform from /odom messages

6. Static Transforms

static_tf_lidar = Node(
    package='tf2_ros',
    executable='static_transform_publisher',
    arguments=['0', '0', '0', '0', '0', '0', 'lidar_1', 'squarobot/base_link/lidar'],
    output='screen'
)

Purpose: Fixes frame name mismatch between Gazebo and ROS 2

Navigation-Specific Components

AMCL (navigation_with_map.launch.py)

amcl = Node(
    package='nav2_amcl',
    executable='amcl',
    name='amcl',
    output='screen',
    parameters=[nav2_params_file]
)

Purpose: Localization on pre-existing map

SLAM Toolbox (slam_*.launch.py)

slam_toolbox = Node(
    package='slam_toolbox',
    executable='async_slam_toolbox_node',
    name='slam_toolbox',
    output='screen',
    parameters=[slam_params_file, {'use_sim_time': True}]
)

Purpose: Real-time SLAM mapping

Nav2 Servers

# Controller - Path following
controller_server = Node(package='nav2_controller', ...)

# Planner - Global path planning
planner_server = Node(package='nav2_planner', ...)

# Behaviors - Recovery actions
behavior_server = Node(package='nav2_behaviors', ...)

# BT Navigator - High-level navigation logic
bt_navigator = Node(package='nav2_bt_navigator', ...)

Purpose: Complete autonomous navigation stack

Launch File Parameters

Common Parameters

All launch files support:

use_sim_time: True - Use Gazebo simulation time
Output to screen for logging

Configurable Parameters

navigation_with_map.launch.py

map: Path to map YAML file (default: ~/Final/my_maze_map.yaml)

slam_simulation.launch.py

None (uses default configuration files)

display.launch.py

gui: Show joint state publisher GUI (default: True)

Configuration Files Reference

Nav2 Parameters: `config/nav2_params.yaml`

Contains configuration for:

amcl - Localization parameters
bt_navigator - Behavior tree configuration
controller_server - DWB local planner settings
planner_server - NavFn global planner settings
behavior_server - Recovery behavior settings
collision_monitor - Dynamic obstacle avoidance
velocity_smoother - Velocity smoothing
And more...

SLAM Parameters: `config/slam_params.yaml`

Contains SLAM Toolbox configuration:

Loop closure settings
Scan matching parameters
Map resolution
Processing modes

RViz Configurations

nav.rviz - Navigation layout with costmaps
slam.rviz - SLAM-focused layout
display.rviz - URDF visualization layout (in squarobot_urdf)

Troubleshooting Launch Files

Common Issues

Issue: "Frame [map] does not exist"

Affected: navigation_with_map.launch.py
Solution: Set initial pose in RViz using "2D Pose Estimate"

Issue: SLAM Toolbox not publishing map

Affected: slam_*.launch.py
Solution: Activate SLAM lifecycle:

ros2 lifecycle set /slam_toolbox configure
ros2 lifecycle set /slam_toolbox activate

Issue: Robot doesn't spawn in Gazebo

Affected: All gazebo launch files
Solution: Check Gazebo resource path and wait for Gazebo to fully load

Issue: No lidar data

Affected: All simulation files
Solution: Check bridge topics and static transform

Debugging Commands

# Check all running nodes
ros2 node list

# Check topics
ros2 topic list

# Check TF tree
ros2 run rqt_tf_tree rqt_tf_tree

# Monitor specific topic
ros2 topic echo /scan
ros2 topic echo /odom

# Check node parameters
ros2 param list /amcl

Summary

Production Recommendation

For most use cases, use files from squarobot_gazebo package:

Navigation: navigation_with_map.launch.py ⭐
Mapping: slam_simulation.launch.py
Exploration: slam_nav_simulation.launch.py
Testing: simulation.launch.py

Development Recommendation

For URDF development, use squarobot_urdf package:

Visualization: display.launch.py

Key Takeaways

✅ navigation_with_map.launch.py is the most complete and reliable
✅ All navigation files require setting initial pose
✅ SLAM files need lifecycle activation
✅ Use squarobot_gazebo for production
✅ Use squarobot_urdf for development only

Documentation maintained by: ROS 2 Navigation Team
Contact: See README.md for support
Related Docs:

FilesExpand file tree

LAUNCH_FILES_REFERENCE.md

Latest commit

History

LAUNCH_FILES_REFERENCE.md

File metadata and controls

Launch Files Documentation

Table of Contents

Overview

Package Purposes:

squarobot_gazebo Launch Files

1. navigation_with_map.launch.py ⭐ RECOMMENDED

2. slam_nav_simulation.launch.py

3. slam_simulation.launch.py

4. simulation.launch.py

squarobot_urdf Launch Files

5. display.launch.py

6. gazebo.launch.py

7. gz_sim.launch.py

8. squaro.launch.py

9. simulation.launch.py (squarobot_urdf)

Comparison Matrix

When to Use Which Launch File

Decision Tree

By Use Case

Launch File Architecture

Common Components

1. Robot Description (URDF/Xacro)

2. Robot State Publisher

3. Gazebo Simulation

4. ROS-Gazebo Bridge

5. Odometry to TF

6. Static Transforms

Navigation-Specific Components

AMCL (navigation_with_map.launch.py)

SLAM Toolbox (slam_*.launch.py)

Nav2 Servers

Launch File Parameters

Common Parameters

Configurable Parameters

navigation_with_map.launch.py

slam_simulation.launch.py

display.launch.py

Configuration Files Reference

Nav2 Parameters: config/nav2_params.yaml

SLAM Parameters: config/slam_params.yaml

RViz Configurations

Troubleshooting Launch Files

Common Issues

Issue: "Frame [map] does not exist"

Issue: SLAM Toolbox not publishing map

Issue: Robot doesn't spawn in Gazebo

Issue: No lidar data

Debugging Commands

Summary

Production Recommendation

Development Recommendation

Key Takeaways

1. `navigation_with_map.launch.py` ⭐ RECOMMENDED

2. `slam_nav_simulation.launch.py`

3. `slam_simulation.launch.py`

4. `simulation.launch.py`

5. `display.launch.py`

6. `gazebo.launch.py`

7. `gz_sim.launch.py`

8. `squaro.launch.py`

9. `simulation.launch.py` (squarobot_urdf)

Nav2 Parameters: `config/nav2_params.yaml`

SLAM Parameters: `config/slam_params.yaml`