Skip to content

Consolidated into OT-0001 on 2026-05-02 per ADR-0047. This source file is retained as a reference; the canonical content is in OT-0001.

ADR-OT-0001: OT sensor node naming convention

Status

Amended — 2026-04-20

Original: Accepted 2026-03-31. See ## Amendment — 2026-04-20 for changes.

Context

OT field devices need a naming convention that is cluster-aware, zone-aware, scalable, and aligned with the IEC 62443 zone and conduit model. The original convention used esp as a hardware-specific type code tied to ESP32 boards. As the OT device inventory grows beyond a single hardware platform, a function-based type code registry is required so node names survive board swaps and describe operational role rather than chip vendor.

Decision

Pattern: cae{cluster}ot{zone}{type}{nn}

Where {type} is a 3-char function code from the registry below and {nn} is a 2-digit zero-padded sequence (01–99).

Type Code Registry

Code Full Name Primary Function Example
snr Sensor node Multi-sensor node (ESP32 or equivalent); primary function is data acquisition caneast-site1-ot1-snr01
cam Vision/camera node Image capture, any compute platform caneast-site1-ot2-cam01
gwy Gateway node Protocol bridge, MQTT broker caneast-site1-ot1-gwy01
ctr Controller node Actuator control, relays, valves caneast-site1-ot2-ctr01
dsp Display node Kiosk, dashboard screen, MagicMirror caneast-site1-ot2-dsp01
pwr Power monitor node Current sensing, EV charger, solar caneast-site1-ot4-pwr01
hvc HVAC node Thermostat, zone controller caneast-site1-ot2-hvc01
mtr Motor/mechanical node Compressor monitor, pump, vibration caneast-site1-ot1-mtr01
aud Audio node Microphone array, speaker, voice assistant caneast-site1-ot2-aud01
net Network node Pi-hole, WireGuard, packet capture caneast-site1-ot4-net01
sec Security node Door lock, motion detector, alarm panel bridge caneast-site1-ot2-sec01
env Environmental node Air quality, CO2, radon, particle sensor caneast-site1-ot3-env01

Sequence Format

All sequences are 2-digit zero-padded: 01 through 99. caneast-site1-ot1-esp1 was grandfathered and renamed to caneast-site1-ot1-snr01 at the time of this amendment.

Zone Map

Zone Physical Location
ot-zone Basement
ot-zone Main floor / garage
ot-zone Outdoor
ot-zone Rack monitoring

MQTT Topic Alignment

The mapping from node ID to MQTT topic prefix is deterministic (see ADR-OT-0002): - Strip the site digit from the region+site prefix: cae1 → cae - Keep ot{zone} and {type}{nn} segments - Join with slashes: caneast-site1-ot1-snr01 → topic prefix caneast/ot-zone/snr01/

Current Nodes

Node ID Location Sensors
caneast-site1-ot1-snr01 Basement — sump pit HC-SR04 level, float switch flood, rain sensor, MPU-6050 IMU

Amendment — 2026-04-20

  • Renamed type code esp → snr (sensor node). Rationale: esp was hardware-specific; snr is function-based and survives board swaps.
  • Added 12-code type registry covering vision, gateway, controller, display, power, HVAC, motor, audio, network, security, and environmental nodes.
  • Mandated 2-digit zero-padded sequences (snr01, not snr1). Prevents naming collisions at 10+ nodes per zone.
  • Added explicit MQTT topic alignment rule, closing the implicit mapping gap identified in the 2026-04-20 naming convention audit.
  • Renamed deployed node caneast-site1-ot1-esp1 → caneast-site1-ot1-snr01. MQTT topic tree updated in ADR-OT-0002 and Telegraf config. Historical InfluxDB data under esp1_* measurements requires a Flux migration task (documented in ADR-OT-0005 addendum, not retroactively re-flashed).

Alternatives Considered (original 2026-03-31)

cae1 flat (no zone) — Flat namespace, doesn't scale, no zone semantics.

cae1-ot-zone1-esp1 (hyphenated) — DNS-safe names prefer no nested hyphens. Note: this referenced the original esp type code, superseded by this amendment.

UUID-based naming — Not human-readable, poor ops experience.

Consequences

  • All new OT sensors must follow cae{cluster}ot{zone}{type}{nn} with 2-digit padding
  • MQTT topic structure aligns deterministically with node name (see ADR-OT-0002)
  • Ansible OT inventory groups nodes by zone
  • IEC 62443 zone model can be demonstrated using this naming as an anchor
  • InfluxDB measurement names follow {type}{nn}_{metric} pattern (e.g., snr01_level)
  • Historical InfluxDB data under esp1_* measurements requires a Flux migration task after Telegraf is redeployed with snr01_* topic subscriptions

References

  • IEC 62443-3-3 zone and conduit model
  • ADR-OT-0002 (MQTT topic structure)
  • ADR-0024 (region-based node naming)
  • ADR-OT-0005 (InfluxDB historian retention — migration task documented there)