# nubot-nudt/nubot_ws architecture

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

- Interactive diagram: https://gitdiagram.com/nubot-nudt/nubot_ws
- Repository: https://github.com/nubot-nudt/nubot_ws

## Overview

##### Project Type and Purpose
- TYPE: A robotic soccer system, built on the ROS (Robot Operating System) framework.

##### File Structure
- The top-level directories (e.g., src, doc, .catkin_workspace) indicate a catkin workspace and multiple ROS packages.
- Several packages are clearly identifiable:
- Modules for camera drivers (e.g., camera_umd, prosilica_driver)
- Vision and calibration functionalities (e.g., nubot/front_vision, nubot/omni_vision, color_segment)
- Core libraries and messaging (nubot_common, world_model)
- Control and hardware interfacing (nubot_control, nubot_hwcontroller, joystick_drivers)
- Simulation interface and plotting tools (simulation_interface, 2D_Plot_Tool)
- CMakeLists.txt and package.xml files in each package indicate standard ROS build and dependency management practices.

##### Extract Insights from the README
- It explains launch sequences for real robot operations versus simulation.
- It highlights how the different modules are invoked (e.g., using roslaunch commands for nubot_common, nubot_hwcontroller, etc.).
- It mentions specific dependencies like Qt (for GUI-based calibration in the color_segment package) and ncurses for hardware controller components.

a. Main Components to Include:
- ROS Master / Communication Backbone
- Sensor/Driver Nodes:
- Camera modules (camera_umd – including jpeg_streamer & uvc_camera; prosilica_driver components)
- Joystick driver nodes (joystick_drivers)
- Vision Processing:
- Front Vision and Omni Vision nodes (nubot/front_vision, nubot/omni_vision)
- Control Modules:
- Nubot Control (nubot_control) which likely processes sensor inputs and generates motion commands.
- Nubot Hardware Controller (nubot_hwcontroller) for low-level actuation and interfacing.
- Data and World Modeling:
- Nubot Common and World Model nodes (nubot_common, world_model) which aggregate sensor data and may provide decision making or coordination.
- Simulation Interfaces:
- Simulation spawn scripts and simulation_interface package for simulated robot instances.
- Supporting Tools:
- Realtime tools and other utility packages supporting timing and data publishing.

b. Demarcate Relationships/Interactions:
- For example: Camera nodes publish image data → Vision nodes subscribe to images → Nubot control nodes subscribe/process vision output → Commands sent to nubot_hwcontroller.
- Flow of commands from the control nodes (nubot_control) to actuation hardware through the hardware controller.
- How simulation spawn scripts (cyan_spawn_model.sh, magenta_spawn_model.sh) integrate with the rest of the system when the simulation flag is enabled.

c. Architectural Patterns:
- Modular design inherent in ROS: each package is a self-contained module communicating over topics or services.
- Separation of concerns is evident: sensing, perception, control, simulation, and common messaging packages are clearly separated.
- The use of launch files per package indicates orchestration using ROS launch hierarchy.

d. Technologies, Frameworks, or Libraries:
- ROS: the backbone for inter-node communication and orchestration.
- Catkin: for building and managing the packages.
- Qt: used in the color_segment package for its GUI components.
- CMake: for project building (many CMakeLists.txt files and ROS-specific cmake modules).
- Real-time tools: realtime_tools package for managing time-critical processes.
- Various sensor and driver libraries (e.g., prosilica SDK, uvc driver libraries).

##### Elements to Be Included
- Component Blocks: Clearly labeled blocks for packages/nodes (e.g., "Camera Driver (camera_umd)", "Vision Processing (nubot/front_vision, nubot/omni_vision)", "Control (nubot_control)", "Hardware Interface (nubot_hwcontroller)").
- Annotations: Include notes and labels indicating important ROS elements (topics, services, launch file relationships) and mention any external dependencies (e.g., Qt GUI, real-time publishing).

##### Summary
- Create distinct clusters for sensing, perception, control, simulation/data management, and utility tools.
- How each module interacts (publishing/subscribing messages) and indicate which packages provide core functionality (nubot_common & world_model) that act as shared services.

## Diagram (Mermaid)

