Migrating ZHA to the Sonoff Zigbee 3.0 USB Dongle plus without annoying data loss

Migrating ZHA to a new coordinator can be easy once you figure out how. I have been running my smart home Zigbee network with Home Assistant, ZHA and a Sonoff Zigbee wifi bridge flashed with Tasmota for a couple of years now. With the release of the new cheap and Zigbee 3 enable dongle plus I am switching to that to see if performance improves. This is how to switch without having to re-pair all devices.

My old setup with a Wifi to Zigbee bridge

When I started using Zigbee devices I only had a couple of sensors and started with a cheap CC2531 USB stick flashed with custom firmware to communicate with my devices. Back then I used OpenHab and Zigbee2MQTT. This small USB stick is not very powerful though so I switched to another device: the Sonoff Wifi Zigbee bridge.

If you want to upgrade your Zigbee smart home and support this blog consider buying the bridges via these affiliate links:
Sonoff Zigbee 3.0 dongle plus
+ a USB extension to avoid interference
Sonoff Zbridge Wifi-Zigbe bridge

The Wifi Zigbee bridge has two big advantages over the old CC2531 stick: it can be placed everywhere within Wifi coverage (and therefore in a more central position even if your server is not there) and it is support by the great open source firmware Tasmota.

I described the general process of flashing Tasmota here but there is a more in-depth guide for the Zbridge here. Using the Zbridge worked very well for me with ZHA and Zigbee2MQTT, no problems at all. The big disadvantage is the second wireless protocol though. If your network is down, or even just your Wifi, you will lose connection to all of your Zigbee devices too. You might also see errors in the logs from time to time hinting to small timeout issues when the connection is unstable.

A new challenger approaches: the Zigbee Dongle plus

Fortunately in my current apartment my small home server is in a pretty central position (and I have lots of smart light bulbs in my smart lighting system acting as repeaters) so I can use a stick in the Raspberry Pi without a problem.

There are a lot of Zigbee USB adapters out there that are more powerful than the old CC2531 sticks but many come with their own disadvantages: many are expensive or complicated to order, some do not support the newer Zigbee 3.0 standard and often they are quite big.

Fortunately a very interesting new product was introduced recently: the Zigbee 3 dongle plus from Sonoff. A small USB stick with a nice metal case (not really used as a heat sink but good for shielding) that is quite cheap (around 15€), supported by open source firmware, ZHA & Zigbee2MQTT and with a newer chip ready for Zigbee 3.0.

Make sure though to connect your Zigbee dongle via an extension cable to avoid interference. I described my solution here where I built a custom wallmount for it.

Do I really need one? No! Do I want one? Yes! Does it improve my network? We will see.

Migrating ZHA Zigbee devices to the Sonoff Dongle plus

Update September 2022: With version 2022.9 of Home Assistant the functionality of taking and restoring backups of the Zigbee controller is finally directly integrated into Home Assistant and ZHA. I have not tried it yet but this looks very promising. Here is still the manual method that definitely worked for me:

Although I might also give Zigbee2MQTT a try again in the future for now the simpler to use ZHA works great for me. I do have a network of around 35 Zigbee devices at the moment though, so I want to avoid having to re-pair all of my devices with the new controller – the USB stick. Instead I was looking for a solution to seamlessly migrate my devices and I found one.

The starting point was this great video from everything smart home which describes the process. Not everything shown there worked exactly like that for me though and before even starting the migration process you should also update your devices firmware first.

I did both – the update and the migration from Zbridge to dongle plus – and will document the whole process here so it might be easier for others to follow.

Flashing the newest firmware to the Sonoff dongle plus

The USB dongle is always shipped with open source firmware from Koenkk but by the time you receive it the version might be quite outdated. Especially in the beginning there might be quite a lot of new relevant fixes in the updates so it might be better to use the newest version.

There are two ways of flashing that new firmware to your stick. One needs a Windows PC a certain software and you need to press a button on the stick itself. This works well but is a bit of a tedious process. You can find it in this video.

I also tried out a faster way if you have a Linux machine you could connect the stick to. I just used the Raspberry Pi that is my smart home server. After plugging in the stick check with lsusb to make sure it shows up and use ls /dev/serial/by-id to find its unique name. Mine looks like

/dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_lotsOfRandomCharactersHere-if00-port0 -e -v -w --bootloader-sonoff-usb

Also make sure that the stick is not used by any software at the moment, so shut down ZHA or Zigbee2MQTT if it is already configured to use the stick. Now we can to flashing:

// check which is the python 3 version and pip based on that
python --version
python3 --version
pip --version
pip3 --version
// we need python 3.x If python is still on 2.x then use python3 & pip3 in the following commands

// stop homeassistant
git clone https://github.com/JelmerT/cc2538-bsl.git
cd cc2538-bsl/
pip install wheel pyserial intelhex python-magic
pip install .

wget https://github.com/Koenkk/Z-Stack-firmware/raw/master/coordinator/Z-Stack_3.x.0/bin/CC1352P2_CC2652P_launchpad_coordinator_20220219.zip
unzip CC1352P2_CC2652P_launchpad_coordinator_20220219.zip

