# mo-elshamy/ros2_gazebo_sim_tutorial architecture

> Architecture diagram of the GitHub repository mo-elshamy/ros2_gazebo_sim_tutorial, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mo-elshamy/ros2_gazebo_sim_tutorial
- Repository: https://github.com/mo-elshamy/ros2_gazebo_sim_tutorial

## Overview

##### Project Type and Purpose
- This is a ROS 2 robotics simulation package that integrates a TurtleBot3 Waffle model (with LiDAR and camera sensors) into Gazebo Sim (Ignition) and visualizes sensor data in RViz 2.
- It lives under a single ROS 2 package named `robot_description` and relies on `ros_gz_sim`, `ros_gz_bridge`, and SDFormat.

##### Main Components
a. Gazebo Sim (Ignition)
- The simulation engine that loads SDF world files (`robot_description/worlds/*.sdf`) and the robot model (`robot_description/models/*`).
- Hosts the sensor plugins (LiDAR, camera).
b. ROS 2 Middleware
- Core ROS 2 nodes and DDS communications.
- `ros_gz_sim` node: spins up Gazebo as a ROS 2 node.
- `ros_gz_bridge` node: translates Gazebo topics into ROS 2 topics.
c. robot_description Package
- URDF/SDF files and meshes under `models/`
- Launch file (`launch/robot.launch.py`) that brings up Gazebo, bridges, and optionally RViz.
- Parameter YAML for bridge topics (`params/ros_bridge.yaml`).
- RViz config (`rviz/rviz.rviz`).
d. teleop_twist_keyboard Node
- A ROS 2 executable that publishes `/cmd_vel` Twist messages.
e. RViz 2
- A separate visualization node subscribing to sensor topics and TF frames.

##### Relationships & Data Flow
- teleop node → publishes `/cmd_vel` → ros_gz_bridge → Gazebo plugin subscribes → moves robot.
- Gazebo LiDAR plugin → publishes `/scan` (in Ignition) → ros_gz_bridge → ROS 2 `/scan` topic → RViz subscribes.
- Gazebo camera plugin → publishes `/camera/image` → ros_gz_bridge → ROS 2 topic → RViz.
- Static TF and joint states also bridged for RViz.

##### Architectural Patterns & Principles
- Publish–Subscribe (ROS 2 topics) decouples components.
- Separation of concerns: simulation engine vs. middleware vs. visualization.
- Launch-driven orchestration: single `robot.launch.py` brings up all nodes with the correct parameters.

