# alexfigas/usv architecture

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

- Interactive diagram: https://gitdiagram.com/alexfigas/usv
- Repository: https://github.com/alexfigas/usv

## Overview

##### Project Type and Purpose
- From the README (“USV – Master Thesis code and documentation”) and the structured folders in src (GPS, IMU, communication, USV), the project is focused on controlling or monitoring an unmanned surface vehicle using sensor input and wireless communication.
- The project likely interfaces with hardware (Arduino/ESP boards, as seen by the Arduino .ino sketches in the docs folder for ESP-32, among others), suggesting it’s an embedded application with real-time sensor reading and control logic.

##### File Structure
- Top-level components: Several directories (docs, src, lib, include, test, examples) indicate that documentation, source code, auxiliary libraries, and test cases are all maintained.
- In the src directory, you see clear separation into:
- GPS: Contains modules such as GPSData and sensor-specific code (e.g., GPS_BN880.cpp) handling GPS sensor data.
- IMU: Contains modules for inertial measurement unit data processing (IMUData and IMU_ICM_20948).
- communication: Has a LoRaSender module, which likely manages the wireless communication aspect.
- USV: Contains usv.cpp and usv.h that potentially encapsulate the core USV/control logic.
- A central main.cpp that brings all modules together.
- Other folders like docs provide supporting materials such as datasheets, manuals, and example sketches that show how different hardware components (motor drivers, I2C scanners, etc.) are intended to be used.

a. Main Components to Represent:
- Hardware Interface Layer:
- Sensors (GPS module, IMU sensor)
- Communication hardware (LoRa transceiver)
- Motor control or other actuators (implied by TurnOut programs and motor driver datasheets in docs)
- Software Layers:
- Sensor Abstraction Modules: Represent the GPS and IMU modules (src/GPS and src/IMU) where low-level sensor data acquisition and processing occur.
- Communication Module: Represent the LoRaSender (src/communication) component that handles wireless data transmission.
- USV Core Module: Represent the usv.cpp from src/USV that acts as the control center for vehicle behavior.
- Main Application: The main.cpp acts as the orchestrator that integrates the modules.
- Supporting Components:
- Libraries (Utils and UtilsBoards in docs/Programas/Libraries) which provide auxiliary functionality.
- Test and Example suites for validation and demonstration.
- Documentation that supports system understanding.

b. Relationships and Interactions:
- The USV module’s decisions and control signals then interact with actuators (not explicitly detailed in the src but implied by the documentation).
- LoRaSender sends telemetry or commands likely resulting from processed sensor data.
- The main.cpp “central hub” should be drawn linking these modules by calling on the sensor modules, then feeding that into the USV control and communication modules.

c. Architectural Patterns or Design Principles:
- Modular design: Each sensor/component is encapsulated in its own module (as seen in separate folders under src).
- Separation of concerns: Sensor data acquisition, vehicle control (USV), and wireless communication are clearly distinct.
- Scalability and reusability: The presence of libraries under docs/Programas/Libraries/ indicates that common utilities are factored out.
- Real-time data processing for embedded systems.

d. Relevant Technologies and Frameworks:
- Embedded development toolchain (PlatformIO indicated by platformio.ini).
- Hardware-specific code (Arduino sketches, C++ code in src).
- Communication protocols (LoRa) and sensor interfaces (I2C for IMU, Serial/GPS protocols).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Interface Layer
    subgraph "Hardware Interface"
        GPS_HW("GPS Sensor Hardware"):::hardware
        IMU_HW("IMU Sensor Hardware"):::hardware
        LoRa_HW("LoRa Transceiver"):::hardware
    end

    %% Software Layers
    subgraph "Software Layers"
        MAIN("Main Application (src/main.cpp)"):::mainApp
        subgraph "Sensor Abstraction Modules"
            GPS_MOD("GPS Module (src/GPS)"):::sensor
            IMU_MOD("IMU Module (src/IMU)"):::sensor
        end
        USV_CORE("USV Control (src/USV)"):::control
        LORA_COMM("LoRa Communication (src/communication)"):::comm
    end

    %% Supporting Libraries
    subgraph "Supporting Libraries"
        UTILS("Utils Library"):::lib
        UTILS_BOARDS("UtilsBoards Library"):::lib
    end

    %% Data Flow Connections from Main Application
    MAIN -->|"calls"| GPS_MOD
    MAIN -->|"calls"| IMU_MOD
    MAIN -->|"calls"| USV_CORE
    MAIN -->|"calls"| LORA_COMM

    %% Sensor Modules feed into USV Core
    GPS_MOD -->|"sendsData"| USV_CORE
    IMU_MOD -->|"sendsData"| USV_CORE

    %% USV Core sends commands to Communication Module
    USV_CORE -->|"commands"| LORA_COMM

    %% Hardware Connections to Sensor/Communication Modules
    GPS_HW -->|"providesData"| GPS_MOD
    IMU_HW -->|"providesData"| IMU_MOD
    LoRa_HW -->|"interfacesWith"| LORA_COMM

    %% Supporting Libraries provide auxiliary functions to Main Application
    UTILS -.->|"supports"| MAIN
    UTILS_BOARDS -.->|"supports"| MAIN

    %% Click Events for Component Mapping
    click GPS_MOD "https://github.com/alexfigas/usv/tree/main/src/GPS"
    click IMU_MOD "https://github.com/alexfigas/usv/tree/main/src/IMU"
    click LORA_COMM "https://github.com/alexfigas/usv/tree/main/src/communication"
    click USV_CORE "https://github.com/alexfigas/usv/tree/main/src/USV"
    click MAIN "https://github.com/alexfigas/usv/blob/main/src/main.cpp"
    click UTILS "https://github.com/alexfigas/usv/tree/main/docs/Programas/Libraries/Utils"
    click UTILS_BOARDS "https://github.com/alexfigas/usv/tree/main/docs/Programas/Libraries/UtilsBoards"

    %% Style Definitions
    classDef sensor fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef control fill:#A9DFBF,stroke:#28B463,stroke-width:2px;
    classDef comm fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
    classDef mainApp fill:#D2B4DE,stroke:#884EA0,stroke-width:2px;
    classDef lib fill:#D5DBDB,stroke:#7B7D7D,stroke-width:2px;
    classDef hardware fill:#FAD7A0,stroke:#D68910,stroke-width:2px;
```
