Gazebo Sim

Gazebo Simulation & ROS 2 Integration Instructions (Ubuntu 24.04 LTS)

1. Core Principles & Distro Pairings

• Target OS & Distro Pairings:
• Ubuntu 24.04 LTS & ROS 2 Jazzy: Officially paired with Gazebo Harmonic (https://gazebosim.org/docs/harmonic/).
• (Legacy reference: Ubuntu 22.04 LTS & ROS 2 Humble pair with Gazebo Fortress https://gazebosim.org/docs/fortress/).
• Modern Gazebo Architecture: Strictly use modern Gazebo Sim (formerly Ignition Gazebo / gz) and ros_gz. Do not mix legacy Gazebo Classic (gazebo_ros_pkgs / gazebo_ros) unless explicitly requested for older legacy systems.
• Zero-Hallucination Policy: Always verify plugin system filenames (e.g., gz-sim-diff-drive-system), SDF tags, and ros_gz_bridge topic syntax against official documentation.

2. Official Documentation Reference Directives

Whenever creating simulation worlds, URDF/SDF models, Gazebo sensor plugins, or ros_gz launch files:

A. Master Gazebo Documentation Portals

• Gazebo Sim Master Docs: https://gazebosim.org/docs
• Gazebo Harmonic Docs (Jazzy): https://gazebosim.org/docs/harmonic/
• Gazebo Fortress Docs (Humble): https://gazebosim.org/docs/fortress/
• SDFormat Specification: https://sdformat.org/

B. ROS 2 & Gazebo Integration (ros_gz)

• ros_gz Repository & Integration Guide: https://github.com/gazebosim/ros_gz
• ros_gz_bridge Topic Bridge: https://github.com/gazebosim/ros_gz/tree/ros2/ros_gz_bridge
• Description: Bidirectional topic bridging between Gazebo Transport and ROS 2 topics (/scan, /odom, /cmd_vel, /camera/image_raw, /imu).
• Bridge Syntax: ros2 run ros_gz_bridge parameter_bridge /scan@sensor_msgs/msg/LaserScan[gz.msgs.LaserScan or YAML bridge config files.
• ros_gz_sim Launch & Spawning: https://github.com/gazebosim/ros_gz/tree/ros2/ros_gz_sim
• Description: Launching Gazebo world files (.sdf), spawning robot models using ros_gz_sim create -topic robot_description or gz_sim.launch.py.

C. Nav2 Simulation Setup Guides

• Nav2 Setup Guide for Gazebo: https://docs.nav2.org/setup_guides/gazebo.html
• URDF & Robot State Publisher Setup: https://docs.nav2.org/setup_guides/urdf/setup_urdf.html
• SDF World & Model Setup: https://docs.nav2.org/setup_guides/sdf/setup_sdf.html
• Simulating Odometry in Gazebo: https://docs.nav2.org/setup_guides/odom/setup_odom_gz.html
• Description: Differential drive plugin (gz-sim-diff-drive-system) setup and broadcasting odom -> base_link.
• Simulating Sensors in Gazebo: https://docs.nav2.org/setup_guides/sensors/setup_sensors_gz.html
• Description: Configuring GPU Lidar (gpu_lidar), IMU (imu), and Depth Camera sensors in Gazebo Sim.

3. Sensor & Motion Plugins Reference (SDF)

A. Differential Drive Motion Plugin

  left_wheel_joint
  right_wheel_joint
  0.3
  0.05
  50
  /cmd_vel
  /odom
  odom
  base_link

B. GPU LiDAR Sensor Plugin

  10
  /scan
  
    
      
        360
        1
        -3.14159
        3.14159
      
    
    
      0.15
      12.0
    
  
  
    ogre2
  

4. Symptom -> Root Cause -> Action

| Symptom | Likely root cause | Action | | :--- | :--- | :--- | | Robot spawns then falls through the ground | Missing ` on links, or zero/invalid | Add collision geometry; give every non-fixed link real mass and inertia | | /cmdvel published but robot doesn't move in sim | Bridge direction wrong ([ is GZ->ROS, ] is ROS->GZ, @ bidirectional) or plugin mismatch | Check bridge arg direction char; gz topic -l to see what the plugin actually subscribes to | | LiDAR/camera topic exists but publishes nothing | gz-sim-sensors-system plugin missing from the world SDF (rendering sensors need it) | Add with renderengine to the world | | IMU topic silent in sim | gz-sim-imu-system world plugin missing | Add the IMU system plugin to the world SDF | | TF extrapolation errors as soon as sim starts | /clock not bridged, or nodes missing usesimtime: true | Bridge /clock@rosgraphmsgs/msg/Clock[gz.msgs.Clock; set usesimtime on every node | | Sensor data arrives in an unknown/prefixed frame | Gazebo composes frame as // while URDF expects the bare link name | Set explicit /frame remapping, or align frameid with the URDF link | | Sim odometry perfect but Nav2 behaves differently on the real robot | Sim plugin uses ideal kinematics; real wheelradius/friction differ | Never tune Nav2 solely in sim; re-verify on hardware with scripts/checkodom_direction.py` |

5. Local System Verification

Check installed Gazebo & ROS 2 bridge packages locally:

• Run ros2 pkg prefix ros_gz_bridge to inspect bridge dependencies.
• Run gz sim --version in terminal to confirm active Gazebo Harmonic or Fortress version.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Leehyunbin0131
• Source: Leehyunbin0131/claude-ros2-skills
• License: MIT

Install and usage instructions live in the source repository linked above.