```mermaid
graph TD
    %% ROS Core
    ROSM("ROS Master"):::core

    %% Sensor/Input Layer
    subgraph "Sensor/Input Layer"
        CAM1("Camera_UMD"):::sensor
        PROS("Prosilica_Driver"):::sensor
        JOY("Joystick_Drivers"):::sensor
    end

    %% Perception Layer
    subgraph "Perception Layer"
        FV("Front_Vision"):::perception
        OV("Omni_Vision"):::perception
        CS1("Color_Segmentation (Standalone)"):::perception
        CS2("Color_Segmentation (Nubot)"):::perception
    end

    %% Control Layer
    subgraph "Control Layer"
        NC("Nubot_Control"):::control
        NHW("Nubot_Hardware_Controller"):::control
    end

    %% Data & Communication Layer
    subgraph "Data & Communication"
        NCMM("Nubot_Common"):::data
        WM("World_Model"):::data
        SIM("Simulation_Interface"):::data
    end

    %% Supporting Tools Layer
    subgraph "Supporting Tools"
        PLOT("2D_Plot_Tool"):::tools
        RT("Realtime_Tools"):::tools
    end

    %% Connections between layers
    %% Sensor to Perception (image data)
    CAM1 -->|"pubImage"| FV
    CAM1 -->|"pubImage"| OV
    CAM1 -->|"pubImage"| CS1
    CAM1 -->|"pubImage"| CS2
    PROS -->|"pubImage"| FV
    PROS -->|"pubImage"| OV
    PROS -->|"pubImage"| CS1
    PROS -->|"pubImage"| CS2

    %% Joystick command to Control
    JOY -->|"cmd"| NC

    %% Perception to Data (processed sensor data)
    FV -->|"data"| NCMM
    OV -->|"data"| NCMM
    CS1 -->|"data"| NCMM
    CS2 -->|"data"| NCMM

    %% Data to other layers
    NCMM -->|"sync"| WM
    NCMM -->|"info"| NC

    %% Control Layer
    NC -->|"cmdToHW"| NHW

    %% Simulation interactions
    NC -->|"simCmd"| SIM
    SIM -->|"simData"| WM

    %% Supporting tools connections
    WM -->|"visualize"| PLOT
    NC -->|"rtFeedback"| RT

    %% All nodes register with the ROS Master (dashed lines)
    CAM1 -.->|"ros"| ROSM
    FV -.->|"ros"| ROSM
    NC -.->|"ros"| ROSM
    NCMM -.->|"ros"| ROSM
    PLOT -.->|"ros"| ROSM

    %% Click Events
    click CAM1 "https://github.com/nubot-nudt/nubot_ws/tree/master/src/camera_umd"
    click PROS "https://github.com/nubot-nudt/nubot_ws/tree/master/src/prosilica_driver"
    click JOY "https://github.com/nubot-nudt/nubot_ws/tree/master/src/joystick_drivers"
    click FV "https://github.com/nubot-nudt/nubot_ws/tree/master/src/nubot/front_vision"
    click OV "https://github.com/nubot-nudt/nubot_ws/tree/master/src/nubot/omni_vision"
    click CS1 "https://github.com/nubot-nudt/nubot_ws/tree/master/src/color_segment"
    click CS2 "https://github.com/nubot-nudt/nubot_ws/tree/master/src/nubot/color_segment"
    click NCMM "https://github.com/nubot-nudt/nubot_ws/tree/master/src/nubot/nubot_common"
    click NC "https://github.com/nubot-nudt/nubot_ws/tree/master/src/nubot/nubot_control"
    click NHW "https://github.com/nubot-nudt/nubot_ws/tree/master/src/nubot/nubot_hwcontroller"
    click SIM "https://github.com/nubot-nudt/nubot_ws/tree/master/src/nubot/simulation_interface"
    click WM "https://github.com/nubot-nudt/nubot_ws/tree/master/src/nubot/world_model"
    click PLOT "https://github.com/nubot-nudt/nubot_ws/tree/master/src/2D_Plot_Tool"
    click RT "https://github.com/nubot-nudt/nubot_ws/tree/master/src/realtime_tools"

    %% Styles
    classDef sensor fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef perception fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef control fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef data fill:#DDA0DD,stroke:#000,stroke-width:1px;
    classDef tools fill:#FFFFE0,stroke:#000,stroke-width:1px;
    classDef core fill:#FFE4B5,stroke:#000,stroke-width:1px;
```
