# hkpolyu-uav/bluerov2 architecture

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

- Interactive diagram: https://gitdiagram.com/hkpolyu-uav/bluerov2
- Repository: https://github.com/hkpolyu-uav/bluerov2

## Overview

##### Project Type and Purpose
- This is a ROS‐based simulation and control framework for an unmanned underwater vehicle (BlueROV2)
- Provides multi‐node state estimation, path planning, NMPC (and DOB‐MPC) control, plus a Gazebo/UUV simulation environment
- Integrates external libraries (acados), ROS packages (mavros, uuv_simulator), joystick and video streaming

##### File Structure
- Top‐level ROS packages:
– bluerov2_environ: Gazebo world, URDF/XACRO robot models, meshes, launch files
– bluerov2_states: state estimation nodelets, IMU fusion, config, scripts
– bluerov2_path: trajectory definitions, path‐planning node, wrench publisher
– bluerov2_dobmpc / bluerov2_mpc: core control logic, message defs, C++ nodes, config, code-generation scripts
– realsense-ros-gazebo, ros_utilities, uuv_simulator: external simulation & utilities
- Config files: YAML under each package for controllers, thrusters, environment parameters
- CMakeLists, package.xml: build & dependency declarations
- Scripts: code‐generation (generate_c_code.py), plotting, data processing

##### README Insights
- Emphasizes ROS noetic, uuv_simulator, mavros, acados
- Launch workflows: no‐controller simulation, MPC demo, DOB‐MPC demo
- Docker image available

