# mcgill-robotics/auv-2025 architecture

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

- Interactive diagram: https://gitdiagram.com/mcgill-robotics/auv-2025
- Repository: https://github.com/mcgill-robotics/auv-2025

## Overview

Based on our analysis of the file tree and README, this project is an autonomous underwater vehicle (AUV) software system built for the Douglas AUV intended for RoboSub2025. It is built on top of ROS (using a Catkin workspace) and is structured as a modular robotics software suite with several core functionalities (controls, planner, propulsion, sensors, state estimation, vision, simulation) combined with Docker‐based deployment support for different target platforms (e.g., Jetson, poolside, simulated environments, etc.).

##### And Group the Main Components
- Hardware & Deployment Containers:
- Docker directory shows multiple Dockerfiles (for different hardware targets like Jetson, poolside, trottier, sim). Represent these as separate “deployment containers” that encapsulate the software runtime environments.
- ROS-Based Software Modules (inside catkin_ws):
- Controls: Contains PID controllers, quaternion handling, and server components (under catkin_ws/src/controls).
- Planner: Handles mission planning, joystick input, and various search/maneuver strategies.
- Propulsion: Deals with thrust mapping and driving the physical propulsion mechanisms.
- Sensors: Manages sensor data acquisition (IMU, DVL, hydrophones, etc.) and calibration.
- State Estimation: Takes in sensor input to determine the vehicle’s state (localization, depth, orientation).
- Vision: Handles camera input, object detection (YOLO models are referenced), image processing, lane marker measurements.
- Simulation: Provides a simulation environment using custom packages (sim folder) and an endpoint for TCP communication with Unity (ROS TCP endpoint modules).
- Communication Infrastructure:
- ROS Launch files: Launch files in each module indicate orchestration of node startup sequences.
- Supporting Infrastructure:
- Scripts: Helper scripts exist for tasks like setting environment variables, clearing ports, etc.
- CI/CD Workflow: GitHub workflows and associated files show automated deployment/CI processes.
- Configuration Files: YAML configuration files exist for sensors and deployment, emphasizing adjustable parameters.

##### Detail Relationships and Data Flows
- For example, sensor nodes (in Sensors) send data to State Estimation and Planner.
- Planner commands through Controls which subsequently drive Propulsion.
- Vision components perform object detection and feed results to the Planner or even State Estimation.
- Docker containers encapsulate these modules, so highlight interactions between containerized environments and the hardware deployment targets (e.g., Jetson board handling real sensor input).
- Interactions between simulation and real-time control: The Sim package provides a TCP endpoint which could be integrated with simulation environments (e.g., Unity) for testing.

##### Architectural Patterns and Design Principles
- Modular Design: The clear separation of concerns (controls, sensors, planning, etc.) follows a modular design pattern typical in ROS-based projects.
- Message-Driven Communication: Emphasize the usage of ROS messaging patterns (topics, actions, and messages defined in auv_msgs).
- Containerization and Deployment: Docker’s presence under multiple folders reflects the need for reproducible environments across different platforms (embedded, simulation, etc.).