- Clear, distinct labels for components and topics.
- Simulation engine (Gazebo/SDFormat)
- Bridge/middleware nodes
- User-space nodes (teleop, RViz)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Simulation Engine
    subgraph "Simulation Engine" 
        direction TB
        world_files[/"World Files"/]:::docs
        empty_world["empty_world.sdf"]:::docs
        turtlebot3_world_file["turtlebot3_world.sdf"]:::docs
        GazeboSim["Gazebo Sim<br/>(Ignition)"]:::simulation
        robot_model_docs[/"Robot Model Files"/]:::docs
        waffle_model_sdf["model.sdf"]:::docs
        waffle_model_config["model.config"]:::docs
        lds_mesh["lds.dae"]:::docs
        tire_mesh["tire.dae"]:::docs
        waffle_base_mesh["waffle_base.dae"]:::docs
        tb3_world_model_docs[/"TurtleBot3 World Model"/]:::docs
        tb3_world_model_sdf["model.sdf"]:::docs
        tb3_world_model_14["model-1_4.sdf"]:::docs
        tb3_world_model_config["model.config"]:::docs
        hexagon_mesh["hexagon.dae"]:::docs
        wall_mesh["wall.dae"]:::docs
    end

    %% ROS 2 Middleware
    subgraph "ROS 2 Middleware" 
        direction TB
        ros_gz_sim["ros_gz_sim Node"]:::middleware
        ros_gz_bridge["ros_gz_bridge Node"]:::middleware
        launch_file["robot.launch.py<br/>(Launch)"]:::middleware
        bridge_params["ros_bridge.yaml"]:::middleware
    end

    %% User / Visualization
    subgraph "User & Visualization"
        direction TB
        teleop["teleop_twist_keyboard"]:::user
        RViz2["RViz 2"]:::user
        rviz_config["rviz.rviz"]:::user
    end

    %% Package Root
    robot_description["robot_description/"]:::package

    %% Connections: Launch orchestration
    robot_description -->|includes| launch_file
    launch_file -->|loads| GazeboSim
    launch_file -->|loads| ros_gz_sim
    launch_file -->|loads| ros_gz_bridge
    launch_file -->|loads| RViz2

    %% Teleop to Gazebo via bridge
    teleop -->|"/cmd_vel"| ros_gz_bridge
    ros_gz_bridge -->|"/cmd_vel"| GazeboSim

    %% Sensor data from Gazebo to ROS 2 to RViz
    GazeboSim -->|"/scan"| ros_gz_bridge
    ros_gz_bridge -->|"/scan"| RViz2

    GazeboSim -->|"/camera/image"| ros_gz_bridge
    ros_gz_bridge -->|"/camera/image"| RViz2

    GazeboSim -->|"/tf, /joint_states"| ros_gz_bridge
    ros_gz_bridge -->|"/tf, /joint_states"| RViz2

    %% Asset loading
    launch_file -->|uses| world_files
    world_files --> empty_world
    world_files --> turtlebot3_world_file
    launch_file -->|uses| robot_model_docs
    robot_model_docs --> waffle_model_sdf
    robot_model_docs --> waffle_model_config
    robot_model_docs --> lds_mesh
    robot_model_docs --> tire_mesh
    robot_model_docs --> waffle_base_mesh
    launch_file -->|uses| tb3_world_model_docs
    tb3_world_model_docs --> tb3_world_model_sdf
    tb3_world_model_docs --> tb3_world_model_14
    tb3_world_model_docs --> tb3_world_model_config
    tb3_world_model_docs --> hexagon_mesh
    tb3_world_model_docs --> wall_mesh

    launch_file -->|params| bridge_params
    launch_file -->|config| rviz_config
    robot_description -->|metadata| pkg_xml
    robot_description -->|build| cmakelists

    %% Click Events
    click robot_description "https://github.com/mo-elshamy/ros2_gazebo_sim_tutorial/tree/main/robot_description/"
    click empty_world "https://github.com/mo-elshamy/ros2_gazebo_sim_tutorial/blob/main/robot_description/worlds/empty_world.sdf"
    click turtlebot3_world_file "https://github.com/mo-elshamy/ros2_gazebo_sim_tutorial/blob/main/robot_description/worlds/turtlebot3_world.sdf"
    click waffle_model_sdf "https://github.com/mo-elshamy/ros2_gazebo_sim_tutorial/blob/main/robot_description/models/waffle/model.sdf"
    click waffle_model_config "https://github.com/mo-elshamy/ros2_gazebo_sim_tutorial/blob/main/robot_description/models/waffle/model.config"
    click lds_mesh "https://github.com/mo-elshamy/ros2_gazebo_sim_tutorial/blob/main/robot_description/models/waffle/meshes/lds.dae"
    click tire_mesh "https://github.com/mo-elshamy/ros2_gazebo_sim_tutorial/blob/main/robot_description/models/waffle/meshes/tire.dae"
    click waffle_base_mesh "https://github.com/mo-elshamy/ros2_gazebo_sim_tutorial/blob/main/robot_description/models/waffle/meshes/waffle_base.dae"
    click tb3_world_model_sdf "https://github.com/mo-elshamy/ros2_gazebo_sim_tutorial/blob/main/robot_description/models/turtlebot3_world/model.sdf"
    click tb3_world_model_14 "https://github.com/mo-elshamy/ros2_gazebo_sim_tutorial/blob/main/robot_description/models/turtlebot3_world/model-1_4.sdf"
    click tb3_world_model_config "https://github.com/mo-elshamy/ros2_gazebo_sim_tutorial/blob/main/robot_description/models/turtlebot3_world/model.config"
    click hexagon_mesh "https://github.com/mo-elshamy/ros2_gazebo_sim_tutorial/blob/main/robot_description/models/turtlebot3_world/meshes/hexagon.dae"
    click wall_mesh "https://github.com/mo-elshamy/ros2_gazebo_sim_tutorial/blob/main/robot_description/models/turtlebot3_world/meshes/wall.dae"
    click launch_file "https://github.com/mo-elshamy/ros2_gazebo_sim_tutorial/blob/main/robot_description/launch/robot.launch.py"
    click bridge_params "https://github.com/mo-elshamy/ros2_gazebo_sim_tutorial/blob/main/robot_description/params/ros_bridge.yaml"
    click rviz_config "https://github.com/mo-elshamy/ros2_gazebo_sim_tutorial/blob/main/robot_description/rviz/rviz.rviz"
    click pkg_xml "https://github.com/mo-elshamy/ros2_gazebo_sim_tutorial/blob/main/robot_description/package.xml"
    click cmakelists "https://github.com/mo-elshamy/ros2_gazebo_sim_tutorial/blob/main/robot_description/CMakeLists.txt"

    %% Styles
    classDef simulation fill:#E3F2FD,stroke:#90CAF9,color:#0D47A1
    classDef middleware fill:#E8F5E9,stroke:#A5D6A7,color:#1B5E20
    classDef user fill:#FFFDE7,stroke:#FFF59D,color:#F57F17
    classDef docs fill:#F3E5F5,stroke:#CE93D8,color:#4A148C,shape:folder
    classDef package fill:#ECEFF1,stroke:#B0BEC5,color:#37474F,shape:folder
```
