Introduction to OpenAwair
Relevant source files
The following files were used as context for generating this wiki page:
OpenAwair is an open-source project designed to restore local-first functionality to Awair Glow C and Awair Element air quality monitors. These devices lost cloud support in 2022, and this project aims to provide fully offline operation by replacing the original firmware and providing host-side tooling for integration with ecosystems like Home Assistant.
The project architecture is divided into two primary domains: embedded firmware written in C/C++ for the STM32F412 MCU and host-side tooling written in TypeScript for Device Firmware Updates (DFU), Wi-Fi provisioning, and communication bridging.
Sources: README.md:1-5, CLAUDE.md:5-9
Hardware Architecture
Both supported devices utilize the Laird Sterling-EWB module, which integrates an STM32F412 ARM Cortex-M4 MCU with a Cypress CYW4343W Wi-Fi/BLE chipset. The project targets the AWAIR-LITE-MAIN V2.0 board found in the Element and the specific sensor arrays in the Glow C.
Supported Devices and Sensors
| Device | Temperature/Humidity | VOC/CO₂ | Other Sensors | Actuators |
|---|---|---|---|---|
| Glow C | SHTC3 (I²C) | SGP30 (I²C) | PIR Motion (GPIO) | RGB LED, Relay |
| Element | SHT30 (I²C) | SGP30 & T6703 | HPMA115S0 (PM2.5), Light | Dot-matrix LED |
Sources: CLAUDE.md:11-23, host/src/shared/telemetry.ts:9-16
Software Architecture
OpenAwair employs a decoupled architecture where the host-side TypeScript code defines the behavioral contracts and logic that the embedded C firmware implements.
Host Tooling Structure
The host-side logic handles the complex orchestration of telemetry, networking, and firmware management.
The AwairDevice class acts as the central controller, managing a SensorScheduler to poll drivers and providing methods to interact with hardware components like the power relay.
Sources: CLAUDE.md:43-55, host/src/firmware/device.ts:6-21
Embedded Firmware
The firmware is intended to be built using the WICED SDK or Infineon ModusToolbox. It manages low-level hardware initialization, sensor timing, and the DFU recovery environment.
- Bootloader Region: 64-128KB; handles BLE DFU and recovery.
- Application Region: Main firmware containing sensor tasks and networking stacks.
Sources: CLAUDE.md:57-64, firmware/README.md:3-8
Networking and Integration
OpenAwair provides multiple interfaces for data access and device control, ensuring compatibility with modern home automation systems.
MQTT and Home Assistant Discovery
The firmware sends telemetry as JSON payloads and supports Home Assistant MQTT Discovery for automatic entity creation.
REST API
Local access is provided via a REST API compatible with the original Awair local API.
GET /air-data/latest: Retrieves current sensor readings.POST /api/v1/relay: Toggles the Glow C power relay.
Sources: CLAUDE.md:104-107, host/src/firmware/networking/rest.ts:17-26
Bootloader and DFU Flow
Updates are delivered via a BLE DFU (Device Firmware Update) protocol. The loader application streams the firmware in ~512-byte chunks, which are validated using CRC32 before being committed to flash.
The DfuSession class manages this state, ensuring that only valid, complete images are marked for execution.
Sources: CLAUDE.md:73-86, host/src/firmware/bootloader/dfu.ts:20-45
Development and Management
Project tasks are managed through a phased PRD (Product Requirements Document) system located in docs/tasks/.
| Phase | Focus | Key Components |
|---|---|---|
| Phase 1 | Foundation | Hardware validation, sensor drivers, scheduler |
| Phase 2 | Networking | Wi-Fi provisioning, MQTT, REST |
| Phase 3 | Features | Glow C/Element specific logic (Relay, LED) |
| Phase 4 | DFU/OTA | Bootloader, BLE DFU protocol, host tooling |
Sources: CLAUDE.md:120-145, package.json:8-12