# airgradienthq/airgradient-firmware architecture

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

- Interactive diagram: https://gitdiagram.com/airgradienthq/airgradient-firmware
- Repository: https://github.com/airgradienthq/airgradient-firmware

## Overview

1. **This is an ESP-IDF firmware monorepo, not a single app.**  
   The repository is organized into reusable firmware components under `components/`, product-specific application roots under `products/`, and host-side test entrypoints under `tests/`. The main architectural goal is to keep hardware/software capabilities shared and the product roots thin.

2. **Shared code is split by capability, with clear HAL/driver/service boundaries.**  
   Most shared components follow the same pattern: a `drivers/` layer for chip-specific implementations, a `hal/` layer for abstract interfaces, and sometimes `services/` for orchestration logic. This makes the architecture portable across products and allows host tests to target the higher-level service code.

3. **The sensor stack is a major shared subsystem.**  
   `components/airgradient-sensors` contains multiple sensor drivers for PM, CO2, temperature/humidity, pressure, TVOC/NOx, ozone/NO2, and sunlight-related sensing. The `sensor_manager` service aggregates these into a unified sensor capability behind sensor-specific HAL interfaces like `pm_sensor.h`, `co2_sensor.h`, and `temp_hum_sensor.h`.

4. **Connectivity is modularized into separate communication subsystems.**  
   BLE lives in `components/airgradient-ble` with a NimBLE-based server implementation. Cellular lives in `components/airgradient-cellular`, with a modem driver for the Simcom A7672x plus an AT command service. GPS has its own NMEA-based component, and serial transport is separated into `components/airgradient-serial` with UART and I2C-serial variants.

5. **Power, battery, and storage are isolated as distinct platform services.**  
   Battery management appears in `components/airgradient-bms`, with drivers for TI BQ devices and shared BMS types. Nonvolatile configuration uses `components/airgradient-config` with an NVS-backed store. Local payload buffering is handled by `components/airgradient-payload-cache`, which stores cached payloads in RTC-backed storage.

6. **Low-level hardware abstraction is centralized for portability.**  
   `components/airgradient-gpio` provides native GPIO support, `components/airgradient-touch` wraps a CAP1203 touch controller, and `components/airgradient-nand-storage` abstracts SPI NAND storage. `components/ads1115` and `components/bq25629` are standalone shared device libraries where needed by higher-level components.

7. **Common infrastructure lives in `airgradient-common`.**  
   This component provides cross-cutting utilities such as logging, common types, measure definitions, and RTOS helpers. It is the shared “plumbing” used across product and component layers rather than a feature subsystem itself.

8. **`products/go` is the primary application and assembly layer.**  
   The Go portable monitor is composed from small product modules: BLE, display, GPS, input, power, settings, storage, sensor producer, UI, and the orchestrator. These files are the product-specific wiring that bind shared components into a device experience.

9. **The Go product uses an event-driven orchestration model.**  
   The visible product split suggests a data path of hardware input and sensor acquisition feeding a `sensor_producer`, then flowing through `orchestrator`, `ui`, `display`, `storage`, and `ble` services. `go_events.h` and the module separation indicate a central event bus or message-driven coordination rather than tight coupling between subsystems.

10. **Display and UI are separated from sensor acquisition.**  
    The Go product has distinct `go_display` and `go_ui` modules, which implies a presentation layer that consumes state/events rather than directly querying hardware. That separation is important for diagramming because the display is likely updated from a shared state model or event stream, not from sensors directly.

11. **`products/reference` is a thin hardware validation app.**  
    The reference product includes test modules for BLE, GPIO, NAND storage, payload cache, sensors, serial, touch, and configuration. This looks like a board-support and component-validation root, useful for exercising shared components without the complexity of the Go application.

12. **Testing is split between native host tests and ESP-IDF build tests.**  
    Each major component and product has its own `tests/` subtree with CMake entrypoints, enabling unit-style validation of services and drivers. The top-level `tests/ble-integration` directory adds Python-based BLE integration tests, so the repo has both host-side logic tests and protocol/device integration coverage.

13. **Third-party code is vendored as shared infrastructure where needed.**  
    The repo includes libraries like `esp-nimble-cpp`, `libnmea-esp32`, and `u8g2` under `components/`, indicating that the firmware links against embedded third-party stacks directly within the monorepo. These are treated as supporting dependencies rather than product-owned code.

14. **The main architectural boundary is: shared capability vs product assembly.**  
    Shared components own reusable drivers, HALs, and generic services; products own board configuration, sequencing, and user-facing behavior. For a diagram, the cleanest flow is: hardware and external interfaces at the bottom, shared components in the middle, and product orchestration/UI/application logic at the top.

