Zigbee: 127 devices, zero re-pairing¶
Goal: move ZHA/ZBT-1 (Pi, multiprotocol) → Zigbee2MQTT/ZBT-2 (av, Docker) without touching a single device.
Steps (detail: docs/runbooks/zigbee-migration.md):
1. Fresh ZHA network backup + consistent sqlite copy of zigbee.db + registries.
2. Convert zigbee.db → Z2M database.db (custom converter; key gotcha: herdsman
wants ieeeAddr, not ieee) with a renormalized naming map.
3. Pre-provision ZBT-2 with the OLD network identity via zigpy-cli restore:
PAN, channel, network key, and the coordinator IEEE (rewritable EUI64
token on EmberZNet 7.4+). Ext PAN ID is byte-reversed between ZHA and Z2M.
4. Cutover: disable ZHA, stop multiprotocol (old radio definitively off-air),
start Z2M with the converted DB. Frame counter must jump PAST the backup's.
5. Reflash ZBT-1 → OpenThread RCP; Thread/Matter moves to containers on av.
6. Validation gates: router count, battery-device check-ins (~1h), per-room
control probes, 24h availability soak.
7. Post-migration hygiene that BIT US LATER: bulbs keep old ZHA group
memberships in their own flash — renumber Z2M groups out of the legacy id
range (we used 101+) and wipe with group/members/remove_all. See war story.