This guide is based on my experience flashing the firmware of an Electrolama ZZH! dongle. It should work with every Zigbee dongle that is supported by the Z-Stack-firmware.
These steps are based on information and tools from these sources:
- https://github.com/Koenkk/Z-Stack-firmware
- https://support.electrolama.com/radio-docs/flash-cc-bsl/
- https://github.com/zigpy/zigpy-znp/blob/dev/TOOLS.md#backup-and-restore
Ubuntu Live
We use a live install of Ubuntu Desktop on an USB-drive. Download the ISO and use a tool like Rufus or BalenaEtcher to flash the ISO onto the USB-drive. Boot the device from the USB drive, ensure you are on the desktop, and confirm you have a working internet connection before proceeding.
Preparations
Before we can flash the new firmware onto the dongle, we first need to download the new firmware and install some Python modules. This way, we can backup the current configuration, flash the firmware and then restore the backup into the new firmware.
Download new firmware
First, consult this page to find which firmware you need for your Zigbee dongle: https://github.com/Koenkk/Z-Stack-firmware/blob/master/coordinator/Z-Stack_3.x.0/bin/README.md
After finding the correct version, download the compatible Z-Stack firmware from KoenKK’s GitHub: https://github.com/Koenkk/Z-Stack-firmware/tree/master/coordinator/Z-Stack_3.x.0/bin
Extract the correct .hex
file from the zip-file into /home/ubuntu/
Download cc2538-bsl
Open the terminal and make sure you are in /home/ubuntu/
. Then type the following command:
wget -O cc2538-bsl.zip https://codeload.github.com/JelmerT/cc2538-bsl/zip/master && unzip cc2538-bsl.zip
Install python-pip
The next steps are all executed in the terminal in the folder /home/ubuntu/ as root:
Open the terminal and insert the following:
sudo -s
You should now see root@ubuntu:/home/ubuntu#
We need pip
to install other packages, therefore we install this one first:
apt install python3-pip
Because it’s a live install, things can get broken when installing packages via pip
. The following message will appear when trying to install new Python modules:
error: externally-managed-environment × This environment is externally managed ╰─> To install Python packages system-wide, try apt install python3-xyz, where xyz is the package you are trying to install. If you wish to install a non-Debian-packaged Python package, create a virtual environment using python3 -m venv path/to/venv. Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make sure you have python3-full installed. If you wish to install a non-Debian packaged Python application, it may be easiest to use pipx install xyz, which will manage a virtual environment for you. Make sure you have pipx installed. See /usr/share/doc/python3.11/README.venv for more information. note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages. hint: See PEP 668 for the detailed specification.
But it’s necessary that we install these packages, so we use an option to override this warning:
pip install zigpy-znp intelhex pyserial --break-system-packages
When these packages are installed, it’s time to back-up the current configuration:
python3 -m zigpy_znp.tools.network_backup /dev/serial/by-id/... -o zigbee_backup.json
Next, it’s time to update the firmware:
python3 cc2538-bsl.py -p /dev/serial/by-id/... -evw NEW_FIRMWARE.hex
When this is done, it’s time to restore the backup into the new firmware:
python3 -m zigpy_znp.tools.network_restore /dev/serial/by-id/... -i zigbee_backup.json
If everything went well, your Zigbee dongle should now be running the new firmware, making your network more stable, responsive, and secure.