gazebo_ros2

A modern ROS 2 package that provides a convenient wrapper for launching Gazebo Harmonic simulations with customizable parameters and seamless integration.

📋 Table of Contents

• Overview
• Features
• Prerequisites
• Installation
• Usage
• Launch Arguments
• Package Structure
• Examples
• Contributing
• License

🎯 Overview

The gazebo_ros2 package simplifies the process of launching Gazebo Harmonic simulations within ROS 2 environments. It provides a configurable launch file that handles common Gazebo setup tasks, including world loading, resource path configuration, and simulation parameters.

✨ Features

• 🚀 Easy Integration: Simple launch file inclusion in your ROS 2 projects
• ⚙️ Configurable Parameters: Extensive customization options for simulation setup
• 🎨 GUI Control: Toggle between headless and GUI modes
• 📁 Resource Management: Flexible path configuration for models and worlds
• 🔧 Plugin Support: Custom plugin path configuration
• 🏃 Auto-start: Optional automatic simulation start

📦 Prerequisites

• ROS 2 Jazzy or later
• Gazebo Harmonic
• Ubuntu 22.04 or later

🛠️ Installation

System Dependencies

sudo apt update && sudo apt install -y \
    ros-${ROS_DISTRO}-ros-gz \
    ros-${ROS_DISTRO}-ros-gz-sim

Package Installation

1. Clone the repository:

   cd ~/your_ws/src
   git clone https://github.com/your-username/gazebo_ros2.git

2. Build the package:

   cd ~/your_ws
   colcon build --packages-select gazebo_ros2

3. Source the workspace:

   source ~/your_ws/install/setup.bash

🚀 Usage

Basic Launch

ros2 launch gazebo_ros2 gazebo_ros2.launch.py

With Custom World

ros2 launch gazebo_ros2 gazebo_ros2.launch.py world_path:=/path/to/your/world.sdf

Headless Mode

ros2 launch gazebo_ros2 gazebo_ros2.launch.py gui:=false

⚙️ Launch Arguments

Parameter	Type	Default	Description
gui	bool	true	Enable GUI. If false, launches in server-only mode
verbose	string	3	Verbosity level (0-4) for Gazebo simulation
world_path	string	''	Absolute path to .world or .sdf file
gz_sim_resource_path	string	''	Additional resource paths (colon-separated)
gz_sim_plugin_path	string	''	Additional plugin paths (colon-separated)
run_on_start	bool	true	Start simulation immediately

📁 Package Structure

gazebo_ros2/
├── gazebo_ros2/
│   └── __init__.py              # Python package initialization
├── launch/
│   └── gazebo_ros2.launch.py    # Main launch file
├── resource/
│   └── gazebo_ros2              # ROS 2 resource marker
├── test/
│   ├── test_copyright.py        # Copyright compliance tests
│   ├── test_flake8.py          # Code style tests
│   └── test_pep257.py          # Docstring tests
├── LICENSE                      # License file
├── package.xml                  # Package metadata
├── README.md                   # This file
├── setup.cfg                   # Setup configuration
└── setup.py                    # Package setup script

📚 Examples

Example 1: Basic Integration

#!/usr/bin/env python3
import os
from launch import LaunchDescription
from launch.actions import IncludeLaunchDescription
from launch.launch_description_sources import PythonLaunchDescriptionSource
from ament_index_python.packages import get_package_share_directory

def generate_launch_description():
    # Get package directory
    gazebo_ros2_share = get_package_share_directory('gazebo_ros2')
    
    # Include gazebo_ros2 launch
    gazebo_launch = IncludeLaunchDescription(
        PythonLaunchDescriptionSource([
            os.path.join(gazebo_ros2_share, 'launch', 'gazebo_ros2.launch.py')
        ]),
        launch_arguments={
            'gui': 'true',
            'verbose': '3'
        }.items()
    )
    
    return LaunchDescription([gazebo_launch])

Example 2: Load Turtlebot3 World

#!/usr/bin/env python3
import os
from launch import LaunchDescription
from launch.actions import IncludeLaunchDescription
from launch.launch_description_sources import PythonLaunchDescriptionSource
from ament_index_python.packages import get_package_share_directory

def generate_launch_description():
    # Package paths in the package share directory
    tb3_gz_pkg_share = get_package_share_directory('turtlebot3_gazebo')
    gz_ros2_share = get_package_share_directory('gazebo_ros2')

    # Join file paths with package share directory
    world_path = os.path.join(tb3_gz_pkg_share, 'worlds', 'turtlebot3_dqn_stage2.world')
    gazebo_ros2_launch_path = os.path.join(gz_ros2_share, 'launch', 'gazebo_ros2.launch.py')

    # Include gazebo_ros2 launch file + pass args
    gazebo_ros2_launch = IncludeLaunchDescription(
        PythonLaunchDescriptionSource(gazebo_ros2_launch_path),
        launch_arguments={
            'world_path': world_path,
            'gz_sim_resource_path': os.path.join(tb3_gz_pkg_share, 'models'),
            'gui': 'true',
            'verbose': '4',
            'run_on_start': 'true',
        }.items(),
    )

    return LaunchDescription([
        gazebo_ros2_launch
    ])

Fig. 1: LaunchMap visualization of example code

🧪 Testing

Run the package tests:

# Run all tests
colcon test --packages-select gazebo_ros2

# Run specific tests
python3 -m pytest src/gazebo_ros2/test/

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🔗 Related Projects

• ROS 2 Documentation
• Gazebo Documentation
• ros_gz packages

---

Maintainer: Kevin Eppacher