# mp-se/gravitymon architecture

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

- Interactive diagram: https://gitdiagram.com/mp-se/gravitymon
- Repository: https://github.com/mp-se/gravitymon

## Overview

##### Project type and purpose
- This is an embedded-firmware project (“GravityMon”) for ESP32/ESP8266-compatible hardware, providing a drop-in replacement firmware for the iSpindle beer-brewing hydrometer.
- It reads sensor data (gyro/accel, temperature, battery), hosts a web UI, exposes BLE services, and pushes gravity readings to an external server.

##### File structure
- Top-level
- platformio.ini → PlatformIO build config
- boards/ → custom board definitions (ESP32 variants)
- src/ → main firmware C++ code (drivers, services, web, BLE, push)
- lib/ → third-party drivers (MPU6050 I²C)
- html/ → prebuilt web assets (index.html, app.js.gz, app.css.gz)
- script/ → Python helpers (flash, versioning, build tooling)
- test/ → unit tests & Python scripts
- src_docs/ → Sphinx-based docs
- bin/ → generated firmware binaries and bootloaders

##### Extract insights from the README
- Core functionality: sensor acquisition, web interface, BLE, data push to brewflasher.com or custom endpoints
- Compatibility: multiple ESP32 family boards, no hardware changes

##### Main components & interactions
a. Hardware Platform
- ESP32 microcontroller
- Sensors: I²C bus → MPU6050 or ICM42670 gyro/accel, temperature sensor, battery monitor
- Power system (battery, calibration data in .env/default_calibration.xlsx)
b. Firmware Subsystems (running on ESP32)
1. Sensor Drivers (lib/mpu6050 + src/ICM42670P*, src/MPU6050*)
2. Sensor Processing & Filtering (src/gyro.*, src/lowpass.hpp, src/helper.cpp)
3. Configuration Manager (src/config_*.hpp)
4. Communication Services
- BLE GravityMon Service (src/ble_gravitymon.*)
- Wi-Fi Web Server (src/web_*.cpp/.hpp serving html assets)
- Push Client (src/pushtarget.*, src/push_*.cpp)
5. Main Application Logic
- Entry points: src/main_gravitymon.cpp, src/main.hpp
- Brewing mode handlers: src/web_brewing.*, src/config_brewing.*
6. Battery Management (src/battery.*)
7. Versioning & Bootloader Integration (scripts + bin/boot32*.bin)
c. External Systems
- Brewflasher.com (OTA/flasher service)
- GravityMon Cloud (optional HTTP/MQTT endpoints)
- User’s Web Browser or Mobile App (connects via BLE or HTTP)
- CI/CD & Documentation
- GitHub Actions workflows (.github/workflows/*.yaml)
- Sphinx (src_docs)

##### Architectural patterns & design principles
- Modular C++: separate driver, processing, service, and config layers
- Event/interrupt-driven sensor polling under FreeRTOS (implicitly via ESP-Arduino)
- Single-binary “fat” firmware: all subsystems compiled into one image
- Clear separation of I/O (hardware drivers), business logic, and presentation (web/BLE)

##### Essential elements
- Hardware: ESP32, sensors, battery
- Firmware subsystems: Drivers / Processing / Config / Comms / Main logic
- External: Brewflasher, GravityMon cloud, User clients
- CI/CD & Docs pipelines

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Layer
    subgraph "Hardware Platform" 
        direction TB
        ESP32["ESP32 Microcontroller"]:::hardware
        I2C["I²C Bus"]:::hardware
        Sensors["Sensors"]:::hardware
        MPU6050["MPU6050 (Accel/Gyro)"]:::hardware
        ICM42670["ICM42670 (Accel/Gyro)"]:::hardware
        TempSensHW["Temperature Sensor"]:::hardware
        BatteryHW["Battery Monitor"]:::hardware
        Calibration["Default Calibration Data"]:::hardware
        BoardDefs["Board Definitions"]:::hardware
    end

    click BoardDefs "https://github.com/mp-se/gravitymon/tree/master/boards/"
    click Calibration "https://github.com/mp-se/gravitymon/blob/master/default_calibration.xlsx"

    %% Sensor Drivers
    subgraph "Sensor Drivers" 
        direction TB
        MPU6050Driver["MPU6050 Driver"]:::drivers
        ICM42670Driver["ICM42670 Driver"]:::drivers
        MPU6050Gyro["MPU6050 Gyro Driver"]:::drivers
    end

    click MPU6050Driver "https://github.com/mp-se/gravitymon/blob/master/lib/mpu6050/MPU6050.cpp"
    click ICM42670Driver "https://github.com/mp-se/gravitymon/blob/master/src/ICM42670P_gyro.cpp"
    click MPU6050Gyro "https://github.com/mp-se/gravitymon/blob/master/src/MPU6050_gyro.cpp"

    %% Processing
    subgraph "Processing & Filtering"
        direction TB
        CoreProcessing["Core Processing & Maths"]:::processing
        Lowpass["Filtering Utilities"]:::processing
        Helper["Helpers"]:::processing
    end

    click CoreProcessing "https://github.com/mp-se/gravitymon/blob/master/src/gyro.cpp"
    click Lowpass "https://github.com/mp-se/gravitymon/blob/master/src/lowpass.hpp"
    click Helper "https://github.com/mp-se/gravitymon/blob/master/src/helper.cpp"

    %% Configuration
    subgraph "Configuration Manager"
        direction TB
        ConfigGM["GravityMon Config"]:::config
        ConfigBrew["Brewing Mode Config"]:::config
    end

    click ConfigGM "https://github.com/mp-se/gravitymon/blob/master/src/config_gravitymon.cpp"
    click ConfigBrew "https://github.com/mp-se/gravitymon/blob/master/src/config_brewing.cpp"

    %% Communication Services
    subgraph "Communication Services"
        direction TB
        BLE["BLE GravityMon Service"]:::comms
        WebGM["Web Server (GravityMon UI)"]:::comms
        HTML["Web Assets"]:::comms
        WebBrew["Web Server (Brewing UI)"]:::comms
        PushGM["Push Client (GravityMon)"]:::comms
        PushTarg["Push Target Abstraction"]:::comms
    end

    click BLE "https://github.com/mp-se/gravitymon/blob/master/src/ble_gravitymon.cpp"
    click WebGM "https://github.com/mp-se/gravitymon/blob/master/src/web_gravitymon.cpp"
    click HTML "https://github.com/mp-se/gravitymon/tree/master/html/"
    click WebBrew "https://github.com/mp-se/gravitymon/blob/master/src/web_brewing.cpp"
    click PushGM "https://github.com/mp-se/gravitymon/blob/master/src/push_gravitymon.cpp"
    click PushTarg "https://github.com/mp-se/gravitymon/blob/master/src/pushtarget.cpp"

    %% Main Application
    subgraph "Main Application Logic"
        direction TB
        MainEntry["Entry Point & Core"]:::main
    end

    click MainEntry "https://github.com/mp-se/gravitymon/blob/master/src/main_gravitymon.cpp"

    %% Battery Management
    subgraph "Battery Management"
        direction TB
        Battery["Battery Monitoring"]:::battery
        TempHW["Temperature Sensor Driver"]:::battery
    end

    click Battery "https://github.com/mp-se/gravitymon/blob/master/src/battery.cpp"
    click TempHW "https://github.com/mp-se/gravitymon/blob/master/src/tempsensor.cpp"

    %% Versioning & Bootloader
    subgraph "Versioning & Bootloader"
        direction TB
        VersionScript["Version JSON Script"]:::version
        Bootloader["Prebuilt Bootloaders"]:::version
    end

    click VersionScript "https://github.com/mp-se/gravitymon/blob/master/script/create_versionjson.py"
    click Bootloader "https://github.com/mp-se/gravitymon/tree/master/bin/"

    %% CI/CD & Documentation
    subgraph "CI/CD & Docs"
        direction TB
        BuildWF["Build Workflow"]:::ci
        DocWF["Docs Workflow"]:::ci
        Sphinx["Sphinx Documentation"]:::docs
    end

    click BuildWF "https://github.com/mp-se/gravitymon/blob/master/.github/workflows/pio-build.yaml"
    click DocWF "https://github.com/mp-se/gravitymon/blob/master/.github/workflows/doc-build.yaml"
    click Sphinx "https://github.com/mp-se/gravitymon/tree/master/src_docs/"

    %% External Systems
    subgraph "External Systems"
        direction TB
        Brewflasher["Brewflasher.com"]:::external
        Cloud["GravityMon Cloud"]:::external
        UserClient["User Client (Browser/Mobile)"]:::external
    end

    %% Connections
    ESP32 --> I2C
    I2C --> MPU6050Driver
    I2C --> ICM42670Driver
    MPU6050Driver --> CoreProcessing
    ICM42670Driver --> CoreProcessing
    BatteryHW --> Battery
    TempSensHW --> TempHW
    Battery --> CoreProcessing
    TempHW --> CoreProcessing
    Calibration --> ConfigGM
    ConfigGM --> CoreProcessing
    ConfigBrew --> CoreProcessing
    CoreProcessing --> BLE
    CoreProcessing --> WebGM
    CoreProcessing --> PushGM
    Helper --> CoreProcessing
    Lowpass --> CoreProcessing
    WebGM --> HTML
    WebBrew --> HTML
    PushGM --> PushTarg
    MainEntry --> MPU6050Driver
    MainEntry --> ICM42670Driver
    MainEntry --> CoreProcessing
    MainEntry --> ConfigGM
    MainEntry --> ConfigBrew
    MainEntry --> BLE
    MainEntry --> WebGM
    MainEntry --> WebBrew
    MainEntry --> PushGM
    MainEntry --> Battery
    MainEntry --> TempHW
    MainEntry --> VersionScript
    VersionScript --> Bootloader
    BuildWF --> Bootloader
    BuildWF --> ESP32
    DocWF --> Sphinx
    UserClient --> BLE
    UserClient --> WebGM
    UserClient --> WebBrew
    Brewflasher --> ESP32
    Cloud --> PushTarg

    %% Styles
    classDef hardware fill:#D0E6A5,stroke:#333,stroke-width:1px
    classDef drivers fill:#A8D5BA,stroke:#333,stroke-width:1px
    classDef processing fill:#FFD97D,stroke:#333,stroke-width:1px
    classDef config fill:#FFDAC1,stroke:#333,stroke-width:1px
    classDef comms fill:#FF9AA2,stroke:#333,stroke-width:1px
    classDef main fill:#B5EAEA,stroke:#333,stroke-width:1px
    classDef battery fill:#C7CEEA,stroke:#333,stroke-width:1px
    classDef version fill:#E2F0CB,stroke:#333,stroke-width:1px
    classDef ci fill:#F1F1F1,stroke:#333,stroke-width:1px
    classDef docs fill:#FFF2B2,stroke:#333,stroke-width:1px
    classDef external fill:#D3CCE3,stroke:#333,stroke-width:1px
```
