# themaxnet/hiveparafoil architecture

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

- Interactive diagram: https://gitdiagram.com/themaxnet/hiveparafoil
- Repository: https://github.com/themaxnet/hiveparafoil

## Overview

##### Project type and purpose
- This is an embedded‐software project for an Arduino/ESP32‐based GPS navigation system (parafoil guidance).
- The firmware reads NMEA sentences from a GPS module, applies a Kalman filter for smoothing/estimation, and likely outputs processed position data (e.g., on telemetry or SD card).
- The accompanying directories (“Docs” with filter specs and NMEA manual, “Misc” with test scripts, “Oakleigh GPS Test” data files) support development, calibration, and post‐processing.

##### File structure
Top‐level directories:
- Docs – contains Kalman filter and NMEA reference manuals (design inputs).
- Misc – Python test script (testnav.py) for verifying navigation logic against recorded data.
- Oakleigh GPS Test – raw CSV, MATLAB, and text files for real‐world GPS data.
- Old – archived versions of ESP32/Arduino sketches demonstrating earlier iterations.
- parafoilarduino – the current, active Arduino sketch (parafoilarduino.ino).
- readme.md – points to the current firmware location.
Build/deployment specifics:
- The .ino file compiles via the Arduino or PlatformIO toolchain, targets an ESP32/Arduino board.
- No explicit CI or Dockerfiles are present, so deployment is local to the development machine.

##### README for additional insights
- README is minimal: directs to the main Arduino script.

##### Main components & their relationships
a. Hardware Layer
- GPS sensor (UART output of NMEA sentences)
- Microcontroller board (Arduino/ESP32)
- Optional peripherals: SD card module (for logging), telemetry radio or USB serial
b. Firmware Layer (on Arduino)
- UART driver – reads raw NMEA strings
- NMEA parser – tokenizes and extracts GGA/RMC fields
- Kalman filter module – applies state estimation (from Docs/Kalman filter.pdf)
- Data logger / Telemetry output – writes filtered data to SD or streams over serial
- Configuration/constants – filter tuning parameters, system timing
c. Off‐board Tools
- Python test script (Misc/testnav.py) – ingests logged or sample data, verifies filter accuracy
- MATLAB/CSV data sets (Oakleigh GPS Test) – used by the test script to benchmark performance

Interaction flow:
GPS sensor → Serial input → NMEA parser → Kalman filter → {Data logger, Telemetry}
Logged data + Oakleigh test sets → Python script → Performance plots

##### Architectural patterns & principles
- Layered processing pipeline: sensor interface → parsing → estimation → output
- Single MCU monolith – no service‐oriented or distributed microservices, but clear modular separation in code (parser module, filter module, comms module).
- Reusability: archived “Old” sketches demonstrate iterative design and fallback points.

##### Detail
- Every key processing block in the Arduino firmware.
- Configuration sources (Kalman docs, NMEA manual).
- Test harness outside the MCU boundary.
- Don’t overthink – more granular separation (parser vs. filter vs. logger) yields clarity and easier future extensions.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Layer
    subgraph "Hardware Layer"
        GPS["GPS Module"]:::hardware
        UART["UART Bus (NMEA over UART)"]:::hardware
        MCU["Arduino/ESP32 MCU"]:::hardware
    end

    %% Firmware Layer inside MCU
    subgraph "Firmware Layer"
        UDriver["UART Driver"]:::firmware
        Parser["NMEA Parser"]:::firmware
        Filter["Kalman Filter"]:::firmware
        Logger["Data Logger / Telemetry Interface"]:::firmware
        Config["Configuration / Constants"]:::firmware
    end

    %% Storage and Communication
    subgraph "Storage / Communication"
        SD["SD Card Storage"]:::storage
        Radio["USB Serial / Radio Link"]:::storage
    end

    %% Documentation
    subgraph "Documentation"
        KFspec["Kalman Filter Spec"]:::docs
        NMEAref["NMEA Reference Manual"]:::docs
        Readme["README"]:::docs
    end

    %% Off-board Tools and Data
    subgraph "Off-board Tools & Data"
        PyTest["Python Test Script"]:::tools
        DataSets["Oakleigh GPS Test Data Sets"]:::tools
        Arch1["Archived Sketch esp32gps_1"]:::tools
        Arch2["Archived Sketch esp32gps_2"]:::tools
        Arch3["Archived Sketch commented_esp32gps_2"]:::tools
    end

    %% Data Flow
    GPS --> UART
    UART --> UDriver
    UDriver --> Parser
    Parser --> Filter
    Filter --> Logger
    Logger --> SD
    Logger --> Radio

    SD --> PyTest
    DataSets --> PyTest
    PyTest -.-> Config

    Readme --> MCU
    KFspec -.-> Filter
    NMEAref -.-> Parser

    %% Click Events
    click UDriver "https://github.com/themaxnet/hiveparafoil/blob/main/parafoilarduino/parafoilarduino.ino"
    click Parser "https://github.com/themaxnet/hiveparafoil/blob/main/parafoilarduino/parafoilarduino.ino"
    click Filter "https://github.com/themaxnet/hiveparafoil/blob/main/parafoilarduino/parafoilarduino.ino"
    click Logger "https://github.com/themaxnet/hiveparafoil/blob/main/parafoilarduino/parafoilarduino.ino"
    click Config "https://github.com/themaxnet/hiveparafoil/blob/main/parafoilarduino/parafoilarduino.ino"
    click KFspec "https://github.com/themaxnet/hiveparafoil/blob/main/Docs/Kalman filter.pdf"
    click NMEAref "https://github.com/themaxnet/hiveparafoil/blob/main/Docs/NMEA_Reference_Manual-Rev2.1-Dec07.pdf"
    click PyTest "https://github.com/themaxnet/hiveparafoil/blob/main/Misc/testnav.py"
    click DataSets "https://github.com/themaxnet/hiveparafoil/tree/main/Oakleigh GPS Test/"
    click Arch1 "https://github.com/themaxnet/hiveparafoil/tree/main/Old/esp32gps_1/"
    click Arch2 "https://github.com/themaxnet/hiveparafoil/tree/main/Old/esp32gps_2/"
    click Arch3 "https://github.com/themaxnet/hiveparafoil/tree/main/Old/commented_esp32gps_2/"
    click Readme "https://github.com/themaxnet/hiveparafoil/blob/main/readme.md"

    %% Styles
    classDef hardware fill:#D6EAF8,stroke:#1B4F72,color:#1B2631;
    classDef firmware fill:#D5F5E3,stroke:#145A32,color:#0E2F1A;
    classDef storage fill:#F9E79F,stroke:#7D6608,color:#513B0A;
    classDef docs fill:#E5E8E8,stroke:#424949,color:#1C2833;
    classDef tools fill:#FADBD8,stroke:#922B21,color:#641E16;
```
