How airgradienthq/airgradient-firmware works
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: main.cpp Reference app · go_ble.cpp Device services · airgradient-common Common · airgradient-ble BLE
Components 24
Shared components
Reusable firmware capabilities built as drivers, HALs, and services.
- Common · Cross-cutting logging, common types, measures, and RTOS helpers.
components/airgradient-common - Sensors · Shared sensor subsystem with HALs, drivers, and a sensor manager service.
components/airgradient-sensors - BLE · Modular Bluetooth Low Energy server stack with HAL and NimBLE driver.
components/airgradient-ble - Cellular · Cellular modem abstraction plus AT-command orchestration.
components/airgradient-cellular - GPS · NMEA-based GPS sensor component and supporting types.
components/airgradient-gps - Serial · Shared UART and I2C-serial transport abstractions.
components/airgradient-serial - BMS · Battery management HAL and drivers for TI BQ devices.
components/airgradient-bms - Config · Persistent configuration abstraction backed by NVS storage.
components/airgradient-config - Payload cache · Local payload buffering and RTC-backed cache storage service.
components/airgradient-payload-cache - GPIO · Portable GPIO abstraction with native driver implementation.
components/airgradient-gpio - Touch · CAP1203 touch controller HAL and driver.
components/airgradient-touch - NAND storage · SPI NAND storage abstraction for local persistence.
components/airgradient-nand-storage - ADS1115 · Standalone ADC device library reused by sensor-related code.
components/ads1115 - BQ25629 · Standalone charger/power-management device library.
components/bq25629
Go product
Primary application assembly and event-driven orchestration for the portable monitor.
- Go app · Product application entrypoint and board assembly for the Go monitor.
products/go/main/main.cpp - Orchestrator · Event-driven coordinator that binds product services together.
products/go/main/go_orchestrator.cpp - Sensor producer · Product-side acquisition and normalization path for sensor data.
products/go/main/go_sensor_producer.cpp - UI + display · Presentation layer that renders state and user-facing output.
products/go/main/go_ui.cpp - Device 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 · Thin hardware/component validation root for the reference product.
products/reference/main/main.cpp - BLE tests · Host-side BLE protocol and service integration coverage.
tests/ble-integration
Vendored deps
Third-party libraries embedded under components/ as support infrastructure.
- u8g2 · Vendored graphics and font library used by display code.
components/u8g2 - NimBLE CPP · Vendored C++ wrapper for NimBLE used by the BLE component.
components/esp-nimble-cpp - libnmea · Vendored NMEA parsing library used by GPS support.
components/libnmea-esp32
Connections 34
- 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.