# fiu-mora-lab/searobotics_surveyor architecture

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

- Interactive diagram: https://gitdiagram.com/fiu-mora-lab/searobotics_surveyor
- Repository: https://github.com/fiu-mora-lab/searobotics_surveyor

## Overview

##### Project Type and Purpose
- This is a distributed, hardware‐centric Python library (“surveyor_lib”) that wraps client/server communications to operate an Autonomous Surface Vehicle (ASV) and its sensors (YSI EXO2 multiparameter sonde, LIDAR, camera).
- It is neither a traditional frontend/backend web app nor a compiler; it’s an open‐source robotics tool that abstracts sensor I/O behind networked servers and Python clients, and provides utility helpers for logging, message formatting, and data persistence.

##### Main Components
- **Physical Hardware Nodes**
- Surveyor ASV with onboard Raspberry Pi running camera_server.py & lidar_server.py
- External DAC (Windows PC) running exo2_server.py (Flask or raw socket)
- Sensors: EXO2 Sonde, LIDAR device, IP/USB camera
- **Network Fabric**
- Local Ethernet/Wi-Fi network interconnecting Pi, DAC, and control laptop
- Static IP assignments (e.g. Pi at 192.168.0.20, DAC at 192.168.0.68)
- **Servers (surveyor_lib/servers)**
- camera_server.py (streams image frames)
- lidar_server.py (streams scan data via rplidar .so bindings)
- exo2_flask_server.py / exo2_server.py (exposes Sonde data over HTTP or raw socket)
- **Clients (surveyor_lib/clients)**
- BaseClient: generic socket/HTTP connector
- CameraClient, LidarClient, Exo2Client: specialized parsers for each sensor stream
- **Orchestration Layer**
- Surveyor class (surveyor_lib/surveyor.py) initializes and manages sensor clients, provides unified API to application code
- **Helper Utilities (surveyor_lib/helpers)**
- hdf5_logger.py: logs timestamped sensor data to HDF5
- logger.py: configurable console/file logger
- read_save_helper.py: I/O utilities
- surveyor_messages_helper.py & waypoint_helper.py: message formatting and waypoint management
- **External Application**
- Your_application.py: imports Surveyor, kicks off sensor servers, processes data, issues waypoints
- **Tests**
- Unit tests under tests/ verifying clients, helpers, and Surveyor functionality

##### Relationships and Data Flow
- Sensor hardware → Server process on respective node (Pi or DAC)
- Server binds to IP:port → streams raw/binary data
- Client in Surveyor library connects over TCP/HTTP → receives, decodes, and buffers data
- Surveyor class polls or subscribes to client data → feeds to application logic
- Helpers log or persist data locally (HDF5, text logs)
- Application can command waypoints or camera snapshots via Surveyor API

##### Architectural Patterns & Design Principles
- **Client–Server**: loose coupling of sensor I/O (servers) from data consumption (clients) via network abstractions
- **Modular Separation**: each sensor has its own server/client pair; helpers are pluggable
- **Single Responsibility**: Surveyor orchestrates only clients; helpers manage logging, formatting, persistence
- **Extensibility**: to add a new sensor, create new server module + client subclass + docs

