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.