Home Assistant Auto-Discovery
Relevant source files
The following files were used as context for generating this wiki page:
The Home Assistant Auto-Discovery system in OpenAwair enables seamless integration of Awair Glow C and Awair Element devices into Home Assistant without manual configuration. By leveraging the MQTT protocol, the firmware sends specific configuration payloads that allow Home Assistant to automatically identify the device, its model, and the available sensors it carries.
This mechanism is a core component of the project's goal to provide local-first functionality for discontinued Awair hardware. On the first connection to the MQTT broker, the firmware publishes discovery messages to the standard homeassistant/ topic prefix, triggering the automatic creation of entities in the Home Assistant UI.
Sources: CLAUDE.md:12-14, CLAUDE.md:120-121
System Architecture
The auto-discovery logic is centralized in the host-side tooling and designed to be implemented within the device firmware. The system consists of data structures defining the device and its sensors, and a generator function that transforms these structures into MQTT messages formatted for Home Assistant's expectations.
Data Flow Overview
The following diagram illustrates the flow from device metadata and sensor definitions to the final MQTT discovery messages published to the broker.
The discovery process starts by aggregating device identifiers and sensor capabilities, which are then mapped to specific MQTT topics.
Sources: host/src/firmware/networking/mqttDiscovery.ts:21-25, host/test/mqttDiscovery.test.ts:7-25
Components and Data Structures
The system relies on two primary interfaces to define the hardware state for discovery: DiscoveryDevice and DiscoverySensor.
DiscoveryDevice
This interface encapsulates the physical attributes of the Awair hardware.
| Field | Type | Description |
|---|---|---|
identifiers | string[] | Unique hardware IDs (e.g., MAC address or serial) |
name | string | Human-readable name (e.g., "Awair Glow C") |
model | string | Specific hardware model |
manufacturer | string | Device manufacturer (set to "Awair") |
Sources: host/src/firmware/networking/mqttDiscovery.ts:3-8
DiscoverySensor
This interface defines how individual environmental metrics are exposed to Home Assistant.
| Field | Type | Description |
|---|---|---|
name | string | The sensor name (e.g., "Temperature") |
uniqueId | string | Unique entity ID for HA |
stateTopic | string | The MQTT topic where data is published |
unitOfMeasurement | string | Unit (e.g., "°C", "ppm", "ppb") |
deviceClass | string | HA device class for icons/behavior |
valueTemplate | string | JSONPath to extract value from telemetry |
Sources: host/src/firmware/networking/mqttDiscovery.ts:10-17
Implementation Logic
The discovery logic is implemented in the buildDiscoveryMessages function. It iterates through a list of sensors and generates a dedicated MQTT message for each.
Topic Structure
Discovery messages are published using the following topic format:
homeassistant/sensor/{baseId}/{sensorUniqueId}/config
Where baseId is the first identifier in the device's identifier list.
Sources: host/src/firmware/networking/mqttDiscovery.ts:48, host/test/mqttDiscovery.test.ts:30
Payload Construction
The payload is a JSON string containing both sensor-specific configuration and the parent device metadata. This grouping ensures that all sensors (Temperature, Humidity, CO2, etc.) appear under a single "Device" in the Home Assistant dashboard.
Integration with Telemetry
The discovery configuration explicitly links to the telemetry topics defined in the MqttPublisher class. For example, a discovery message for temperature will set its stateTopic to openawair/{deviceId}/telemetry and use a valueTemplate like {{ value_json.sensors.temperatureC }} to parse the incoming sensor data.
| Metric | Source Field | Unit | Topic |
|---|---|---|---|
| Temperature | temperatureC | °C | openawair/{id}/telemetry |
| Humidity | humidityPercent | % | openawair/{id}/telemetry |
| CO2 | co2Ppm | ppm | openawair/{id}/telemetry |
| VOC | vocPpb | ppb | openawair/{id}/telemetry |
| PM2.5 | pm25UgM3 | µg/m³ | openawair/{id}/telemetry |
Sources: host/src/shared/telemetry.ts:8-15, host/src/firmware/networking/mqtt.ts:10-15, host/test/mqttDiscovery.test.ts:20-22
Summary
The Home Assistant Auto-Discovery module provides a standardized way to describe OpenAwair hardware capabilities to external smart home controllers. By generating standardized MQTT payloads based on DiscoveryDevice and DiscoverySensor definitions, the system automates the setup process, ensuring that telemetry data from the STM32F412-based devices is immediately usable upon connection.