OT-0001 Sensor Hardware Conventions¶

Field	Value
ID	OT-0001
Date	2026-05-02
Status	Accepted
Deciders	Ben Peries
Consolidates	OT-0001 (2026-04-01), OT-0003 (2026-04-02), OT-0004 (2026-04-02), OT-0008 (2026-04-14)

Context¶

OT sensor nodes require consistent naming, GPIO pin assignments, and measurement unit conventions across all deployed hardware. Four earlier ADRs captured these decisions individually as nodes were added. This consolidation unifies them into a single authoritative reference.

Section 1 - Sensor Naming Convention¶

Source: OT-0001 (2026-04-01), amended 2026-04-20

Decision¶

Node identifiers follow the pattern:

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

Segment	Meaning	Example
`cae`	CanEast cluster prefix	fixed
`{cluster}`	Cluster number	`1`
`ot{zone}`	OT zone number	`ot-zone` = Basement
`{type}`	3-letter type code	`snr`
`{nn}`	2-digit zero-padded sequence	`01`

Full example: caneast-site1-ot1-snr01 - CanEast cluster 1, OT zone 1 (Basement), sensor node 01.

Type Code Registry¶

Code	Type	Notes
`snr`	Sensor node	General-purpose sensing (renamed from `esp` 2026-04-20)
`cam`	Camera	Image/video capture
`gwy`	Gateway	Protocol bridge (e.g., Modbus→MQTT)
`ctr`	Controller	Actuator-capable node
`dsp`	Display	HMI / panel display
`pwr`	Power monitor	Current, voltage, energy metering
`hvc`	HVAC node	Climate control sensing/actuation
`mtr`	Motor controller	Drive / pump controller
`aud`	Audio node	Sound detection / alerting
`net`	Network node	Network probe / tap
`sec`	Security node	Door/window sensor, PIR
`env`	Environment node	Air quality, CO₂, temperature

Zone Map¶

Zone	Location
`ot-zone`	Basement
`ot-zone`	Main floor / garage
`ot-zone`	Outdoor
`ot-zone`	Server rack

Amendment - 2026-04-20¶

esp type code retired; snr is the canonical sensor-node code.
All type codes are exactly 3 characters.
Sequence numbers are always 2-digit zero-padded (01, 02, …, 99).

Section 2 - GPIO Pin Assignments¶

Source: OT-0003 (2026-04-02), OT-0004 (2026-04-02), OT-0008 (2026-04-14)

Rain Sensor - GPIO PIN 34¶

Decision: The rain sensor (tipping-bucket pulse counter) on caneast-site1-ot1-snr01 is wired to GPIO PIN 34.

Rationale: PIN 34 is ADC1_CH6 on the ESP32. It is input-only with no internal pull-up resistor, which is correct for a passive pulse-counting circuit. PIN 19 was the alternative but is part of the SPI bus (MISO) and is unsuitable for high-frequency interrupt-driven counting.

HC-SR04 - Millimetres, Not Centimetres¶

Decision: The HC-SR04 ultrasonic distance sensor publishes measurements in millimetres (mm).

Formula:

distance_mm = duration_us × 0.343 / 2

Where duration_us is the echo pulse duration in microseconds and 0.343 mm/µs is the speed of sound at ~20 °C.

Rationale: Centimetre resolution (1 cm ≈ 10 mm) is insufficient for sump-pit level monitoring where 5 mm changes are operationally significant. Publishing in mm avoids floating-point division in firmware and keeps MQTT payloads as integers.

caneast-site1-ot1-snr02 - Basement Freezer Sensor Node¶

Status: Proposed (hardware spec locked; firmware pending)

caneast-site1-ot1-snr02 is the second OT sensor node in OT zone 1 (Basement). It monitors the chest freezer for temperature, compressor vibration, and door state.

Hardware:

Component	Purpose
ESP32 (30-pin)	Compute
DS18B20 × 2	Interior temperature + compressor surface temperature
MPU-6050	Compressor vibration (accelerometer)
MC-38 reed switch	Door open/closed state

