# uuvsimulator/uuv_simulator architecture

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

- Interactive diagram: https://gitdiagram.com/uuvsimulator/uuv_simulator
- Repository: https://github.com/uuvsimulator/uuv_simulator

## Overview

##### Project type and purpose
- This is a modular ROS/Gazebo simulation framework (“uuv_simulator”) for Unmanned Underwater Vehicles. It provides:
- Gazebo physics and sensor plugins (C++)
- ROS message/service definitions
- Vehicle/world models (URDF/Xacro, SDF)
- ROS controller nodes (Python/C++)
- Teleop and assistant scripts
- Tutorial/launch infrastructure

##### High‐level architectural components
a. Simulation Core
– Gazebo Simulator (physics engine + SDF world loader)
b. Gazebo Plugins
– Hydrodynamics & inertial plugins (uuv_gazebo_plugins)
– Thruster & fin plugins
– World plugins (underwater current models)
– Sensor plugins (IMU, DVL, GPS, pressure, RPT, camera)
– ROS interface plugins (uuv_gazebo_ros_plugins & uuv_sensor_ros_plugins)
c. Models
– Vehicle descriptions (URDF/Xacro, meshes) in uuv_descriptions
– World definitions & assets (uuv_gazebo_worlds)
d. ROS Communication
– Topics (state feedback, sensor data, thruster commands)
– Services (set parameters, get model properties, change sensor state)
– Message/service definitions (uuv_control_msgs, uuv_sensor_plugins_msgs, uuv_world_ros_plugins_msgs)
e. Control Layer (ROS nodes)
– Thruster manager (uuv_thruster_manager)
– Control allocator (uuv_auv_control_allocator)
– PID, sliding mode, geometric controllers (uuv_control_cascaded_pids, uuv_trajectory_control)
– Utility nodes (uuv_control_utils)
f. Teleop & Assistants
– Teleoperation scripts (uuv_teleop)
– Automation helpers & launch scripts (uuv_assistants)
g. Tutorials & Demos
– Pre‐configured launch files & example worlds/scripts (uuv_tutorials)

##### Relationships and data flows
- Gazebo loads world (SDF) and vehicle (URDF) models.
- Gazebo plugins compute physics (forces, currents, hydrodynamics) and publish sensor data to ROS topics via ROS‐interface plugins.
- Controller ROS nodes subscribe to sensor/state topics (and /tf transforms), compute control actions, and publish desired wrench/thruster commands.
- Thruster manager node converts high‐level wrench commands into individual thruster commands and publishes them to the thruster plugin topics.
- Teleop nodes generate setpoints (e.g. joystick → cmd_vel) feeding into controllers.
- Services allow dynamic reconfiguration (e.g. set current velocity, enable/disable sensors).

##### Key architectural patterns and principles
- ROS modularity: each package is a self‐contained component providing nodes, plugins, messages, launch files.
- Publisher/subscriber for streaming data; services for parameter/configuration.
- Gazebo plugin pattern: separate C++ plugins for dynamics, sensors, world, each exposing ROS interfaces.
- Clear separation of concerns: simulation (Gazebo + plugins) vs. control (ROS nodes) vs. utilities/launch.
- Use of standard ROS build tools (Catkin/CMake) and ROS message/service definitions for interoperability.

