docs: move zigbee battery plan to completed
All checks were successful
Run nix flake check / flake-check (push) Successful in 2m17s
Run nix flake check / flake-check (pull_request) Successful in 2m19s

Updated plan with:
- Full device inventory from ha1
- Backup verification details
- Branch and commit references

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
2026-02-05 22:49:49 +01:00
parent c515a6b4e1
commit 32968147b5

View File

@@ -1,5 +1,9 @@
# Zigbee Sensor Battery Monitoring # Zigbee Sensor Battery Monitoring
**Status:** Completed
**Branch:** `zigbee-battery-fix`
**Commit:** `c515a6b home-assistant: fix zigbee sensor battery reporting`
## Problem ## 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. 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.
@@ -19,6 +23,25 @@ The **Temp Bedroom** sensor (`0x00124b0025495463`) is a SONOFF SNZB-02 and repor
- The `voltage` field is not exposed as a Prometheus metric — it exists only in the MQTT payload. - 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 WSDCGQ12LM sensors that always report 0% battery. - This is a known firmware quirk with some Aqara WSDCGQ12LM sensors that always report 0% battery.
## Device Inventory
Full list of Zigbee devices on ha1 (12 total):
| Device | IEEE Address | Model | Type |
|--------|-------------|-------|------|
| temp_server | 0x54ef441000a564b6 | WSDCGQ12LM | Temperature sensor (battery fix applied) |
| (Temp Living Room) | 0x54ef441000a54d3c | WSDCGQ12LM | Temperature sensor (battery fix applied) |
| (Temp Office) | 0x54ef441000a547bd | WSDCGQ12LM | Temperature sensor (battery fix applied) |
| (Temp Bedroom) | 0x00124b0025495463 | SNZB-02 | Temperature sensor (battery works) |
| (Water leak) | 0x54ef4410009ac117 | SJCGQ12LM | Water leak sensor |
| btn_livingroom | 0x54ef441000a1f907 | WXKG13LM | Wireless mini switch |
| btn_bedroom | 0x54ef441000a1ee71 | WXKG13LM | Wireless mini switch |
| (Hue bulb) | 0x001788010dc35d06 | 9290024688 | Hue E27 1100lm (Router) |
| (Hue bulb) | 0x001788010dc5f003 | 9290024688 | Hue E27 1100lm (Router) |
| (Hue ceiling) | 0x001788010e371aa4 | 915005997301 | Hue Infuse medium (Router) |
| (Hue ceiling) | 0x001788010d253b99 | 915005997301 | Hue Infuse medium (Router) |
| (Hue wall) | 0x001788010d1b599a | 929003052901 | Hue Sana wall light (Router, transition=5) |
## Implementation ## Implementation
### Solution 1: Calculate battery from voltage in Zigbee2MQTT (Implemented) ### Solution 1: Calculate battery from voltage in Zigbee2MQTT (Implemented)
@@ -30,6 +53,7 @@ Override the Home Assistant battery entity's `value_template` in Zigbee2MQTT dev
**Changes in `services/home-assistant/default.nix`:** **Changes in `services/home-assistant/default.nix`:**
- Device configuration moved from external `devices.yaml` to inline NixOS config - Device configuration moved from external `devices.yaml` to inline NixOS config
- Three affected sensors have `homeassistant.sensor_battery.value_template` override - Three affected sensors have `homeassistant.sensor_battery.value_template` override
- All 12 devices now declaratively managed
**Expected battery values based on current voltages:** **Expected battery values based on current voltages:**
| Sensor | Voltage | Expected Battery | | Sensor | Voltage | Expected Battery |
@@ -47,6 +71,27 @@ Added Prometheus alert `zigbee_sensor_stale` in `services/monitoring/rules.yml`
- Severity: warning - Severity: warning
- For: 5m - For: 5m
## Pre-Deployment Verification
### Backup Verification
Before deployment, verified ha1 backup configuration and ran manual backup:
**Backup paths:**
- `/var/lib/hass`
- `/var/lib/zigbee2mqtt`
- `/var/lib/mosquitto`
**Manual backup (2026-02-05 22:45:23):**
- Snapshot ID: `59704dfa`
- Files: 77 total (0 new, 13 changed, 64 unmodified)
- Data: 62.635 MiB processed, 6.928 MiB stored (compressed)
### Other directories reviewed
- `/var/lib/vault` — Contains AppRole credentials; not backed up (can be re-provisioned via Ansible)
- `/var/lib/sops-nix` — Legacy; ha1 uses Vault now
## Post-Deployment Steps ## Post-Deployment Steps
After deploying to ha1: After deploying to ha1:
@@ -61,3 +106,4 @@ After deploying to ha1:
- Device configuration is now declarative in NixOS. Future device additions via Zigbee2MQTT frontend will need to be added to the NixOS config to persist. - Device configuration is now declarative in NixOS. Future device additions via Zigbee2MQTT frontend will need to be added to the NixOS config to persist.
- The `devices.yaml` file on ha1 will be overwritten on service start but can be removed after confirming the new config works. - The `devices.yaml` file on ha1 will be overwritten on service start but can be removed after confirming the new config works.
- The NixOS zigbee2mqtt module defaults to `devices = "devices.yaml"` but our explicit inline config overrides this.