Skip to content

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.