MQTT Telemetry Publishing

Relevant source files

The following files were used as context for generating this wiki page:

• host/src/firmware/networking/mqtt.ts
• host/src/shared/telemetry.ts
• host/src/firmware/networking/mqttDiscovery.ts
• host/src/firmware/device.ts
• CLAUDE.md
• host/test/mqtt.test.ts

The MQTT Telemetry Publishing system in OpenAwair provides a standardized mechanism for transmitting environmental sensor data from Awair Glow C and Awair Element devices to central brokers. This system ensures that air quality metrics are accessible for local-first integrations, specifically targeting Home Assistant via MQTT Discovery protocols.

The architecture relies on a specialized publisher class that formats internal device metrics into JSON payloads and maps them to structured MQTT topics. This allows for fully offline operation where data is distributed over the local network rather than relying on discontinued cloud services.
Sources: CLAUDE.md:8-10, host/src/firmware/networking/mqtt.ts:1-20

Core Architecture and Data Flow

The telemetry system follows a structured flow from hardware sensor acquisition to formatted network transmission. The AwairDevice controller orchestrates sensor sampling, which produces DeviceMetrics. These metrics are then consumed by the MqttPublisher to generate routable MQTT messages.

This diagram illustrates the transformation of raw sensor data into MQTT-ready messages.
Sources: host/src/firmware/device.ts:7-24, host/src/firmware/networking/mqtt.ts:9-22

Telemetry Payload Structure

The telemetry data is encapsulated in the DeviceMetrics interface, which includes device identification, model information, and a collection of sensor readings.

Field	Type	Description
deviceId	string	Unique identifier for the hardware unit.
model	string	Literal type: 'AwairGlowC' or 'AwairElement'.
sensors	SensorReading	Object containing timestamps and numerical sensor values.
motionDetected	boolean	Optional flag for PIR sensor state (Glow C).
ambientLightLux	number	Optional light intensity value (Element).

Sources: host/src/shared/telemetry.ts:18-24

MqttPublisher Implementation

The MqttPublisher class serves as the primary engine for creating standardized MQTT messages. It defines two main types of communication: state telemetry and device availability.

Telemetry Messages

Telemetry messages are published to topics following the pattern openawair/{deviceId}/telemetry. The payload is a stringified JSON representation of the DeviceMetrics object.

// Example of building a telemetry message
public buildTelemetryMessage(metrics: DeviceMetrics): MqttMessage {
  return {
    topic: `openawair/${metrics.deviceId}/telemetry`,
    payload: JSON.stringify(metrics)
  };
}

Sources: host/src/firmware/networking/mqtt.ts:11-16

Availability Status

To support robust monitoring, the system publishes availability messages to openawair/{deviceId}/availability. These payloads indicate whether the device is 'online' or 'offline', allowing integration platforms to track connection states.
Sources: host/src/firmware/networking/mqtt.ts:18-21, CLAUDE.md:129

Home Assistant MQTT Discovery

OpenAwair supports automatic entity creation in Home Assistant through MQTT Discovery. This removes the need for manual configuration by publishing specific configuration payloads to the homeassistant/ base topic.

The discovery process establishes the relationship between MQTT topics and Home Assistant entities.
Sources: host/src/firmware/networking/mqttDiscovery.ts:31-57, CLAUDE.md:133-134

Discovery Configuration Components

The system generates discovery messages for each individual sensor. Key configuration fields include:

• Unique ID: Combines the device ID and sensor name (e.g., awair-01-temp).
• State Topic: Points back to the standard telemetry topic used by the MqttPublisher.
• Value Template: A Jinja2 template (e.g., {{ value_json.sensors.temperatureC }}) used by Home Assistant to extract specific values from the telemetry JSON.
• Device Class: Categorizes the sensor (e.g., temperature, humidity) for appropriate UI rendering.

Sources: host/src/firmware/networking/mqttDiscovery.ts:11-20, host/test/mqttDiscovery.test.ts:14-20

Summary

The MQTT Telemetry Publishing module is a critical component of the OpenAwair host-side architecture. By abstracting the complexities of topic management and payload formatting into the MqttPublisher and mqttDiscovery utilities, the project ensures that sensor data from reclaimed hardware is seamlessly integrated into modern smart home ecosystems using standard, local-only protocols.
Sources: CLAUDE.md:9-12, host/src/index.ts:7-8