GPIO Assignments:

GPIO	Function	Protocol
4	DS18B20 data bus	OneWire
21	MPU-6050 SDA	I²C
22	MPU-6050 SCL	I²C
23	MC-38 reed switch	Digital input (pull-up)

MQTT Topics (under caneast/ot-zone/snr02/):

Topic	Unit	Description
`temp_interior`	°C (float)	Freezer interior temperature
`temp_compressor`	°C (float)	Compressor surface temperature
`accel_x`	m/s²	X-axis acceleration (vibration)
`accel_y`	m/s²	Y-axis acceleration
`accel_z`	m/s²	Z-axis acceleration
`vibration_stddev`	m/s²	Rolling stddev (vibration proxy)
`door_state`	0/1	0 = closed, 1 = open
`rssi`	dBm	Wi-Fi signal strength

Alert Thresholds:

Condition	Threshold	Severity
Interior temp > −12 °C	Sustained 5 min	Warning
Interior temp > −8 °C	Sustained 2 min	Critical
Door open > 3 min	-	Warning
Compressor silent > 24 h	vibration_stddev < 0.05	Info

Rationale¶

Consolidating four hardware-specification ADRs removes redundancy and provides a single reference for firmware authors and MQTT pipeline maintainers. The naming convention, pin assignments, and measurement units are stable decisions that do not require individual ADR lifecycle management.

Consequences¶

All new sensor nodes must follow the cae{cluster}ot{zone}{type}{nn} pattern.
snr is the only valid code for ESP32 general-purpose sensing nodes; esp is retired.
HC-SR04 firmware must publish mm (integer); cm variants are non-compliant.
GPIO 4/21/22/23 are reserved on caneast-site1-ot1-snr02 and must not be reused.

Sources¶

Original ADR	Date	Content
OT-0001 Sensor Naming Convention	2026-04-01 (amended 2026-04-20)	Naming pattern, type codes, zone map
OT-0003 Rain Sensor PIN 34	2026-04-02	GPIO selection rationale
OT-0004 HC-SR04 mm not cm	2026-04-02	Measurement unit decision
OT-0008 snr02 Basement Freezer	2026-04-14	Hardware spec, GPIO map, MQTT topics

References¶

Addendum -- 2026-05-02¶

caneast-site1-ot2-cam01 hardware specification (WI-395):

Field	Value
Node ID	caneast-site1-ot2-cam01
Type code	cam (Camera/Vision)
Zone	ot-zone (main floor, garage)
Platform	Raspberry Pi 5 4GB
OS	Raspberry Pi OS Lite 64-bit Trixie (Debian 13, kernel 6.12 LTS, aarch64)
Camera	Camera Module 3 NoIR, CSI-2
Reed switch	MC-38 magnetic contact, GPIO 17 (pull-up)
Load cell	HX711 + 5 kg single-point load cell
Network	Wi-Fi (192.168.2.x DHCP-reserved)
SSH	Port 22; operator (interactive/bootstrap), ansible-ot-svc-account (automation, provisioned by Ansible)
MQTT broker	caneast-site1-mqtt1 (REDACTED:[REDACTED])
Inference endpoint	Ollama REDACTED:[REDACTED] (Tier 1)
Capture mode	Event-driven: MC-38 reed switch triggers frame capture

MQTT Topics (under caneast/ot-zone/cam01/):

Topic	Type	Description
door_state	0/1	0 = closed, 1 = open (reed switch)
capture_triggered	0/1	1 = frame captured and queued for inference
inference_result	JSON string	VL model output (label + confidence + tier used)
weight_kg	float	Load cell reading (kg)
rssi	dBm	Wi-Fi signal strength

GPIO Map:

GPIO	Function	Protocol
17	MC-38 reed switch	Digital input (pull-up)
5	HX711 DOUT	Bit-bang
6	HX711 SCK	Bit-bang