Device Controller Abstraction
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Device Controller Abstraction in OpenAwair serves as the central orchestration layer for managing Awair Glow C and Awair Element hardware. It provides a high-level TypeScript interface (AwairDevice) that encapsulates sensor scheduling, hardware state management (such as relay control), and telemetry aggregation. This abstraction ensures that host-side tooling can interact with different Awair models through a unified API, regardless of the underlying hardware variations.
Sources: host/src/firmware/device.ts:1-30, CLAUDE.md:50-65
Architecture and Core Components
The AwairDevice Class
The primary controller is the AwairDevice class. It acts as a facade for the device's internal subsystems, specifically managing a SensorScheduler to coordinate data collection from various hardware drivers.
The diagram above shows the relationship between the main device controller and the sensor subsystem.
Sources: host/src/firmware/device.ts:6-29, host/src/firmware/sensors/sensor.ts
Hardware Support
The abstraction supports two primary hardware models, defined in both the C firmware headers and the TypeScript shared types:
- Awair Glow C: Includes sensors for temperature, humidity (SHTC3), TVOC (SGP30), and a physical relay.
- Awair Element: Includes sensors for temperature, humidity (SHT30), TVOC (SGP30), CO2 (T6703), and PM2.5 (HPMA115S0).
Sources: firmware/include/firmware_config.h:4-5, host/src/shared/telemetry.ts:18-19, CLAUDE.md:14-27
Data Models and Telemetry
Device Metrics
The DeviceMetrics interface defines the standardized format for all data collected by the controller. This object is used for both MQTT publishing and REST API responses.
| Field | Type | Description |
|---|---|---|
deviceId | string | Unique identifier for the device |
model | enum | Either 'AwairGlowC' or 'AwairElement' |
sensors | SensorReading | Object containing all active sensor values |
motionDetected | boolean | State of the PIR sensor (Glow C specific) |
ambientLight | number | Lux value from the light sensor |
Sources: host/src/shared/telemetry.ts:16-23
Metrics Collection Flow
When collectMetrics is called, the device triggers the scheduler to poll all registered SensorDriver instances.
Interaction Endpoints
REST API Mapping
The controller's methods are directly exposed via REST endpoints to maintain compatibility with original Awair local API patterns.
GET /api/v1/metrics: CallscollectMetrics()to return the latestDeviceMetrics.POST /api/v1/relay: ExecutestoggleRelay()and returns the new state.
Sources: host/src/firmware/networking/rest.ts:10-29
Control Logic
The AwairDevice maintains internal state for the Glow C's power relay. The abstraction ensures that state changes are tracked locally before being dispatched to the hardware.
// host/src/firmware/device.ts:24-29
public toggleRelay(): void {
this.relayEnabled = !this.relayEnabled;
}
public getRelayState(): boolean {
return this.relayEnabled;
}
Sources: host/src/firmware/device.ts:24-29
Conclusion
The Device Controller Abstraction provides a robust foundation for the OpenAwair project by decoupling high-level logic from specific sensor implementations. By centralizing hardware state and telemetry collection within the AwairDevice class, the system achieves a consistent interface for external integrations like Home Assistant while managing the complexities of multiple hardware revisions.