Backup your ZHA/HUSBZB-1 stick and even seamlessly migrate to a new stick without re-pairing!

You can now backup your Zigbee ZHA network for safe keeping – or even restore the backup on a new stick or Sonoff ZBBridge to seamlessly migrate your zigbee network without having to re-pair all devices.

I recently used this mechanism to backup my 114 device network from my HUSBZB-1 to a Elelabs ELU13 all without having to repair everything.

Keeping a backup file is also just a good precaution in case something happens to your stick or if the thought of re-pairing everything makes you shudder – like it does to me.

Requirements and notes:

  • EZSP compatible stick/coordinator like the HUSBZB-1, Elelabs, or flashed Sonoff ZBBridge
  • Direct and exclusive access to the stick with Home Assistant stopped - Home Assistant OS ( users will need to pull their stick and run this procedure on another system
  • Home Assistant 0.115 or higher
  • Python 3.8
  • For seamless migration, you need to overwrite the EUI64 on your target stick/bridge. This is a one time operation and can not be undone or changed in future (without a SWD flasher) so this should only be done if you are sure of the change. If you do not overwrite the EUI64 the binding tables on your devices will be incorrect and they will need to be reset and rejoined. That said, there is very little downside to overwriting the EUI64 – You can have two sticks/hubs with the same EUI64 online at the same time with out any conflicts if you create a new network on one of the two sticks. (bellows leave && bellows form)
  • The backup only stores the network level information for your Zigbee stick. You still need your Home Assistant backups that contain all the device/entity information for all your ZHA devices.
  • For HUSBZB-1 users, the Z-wave side of the stick is not backed up, affected or changed in any way.
  • If you migrate to a new stick and then want to go back to your original stick, you may need to restore the backup on it as well as the nwkUpdateID may be behind the current network setting.

Backup Procedure

  1. Find the /dev/ttyUSBx of your stick - Re-plug stick in and run dmesg - Or for Sonoff ZBBridge make sure you have the current IP
  2. Make sure bellows is installed and up to date. Run sudo pip3 install bellows
  3. Run sudo bellows -d /dev/ttyUSBX info to make sure bellows can talk to your stick.
  • Replace /dev/ttyUSBX with the correct path for your device.
  • For Sonoff ZBBridge use socket://<ip>:8888 for the device.
  • For Elelabs and/or Sonoff you may need/want to run sudo bellows -d /dev/ttyUSBX -b 115200 info (If that is the case, add -b 115200 for all future bellows commands)
  1. Make a note of the EUI64 (first line of output), the extendedPanId, the nwkUpdateId and the trustCenterLongAddress.
  2. Backup your stick to a file sudo bellows -d /dev/ttyUSBX backup > backup.txt

Restore Procedure

  1. Follows steps 1 through 4 of the above backup procedure, making sure you have the correct -d device location for your new stick/bridge.
  2. Restore the backup you took. Run sudo bellows -d /dev/ttyUSBX restore --i-understand-i-can-update-eui64-only-once-and-i-still-want-to-do-it -B backup.txt
  3. Verify backup was restored correctly. Run sudo bellows -d /dev/ttyUSB1 info and check that EUI64 (first line outputed), and extendedPanId, nwkUpdateId and trustCenterLongAddress match what your noted in step five of the backup procedure.
  4. If the values do not match, run the restore again like this sudo bellows -d /dev/ttyUSBX -f -B backup.txt
  • This is ommiting the --i-understand-i-can-update-eui64-only-once-and-i-still-want-to-do-it and adding -f flag
    bellows info`

That’s it! Now move the stick back to your Home Assistant host, or restart Home Assistant.

Final Notes


Tried using the docker image in windows on tasmota flashed Sonoff Zigbee Bridge, get the following error when I add the -b command, otherwise I get another error…

docker run --rm --device=socket:// -b 115200 -v .:/data -e EZSP_DEVICE='socket://' -e LANG='C.UTF-8' -it walthowd/husbzb-firmware bash unknown shorthand flag: 'b' in -b See 'docker run --help'.

docker run --rm --device=socket:// -v .:/data -e EZSP_DEVICE='socket://' -e LANG='C.UTF-8' -it walthowd/husbzb-firmware bash docker: bad format for path: socket:// See 'docker run --help'.

Thanks for this guide. Managed to get it working with a rPi OS rather than docker.
FYI, within the instructions you use ‘bellows -D’ but I had to use ‘bellows -d’ (lowercase d). Not sure if this was just for me or just a mistype.

Also looks like you may have accidently put ‘bellows’ twice in this line, I had to remove the second one :slight_smile:
6. Backup your stick to a file sudo bellows -D /dev/ttyUSBX bellows backup > backup.txt

Just tried this a few minutes ago and it worked. I run Home Assistant core in Docker and ZHA on a Sonoff ZBBridge. Had to install python3-pip on the host, then install bellows from pip. Same comments as @johnyb for the most part. I did not attempt a restore.

  • Use -d and not -D
  • Bellows is called out twice in the backup line. Remove the second “bellows”

Here are the final commands I used:

sudo bellows -d socket://<ip address>:8888 info
sudo bellows -d socket://<ip address>:8888 backup > backup.txt

Thanks guys, updated the original.

Thank you for bringing this up in the first place. Didn’t know it was even possible.

Can this work for nortek to a sonoff zigbee 3.0 dongle?

FYI, posted a feature request for Zigbee coordinator backup and restore in the ZHA UI here:

Yes, you can you this type of method to migrate between Silicon Labs and Texas Instruments dongles.

However note that while would still use bellows to backup you will need to use zigpy-znp for restore:

Where does the backup file get stored and is there a script for it to get backed up daily? I’m using zha

There is no finished out-of-the-box backup feature for ZHA as of yet, again see this feature request:

You could, however, do it manually or make your own scripts where script for backup/restoring Silicon Labs based dongles could be made with “bellows” and script for backup/restoring Texas Instruments based dongles could be made with “zigpy-znp” which have CLI tools to backup and restore respectively.

The video by Everything Smart Home linked above goes over the steps and commands needed.

I’m using the Conbee II and I bought the SonOFF Zigbee 3 controller, I really with I won’t have to re pair my 70 devices and rename 101+ entities

the conbee use a different path though :

should I enter "/dev/ttyACM0" instead of the IP address or the full path which seems to be /dev/serial/by-id/usb-dresden_elektronik_ingenieurtechnik_GmbH_ConBee_II_DE2457767-if00

bellows -d /dev/ttyACM0 backup > /config/zigbee-backup.json

Update that’s seems wrong since I have a lot of time out

bellows is for Silicon Labs based dongles. I don’t know which one you need for Conbee.

As already mentioned, you can not backup ConBee/RaspBee with bellows as the bellows library and CLI tools is only for Silicon Labs based Zigbee dongles/adapters.

ConBee/RaspBee uses " deconz" as radio type in ZHA which is dependent on the zigpy-deconz project.

I am however not sure if zigpy-deconz support ConBee/RaspBee backup to zigpy’s “Open ZigBee Coordinator Backup Format” (universal backup and restore format needed for cross-hardware migrations) as of yet but you can try asking about that in or (as if it does not then either waiting until zigpy-deconz does add support for it or re-pairing all devices is your only choices currently).

If there is no support as of yet there might be in the future as believe the zigpy developers have plans to also support ConBee/RaspBee though zigpy-deconz (though understand that the zigpy developers are volunteers working on it for free as a hobby).

Which exact dongle model do you have? ITead sells two different models that do not use the same chip.

SONOFF Zigbee 3.0 USB Dongle Plus” has Texas Instruments chip so use “znp” radio type in ZHA.

“Zigbee 3.0 USB Dongle” has a Silabs chip so uses “ezsp” radio type (dependent on bellows) in ZHA.

And again, ConBee/RaspBee uses “deconz” (dependent on the zigpy-deconz project) in ZHA.

1 Like

Thank you, I’ll probably gonna manually migrates all this devices then (I did the same two weeks ago migrating from the hue bridge).

I’ll probably gonna do a SD backup, remove the ConBee II, rename all current zigbee devices as devicename_backup and copy past the name (without the backup part) to the new devices pairs with the sonoff.
More annoying part will probably to factory reset all the Philips hue bulb and light strip.

PS: I bought the Sonoff Universal Zigbee 3.0 USB Dongle Plus

I think a tip there is believe that can reset them remotely with “hue-thief” if also buy an EZSP dongle:

Using a Philips Hue Dimmer Switch or Lutron Connected Bulb Remote is otherwise probably the easiest way to factory-reset your Philips Hue bulbs:

It can be good to have EZSP dongle as it can used it Zigbee sniffing if need advanced troubleshooting

At some point when philips started allowing you to pair hue bulbs to echos and what not the bulbs started doing a “factory reset” when removing from the hue bridge in the app… when I moved mine I had the hue bridge active deleted from hue app, and adding device in zha immediately found them. I know this is not how it always was because I had tried previously with no luck without a philips hue remote… I also now was able to get the bulbs to reset with an ecosmart remote (Leedarson) when moving to a new stick from HUSBZB-1 by using the touchlink button presses for that remote. So I would suggest updating firmware in hue app then delete a bulb and see how it goes.

So from my understanding, I can probably use this process to backup my Nortek so I can switch over to a Conbee II? Or should I go a different route? I’ve been using the Nortek for a number of years now but thinking about a change so I can eventually get to Zigbee2MQTT. Thoughts? Or is it really not worth the hassle and I should just stay put since it ain’t broke?

Tip! Might be a good idea to checkout “zha-toolkit ” custom component by @le_top / mdeweerd as he among other things created a Blueprint can perform daily/nightly backups while ZHA is still running:

He also made a Blueprint for backup with zigpy-znp (Texas Instruments ZNP) backup which could perhaps be extended or copied into a Blueprint supporting backup with bellows (Silicon Labs EZSP)?

Maybe even Blueprints that automate migration from ZNP (zigpy-znp) to Silabs (bellows) or vice versa?

Hopefully inspiration can be taken from this to someday integrate such ZHA backup features by default:

Not yet, only Silicon Labs and Texas Instruments based adapters are supported as of yet, but you can read about progress in regards to ConBee/RaspBee/deCONZ here →

Understand that while ZHA support many different brands and manufacturers, only Texas Instruments based adapters are stable in Zigbee2MQTT and their support for other adapters is still experimental.