From 9d74aa5c04a676439cd0dd3a30fb25b8867efabe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torjus=20H=C3=A5kestad?= Date: Thu, 5 Feb 2026 09:21:54 +0100 Subject: [PATCH] docs: add zigbee sensor battery monitoring findings Co-Authored-By: Claude Opus 4.5 --- .../plans/zigbee-sensor-battery-monitoring.md | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 docs/plans/zigbee-sensor-battery-monitoring.md diff --git a/docs/plans/zigbee-sensor-battery-monitoring.md b/docs/plans/zigbee-sensor-battery-monitoring.md new file mode 100644 index 0000000..e5c72ee --- /dev/null +++ b/docs/plans/zigbee-sensor-battery-monitoring.md @@ -0,0 +1,31 @@ +# Zigbee Sensor Battery Monitoring + +## Problem + +Three Aqara Zigbee temperature sensors report `battery: 0` in their MQTT payload, making the `hass_sensor_battery_percent` Prometheus metric useless for battery monitoring on these devices. + +Affected sensors: +- **Temp Living Room** (`0x54ef441000a54d3c`) — area: living_room +- **Temp Office** (`0x54ef441000a547bd`) — area: office +- **temp_server** — area: server_room + +The **Temp Bedroom** sensor (`0x00124b0025495463`) is a different model and reports battery correctly (69% at time of investigation). + +## Findings + +- All three sensors are actively reporting temperature, humidity, and pressure data — they are not dead. +- The Zigbee2MQTT payload includes a `voltage` field (e.g., `2707` = 2.707V), which indicates healthy battery levels (~40-60% for a CR2032 coin cell). +- CR2032 voltage reference: ~3.0V fresh, ~2.7V mid-life, ~2.1V dead. +- The `voltage` field is not exposed as a Prometheus metric — it exists only in the MQTT payload. +- This is a known firmware quirk with some Aqara sensors that always report 0% battery. + +## Possible Solutions + +### 1. Expose voltage as a Prometheus metric +Enable the voltage sensor entities in Home Assistant (they may exist but be disabled by default). The HA Prometheus integration would then export them automatically. + +### 2. Calculate battery from voltage in Zigbee2MQTT +Override the battery calculation using the voltage field. Approximate formula: `(voltage - 2100) / (3000 - 2100) * 100`. + +### 3. Alert on sensor staleness instead +Create a Prometheus alert based on `hass_last_updated_time_seconds` going stale (e.g., no temperature update in 1 hour). This detects dead sensors regardless of battery reporting accuracy.