##### Specific Technologies and Frameworks
- ROS (Robot Operating System) and Catkin: The backbone for node management and inter-module communication.
- Docker: Used for containerized builds and ensuring consistency across platforms.
- Specific Sensor Drivers & Models: YAML config files for sensors, deep learning models for vision (YOLO).
- CI/CD Workflows: Provided in the .github and Docker directories to support automated testing and deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Deployment Containers
    subgraph "Deployment Containers"
        DockerJetson["Docker: Jetson"]:::container
        DockerPoolside["Docker: Poolside"]:::container
        DockerSim["Docker: Sim"]:::container
        DockerTrottier["Docker: Trottier"]:::container
    end

    %% ROS Network
    subgraph "ROS Network"
        ROSMsgs["ROS Messages (auv_msgs)"]:::ros
        Controls["Controls Module"]:::module
        Planner["Planner Module"]:::module
        Propulsion["Propulsion Module"]:::module
        Sensors["Sensors Module"]:::module
        StateEst["State Estimation Module"]:::module
        Vision["Vision Module"]:::module
        Simulation["Simulation Module"]:::module
    end

    %% External Systems
    subgraph "External Systems"
        Unity["Unity Simulation"]:::external
    end

    %% Supporting Infrastructure
    subgraph "Supporting Infrastructure"
        CI_CD["CI/CD Workflows (.github)"]:::support
        Scripts["Helper Scripts"]:::support
    end

    %% Data and Control Flows among ROS Modules
    Sensors -->|"data"| StateEst
    Sensors -->|"data"| Planner
    Vision -->|"detection"| Planner
    Vision -->|"detection"| StateEst
    Planner -->|"commands"| Controls
    Controls -->|"actuation"| Propulsion

    %% Interactions with ROS Messages (auv_msgs)
    ROSMsgs --- Controls
    ROSMsgs --- Planner
    ROSMsgs --- Sensors
    ROSMsgs --- StateEst
    ROSMsgs --- Vision
    ROSMsgs --- Simulation

    %% Simulation interacts with external simulation environment
    Simulation -->|"TCP_Endpoint"| Unity

    %% Docker Containers encapsulate parts of the ROS network
    DockerJetson --- Controls
    DockerJetson --- Sensors
    DockerJetson --- Propulsion
    DockerPoolside --- Sensors
    DockerSim --- Simulation
    DockerTrottier --- Planner

    %% Supporting Infrastructure connected to key ROS components
    CI_CD --- ROSMsgs
    Scripts --- ROSMsgs
    Scripts --- Controls
    Scripts --- Planner

    %% Class Definitions with Colors
    classDef container fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef ros fill:#ccffcc,stroke:#00cc00,stroke-width:2px;
    classDef module fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef support fill:#fff2cc,stroke:#e69500,stroke-width:2px;
    classDef external fill:#e6ccff,stroke:#6600cc,stroke-width:2px;

    %% Click Events for Deployment Containers
    click DockerJetson "https://github.com/mcgill-robotics/auv-2025/tree/noetic/Docker/jetson"
    click DockerPoolside "https://github.com/mcgill-robotics/auv-2025/tree/noetic/Docker/poolside"
    click DockerSim "https://github.com/mcgill-robotics/auv-2025/tree/noetic/Docker/sim"
    click DockerTrottier "https://github.com/mcgill-robotics/auv-2025/tree/noetic/Docker/trottier"

    %% Click Events for ROS Modules and Messages
    click Controls "https://github.com/mcgill-robotics/auv-2025/tree/noetic/catkin_ws/src/controls"
    click Planner "https://github.com/mcgill-robotics/auv-2025/tree/noetic/catkin_ws/src/planner"
    click Propulsion "https://github.com/mcgill-robotics/auv-2025/tree/noetic/catkin_ws/src/propulsion"
    click Sensors "https://github.com/mcgill-robotics/auv-2025/tree/noetic/catkin_ws/src/sensors"
    click StateEst "https://github.com/mcgill-robotics/auv-2025/tree/noetic/catkin_ws/src/state_estimation"
    click Vision "https://github.com/mcgill-robotics/auv-2025/tree/noetic/catkin_ws/src/vision"
    click Simulation "https://github.com/mcgill-robotics/auv-2025/tree/noetic/catkin_ws/src/sim"
    click ROSMsgs "https://github.com/mcgill-robotics/auv-2025/tree/noetic/catkin_ws/src/auv_msgs"

    %% Click Events for Supporting Infrastructure
    click CI_CD "https://github.com/mcgill-robotics/auv-2025/blob/noetic/.github"
    click Scripts "https://github.com/mcgill-robotics/auv-2025/tree/noetic/scripts"
```
