ADR-OT-0002: MQTT topic structure¶
Status¶
Accepted — 2026-03-31
Context¶
MQTT topics need a structure that is hierarchical, filterable via wildcards, aligned with the node naming convention, and extensible for new sensors and zones without restructuring.
Decision¶
Pattern: caneast/ot{zone}/esp{n}/{metric}
Current Topics — caneast-c1-ot1-esp1¶
| Topic | Description | Unit |
|---|---|---|
| caneast/ot1/esp1/level | Sump pit distance (HC-SR04) | mm |
| caneast/ot1/esp1/flood | Float switch state | 0 (dry) / 1 (flood) |
| caneast/ot1/esp1/status | Firmware heartbeat | string |
| caneast/ot1/esp1/rssi | WiFi signal strength | dBm |
Wildcard Subscription Patterns¶
| Pattern | Captures |
|---|---|
caneast/ot1/# |
All OT zone 1 topics |
caneast/+/esp1/level |
Level readings from all zones, node 1 |
caneast/# |
All Archon OT topics |
Alternatives Considered¶
Flat topics (esp1/level) — No zone hierarchy, no wildcard filtering per zone.
JSON payload per node (single topic) — Simpler to publish but harder to subscribe selectively. Telegraf MQTT input handles per-topic cleanly.
Consequences¶
- Telegraf
inputs.mqtt_consumersubscribes tocaneast/ot1/esp1/+for all zone 1 metrics - New sensors add a new
esp{n}subtree — existing subscriptions unaffected - Node-RED flows use zone wildcards for zone-level alerting logic
References¶
- MQTT v3.1.1 topic specification
- ADR-OT-0001 (sensor naming convention)
- Telegraf MQTT consumer plugin