Skip to content

OT-0002 MQTT Topic Structure

Field Value
ID OT-0002
Date 2026-05-02
Status Accepted
Deciders Ben Peries
Migrated from OT-0002 (2026-04-01, amended 2026-04-20)

Context

OT sensor nodes publish telemetry via Mosquitto on caneast-site1-mqtt1. A consistent topic hierarchy is required so that Node-RED pipelines, InfluxDB Telegraf consumers, and Grafana panels can address nodes and metrics deterministically without hardcoding per-node topic lists.

Decision

MQTT topics follow the pattern:

caneast/ot{zone}/{type}{nn}/{metric}
Segment Meaning Example
cae CanEast namespace fixed
ot{zone} OT zone number ot-zone = Basement
{type}{nn} Node type + 2-digit sequence snr01
{metric} Metric leaf level, flood, temp_interior

Full example: caneast/ot-zone/snr01/level — sump pit water level from sensor 01 in Basement zone.

Deterministic Node-to-Topic Mapping Rule

A node's full MQTT prefix is always derivable from its node ID:

node_id = caneast-site1-ot1-snr01
→ prefix  = caneast/ot-zone/snr01/

Strip the cluster prefix (cae1), insert / before ot, then / before the type code. No lookup table required.

Current Topics — caneast-site1-ot1-snr01

Topic Unit Description
caneast/ot-zone/snr01/level mm Sump pit water level (HC-SR04)
caneast/ot-zone/snr01/flood 0/1 Flood alarm state
caneast/ot-zone/snr01/status string Node health string
caneast/ot-zone/snr01/rssi dBm Wi-Fi signal strength
caneast/ot-zone/snr01/rain tips Rain gauge tip count
caneast/ot-zone/snr01/imu/accel_x m/s² IMU X-axis acceleration
caneast/ot-zone/snr01/imu/accel_y m/s² IMU Y-axis acceleration
caneast/ot-zone/snr01/imu/accel_z m/s² IMU Z-axis acceleration

Wildcard Patterns

Pattern Selects
caneast/ot-zone/# All metrics from all zone-1 nodes
caneast/+/snr01/# All metrics from snr01 in any zone
caneast/ot-zone/snr01/+ All leaf metrics from caneast-site1-ot1-snr01

Payload Format

Payloads are plain floats or integers as UTF-8 strings. No JSON envelope. Consumers parse the raw value directly.

Amendment — 2026-04-20

  • esp node type code retired; snr is canonical. Topics containing esp are deprecated; firmware must republish under snr prefix.
  • All type codes in topic paths are exactly 3 characters + 2-digit sequence.

Rationale

The caneast/ot{zone}/{type}{nn}/{metric} pattern mirrors ISA-95 equipment hierarchy (Area → Unit → Tag). The zone segment isolates MQTT namespace by physical location, enabling zone-scoped wildcard subscriptions in Node-RED and Telegraf without per-topic configuration.

Plain scalar payloads avoid JSON parsing overhead in firmware and keep Telegraf MQTT consumer configuration simple.

Consequences

  • All OT firmware must publish under caneast/ot{zone}/{type}{nn}/{metric}.
  • Telegraf inputs.mqtt_consumer topic filters use the deterministic prefix pattern.
  • Grafana panels reference metrics by topic path; changing the pattern requires dashboard updates across all OT panels.
  • New metrics on existing nodes append a new leaf; they do not require a new ADR.

References