##### Key Technologies, Frameworks & Libraries
- Python 3.11, pyproject.toml for project metadata
- Flask (in exo2_flask_server) for HTTP-based sensor streaming
- Raw TCP sockets (base_client) for high‐throughput data
- rplidar C-extension modules (.so) for LIDAR on Raspberry Pi
- h5py for HDF5 logging
- pytest for automated testing
- isort/black/flake8 for code quality

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Physical Hardware Nodes
    subgraph "Raspberry Pi (192.168.0.20)" 
        direction TB
        CameraServer["Camera Server (Pi)"]:::server
        LidarServer["Lidar Server (Pi)"]:::server
    end
    subgraph "External DAC (192.168.0.68)"
        direction TB
        EXO2Flask["EXO2 Flask Server"]:::server
        EXO2Raw["EXO2 Raw-Socket Server"]:::server
    end
    subgraph "Control Laptop"
        direction TB
        subgraph "surveyor_lib"
            direction TB
            Surveyor["Surveyor Orchestrator"]:::orchestrator
            subgraph "Clients"
                direction TB
                BaseClient["BaseClient"]:::library
                CameraClient["CameraClient"]:::library
                LidarClient["LidarClient"]:::library
                Exo2Client["EXO2 Client"]:::library
            end
            subgraph "Helpers"
                direction TB
                HDF5Logger["HDF5 Logger"]:::helper
                Logger["Console/File Logger"]:::helper
                ReadSave["Read/Save Helper"]:::helper
                MsgHelper["Message Formatting Helper"]:::helper
                WaypointHelper["Waypoint Management Helper"]:::helper
            end
        end
    end

    %% Network Data Flows
    CameraServer -->|"TCP:8001"| CameraClient
    LidarServer -->|"TCP:8002"| LidarClient
    EXO2Flask -->|"HTTP:/exo2/data"| Exo2Client
    EXO2Raw -->|"TCP:8003"| Exo2Client

    %% Orchestration
    CameraClient -->|"provides data"| Surveyor
    LidarClient -->|"provides data"| Surveyor
    Exo2Client -->|"provides data"| Surveyor

    %% Helpers
    Surveyor -->|"logs data"| HDF5Logger
    Surveyor -->|"logs events"| Logger
    Surveyor -->|"uses I/O"| ReadSave
    Surveyor -->|"formats messages"| MsgHelper
    Surveyor -->|"manages waypoints"| WaypointHelper

    %% Click Events
    click CameraServer "https://github.com/fiu-mora-lab/searobotics_surveyor/blob/main/surveyor_lib/servers/camera_server.py"
    click LidarServer "https://github.com/fiu-mora-lab/searobotics_surveyor/blob/main/surveyor_lib/servers/lidar_server.py"
    click EXO2Flask "https://github.com/fiu-mora-lab/searobotics_surveyor/blob/main/surveyor_lib/servers/exo2_flask_server.py"
    click EXO2Raw "https://github.com/fiu-mora-lab/searobotics_surveyor/blob/main/surveyor_lib/servers/exo2_server.py"
    click BaseClient "https://github.com/fiu-mora-lab/searobotics_surveyor/blob/main/surveyor_lib/clients/base_client.py"
    click CameraClient "https://github.com/fiu-mora-lab/searobotics_surveyor/blob/main/surveyor_lib/clients/camera_client.py"
    click LidarClient "https://github.com/fiu-mora-lab/searobotics_surveyor/blob/main/surveyor_lib/clients/lidar_client.py"
    click Exo2Client "https://github.com/fiu-mora-lab/searobotics_surveyor/blob/main/surveyor_lib/clients/exo2_client.py"
    click Surveyor "https://github.com/fiu-mora-lab/searobotics_surveyor/blob/main/surveyor_lib/surveyor.py"
    click HDF5Logger "https://github.com/fiu-mora-lab/searobotics_surveyor/blob/main/surveyor_lib/helpers/hdf5_logger.py"
    click Logger "https://github.com/fiu-mora-lab/searobotics_surveyor/blob/main/surveyor_lib/helpers/logger.py"
    click ReadSave "https://github.com/fiu-mora-lab/searobotics_surveyor/blob/main/surveyor_lib/helpers/read_save_helper.py"
    click MsgHelper "https://github.com/fiu-mora-lab/searobotics_surveyor/blob/main/surveyor_lib/helpers/surveyor_messages_helper.py"
    click WaypointHelper "https://github.com/fiu-mora-lab/searobotics_surveyor/blob/main/surveyor_lib/helpers/waypoint_helper.py"

    %% Styles
    classDef hardware fill:#ccffcc,stroke:#333,stroke-width:1px;
    classDef server fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef library fill:#ffffcc,stroke:#333,stroke-width:1px;
    classDef helper fill:#dddddd,stroke:#333,stroke-width:1px;
    classDef orchestrator fill:#ffeb99,stroke:#333,stroke-width:1px;
```
