# petoadam/ros2_sim architecture

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

- Interactive diagram: https://gitdiagram.com/petoadam/ros2_sim
- Repository: https://github.com/petoadam/ros2_sim

## Overview

##### Project Type and Purpose
- Full-stack ROS2 robotics application for UR3 arm simulation, control, and motion planning.
- Components include: robot description, physics simulation, control stack (ros2_control + PID), motion planning (MoveIt2 + custom planner), messaging and gateway, and visualization (RViz and ROS2 Sim UI).

##### Main Components
A. Description & Modeling
– Package: ros2_sim_ur3_description
– Contents: URDF/XACRO, meshes, SRDF, RViz config
– Function: defines robot kinematics & visuals
B. Physics Simulation
– Package: ros2_sim_simulation
– Node: simulation_node
– Function: publishes /joint_states, simulates robot dynamics
C. Control Interface
– Package: ros2_sim_control
– Node: ros2_control hardware interface
– Config: robot_controller.yaml, controllers loaded via ros2_control
– Function: translates JointTrajectory → controller commands
D. Low-Level Actuation (PID)
– Package: ros2_sim_pid_controller
– Node: pid_controller_node
– Function: subscribes to desired joint positions → computes joint efforts
E. Motion Planning
1. MoveIt2 Integration
– Package: ros2_sim_moveit_config
– Nodes: move_group, RViz MotionPlanning plugin
– Config: kinematics, joint_limits, controllers
2. Custom Planner
– Package: ros2_sim_motion_planner & ros2_sim_msgs
– Node: motion_planner_node
– Action: /plan_and_execute (PlanAndExecute.action)
– Function: listens for advanced action goals → plans via MoveIt2 or Pilz → sends trajectories
F. State Gateway
– Package: ros2_sim_gateway
– Node: joint_states_listener
– Function: forwards or transforms joint_states for external UIs
G. Visualization & UI
– RViz2 (configured by ros2_sim_ur3_description)
– ROS2 Sim UI (web renderer under development)

##### Relationships & Data Flows
1. Description → Simulation
- URDF/SRDF loaded by simulation_node
2. Simulation → /joint_states topic → ros2_control & gateway
3. ros2_control → /robot_arm_controller/joint_trajectory topic ← Motion Planner (MoveIt2 or custom)
4. ros2_control hardware interface → desired_positions topic → PID controller → joint_effort commands → back to Simulation
5. Motion Planner Action Client/Server
- External CLI/UI → /plan_and_execute action → motion_planner_node → MoveIt2 → trajectory → ros2_control
6. Visualization
- RViz subscribes to /joint_states, /planned_trajectory, TF frames
- Web UI uses gateway topics

