Switching Zigbee coordinators with ZHA & Home Assistant without re-pairing & testing the TubesZB coordinator

The stability of your Zigbee network is largely determined by the performance of your coordinator (or router). Switching Zigbee coordinators to a new and better one used to require you to repair all your devices though. With Home Assistant 2022.9 that is a thing of the past. In this post I will show how to switch without data loss and how well the TubesZB coordinator works with ZHA.

On switching Zigbee coordinators

If you run a Zigbee network the coordinator is its heart. It is the only device talking to both, other Zigbee devices, and your external network (usually your LAN or a computer). While additional wall powered devices can act as a repeater, building a mesh network, the performance of your coordinator is very important for the stability of your network.

There are many different options out there which differ in price, power, supported Zigbee version and also amount of supported direct children in the network. I personally started with a cheap CC2531 USB stick, switching to a Wifi based Sonoff Zigbee bridge and finally to the Sonoff Zigbee 3.0 dongle plus. They all have different strengths but generally this was an upgrade every time.

The problem with switching coordinators is that not all information about the network is saved in Home Assistant ZHA or Zigbee2MQTT. Instead some needed information (mostly about the structure of the network) is saved on the coordinator itself meaning you need to repair each device if you just switch hardware.

With my last switch to the Sonoff dongle plus I managed to avoid data loss but the process was quite complicated. Fortunately for everyone the great developers at Home Assistant have added backup and migration functionality to HA in version 2022.9. This worked well for me and helps me avoid having to re-pair around 40 Zigbee devices.

Some links are affiliate links. Consider buying your smart home devices via them to support this blog.
Preflashed CC2531 (very cheap but not really recommended anymore)
Sonoff Zigbee bridge (Wifi makes it independent but potentially unreliable)
Sonoff Zigbee 3.0 dongle plus (great and cheap but might not be powerful enough for bigger networks)
TubesZB coordinator (expensive but very powerful)

The Sonoff dongle plus worked well for me, especially for the very cheap price but I ran into some stability issues from time to time as I continued to add more devices. It also has a device limit between 21 and 40 (although apparently that was extended in newer firmware versions) so I might have run into that too. Looking for an even better solution I found the TubesZB CC2652P2 based coordinators. Very powerful at +20DB, modern hardware and great reviews from what I could find. It also supports 50 Direct Children, 100 normal routes and 200 source routes, that should be plenty enough for me. So I bought one of the USB Serial coordinators. This is how the migration went.

Preparing for the migration

To use this simple migration process first make sure that your Home Assistant instance is running at least on version 2022.9. If you are using Docker containers the upgrade can be very easy. You can find my exact setup here. Before you start it might be a good idea to make a full backup of your setup if you can.

Before you plug in your new device make sure to set the proper settings/jumpers/what ever else is need. For the Sonoff dongle plus I had to flash new firmware, for the TubeZB I had to properly set two jumpers. They were set to Ethernet mode but I am using a direct serial connection via USB. Moving both jumpers to the two middle pins worked for me.

Now its time to connect the new coordinator to your hardware. I am using a Raspberry Pi to run my smart home so I could simply connect the coordinator with the included USB cable. Make sure to actually position it in some distance to your Pi, otherwise the onboard power and Wifi chips will interfere with your Zigbee network. If you still experience issues try switching the USB cable and/or check for other possible sources of interference nearby.

Next we need to identify the port the coordinator is connected to and make it available to Home Assistant. A simple ls /dev/serial/by-id should show you all serial devices by there name. This should include your old coordinator but also the new one.

Here you can see usb-1a86_TubesZB_971207DO-if00-port0 which is my new coordinator as well as the old Sonoff dongle plus. The TubesZB is connected to ttyUSB1 but I am going to use the name instead. This is safer as the port could actually change if you plug the physical USB connection into a different port on the Pi, the name (or id) will not.

Now this device needs to be made available for Home Assistant. This depends a bit on your setup but if you use docker(-compose) like I do this can be done by a simple line in the compose file. Go to your file (smarthome.yml in my case) and the new device in the devices: list. It should look something like this:

