# yogangsingh/gui-for-marus architecture

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

- Interactive diagram: https://gitdiagram.com/yogangsingh/gui-for-marus
- Repository: https://github.com/yogangsingh/gui-for-marus

## Overview

##### Core Components
- ROS Environment & Nodes: This includes the fundamental ROS setup (as noted by package.xml, launch files, and srv definitions). It hosts the control algorithms (like the PID controller for USV path following) and provides sensor and command data.
- gRPC Adapter: Found in the “grpc_ros_adapter” directory, this module contains the Python code for translating messages between ROS and Unity. It includes submodules for different services (ping service, parameter server, simulation control, visualization, etc.), message translators, and utilities that manage ROS callbacks and topic streaming.
- Graphical User Interface (GUI): Residing in the “gui” directory, this component (developed in C++ using Qt – evident from the .ui files and mainwindow files) displays real‑time USV metrics, enables waypoint selection, and acts as the user interaction layer.
- Unity Simulation: An external simulation component (referenced in the README and associated with the MARUSimulator ecosystem) where the Unity project consumes gRPC messages, translates them via Protobuf, and renders the dynamics of the USV.
- Configuration & Build Tools: Supplementary components include configuration files (config/server.yaml) and build systems (CMakeLists.txt, package.xml, setup.py) that integrate and manage both the ROS and GUI portions.

##### Relationships & Interactions
- The GUI sends commands (e.g. selected waypoints and mode changes) to the ROS system via the gRPC adapter.
- The gRPC adapter receives these requests, translates them into ROS messages (using Protobuf), and routes them to the appropriate ROS nodes or services (like the simulation control or sensor callbacks).
- The ROS nodes process these messages using onboard controllers (including the PID control) and publish USV telemetry such as location, heading, and other sensor data.
- Processed telemetry data is routed back through the gRPC adapter, converted to a protobuf message format, and transmitted to both the GUI and the Unity simulation, thereby ensuring real-time feedback.
- External setups (like the Unity scene and simulation configuration) connect to the gRPC server to maintain synchronization with the ROS system.
- The configuration file (server.yaml) holds necessary parameters for the gRPC server’s operation and might dictate communication ports/IP addresses.

