# renatobo/bonogps architecture

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

- Interactive diagram: https://gitdiagram.com/renatobo/bonogps
- Repository: https://github.com/renatobo/bonogps

## Overview

##### Main Components
a. Hardware Layer:
- ESP32 Device – the central processing unit running the embedded firmware.
- GPS Receiver(s) – support for u‐blox M8 and M10 series modules (e.g., BN880, BN220).
- Power/Battery and associated peripheral hardware (assembled parts, 3D printed components) found in hardware/assembled and hardware/esp32.

b. Firmware/Software Layer:
- Core Firmware – the source code in src (e.g., bonogps.cpp) and supporting headers and settings in the include folder.
- Connection Handlers – separate modules for interfacing with different connection transports such as BLE, BT-SPP, and TCP-IP (reflected in the software/connecting folder with app-specific configurations).
- Web-based Configuration Interface – the HTML/CSS assets (in software/using and include subfolders) that empower on-device configuration over WiFi.
- Build System – the PlatformIO configuration (platformio.ini and build scripts) indicating dependencies and build instructions.

c. External Interactions:
- Mobile Applications – external devices using apps like Harry’s Lap Timer, RaceChrono, RaceTime, and TrackAddict that receive GPS data (initialized by connecting over BLE/BT/TCP-IP).
- uBlox u-center – debugging/configuration tool via TCP-IP for GPS setup (as referenced in the README).

##### Relationships and Interactions
- The firmware processes these GPS messages, applying any settings found in configuration headers (include), then dispatches the processed data via multiple connectivity stacks:
- Over BLE (for iOS support especially).
- Over BT-SPP (for Android devices, as well as other app compatibilities).
- Via TCP-IP (allowing connectivity both from mobile apps and uBlox u-center for configuration).
- Finally, the external mobile apps are shown connecting and receiving data through these various interfaces. They can also (optionally) inspire configuration changes that loop back via the web interface.

##### Architectural Patterns / Design Principles
- Modular Separation – The file tree is clearly divided between hardware (with schematics, assembly, and GPS configurations) and software (with dedicated modules for building and connecting), which implies a clean separation of concerns.
- Configurability – The presence of runtime configuration and preset save/load functionality of the device should be highlighted. The web configuration interface is a key component, and its role in altering behavior (like toggling WiFi modes) should be clearly depicted.

##### Tools and Technologies
- ESP32 microcontroller.
- u-blox GPS receivers.
- PlatformIO (for build and development).
- Web technologies (HTML, CSS) for the configuration interface.
- Bluetooth and WiFi stacks of the ESP32.
- Mobile app integration proxies for Harry’s Lap Timer, RaceChrono, etc.

##### Essential Elements
- Clear labels for every component (e.g., “GPS Receiver,” “ESP32 Processing Unit,” “BLE Service Module,” “Web Server”).
- Interface types (UART for hardware interconnect, WiFi for web interface, Bluetooth for direct mobile app connectivity).
- Annotations for configuration paths such as “Device Configuration via Web Interface” or “Preset Loading / Saving” based on the README.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interactions
    subgraph "External Interactions"
        MobileApps["Mobile Applications"]:::external
        uBlox["u-blox u-center"]:::external
        ConfigClients["Configuration Clients"]:::external
    end

    %% Firmware/Software Layer
    subgraph "Firmware/Software Layer"
        CoreFW["Core Firmware"]:::firmware
        FwSettings["Firmware Settings"]:::firmware
        ConnHandlers["Connection Handlers"]:::firmware
        WebConfig["Web Configuration Interface"]:::firmware
        BuildSys["Build System"]:::firmware
    end

    %% Hardware Layer
    subgraph "Hardware Layer"
        ESP32["ESP32 Device"]:::hardware
        GPSReceiver["GPS Receiver"]:::hardware
        Assembled["Hardware Assembly"]:::hardware
        GPSBN220["GPS Config BN220"]:::hardware
        GPSBN880["GPS Config BN880"]:::hardware
        GPSDocs["GPS Documents & Specs"]:::hardware
    end

    %% Hardware Relationships
    GPSReceiver -->|"UART:NMEA"| ESP32
    Assembled -->|"Integrates"| ESP32
    GPSBN220 -->|"Configuration"| GPSReceiver
    GPSBN880 -->|"Configuration"| GPSReceiver
    GPSDocs -->|"Specs"| GPSReceiver

    %% Firmware Relationships
    ESP32 -->|"Runs"| CoreFW
    CoreFW -->|"Uses"| FwSettings
    CoreFW -->|"DispatchesData"| ConnHandlers
    CoreFW -->|"Hosts"| WebConfig
    BuildSys -.->|"Builds"| CoreFW

    %% External Communication
    ConnHandlers -->|"TCP-IP/BLE/BT"| MobileApps
    ConnHandlers -->|"TCP-IP"| uBlox
    WebConfig <-->|"WebInterface"| ConfigClients

    %% Click Events
    click CoreFW "https://github.com/renatobo/bonogps/blob/main/src/bonogps.cpp"
    click FwSettings "https://github.com/renatobo/bonogps/blob/main/include/bonogps_board_settings.h"
    click GPSBN220 "https://github.com/renatobo/bonogps/blob/main/hardware/GPS/gps-bn220-config.txt"
    click GPSBN880 "https://github.com/renatobo/bonogps/blob/main/hardware/GPS/gps-bn880-config.txt"
    click ESP32 "https://github.com/renatobo/bonogps/tree/main/hardware/esp32"
    click Assembled "https://github.com/renatobo/bonogps/tree/main/hardware/assembled"
    click ConnHandlers "https://github.com/renatobo/bonogps/tree/main/software/connecting"
    click WebConfig "https://github.com/renatobo/bonogps/tree/main/software/using"
    click BuildSys "https://github.com/renatobo/bonogps/blob/main/platformio.ini"
    click GPSDocs "https://github.com/renatobo/bonogps/blob/main/hardware/GPS/README.md"

    %% Styles
    classDef hardware fill:#aaf,stroke:#333,stroke-width:2px;
    classDef firmware fill:#afa,stroke:#333,stroke-width:2px;
    classDef external fill:#ffa,stroke:#333,stroke-width:2px;
```
