Flash Zigbee dongle with Z-Stack-firmware using Ubuntu Live

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.