##### Technologies, frameworks, and libraries
- Gazebo (physics, rendering, plugin API)
- ROS (nodes, topics, services, launch)
- C++ (plugins, high‐performance code)
- Python (ROS scripts, controllers, helpers)
- Xacro/URDF (vehicle descriptions)
- SDF (world definitions)
- CasADi (optional in control allocator)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Simulation Core
    subgraph "Simulation Core"
        style SimulationCore fill:#D0E6FF,stroke:#0080FF,stroke-width:2px
        SimulationCore["Gazebo Simulator"]:::sim
    end

    %% Gazebo Plugins
    subgraph "Gazebo Plugins"
        style GazeboPlugins fill:#D0E6FF,stroke:#0080FF,stroke-width:2px
        PhysicsPlugins["uuv_gazebo_plugins"]:::sim
        RosInterfacePlugins["uuv_gazebo_ros_plugins"]:::sim
        WorldPlugins["uuv_world_plugins"]:::sim
        WorldRosPlugins["uuv_world_ros_plugins"]:::sim
        SensorPlugins["uuv_sensor_ros_plugins"]:::sim
    end

    %% Models
    subgraph "Models"
        style Models fill:#E8E8E8,stroke:#888888,stroke-width:2px
        VehicleDesc["uuv_descriptions"]:::model
        WorldAssets["uuv_gazebo_worlds"]:::model
    end

    %% ROS Communication
    subgraph "ROS Communication"
        style ROSComm fill:#FFF5CC,stroke:#FFCC00,stroke-width:2px
        ControlMsgs["uuv_control_msgs"]:::msg
        SensorMsgs["uuv_sensor_ros_plugins_msgs"]:::msg
    end

    %% Control Layer
    subgraph "Control Layer"
        style ControlLayer fill:#DFFFE0,stroke:#33AA00,stroke-width:2px
        ThrusterMgr["uuv_thruster_manager"]:::node
        Allocator["uuv_auv_control_allocator"]:::node
        PIDControllers["uuv_control_cascaded_pids"]:::node
        TrajControl["uuv_trajectory_control"]:::node
        Utils["uuv_control_utils"]:::node
    end

    %% Teleop & Assistants
    subgraph "Teleop & Assistants"
        style Teleop fill:#FFE0B3,stroke:#FF8C00,stroke-width:2px
        Teleop["uuv_teleop"]:::script
        Assistants["uuv_assistants"]:::script
    end

    %% Tutorials & Demos
    subgraph "Tutorials & Demos"
        style Tutorials fill:#FFE0B3,stroke:#FF8C00,stroke-width:2px
        Tutorials["uuv_tutorials"]:::script
    end

    %% ROS Master
    ROSMaster["ROS Master"]:::node

    %% Flows
    SimulationCore --> PhysicsPlugins
    SimulationCore --> WorldPlugins
    SimulationCore --> SensorPlugins
    PhysicsPlugins --> RosInterfacePlugins --> ROSMaster
    WorldPlugins --> WorldRosPlugins --> ROSMaster
    SensorPlugins --> SensorMsgs --> ROSMaster
    ROSMaster --> ThrusterMgr
    ThrusterMgr -->|"thruster_cmds"| RosInterfacePlugins
    ROSMaster --> PIDControllers
    ROSMaster --> Allocator
    ROSMaster --> TrajControl
    ROSMaster --> Utils
    Teleop --> ROSMaster
    Assistants --> ROSMaster
    Tutorials --> ROSMaster
    VehicleDesc --> SimulationCore
    WorldAssets --> SimulationCore

    %% Click Events
    click SimulationCore "https://github.com/uuvsimulator/uuv_simulator/tree/master/uuv_gazebo/"
    click PhysicsPlugins "https://github.com/uuvsimulator/uuv_simulator/tree/master/uuv_gazebo_plugins/uuv_gazebo_plugins/"
    click RosInterfacePlugins "https://github.com/uuvsimulator/uuv_simulator/tree/master/uuv_gazebo_plugins/uuv_gazebo_ros_plugins/"
    click WorldPlugins "https://github.com/uuvsimulator/uuv_simulator/tree/master/uuv_world_plugins/uuv_world_plugins/"
    click WorldRosPlugins "https://github.com/uuvsimulator/uuv_simulator/tree/master/uuv_world_plugins/uuv_world_ros_plugins/"
    click VehicleDesc "https://github.com/uuvsimulator/uuv_simulator/tree/master/uuv_descriptions/"
    click WorldAssets "https://github.com/uuvsimulator/uuv_simulator/tree/master/uuv_gazebo_worlds/"
    click SensorPlugins "https://github.com/uuvsimulator/uuv_simulator/tree/master/uuv_sensor_plugins/uuv_sensor_ros_plugins/"
    click SensorMsgs "https://github.com/uuvsimulator/uuv_simulator/tree/master/uuv_sensor_plugins/uuv_sensor_ros_plugins_msgs/"
    click ControlMsgs "https://github.com/uuvsimulator/uuv_simulator/tree/master/uuv_control/uuv_control_msgs/"
    click ThrusterMgr "https://github.com/uuvsimulator/uuv_simulator/tree/master/uuv_control/uuv_thruster_manager/"
    click Allocator "https://github.com/uuvsimulator/uuv_simulator/tree/master/uuv_control/uuv_auv_control_allocator/"
    click PIDControllers "https://github.com/uuvsimulator/uuv_simulator/tree/master/uuv_control/uuv_control_cascaded_pids/"
    click TrajControl "https://github.com/uuvsimulator/uuv_simulator/tree/master/uuv_control/uuv_trajectory_control/"
    click Utils "https://github.com/uuvsimulator/uuv_simulator/tree/master/uuv_control/uuv_control_utils/"
    click Teleop "https://github.com/uuvsimulator/uuv_simulator/tree/master/uuv_teleop/"
    click Assistants "https://github.com/uuvsimulator/uuv_simulator/tree/master/uuv_assistants/"
    click Tutorials "https://github.com/uuvsimulator/uuv_simulator/tree/master/uuv_tutorials/"

    %% Styles
    classDef sim fill:#D0E6FF,stroke:#0080FF
    classDef model fill:#E8E8E8,stroke:#888888
    classDef node fill:#DFFFE0,stroke:#33AA00
    classDef msg fill:#FFF5CC,stroke:#FFCC00
    classDef script fill:#FFE0B3,stroke:#FF8C00
```