homeassistant:
    container_name: homeassistant
    restart: unless-stopped
    image: homeassistant/raspberrypi4-homeassistant:2022.9.7
    devices:
    #  - /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_ea541a88dac9eb119fc4914f1d69213e-if00-port0:/dev/serial/by-i$
      # here comes the important part
      - /dev/serial/by-id/usb-1a86_TubesZB_971207DO-if00-port0:/dev/serial/by-id/usb-1a86_TubesZB_971207DO-if00-port0
    volumes:
      - ${DATADIR}/homeassistant/config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    # alternative needed for auto discovery, bluetooth,...
    network_mode: host
    # ... and the rest 

Afterwards you need to restart once like docker-compose -f smarthome up -d homeassistant and afterwards the devices should be available for HA. Of course if you use Zigbee2MQTT instead the process will be different.

How to migrate ZHA to a new coordinator

This is when the actual migration process starts. Go to your Home Assistant dashboard, integrations, find your ZHA entry and click configure underneath.

Now you should see a new screen with the options to download a backup or migrate the radio. Now is a good time to actually download a backup to be on the safe side. Once that is done you can click the migrate radio button and confirm the warning.

In the following screen you are asked to select the new radio. Chose the right name and the path from above (ttyUSB1 in my case) here and click submit. ZHA will now attempt to restore a backup onto this new coordinator which might take a moment.

Next you have to select the type of radio. This depends on your hardware of course but for both the Sonoff dongle and the TubeZB ZNP is the right choice. Click submit again to continue.

Then its finally time to enter the serial device path. You can either chose /dev/tty* here or as described above the /dev/serial/by-id/... version. The seconds one is to be preferred as it does not change if another physical USB port is used. The port speed of course depends on your hardware again but 115200 should be fine in most cases. Data flow control can be left on default. Now one more click on submit.

This should be the last step and you should be done now. I am not sure why but in my case I unfortunately got an “unknown error” message and the process aborted. I was able to fix this by removing the old coordinator and restarting Home Assistant.

Afterwards I selected the ZHA integration and started the migration again. I was able to select restore from backup here and the process started again. This time it actually worked.

After the migration

That’s it. While apparently not yet flawless the process is quite simple. Even with the error I was done migrating my Zigbee network in under 30 minutes which would have taken much longer having to re-pair all devices. If everything works properly this might even be done in 5 minutes. You can now just keep using your Zigbee devices as before the switch.

After a change in the network its always a good idea to give it a bit of time in case any routes between devices need to be changed. In my case everything started working well right away but to be save better start testing a day later. So far the TubeZB coordinator looks like a great piece of Zigbee hardware.

Update: It is now 2024, I have been running my network with the TubeZB controller for quite some time and have not had any issues with the reliability of my network. In all that time I only ran into two issues, both most likely unrelated to the controller itself. The first one were a couple of IKEA Tradfri lightbulbs dropping from the network once or twice. For most of them a simple power cycle fixed all issues. The other one is that to pair new devices I need to move them really close, like within 2 meters, from the controller. After the pairing process is done they work anywhere within my network though.

It is a bit hard to objectively test Zigbee coordinator power but I can say that everything seems a little bit more snappy right now and there were definitely no problems with the network at all after the switch. The support by ZHA was also great and it looks like the maker of the devices is quite active on the forums if you need any help.

So far I can definitely recommend the coordinator as a high end Zigbee gateway. It works really well so far and of course I will update this article if anything changes here. The price is quite high though at around 40$ plus ~8€ in taxes in Germany so the Sonoff dongle plus might still be the better alternative when you are just starting or not planning to build a bigger network.

If you do build a big Zigbee network the TubeZB coordinator seems great and can even be extended by routers using the same hardware for a (hopefully) super stable Zigbee network.

Finally here are some pictures of my ZHA network before and after the switch. For some reason the connections from the coordinator are mostly red before and after not changing much but it definitely feels better. I am not sure why some devices are not connected in this overview, they definitely send data. There is also one devices in the list that is not actually running anymore so I am not sure how good this visualization actually is.