// flashing firmware
ls /dev/serial/by-id/
python cc2538-bsl.py -p /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_lotsOfRandomCharactersHere-if00-port0 -e -v -w --bootloader-sonoff-usb CC1352P2_CC2652P_launchpad_coordinator_20220219.hex

We are cloning a repository with python code here that is used to flash the USB stick. Make sure to use python 3.x! Afterwards pip is used to install some dependencies and again you should use a version based on python 3 – use pip3 if needed.

Then wget is used to download the actual firmware. I provided the newest version at the time of writing this but you can always check here. Unzip is used to get the actual code file. If unzip is not installed you can use sudo apt install unzip to change that.

Finally I am using python and the code from the repository to flash the firmware. -p should be followed by the unique id of your Zigbee stick (see above). The -w flag should point to the unpacked .hex file of the firmware that was downloaded earlier. Change both of these to fit your needs. The --bootloader-sonoff-usb is also very helpful as it allows you to flash the dongle without having to press the onboard button.

Backing up the Zigbee Wifi bridge

The Zigbee bridge is the coordinator in your Zigbee network – the central point. Just replacing that with a different device with different settings would destroy the network. Instead with need to backup the information on the old coordinator first and later restore it on the new device.

For the backup I used the bellows software. It can be used to make a backup of the current state of your Zbridge device. Before you start you need the bridges IP address though. Check in your router or in your current ZHA settings to find it. In my case it was current reachable as 192.168.3.6 on port 8888.

// install bellows via
sudo pip3 install bellows

// or use your HomeAssistant container if you run it via docker like
docker exec -it homeassistant /bin/bash

// check if the connection works via - replace the IP address
sudo bellows -d socket://192.168.3.6:8888 info
// possibly add -b 115200 for the baudrate if this does not work

// if it does - start the backup
bellows -d socket://192.168.3.6:8888 backup > wifiBridgeOpenBackup240422.json

The commands above will create a json file in the current directory containing all the data of your coordinator. If you ran this process within a Docker container make sure to copy this file to some persistent storage before stopping the container. I found this information in this very helpful forum entry – the restoration process described there does not work for the Zigbee dongle plus though.

Restoring the backup to your Sonoff dongle plus

Now that we have a backup of the old bridge I would advice disconnecting it and making a full backup of your Home Assistant instance (like this, I had to use this once during this process ;( ) if you use ZHA or of your Zigbee2MQTT configuration.

The restoration process used the great zigpy-znp command line tools and the Open Coordinator Backup Format. The installation is described on their Github page and should be done using a virtualenv to ensure you have the right dependencies. Make sure you also have the unique Id of the stick and the backup file from before available. This is what I did:

// install the backup tools via
sudo apt install python3 python3-virtualenv  # if needed
virtualenv -p 3 venv
source venv/bin/activate
pip install zigpy-znp

// restore backup to new bridge
python3 -m zigpy_znp.tools.network_restore /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_lotsOfRandomCharactersHere-if00-port0 -i wifiBridgeOpenBackup240422.json

// leave virtual env again
deactivate

Again python (3) is used to install these tools. Then they are used together with the path and the backup json file to restore the configuration to the Zigbee stick. I would suggest using an extension cable with the USB stick to avoid interference from the other components of the Raspberry Pi. Without that I had some failures.

The restoration process should finish pretty quickly and looked like this for me:

Now we are nearly done. The last step is to point Home Assistant and ZHA to the new stick instead of the old one. To do this you need to edit a configuration file: /homeassistant/config/.storage/core.config_entries (where /homeassistant has to be your Home Assistant configuration folder).

It will include a “zha” block which you need to update. Make sure to create a backup first using something like:

cp /homeassistant/config/.storage/core.config_entries config_entries.backup

Finally edit that file, for example using nano or vi and change the title (to anything you want) and the path to the unique path of your Zigbee stick. If Home Assistant is running inside a Docker container make sure that it can reach this device. Finally you might also have to change the radio_type – in case of the dongle plus (only the plus!) use znp.

Afterwards save the file and start Home Assistant again. Check the logs to see if there are any errors during startup related to ZHA. If there are not check the integrations settings and see if the ZHA panel now shows the new title you just provided.

At least in my case all of my Zigbee devices were disabled in Home Assistant at that time. Don’t panic! Your network will need some time to reorganize after switching to the new controller. I manually restarted some devices which sped things up but you should just wait some 15 minutes to give it some time to settle. So far it looks like all my devices survived the switch.

Is the Sonoff Zigbee 3.0 Dongle plus worth it?

So far I think yes! I will update this again later if anything changes. It works well with ZHA, is small and robust and also quite cheap. Due to the price and open source firmware it is also quite popular with open software projects so support from all major platforms is already there.

The Zigbee Wifi bridge from Sonoff also worked well for me for a long time but I have heard many others having problems due to the additional Wifi connection. If you can use it a direct connection is always better.

So far I can recommend the Sonoff dongle plus to everyone getting started with a cheap Zigbee based smart home. The flashing process is quite easy and even the migration process is doable if you use this documentation. If have no professional measurements but to me it also seems like my devices are reacting slightly quicker now with the new dongle.

For everyone that has to place the coordinator physically separate from the server the Zbridge can still be a good choice though.