##### Architectural Patterns & Principles
- Modular ROS2 packages—each with its own CMakeLists.xml & package.xml
- Strict separation of concerns: simulation vs. control vs. planning vs. visualization
- Pub/Sub for state & command transfers, Actions for goal-oriented planning
- Configuration-driven (YAML) for controllers, kinematics, PID gains

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Orchestration
    Launch["Launch Coordinator\n(launch_all_with_rviz.launch.py)"]:::orchestration
    click Launch "https://github.com/petoadam/ros2_sim/blob/main/launch_all_with_rviz.launch.py"

    %% Description & Modeling Layer
    subgraph "Description & Modeling" 
        desc_pkg["ros2_sim_ur3_description\n(C++/Python)"]:::description
        URDF["robot.urdf\n(XACRO)"]:::description
        Meshes["meshes/"]:::description
        SRDF["ur3.srdf"]:::description
        RVizConfig["robot.rviz\nplanner.rviz"]:::description
        LaunchDesc["display.launch.py\nplanner.launch.py\nsimulation.launch.py"]:::description
    end
    click desc_pkg "https://github.com/petoadam/ros2_sim/tree/main/src/ros2_sim_ur3_description"
    click URDF "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_ur3_description/urdf/robot.urdf"
    click Meshes "https://github.com/petoadam/ros2_sim/tree/main/src/ros2_sim_ur3_description/meshes/"
    click SRDF "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_moveit_config/config/ur3.srdf"
    click RVizConfig "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_ur3_description/rviz/robot.rviz"
    click RVizConfig "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_ur3_description/rviz/planner.rviz"
    click LaunchDesc "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_ur3_description/launch/display.launch.py"

    %% Simulation Layer
    subgraph "Physics Simulation" 
        sim_pkg["ros2_sim_simulation\n(C++)"]:::simulation
        SimNode["simulation_node"]:::simulation
        SimConfig["simulation_config.yaml"]:::simulation
        SimLaunch["simulation.launch.py"]:::simulation
    end
    click sim_pkg "https://github.com/petoadam/ros2_sim/tree/main/src/ros2_sim_simulation"
    click SimNode "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_simulation/src/simulation_node.cpp"
    click SimConfig "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_simulation/config/simulation_config.yaml"
    click SimLaunch "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_simulation/launch/simulation.launch.py"

    %% Control Interface Layer
    subgraph "Control Interface" 
        control_pkg["ros2_sim_control\n(C++)"]:::control
        Hardware["robot_hardware.cpp\nrobot_hardware.hpp"]:::control
        CtrlConfig["robot_controller.yaml"]:::control
        CtrlLaunch["ros2_sim_control.launch.py"]:::control
        URDFCtrl["robot.urdf"]:::control
    end
    click control_pkg "https://github.com/petoadam/ros2_sim/tree/main/src/ros2_sim_control"
    click Hardware "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_control/hardware/robot_hardware.cpp"
    click CtrlConfig "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_control/bringup/config/robot_controller.yaml"
    click CtrlLaunch "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_control/bringup/launch/ros2_sim_control.launch.py"
    click URDFCtrl "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_control/description/urdf/robot.urdf"

    %% PID Controller Layer
    subgraph "Low-Level Actuation (PID)" 
        pid_pkg["ros2_sim_pid_controller\n(C++)"]:::control
        PIDNode["pid_controller_node"]:::control
        PIDConfig["pid_controller_config.yaml"]:::control
        PIDLaunch["pid_controller.launch.py"]:::control
    end
    click pid_pkg "https://github.com/petoadam/ros2_sim/tree/main/src/ros2_sim_pid_controller"
    click PIDNode "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_pid_controller/src/pid_controller_node.cpp"
    click PIDConfig "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_pid_controller/config/pid_controller_config.yaml"
    click PIDLaunch "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_pid_controller/launch/pid_controller.launch.py"

    %% Planning Layer
    subgraph "Motion Planning" 
        subgraph "MoveIt2 Integration"
            moveit_pkg["ros2_sim_moveit_config"]:::planning
            Kinematics["kinematics.yaml\njoint_limits.yaml"]:::planning
            Controllers["moveit_controllers.yaml\nros2_controllers.yaml"]:::planning
            URDFMoveIt["ur3.urdf.xacro"]:::planning
            SRDFMoveIt["ur3.srdf"]:::planning
            RVizMove["moveit.rviz"]:::planning
            MoveItLaunch["move_group.launch.py\nmoveit_rviz.launch.py"]:::planning
        end
        subgraph "Custom Planner"
            planner_pkg["ros2_sim_motion_planner\nros2_sim_msgs"]:::planning
            PlannerNode["motion_planner_node"]:::planning
            ActionDef["PlanAndExecute.action"]:::planning
            PlannerLaunch["motion_planner.launch.py"]:::planning
        end
    end
    click moveit_pkg "https://github.com/petoadam/ros2_sim/tree/main/src/ros2_sim_moveit_config"
    click Kinematics "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_moveit_config/config/kinematics.yaml"
    click Controllers "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_moveit_config/config/moveit_controllers.yaml"
    click URDFMoveIt "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_moveit_config/config/ur3.urdf.xacro"
    click SRDFMoveIt "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_moveit_config/config/ur3.srdf"
    click RVizMove "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_moveit_config/config/moveit.rviz"
    click MoveItLaunch "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_moveit_config/launch/move_group.launch.py"
    click planner_pkg "https://github.com/petoadam/ros2_sim/tree/main/src/ros2_sim_motion_planner"
    click PlannerNode "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_motion_planner/src/command_listener_node.cpp"
    click ActionDef "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_msgs/action/PlanAndExecute.action"
    click PlannerLaunch "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_motion_planner/launch/motion_planner.launch.py"

    %% State Gateway Layer
    subgraph "State Gateway" 
        gateway_pkg["ros2_sim_gateway\n(C++)"]:::control
        GatewayNode["joint_states_listener"]:::control
        GatewayLaunch["ros2_sim_gateway.launch.py"]:::control
    end
    click gateway_pkg "https://github.com/petoadam/ros2_sim/tree/main/src/ros2_sim_gateway"
    click GatewayNode "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_gateway/src/joint_states_listener.cpp"
    click GatewayLaunch "https://github.com/petoadam/ros2_sim/blob/main/src/ros2_sim_gateway/launch/ros2_sim_gateway.launch.py"

    %% Visualization & UI Layer
    subgraph "Visualization & UI"
        RViz2["RViz2"]:::viz
        WebUI["Web UI (placeholder)"]:::viz
    end

    %% Data Flows
    Launch --> desc_pkg
    desc_pkg --> SimNode
    SimNode -->|"joint_states"| control_pkg
    SimNode -->|"joint_states"| gateway_pkg
    control_pkg -->|"desired_positions"| PIDNode
    PIDNode -->|"joint_efforts"| SimNode
    moveit_pkg -->|"trajectory"| control_pkg
    planner_pkg -->|"PlanAndExecute action"| PlannerNode
    PlannerNode -->|"trajectory"| control_pkg
    gateway_pkg -->|"gateway topics"| WebUI
    SimNode --> RViz2
    control_pkg --> RViz2
    moveit_pkg --> RViz2

    %% Styles
    classDef description fill:#d3c1f2,stroke:#8e73c2
    classDef simulation fill:#a3d5f2,stroke:#3a9ecb
    classDef control fill:#c2e7c2,stroke:#6bbf6b
    classDef planning fill:#f2c29d,stroke:#e07b36
    classDef viz fill:#e0e0e0,stroke:#8a8a8a
    classDef orchestration fill:#a0e0e0,stroke:#36b0af
```
