diff --git a/source/_integrations/zha.markdown b/source/_integrations/zha.markdown index 06d4870062e..1d096ce7359 100644 --- a/source/_integrations/zha.markdown +++ b/source/_integrations/zha.markdown @@ -431,6 +431,44 @@ After restoring a Home Assistant backup, you can re-configure ZHA and migrate to Within ZHA is possible to use this backup and restore feature to migrate between some different radio types, if the respective radio library supports it. Currently, ZHA supports migrating the Zigbee network between different Zigbee Coordinator adapters based on chips from Silicon Labs, Texas Instruments, or ConBee/RaspBee if the backup was made from inside ZHA. +## Migrating to a new Zigbee coordinator adapter inside ZHA + +Follow this guide if you have a Zigbee Home Assistant (ZHA) network running and want to migrate from one Zigbee coordinator radio adapter to another Zigbee coordinator radio adapter. + +### Prerequisites + +- Your old Zigbee Coordinator radio adapter is used in the ZHA integration (not in deCONZ or MQTT). +- It is of radio type ezsp (Silicon Labs EmberZnet), znp (Texas Instruments Z-Stack ZNP), or deCONZ (ConBee/RaspBee from dresden elektronik). + - If your old Zigbee coordinator is a deCONZ (ConBee/RaspBee) radio adapter, make sure it is running [firmware 0x26700700 (from 2021-08-18)](https://github.com/dresden-elektronik/deconz-rest-plugin/wiki/Firmware-Changelog) or later. + +### To migrate to a new Zigbee coordinator radio inside ZHA + +1. Go to **{% my integrations title="Settings > Devices & Services" %}** and select the ZHA integration. Then select **Configure**. +2. Under **Network settings**, select **Migrate radio**. +3. Reconfiguration of ZHA will start. Select **Submit**. +4. Under **Migrate or re-configure**, select **Migrate to a new radio**. +5. **Migrate to a new radio** will inform you that an automatic backup will be performed and that your old Zigbee coordinator radio will then be reset before the backup is automatically restored. + - Select **Submit**. +6. **Unplug your old radio** will inform you that your old Zigbee coordinator radio has been reset and that you can now plug in your new Zigbee coordinator radio adapter. + - To avoid interference, use a USB extension cable. + - Use a USB 2.0 port or a powered USB 2.0 hub and keep the Zigbee stick away from USB 3.0 devices. + - You may now also choose to either unplug your old Zigbee coordinator radio adapter or keep your old radio plugged in. + - If that radio was a combined Z-Wave and Zigbee radio, like the HUSBZB-1 adapter, then only the Zigbee radio part of it was reset. Confirm that the Zigbee Coordinator radio adapter is properly connected and select **Submit**. +7. You now need to start the backup restore process. + - Select your new Zigbee radio from the list of serial ports and select **Next**. + - If your new radio does not appear or you need to reboot after plugging in new hardware, you can resume the migration after a reboot: under **Network Settings**, select **Re-configure the current radio** and choose your new radio. +8. Under **Network Formation**, select **Restore an automatic backup**. +9. Under **Restore Automation Backup**, choose the latest automatic backup and select **Submit**. +10. If your radio requires overwriting the IEEE address, you will see a screen titled **Overwrite Radio IEEE Address**. Check the **Permanently replace the radio IEEE address** box and click **Submit**. Overwriting the IEEE address may take a while. + - Your old Zigbee Coordinator radio and your new stick will now have the same Zigbee IEEE address (unique MAC address for the Zigbee device). + - Selecting this option is required for the migration process to complete successfully. + - From this point onwards, you should not operate the old stick in the same area unless you change the Zigbee IEEE address on it. + - If you do not migrate the Zigbee IEEE address from your old Zigbee Coordinator radio, then you will have to re-join/re-pair many of your devices in order to keep them working. +11. Finally, a **Success!** message should pop up with information that all options were successfully saved. + - Select **Finish** to confirm. + +The migration process is complete. However, be aware that you will not be able to control your existing Zigbee devices until the new coordinator fully joins the network. This process can take a few minutes. If some existing devices do not function after some time, try power-cycling them to allow them to re-join the network. + ## Troubleshooting To help resolve any kinks or compatibility problems, report bugs as issues with debug logs. Please note the current limitations and follow the instructions in this troubleshooting section.