How to Migrate a Zigbee Network Without Re-Pairing Every Device

When a Zigbee coordinator dies, the first thought is usually dread—a whole weekend lost to re-pairing. Every bulb, sensor, and switch gets pulled off its bracket, power-cycled, and sweet-talked back into the mesh. But swapping the coordinator doesn’t have to mean starting from scratch. If you’re running a local Zigbee stack with a decent radio and a backup plan that actually respects the network’s state, you can move the entire mesh in under an hour. This piece walks through the method, the tradeoffs, and the failure modes you need to stare down before you touch any hardware.

What a Zigbee Network Migration Actually Means

Zigbee networks run on a trust hierarchy. The coordinator owns the network key, the PAN ID, the extended PAN ID, the channel mask, and the list of joined devices. Yank the coordinator without restoring that state, and every device sees a foreign network and clams up. A migration is just the act of handing off that identity—the network parameters and the key material—from one coordinator radio to another, so the rest of the mesh never notices the change.

This isn’t cloning. Cloning suggests a bit-for-bit copy of the radio’s firmware and flash. Migration is a selective transfer of the network layer state. It works because Zigbee devices bind to a logical network, not a physical chip. As long as the new coordinator presents the same PAN ID, extended PAN ID, channel, and network key, the devices will rejoin without a full re-pair.

When Migration Is Worth the Effort

Migration is a targeted tool, not a universal best practice. It earns its keep when you’ve got more than about 15 devices, especially ones installed in awkward spots—ceiling-mounted motion sensors, under-cabinet LED controllers, or outdoor contact sensors. It’s also the right call when you’ve sunk hours into tuning Zigbee groups, scenes, and bindings that live in the coordinator’s memory. Rebuilding those from scratch invites human error and burns time you could spend auditing the small systems that quietly run your week.

Skip migration if you’re moving from a vendor-locked hub (like Philips Hue or Aqara’s proprietary bridge) to a general-purpose coordinator. Those hubs often lean on non-standard extensions or encrypted keys that won’t export cleanly. In that case, a clean start is more reliable than a half-baked migration that leaves devices in a confused state.

Pre-Migration Audit: Know What You’re Carrying

Before you touch the coordinator, document the network’s current state. This isn’t busywork—it’s your rollback plan. Pull the following from your existing Zigbee stack:

• PAN ID (2 bytes, hexadecimal)
• Extended PAN ID (8 bytes, hexadecimal)
• Channel (11–26 for 2.4 GHz Zigbee)
• Network key (16 bytes, hexadecimal)
• Device list with IEEE addresses and NWK addresses

Most open-source coordinator software—Zigbee2MQTT, ZHA, or the deCONZ REST API—exposes these values. In Zigbee2MQTT, the database.db file holds the network key and device table. In ZHA, the network settings sit in the coordinator’s NVRAM and can be read via the zha-toolkit custom component. Export them to a text file and stash it somewhere that isn’t the machine you’re about to reconfigure.

Coordinator Hardware: What Carries the Identity

Not all Zigbee radios are equal when it comes to migration. The method depends on whether your coordinator is a Texas Instruments CC2652/CC1352 series, a Silicon Labs EFR32, or an older CC2531. The CC2652 family—common in adapters like the Slaesh stick, zzh, and Tube’s Coordinator—stores network parameters in NVRAM that can be backed up and restored using zigpy-znp or TI’s Flash Programmer 2. Silicon Labs EFR32 radios use a different NVRAM layout but support backup via Simplicity Commander or the bellows library. Older CC2531 sticks are more fragile; their flash has limited write cycles, and a failed migration can corrupt the firmware.

If you’re on a CC2652-based coordinator, you’re in the best spot. The migration path is well-trodden and supported by the community firmware. If you’re on a Conbee II or RaspBee, the deCONZ software has its own backup mechanism, but it’s less transparent—you’re trusting the tool to capture everything correctly.

Step-by-Step: Migrating a Zigbee2MQTT Network

This is the most common scenario for local-control operators. The process assumes you’re moving from one CC2652-based adapter to another, but the logic applies to any coordinator that Zigbee2MQTT supports with a backup/restore path.

1. Stop Zigbee2MQTT and Back Up the Configuration

Shut down the Zigbee2MQTT service. Copy the entire data/ directory—this includes database.db, configuration.yaml, and any channel-specific caches. The database.db file holds the network key and device list. Without it, you’re starting over.

2. Read the Network Parameters from the Old Coordinator

With the old coordinator still plugged in, use the zigpy-znp CLI to read the NVRAM. The command python -m zigpy_znp.tools.nvram_read /dev/ttyUSB0 (adjust the port) will dump a JSON file containing the network key, PAN ID, extended PAN ID, and channel. Save this JSON file—it’s your migration payload.

3. Flash the New Coordinator with the Same Firmware Version

Mismatched firmware versions between old and new coordinators can cause subtle NVRAM layout differences. Use the same Z-Stack firmware build (e.g., CC1352P2_CC2652P_launchpad_coordinator_20221226.hex) on both radios. Flash the new coordinator with this firmware using cc2538-bsl.py or TI’s Flash Programmer 2. Do not connect it to Zigbee2MQTT yet.

4. Restore the Network Parameters to the New Coordinator

With the new coordinator connected, use the zigpy-znp tool to write the backed-up NVRAM JSON. The command is python -m zigpy_znp.tools.nvram_write /dev/ttyUSB1 backup.json. This overwrites the new radio’s network identity with the old one. After writing, power-cycle the coordinator by unplugging it for 10 seconds.

5. Update Zigbee2MQTT’s Port and Restart