Main entry points: [`products/reference/main/main.cpp`](https://github.com/airgradienthq/airgradient-firmware/blob/main/products/reference/main/main.cpp) (Reference app), [`products/go/main/go_ble.cpp`](https://github.com/airgradienthq/airgradient-firmware/blob/main/products/go/main/go_ble.cpp) (Device services), [`components/airgradient-common`](https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-common) (Common), [`components/airgradient-ble`](https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-ble) (BLE)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shared["Shared components"]
  node_airgradient_common["Common<br/>shared plumbing"]
  node_airgradient_sensors["Sensors<br/>sensor stack"]
  node_airgradient_ble["BLE<br/>connectivity"]
  node_airgradient_cellular["Cellular<br/>connectivity"]
  node_airgradient_gps["GPS<br/>location stack"]
  node_airgradient_serial["Serial<br/>transport"]
  node_airgradient_bms["BMS<br/>power stack"]
  node_airgradient_config["Config<br/>nvs store"]
  node_airgradient_payload_cache["Payload cache<br/>rtc buffer"]
  node_airgradient_gpio["GPIO<br/>hardware io"]
  node_airgradient_touch["Touch<br/>input hw"]
  node_airgradient_nand_storage["NAND storage<br/>storage hw"]
  node_ads1115["ADS1115<br/>adc library"]
  node_bq25629["BQ25629<br/>charger lib"]
end

subgraph group_go_product["Go product"]
  node_go_main["Go app<br/>product entry<br/>[main.cpp]"]
  node_go_orchestrator["Orchestrator<br/>coordination"]
  node_go_sensor_producer["Sensor producer<br/>data pipeline"]
  node_go_ui_display["UI + display<br/>presentation<br/>[go_ui.cpp]"]
  node_go_services["Device services<br/>product services<br/>[go_ble.cpp]"]
end

subgraph group_reference_product["Reference product"]
  node_reference_main["Reference app<br/>validation app<br/>[main.cpp]"]
  node_ble_integration["BLE tests<br/>integration suite"]
end

subgraph group_external["Vendored deps"]
  node_u8g2["u8g2<br/>display lib"]
  node_esp_nimble_cpp["NimBLE CPP<br/>ble dep"]
  node_libnmea_esp32["libnmea<br/>gps dep"]
end

node_airgradient_sensors -->|"uses"| node_ads1115
node_airgradient_bms -->|"uses"| node_bq25629
node_airgradient_ble -->|"wraps"| node_esp_nimble_cpp
node_airgradient_gps -->|"parses"| node_libnmea_esp32
node_airgradient_sensors -->|"shares"| node_airgradient_common
node_airgradient_ble -->|"shares"| node_airgradient_common
node_airgradient_cellular -->|"shares"| node_airgradient_common
node_airgradient_gps -->|"shares"| node_airgradient_common
node_airgradient_serial -->|"shares"| node_airgradient_common
node_airgradient_bms -->|"shares"| node_airgradient_common
node_airgradient_config -->|"shares"| node_airgradient_common
node_airgradient_payload_cache -->|"shares"| node_airgradient_common
node_go_main -->|"starts"| node_go_orchestrator
node_go_orchestrator -->|"coordinates"| node_go_sensor_producer
node_go_orchestrator -->|"updates"| node_go_ui_display
node_go_orchestrator -->|"routes"| node_go_services
node_go_sensor_producer -->|"reads"| node_airgradient_sensors
node_go_services -->|"uses"| node_airgradient_ble
node_go_services -->|"uses"| node_airgradient_gps
node_go_services -->|"uses"| node_airgradient_bms
node_go_services -->|"uses"| node_airgradient_config
node_go_services -->|"uses"| node_airgradient_payload_cache
node_go_services -->|"uses"| node_airgradient_serial
node_go_services -->|"uses"| node_airgradient_touch
node_go_ui_display -->|"renders with"| node_u8g2
node_reference_main -->|"exercises"| node_airgradient_ble
node_reference_main -->|"exercises"| node_airgradient_gpio
node_reference_main -->|"exercises"| node_airgradient_nand_storage
node_reference_main -->|"exercises"| node_airgradient_payload_cache
node_reference_main -->|"exercises"| node_airgradient_sensors
node_reference_main -->|"exercises"| node_airgradient_serial
node_reference_main -->|"exercises"| node_airgradient_touch
node_reference_main -->|"exercises"| node_airgradient_config
node_ble_integration -->|"tests"| node_airgradient_ble

click node_airgradient_common "https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-common"
click node_airgradient_sensors "https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-sensors"
click node_airgradient_ble "https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-ble"
click node_airgradient_cellular "https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-cellular"
click node_airgradient_gps "https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-gps"
click node_airgradient_serial "https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-serial"
click node_airgradient_bms "https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-bms"
click node_airgradient_config "https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-config"
click node_airgradient_payload_cache "https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-payload-cache"
click node_airgradient_gpio "https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-gpio"
click node_airgradient_touch "https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-touch"
click node_airgradient_nand_storage "https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-nand-storage"
click node_ads1115 "https://github.com/airgradienthq/airgradient-firmware/tree/main/components/ads1115"
click node_bq25629 "https://github.com/airgradienthq/airgradient-firmware/tree/main/components/bq25629"
click node_u8g2 "https://github.com/airgradienthq/airgradient-firmware/tree/main/components/u8g2"
click node_esp_nimble_cpp "https://github.com/airgradienthq/airgradient-firmware/tree/main/components/esp-nimble-cpp"
click node_libnmea_esp32 "https://github.com/airgradienthq/airgradient-firmware/tree/main/components/libnmea-esp32"
click node_go_main "https://github.com/airgradienthq/airgradient-firmware/blob/main/products/go/main/main.cpp"
click node_go_orchestrator "https://github.com/airgradienthq/airgradient-firmware/blob/main/products/go/main/go_orchestrator.cpp"
click node_go_sensor_producer "https://github.com/airgradienthq/airgradient-firmware/blob/main/products/go/main/go_sensor_producer.cpp"
click node_go_ui_display "https://github.com/airgradienthq/airgradient-firmware/blob/main/products/go/main/go_ui.cpp"
click node_go_services "https://github.com/airgradienthq/airgradient-firmware/blob/main/products/go/main/go_ble.cpp"
click node_reference_main "https://github.com/airgradienthq/airgradient-firmware/blob/main/products/reference/main/main.cpp"
click node_ble_integration "https://github.com/airgradienthq/airgradient-firmware/tree/main/tests/ble-integration"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_airgradient_common,node_airgradient_sensors,node_airgradient_ble,node_airgradient_cellular,node_airgradient_gps,node_airgradient_serial,node_airgradient_bms,node_airgradient_config,node_airgradient_payload_cache,node_airgradient_gpio,node_airgradient_touch,node_airgradient_nand_storage,node_ads1115,node_bq25629 toneBlue
class node_go_main,node_go_orchestrator,node_go_sensor_producer,node_go_ui_display,node_go_services toneAmber
class node_reference_main,node_ble_integration toneMint
class node_u8g2,node_esp_nimble_cpp,node_libnmea_esp32 toneRose
```

## Components

### Shared components

Reusable firmware capabilities built as drivers, HALs, and services.

- [Common](https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-common): shared plumbing · Cross-cutting logging, common types, measures, and RTOS helpers. · `components/airgradient-common`
- [Sensors](https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-sensors): sensor stack · Shared sensor subsystem with HALs, drivers, and a sensor manager service. · `components/airgradient-sensors`
- [BLE](https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-ble): connectivity · Modular Bluetooth Low Energy server stack with HAL and NimBLE driver. · `components/airgradient-ble`
- [Cellular](https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-cellular): connectivity · Cellular modem abstraction plus AT-command orchestration. · `components/airgradient-cellular`
- [GPS](https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-gps): location stack · NMEA-based GPS sensor component and supporting types. · `components/airgradient-gps`
- [Serial](https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-serial): transport · Shared UART and I2C-serial transport abstractions. · `components/airgradient-serial`
- [BMS](https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-bms): power stack · Battery management HAL and drivers for TI BQ devices. · `components/airgradient-bms`
- [Config](https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-config): nvs store · Persistent configuration abstraction backed by NVS storage. · `components/airgradient-config`
- [Payload cache](https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-payload-cache): rtc buffer · Local payload buffering and RTC-backed cache storage service. · `components/airgradient-payload-cache`
- [GPIO](https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-gpio): hardware io · Portable GPIO abstraction with native driver implementation. · `components/airgradient-gpio`
- [Touch](https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-touch): input hw · CAP1203 touch controller HAL and driver. · `components/airgradient-touch`
- [NAND storage](https://github.com/airgradienthq/airgradient-firmware/tree/main/components/airgradient-nand-storage): storage hw · SPI NAND storage abstraction for local persistence. · `components/airgradient-nand-storage`
- [ADS1115](https://github.com/airgradienthq/airgradient-firmware/tree/main/components/ads1115): adc library · Standalone ADC device library reused by sensor-related code. · `components/ads1115`
- [BQ25629](https://github.com/airgradienthq/airgradient-firmware/tree/main/components/bq25629): charger lib · Standalone charger/power-management device library. · `components/bq25629`

### Go product

Primary application assembly and event-driven orchestration for the portable monitor.

- [Go app](https://github.com/airgradienthq/airgradient-firmware/blob/main/products/go/main/main.cpp): product entry · Product application entrypoint and board assembly for the Go monitor. · `products/go/main/main.cpp`
- [Orchestrator](https://github.com/airgradienthq/airgradient-firmware/blob/main/products/go/main/go_orchestrator.cpp): coordination · Event-driven coordinator that binds product services together. · `products/go/main/go_orchestrator.cpp`
- [Sensor producer](https://github.com/airgradienthq/airgradient-firmware/blob/main/products/go/main/go_sensor_producer.cpp): data pipeline · Product-side acquisition and normalization path for sensor data. · `products/go/main/go_sensor_producer.cpp`
- [UI + display](https://github.com/airgradienthq/airgradient-firmware/blob/main/products/go/main/go_ui.cpp): presentation · Presentation layer that renders state and user-facing output. · `products/go/main/go_ui.cpp`
- [Device services](https://github.com/airgradienthq/airgradient-firmware/blob/main/products/go/main/go_ble.cpp): product services · Product wiring for BLE, GPS, input, power, settings, and storage. · `products/go/main/go_ble.cpp`

### Reference product

Thin validation app that exercises shared hardware components.

- [Reference app](https://github.com/airgradienthq/airgradient-firmware/blob/main/products/reference/main/main.cpp): validation app · Thin hardware/component validation root for the reference product. · `products/reference/main/main.cpp`
- [BLE tests](https://github.com/airgradienthq/airgradient-firmware/tree/main/tests/ble-integration): integration suite · Host-side BLE protocol and service integration coverage. · `tests/ble-integration`

### Vendored deps

Third-party libraries embedded under components/ as support infrastructure.

- [u8g2](https://github.com/airgradienthq/airgradient-firmware/tree/main/components/u8g2): display lib · Vendored graphics and font library used by display code. · `components/u8g2`
- [NimBLE CPP](https://github.com/airgradienthq/airgradient-firmware/tree/main/components/esp-nimble-cpp): ble dep · Vendored C++ wrapper for NimBLE used by the BLE component. · `components/esp-nimble-cpp`
- [libnmea](https://github.com/airgradienthq/airgradient-firmware/tree/main/components/libnmea-esp32): gps dep · Vendored NMEA parsing library used by GPS support. · `components/libnmea-esp32`

## Connections

- Sensors → ADS1115: uses · Sensor capability can depend on shared ADC support.
- BMS → BQ25629: uses · Battery management builds on charger device support.
- BLE → NimBLE CPP: wraps · BLE server implementation is built on NimBLE C++.
- GPS → libnmea: parses · GPS capability relies on vendored NMEA parsing.
- Sensors → Common: shares · Sensors reuse common logging, types, and RTOS helpers.
- BLE → Common: shares · BLE component uses common infrastructure.
- Cellular → Common: shares · Cellular component uses common infrastructure.
- GPS → Common: shares · GPS component uses common infrastructure.
- Serial → Common: shares · Serial transport uses common infrastructure.
- BMS → Common: shares · BMS component uses common infrastructure.
- Config → Common: shares · Config store uses common infrastructure.
- Payload cache → Common: shares · Payload cache uses common infrastructure.
- Go app → Orchestrator: starts · Application entrypoint launches the main coordinator.
- Orchestrator → Sensor producer: coordinates · Orchestrator consumes acquired sensor state.
- Orchestrator → UI + display: updates · Orchestrator drives presentation state and display updates.
- Orchestrator → Device services: routes · Orchestrator connects device services through events.
- Sensor producer → Sensors: reads · Product sensor pipeline is built on shared sensor capability.
- Device services → BLE: uses · Product wiring includes the shared BLE subsystem.
- Device services → GPS: uses · Product wiring includes shared GPS capability.
- Device services → BMS: uses · Product wiring includes battery management.
- Device services → Config: uses · Product settings persist through shared config storage.
- Device services → Payload cache: uses · Product storage path can buffer payloads locally.
- Device services → Serial: uses · Product services depend on shared serial transports.
- Device services → Touch: uses · Input handling is backed by the touch controller.
- UI + display → u8g2: renders with · Presentation layer is backed by the graphics library.
- Reference app → BLE: exercises · Reference app validates BLE behavior.
- Reference app → GPIO: exercises · Reference app validates GPIO behavior.
- Reference app → NAND storage: exercises · Reference app validates NAND storage behavior.
- Reference app → Payload cache: exercises · Reference app validates payload caching behavior.
- Reference app → Sensors: exercises · Reference app validates shared sensor behavior.
- Reference app → Serial: exercises · Reference app validates serial transport behavior.
- Reference app → Touch: exercises · Reference app validates touch input behavior.
- Reference app → Config: exercises · Reference app validates configuration behavior.
- BLE tests → BLE: tests · Host integration suite targets BLE services.