##### Components & Interactions
a. Main Components
1) ROS Master (central broker)
2) Gazebo/UUV Simulator + World (ocean_waves, custom worlds)
3) Robot Description (URDF/XACRO, meshes)
4) Sensor Nodes: IMU, DVL, camera (realsense plugin)
5) State Estimator (bluerov2_states nodelets)
6) Path Planner (bluerov2_path node)
7) Reference Generator (trajectories from config)
8) Controller(s):
– MPC (bluerov2_mpc)
– DOB‐MPC (bluerov2_dobmpc)
– PID / cascade controllers (fallback)
9) acados Solver (external library, C‐code modules)
10) Thruster Manager (in ROS, publishes to Gazebo plugin)
11) Joystick / MAVROS Interface
12) Video Stream (OpenCV)
b. Relationships & Data Flow
– Sensor → /imu, /dvl, /camera topics → State Estimator → /state topic
– Path Planner → /reference topic → Controller nodes
– Controller → /thruster_manager/input → Gazebo actuators
– Gazebo sim → /ground_truth, /sensor topics
– acados library is called by controller nodes (generated C‐code via scripts)
– Joystick/MAVROS → teleop topics → thruster_manager or direct control
c. Architectural Patterns & Principles
– ROS node & pub/sub decoupling
– Modular packages (env, states, path, control)
– Config‐driven (YAML) parameterization
– Automated C‐code generation for real‐time solvers
d. Key Technologies & Frameworks
– ROS Noetic, Gazebo, UUV Simulator
– Acados (NMPC solver)
– C++ / Python nodes, message definitions
– MAVROS, joystick drivers, OpenCV

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Simulation Environment
    subgraph "Simulation Environment"
        Gazebo["Gazebo/UUV Simulator + World"]:::simulation
        GazeboLaunch["Environment Launch"]:::simulation
        URDF["Robot Description (URDF/XACRO)"]:::simulation
        Robots["Robot Models"]:::simulation
        Meshes["Meshes"]:::simulation
    end

    %% Sensing & Estimation
    subgraph "Sensing & Estimation"
        IMUNodelets["IMU Fusion Nodelets"]:::sensing
        IMUSrc["IMU/Dynamics Source"]:::sensing
        Realsense["Realsense Plugin"]:::sensing
        UUVSim["UUV Simulator Sensors"]:::sensing
        StateEstimator["State Estimator (EKF/ESKF)"]:::sensing
    end

    %% Planning & Reference Generation
    subgraph "Planning & Reference Generation"
        PathPlanner["Path Planner Node"]:::planning
        CoreLogic["Planner Core Logic"]:::planning
        ReferenceGen["Reference Generator"]:::planning
    end

    %% Control & Solvers
    subgraph "Control & Solvers"
        DOBMPC["DOB-MPC Controller"]:::control
        MPC["MPC Controller"]:::control
        PIDCtrl["PID/Cascade Controller"]:::control
        Acados["acados Solver (C-Code)"]:::control
    end

    %% Actuation
    subgraph "Actuation"
        ThrusterMgr["Thruster Manager"]:::actuation
    end

    %% Interfaces
    subgraph "Interfaces"
        Joystick["Joystick/MAVROS Interface"]:::interface
        Video["Video Stream (OpenCV)"]:::interface
    end

    %% Central Broker
    ROSMaster(("ROS Master")):::master

    %% Flows
    Gazebo -->|"/ground_truth, /sensor topics"| IMUNodelets
    Gazebo --> IMUSrc
    Gazebo --> Realsense
    Gazebo --> UUVSim

    IMUNodelets -->|"/imu"| StateEstimator
    IMUSrc --> StateEstimator
    Realsense --> StateEstimator
    UUVSim --> StateEstimator

    StateEstimator -->|"/state"| PathPlanner
    PathPlanner -->|"/reference"| DOBMPC
    PathPlanner --> CoreLogic
    ReferenceGen -->|"/reference"| MPC

    DOBMPC -->|"/thruster_manager/input"| ThrusterMgr
    MPC --> ThrusterMgr
    PIDCtrl --> ThrusterMgr

    DOBMPC --> Acados
    MPC --> Acados

    Joystick -->|"/teleop"| ThrusterMgr
    Joystick -->|"/teleop"| PIDCtrl
    Video --> StateEstimator

    %% ROS Master Connections
    ROSMaster --- Gazebo
    ROSMaster --- IMUNodelets
    ROSMaster --- StateEstimator
    ROSMaster --- PathPlanner
    ROSMaster --- DOBMPC
    ROSMaster --- MPC
    ROSMaster --- PIDCtrl
    ROSMaster --- ThrusterMgr
    ROSMaster --- Joystick
    ROSMaster --- Video

    %% Click Events
    click Gazebo "https://github.com/hkpolyu-uav/bluerov2/blob/main/bluerov2_environ/worlds/ocean_waves.world"
    click GazeboLaunch "https://github.com/hkpolyu-uav/bluerov2/blob/main/bluerov2_environ/launch/environ.launch"
    click URDF "https://github.com/hkpolyu-uav/bluerov2/blob/main/bluerov2_environ/urdf/base.xacro"
    click Robots "https://github.com/hkpolyu-uav/bluerov2/blob/main/bluerov2_environ/robots/default.xacro"
    click Meshes "https://github.com/hkpolyu-uav/bluerov2/tree/main/bluerov2_environ/meshes"
    click IMUNodelets "https://github.com/hkpolyu-uav/bluerov2/blob/main/bluerov2_states/plugins/nodelets.xml"
    click IMUSrc "https://github.com/hkpolyu-uav/bluerov2/blob/main/bluerov2_states/src/ImuDo.cpp"
    click Realsense "https://github.com/hkpolyu-uav/bluerov2/tree/main/realsense-ros-gazebo/"
    click UUVSim "https://github.com/hkpolyu-uav/bluerov2/tree/main/uuv_simulator/"
    click StateEstimator "https://github.com/hkpolyu-uav/bluerov2/blob/main/bluerov2_states/src/Eskf.cpp"
    click CoreLogic "https://github.com/hkpolyu-uav/bluerov2/blob/main/bluerov2_path/src/bluerov2_path.cpp"
    click PathPlanner "https://github.com/hkpolyu-uav/bluerov2/blob/main/bluerov2_path/src/bluerov2_path_node.cpp"
    click ReferenceGen "https://github.com/hkpolyu-uav/bluerov2/blob/main/bluerov2_path/config/traj/circle.py"
    click DOBMPC "https://github.com/hkpolyu-uav/bluerov2/blob/main/bluerov2_dobmpc/src/bluerov2_dob_node.cpp"
    click MPC "https://github.com/hkpolyu-uav/bluerov2/blob/main/bluerov2_dobmpc/src/ctrller/mpc.cpp"
    click PIDCtrl "https://github.com/hkpolyu-uav/bluerov2/blob/main/bluerov2_dobmpc/src/ctrller/pid.cpp"
    click Acados "https://github.com/hkpolyu-uav/bluerov2/tree/main/bluerov2_dobmpc/scripts/c_generated_code/"
    click ThrusterMgr "https://github.com/hkpolyu-uav/bluerov2/blob/main/bluerov2_dobmpc/config/thruster_manager.yaml"
    click Joystick "https://github.com/hkpolyu-uav/bluerov2/tree/main/bluerov2_dobmpc/config/teleop/"
    click Video "https://github.com/hkpolyu-uav/bluerov2/blob/main/bluerov2_states/scripts/mpc_plot.py"

    %% Styles
    classDef simulation fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1;
    classDef sensing fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20;
    classDef planning fill:#FFE0B2,stroke:#E65100,color:#E65100;
    classDef control fill:#FFCDD2,stroke:#B71C1C,color:#B71C1C;
    classDef actuation fill:#D1C4E9,stroke:#4A148C,color:#4A148C;
    classDef interface fill:#B2EBF2,stroke:#006064,color:#006064;
    classDef master fill:#FFF9C4,stroke:#F57F17,color:#F57F17;
```