Edit configuration.yaml to point serial.port to the new coordinator’s device path. Start Zigbee2MQTT. The log should show the coordinator starting on the same channel and PAN ID. Devices will begin checking in within minutes—battery-powered devices may take longer because they only wake on their reporting interval.

Migration Without Zigbee2MQTT: ZHA and deCONZ

If you’re using ZHA in Home Assistant, the process is similar but less scripted. ZHA stores the network key in the coordinator’s NVRAM and in Home Assistant’s .storage/core.config_entries. You can use the zha-toolkit custom component to export the network settings, then restore them to a new radio using the same toolkit. The critical step is ensuring the IEEE address of the new coordinator is updated in Home Assistant’s configuration, or ZHA will reject the device.

For deCONZ/Conbee users, the Phoscon app has a built-in backup feature under Settings > Gateway > Backup. Restore that backup to a new Conbee II or Conbee III stick. Cross-migration to a different chipset is not officially supported and often fails because of differences in the NVRAM layout.

Common Failure Modes and How to Recover

Migration is a fragile process. The most common failure is a mismatch between the backed-up network key and the key actually in use. Some coordinators rotate keys after a set number of frames, and if your backup was taken before a rotation, the restored key will be rejected by the mesh. Symptoms: devices appear to join but can’t communicate, or they repeatedly drop off the network. The fix is to re-pair the affected devices—there’s no way to extract the rotated key from the old coordinator if it’s already dead.

Another failure mode is channel interference. If your old coordinator was on channel 11 and you restore that channel to a new coordinator in a different RF environment, you may inherit congestion. Run an energy scan on the new coordinator before migration and consider changing the channel if the noise floor is high. Changing the channel, however, forces a full re-pair of all devices—so it defeats the purpose of migration. Weigh this carefully.

Finally, watch for IEEE address conflicts. Some devices bind to the coordinator’s IEEE address. If your new coordinator has a different IEEE address and you don’t update the bindings, those devices will appear offline. Zigbee2MQTT handles this automatically for most devices, but ZHA may require manual intervention.

Testing the Migrated Network

After migration, don’t assume the network is healthy just because devices show as online. Run a LQI (Link Quality Indicator) scan across the mesh. In Zigbee2MQTT, the network map shows link quality between routers and the coordinator. Look for devices with LQI below 50—they may need a router placed closer or a channel reassessment. Trigger a few end-device check-ins to confirm battery-powered sensors are still reporting on schedule.

If you’re using groups or bindings, test them explicitly. A migration can preserve the binding table on the coordinator, but if a device’s group membership was stored in volatile memory, it may have been lost during the coordinator swap. Re-apply any missing group assignments and verify that direct bindings (e.g., switch to bulb) still work without the coordinator relaying the command.

When Migration Fails: The Controlled Re-Pair

Sometimes the backup is incomplete, the firmware versions are incompatible, or the old coordinator is physically destroyed. In that case, you’re looking at a controlled re-pair—not the chaotic weekend you feared, but a methodical rebuild. The key is to re-pair devices in order of their routing role: mains-powered routers first, then end devices. Routers extend the mesh; pairing them first ensures end devices have strong paths to the coordinator from the start.

Use the device list you documented before the failure. Work room by room, and keep a clipboard (physical or digital) to track which devices have been re-paired. If you’re using Zigbee2MQTT, the “permit join” function can be limited to a specific router, which prevents devices from accidentally joining through a weak path. This is especially useful in multi-story homes where a basement sensor might latch onto a distant router on the top floor.

Preventive Habits for the Next Coordinator Failure

Migration is a recovery tactic. The better strategy is to make the next migration trivial. Automate backups of your Zigbee network state. In Zigbee2MQTT, a cron job that copies the data/ directory to a remote location once a week costs nothing and saves hours. For ZHA, use the zha-backup custom component or script a Home Assistant backup that includes the coordinator’s NVRAM via zigpy-znp.

Consider running a second coordinator as a “hot spare.” Flash it with the same firmware, restore the latest backup, and keep it in a drawer. When the primary fails, you swap the USB cable and restart the service. This reduces downtime to minutes and eliminates the panic that leads to mistakes.

Finally, label your hardware. A small label on the coordinator with its IEEE address, firmware version, and the date of the last backup is a low-effort practice that pays off when you’re troubleshooting at 11 p.m. on a Sunday.

FAQ

Can I migrate a Zigbee network from a vendor hub to a generic coordinator?

Rarely. Vendor hubs like Philips Hue or Aqara often use proprietary extensions or encrypted network keys that aren’t exposed to the user. Unless the hub has an official migration tool that exports standard Zigbee parameters, you’ll need to re-pair all devices. Check your hub’s documentation before assuming migration is possible.

Will my Zigbee devices lose their bindings during a coordinator migration?

Direct device-to-device bindings (e.g., a switch bound to a bulb) are stored on the devices themselves and survive a coordinator change. Group memberships and coordinator-side bindings may be lost if they aren’t included in the backup. After migration, verify group assignments and re-apply any that are missing.

How long does a Zigbee network migration take?

For a network with 30–50 devices, the technical steps—backup, flash, restore—take about 20 minutes. Allow another 30 minutes for battery-powered devices to check in and for LQI verification. The total downtime is typically under an hour if the backup is valid and the firmware versions match.

What’s the biggest risk when migrating a Zigbee coordinator?

The biggest risk is an incomplete or corrupted backup of the network key. Without a valid key, the new coordinator cannot decrypt traffic from existing devices, and they’ll appear to join but won’t function. Always verify your backup by checking the JSON or database file for a 16-byte key before decommissioning the old coordinator.