##### Architectural Patterns & Technologies
- Service/Adapter Pattern: The gRPC adapter is a central bridge that decouples the ROS backend from the Unity-based simulation and GUI front-end.
- Client-Server Architecture: The ROS system runs as a “server” handling various services (exposed via gRPC) that are triggered by “clients” – notably the GUI and external Unity simulation.
- Integration of Diverse Stacks:
- ROS (specifically Noetic) for distributed control and communication.
- gRPC and Protobuf for efficient, structured message passing.
- Qt/C++ for the GUI interface.
- Unity (with the MARUSimulator ecosystem) for real-time simulation.
- CMake and Python-based build and configuration tools to integrate these components.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Configuration & Build Tools
    subgraph "Configuration & Build Tools"
        Config_File["Config (server.yaml)"]:::configuration
        CMake["CMakeLists.txt"]:::configuration
        Setup["setup.py"]:::configuration
        Build_Pkg["package.xml (Build)"]:::configuration
    end

    %% GUI Frontend
    subgraph "GUI Frontend"
        GUI_MainWindow["Main Window (mainwindow.ui)\n(automode.ui, mainwindow.cpp)"]:::gui
    end

    %% gRPC Adapter
    subgraph "gRPC Adapter"
        GRPC_Server["Server (server.py)"]:::grpc
        GRPC_Msg["Message Translator (msg_translator.py)"]:::grpc
        GRPC_Services["Services (services)"]:::grpc
        GRPC_Nav["Navigation Callbacks (nav_callbacks)"]:::grpc
        GRPC_Proto["Protobuf (protobuf)"]:::grpc
        GRPC_Utils["Utils (utils)"]:::grpc
    end

    %% ROS Core & PID Controller
    subgraph "ROS Core & PID Controller"
        ROS_Pkg["package.xml (ROS)"]:::ros
        ROS_Launch["Launch Files (launch_server.launch, launch_bts_tutorial.launch)"]:::ros
        ROS_Ping["Ping Service (srv/Ping.srv)"]:::ros
    end

    %% Unity Simulation Engine
    subgraph "Unity Simulation Engine"
        Unity["Unity Simulation Engine"]:::simulation
    end

    %% Inter-component Communications
    GUI_MainWindow -->|"gRPC_call"| GRPC_Server
    GRPC_Server -->|"ROS_Msg"| ROS_Launch
    ROS_Launch -->|"Telemetry"| GRPC_Server
    GRPC_Server -->|"Telemetry"| GUI_MainWindow
    GRPC_Server -->|"Telemetry"| Unity

    Config_File -->|"Config_Data"| GRPC_Server
    Config_File -->|"Config_Data"| ROS_Launch
    Build_Pkg -->|"Build_Data"| GRPC_Server
    Build_Pkg -->|"Build_Data"| ROS_Pkg
    CMake -->|"BuildCommands"| GRPC_Server
    CMake -->|"BuildCommands"| ROS_Pkg
    Setup -->|"Setup"| GRPC_Server

    %% Internal gRPC Adapter structure
    GRPC_Server --> GRPC_Msg
    GRPC_Server --> GRPC_Services
    GRPC_Server --> GRPC_Nav
    GRPC_Server --> GRPC_Proto
    GRPC_Server --> GRPC_Utils

    %% Click Events for ROS Environment & Nodes
    click ROS_Pkg "https://github.com/yogangsingh/gui-for-marus/blob/dev/package.xml"
    click ROS_Launch "https://github.com/yogangsingh/gui-for-marus/blob/dev/launch/launch_server.launch"
    click ROS_Ping "https://github.com/yogangsingh/gui-for-marus/blob/dev/srv/Ping.srv"

    %% Click Events for gRPC Adapter
    click GRPC_Server "https://github.com/yogangsingh/gui-for-marus/blob/dev/grpc_ros_adapter/server.py"
    click GRPC_Msg "https://github.com/yogangsingh/gui-for-marus/blob/dev/grpc_ros_adapter/msg_translator.py"
    click GRPC_Services "https://github.com/yogangsingh/gui-for-marus/tree/dev/grpc_ros_adapter/services"
    click GRPC_Nav "https://github.com/yogangsingh/gui-for-marus/tree/dev/grpc_ros_adapter/nav_callbacks"
    click GRPC_Proto "https://github.com/yogangsingh/gui-for-marus/tree/dev/grpc_ros_adapter/protobuf"
    click GRPC_Utils "https://github.com/yogangsingh/gui-for-marus/tree/dev/grpc_ros_adapter/utils"

    %% Click Events for GUI Frontend
    click GUI_MainWindow "https://github.com/yogangsingh/gui-for-marus/blob/dev/gui/marus_gui/mainwindow.ui"

    %% Click Events for Configuration & Build Tools
    click Config_File "https://github.com/yogangsingh/gui-for-marus/blob/dev/config/server.yaml"
    click CMake "https://github.com/yogangsingh/gui-for-marus/blob/dev/CMakeLists.txt"
    click Setup "https://github.com/yogangsingh/gui-for-marus/blob/dev/setup.py"
    click Build_Pkg "https://github.com/yogangsingh/gui-for-marus/blob/dev/package.xml"

    %% Styling classes
    classDef configuration fill:#f9e79f,stroke:#b7950b,stroke-width:2px;
    classDef ros fill:#aed6f1,stroke:#1f618d,stroke-width:2px;
    classDef grpc fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef gui fill:#f5cba7,stroke:#d35400,stroke-width:2px;
    classDef simulation fill:#e8daef,stroke:#8e44ad,stroke-width:2px;
```
