Skip to content

OT-0004: HC-SR04 publishes distance in mm not cm

Status

Accepted — 2026-04-02

Context

The HC-SR04 ultrasonic sensor on caneast-c1-ot1-esp1 measures sump pit water level. The sensor returns distance in microseconds, which firmware converts to a physical unit before publishing to MQTT topic caneast/ot1/esp1/level. The initial implementation published in centimeters (cm).

Grafana dashboards and Telegram alert thresholds were configured in cm. At sump pit scale (typical range 5–50 cm), integer centimeter resolution loses meaningful granularity — a 1 cm change at the alert threshold can be the difference between normal and alarm state.

Decision

HC-SR04 distance is published in millimeters (mm) on the MQTT topic.

Firmware conversion: distance_mm = duration_us * 0.343 / 2 (speed of sound = 343 m/s at 20°C, round trip halved).

Rationale

  • Millimeter resolution provides 10x granularity over centimeters
  • Sump pit alert thresholds can be set with precision (e.g., 150 mm vs rounding to 15 cm)
  • Integer mm avoids floating-point representation in MQTT payloads
  • Telegraf, InfluxDB, and Grafana all handle the unit natively — only the dashboard axis label and alert threshold values change
  • Converting mm → cm in Grafana is trivial (/1000 for meters, /10 for cm) if display preference changes

Consequences

  • MQTT topic caneast/ot1/esp1/level publishes integer mm values
  • Grafana dashboard Y-axis labeled "mm" with thresholds in mm
  • Telegram alert thresholds updated from cm to mm (e.g., 15 → 150)
  • InfluxDB field level stores mm — historical data prior to this change was in cm and is not backfilled
  • All future OT distance sensors standardize on mm