Project Architecture
Relevant source files
The following files were used as context for generating this wiki page:
OpenAwair is designed to restore local-first functionality to discontinued Awair Glow C and Awair Element air quality monitors. The architecture is bifurcated into two primary domains: embedded firmware (C/C++) and host-side tooling (TypeScript). The firmware replaces the original cloud-dependent software to enable fully offline operation, while the host tooling provides mechanisms for Device Firmware Updates (DFU), Wi-Fi provisioning, and Home Assistant integration via MQTT and REST APIs.
Sources: CLAUDE.md:1-10, README.md:1-12
System Overview
The system architecture facilitates data acquisition from various sensors, local processing, and exposure of this data via multiple communication protocols.
The diagram above illustrates the high-level flow from physical sensors to end-user integrations and maintenance tools.
Sources: CLAUDE.md:43-55, host/src/firmware/device.ts:6-21
Hardware Components
The project supports two main hardware revisions based on the Laird Sterling-EWB module (STM32F412 MCU + CYW4343W Wi-Fi/BLE).
| Component | Awair Glow C | Awair Element |
|---|---|---|
| MCU | STM32F412 | STM32F412 |
| Connectivity | Wi-Fi/BLE (CYW4343W) | Wi-Fi/BLE (CYW4343W) |
| Temp/Humidity | SHTC3 (I2C) | SHT30 (I2C) |
| VOC/eCO2 | SGP30 (I2C) | SGP30 (I2C) |
| CO2 (NDIR) | N/A | Telaire T6703 (UART/I2C) |
| Particulate | N/A | Honeywell HPMA115S0 (UART) |
| Peripherals | PIR, RGB LED, Relay | LED Matrix, Light Sensor |
Sources: CLAUDE.md:13-33, firmware/include/firmware_config.h:4-5
Firmware Architecture
The firmware is structured to handle concurrent tasks including sensor polling, network communication, and system management.
Device Controller and Telemetry
The AwairDevice class acts as the central coordinator, utilizing a SensorScheduler to collect readings from registered SensorDriver instances. These readings are encapsulated into a DeviceMetrics structure for distribution.
Networking and Integration
The architecture supports dual-stack communication for data export and device control:
- MQTT: Used for telemetry streaming and Home Assistant Auto-Discovery. The
MqttPublisherbuilds JSON payloads for topics such asopenawair/{deviceId}/telemetry. - REST API: A
RestRouterhandles incoming HTTP requests. Default endpoints include/api/v1/metricsfor sensor data and/api/v1/relayfor hardware control.
Sources: host/src/firmware/networking/mqtt.ts:8-23, host/src/firmware/networking/restRouter.ts:16-33, host/src/firmware/networking/rest.ts:9-30
Bootloader and DFU Flow
Maintenance and updates are handled via a specialized DFU (Device Firmware Update) protocol, typically over BLE.
The DFU process ensures integrity by validating the entire image against a CRC32 checksum before application.
Sources: host/src/firmware/bootloader/dfu.ts:16-51, CLAUDE.md:88-100
Data Models
Telemetry Schema
Sensor data is standardized into the following technical structure:
| Field | Type | Description |
|---|---|---|
temperatureC | number | Temperature in Celsius |
humidityPercent | number | Relative humidity percentage |
vocPpb | number | Total Volatile Organic Compounds (Parts per Billion) |
co2Ppm | number | Carbon Dioxide levels (Parts per Million) |
pm25UgM3 | number | Particulate Matter 2.5 (μg/m³) |
Sources: host/src/shared/telemetry.ts:1-16
Summary
The OpenAwair architecture transforms proprietary air quality monitors into open, local-first IoT devices. By utilizing a modular TypeScript abstraction for host logic and a C/C++ foundation for firmware, the project provides a robust framework for sensor management, reliable updates via DFU, and seamless integration into modern home automation ecosystems like Home Assistant.
Sources: CLAUDE.md:5-10, README.md:1-5