nixos-servers/docs/plans/zigbee-sensor-battery-monitoring.md

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.