Host TypeScript Tooling
Relevant source files
The following files were used as context for generating this wiki page:
The Host TypeScript Tooling within the OpenAwair project serves as a comprehensive framework for managing, configuring, and integrating Awair Glow C and Awair Element devices. It provides high-level abstractions for device behavior, firmware updates, networking, and sensor data management, enabling seamless integration with ecosystems like Home Assistant.
The tooling is primarily located in the host/ directory and is designed to act as a bridge between the physical hardware (running C/C++ firmware) and end-user applications. It handles critical tasks such as Device Firmware Updates (DFU), Wi-Fi provisioning, and telemetry publishing via MQTT and REST.
Sources: CLAUDE.md:46-60, README.md:11-13
Architecture Overview
The host tooling architecture is modular, separating device logic, networking, and external tooling. It utilizes TypeScript for type safety and compiles to CommonJS for execution.
The architecture facilitates a clear data flow from raw sensor readings to structured telemetry.
Sources: CLAUDE.md:63-75, host/tsconfig.json:3-15
Core Components
Device Management
The AwairDevice class acts as the central controller for a device instance. It manages sensor scheduling and hardware states like the relay.
| Method | Description |
|---|---|
collectMetrics | Gathers sensor data and returns a DeviceMetrics object. |
toggleRelay | Switches the state of the integrated power relay. |
getRelayState | Returns the current boolean state of the relay. |
Sources: host/src/firmware/device.ts:6-30
Device Firmware Update (DFU)
The DFU system manages the transmission and validation of firmware images. It uses a chunk-based approach to handle memory constraints.
The DfuSession ensures that the received firmware matches the expectedCrc before it is considered valid for flashing.
Sources: host/src/firmware/bootloader/dfu.ts:21-61
Networking and Integration
MQTT Connectivity
The MqttPublisher class formats device data into topics compatible with Home Assistant and other MQTT brokers.
- Telemetry Topic:
openawair/{deviceId}/telemetry - Availability Topic:
openawair/{deviceId}/availability
Sources: host/src/firmware/networking/mqtt.ts:10-24
REST API Routing
The RestRouter handles incoming HTTP-like requests for local device interaction, supporting endpoints for metrics and hardware control.
| Endpoint | Method | Purpose |
|---|---|---|
/api/v1/metrics | GET | Retrieve latest DeviceMetrics in JSON format. |
/api/v1/relay | POST | Toggle the device relay and receive the new state. |
Sources: host/src/firmware/networking/restRouter.ts:15-35, host/src/firmware/networking/rest.ts:10-28
Data Models
Telemetry and device states are strictly typed to ensure consistency across the host tooling.
export interface DeviceMetrics {
readonly deviceId: string;
readonly model: 'AwairGlowC' | 'AwairElement';
readonly sensors: SensorReading;
readonly motionDetected?: boolean;
readonly ambientLightLux?: number;
}
Sources: host/src/shared/telemetry.ts:18-24
Development and Build Tooling
The project uses the standard TypeScript compiler (tsc) with specific configurations for linting and testing.
| Command | Script | Description |
|---|---|---|
npm run typecheck | tsc -p host/tsconfig.json --noEmit | Validates types without generating files. |
npm run lint | tsc -p host/tsconfig.lint.json --noEmit | Checks for unused locals and parameters. |
npm run test | node --test dist/test/*.js | Executes tests using the native Node.js test runner. |
Sources: package.json:7-11, host/tsconfig.lint.json:1-7
Summary
The Host TypeScript Tooling provides the necessary infrastructure to restore and extend Awair devices. By abstracting complex tasks like DFU sessions and MQTT discovery into manageable TypeScript modules, it allows for stable local-first operation and easy integration into modern smart home environments.