Skip to content

700 series Controller Firmware Updates (Linux)

Jump to bottom
kpine edited this page Jan 17, 2023 · 117 revisions

Overview

This guide describes how to perform Over-The-Wire (OTW) firmware upgrades for Z-Wave 700-series (or later) controllers in a Linux environment, using freely available tools.

If using command line tools does not appeal to you, stop now and follow your vendor's official instructions, or contact them directly for support. See Disclaimer.

Table of Contents

Disclaimer

⚠️ While much effort has been made to provide accurate and up-to-date information and instructions, use this guide at your own risk. No warranty is implied nor will the author be liable for any damages arising from the use of this guide.

Known Working Platforms

Confirmed working with:

  • Debian 11 amd64
  • Virtualized amd64 Home Assistant OS (HAOS) 9.0 / VirtualBox 6.1.36 / Windows 10 hypervisor
  • Raspberry Pi4 and Raspberry Pi OS 64-bit (Debian 10)
  • Raspberry Pi4 and Ubuntu 20.04 64-bit [*]
  • Raspberry Pi2 Model B and Raspberry Pi OS 32-bit
  • Synology NAS with a Debian 10.9 Docker container [*]

⚠️ Confirmed not working:

  • Apple Silicon and MacOS, using homebrew installed lrzsz and minicom. Update seems to have no effect [*].

Firmware Downloads

The latest certified release is 7.18.3 via the Gecko SDK v4.1.3. Not all manufacturers support the latest version. There is no difference between 7.18.2 and 7.18.3, so if you have 7.18.2 installed, there is no reason to upgrade.

Most controllers use the stock firmware images distributed by Silicon Labs via the Gecko SDK. Some vendors also distribute their own files, but usually these are identical to the Silicon Labs versions. Links to both files are provided when available. We recommend using the vendor provided files.

Select your product to continue:

For alternative download options, see other downloads.

Missing a product? Let us know by submitting an issue.

Aeotec Z-Stick 7 or Z-Pi 7

The Z-Stick 7 and Z-Pi 7 controllers are a BRD4206A radio board (EFR32ZG14 chipset).

See Update Z-Stick 7 with Windows or Update Z-Stick 7 with Raspian OS / RPi for the official Aeotec update instructions.

Supported version: 7.18.1

MD5 checksum: abbc9a40ab1eaaef0b3cc4fa1daed366

Everspring SA370

The Everspring SA370 controller uses a ZGM130S module. There are currently no official update instructions or downloads available.

Known working version: 7.17.2

MD5 checksum: 6cc0961168d209221869bdfd64d5a138

This device may use the same files as the HomeSeer SmartStick+ G3 and Zooz ZST10 700 since it shares the same Z-Wave module. Use those files at your own risk!

HomeSeer SmartStick+ G3

The SmartStick+ G3 controller is a BRD4202A radio board (ZGM130S module).

See Updating SmartStick+ Firmware for the official HomeSeer update instructions. The latest versions are always available at Firmware Downloads.

Supported version: 7.18.2

MD5 checksum: a39fe3dbe638e1d021c2049d9f450e4a

A bundle containing the latest firmware file and the PC Controller software is also available for download. This is an easy alternative if a Windows PC is available.

Silicon Labs UZB-7 (SLUSB001A)

The UZB-7 controller is a BRD4206A radio board (EFR32ZG14 chipset).

See Z-Wave 700: OTW of Controller or Z-Wave 700: Programming UZB7 Controller Stick for official Silicon Labs update instructions. As this is a developer reference board with no official support, the latest version of firmware is listed.

Latest version: 7.18.3

MD5 checksum: 713e99c94d5d0eabe40554f90bfc6b38

Z-Wave.Me RaZberry 7

⚠️ The RaZberry 7 controllers use custom firmware. Do not follow this guide or use any of the referenced firmware files. Visit UZB/RaZberry Firmwares for firmware and support.

Zooz ZST10 700

The Zooz ZST10 700 controller is a BRD4202A radio board (ZGM130S module).

See How to Perform an OTA Firmware Update on Your ZST10 700 Z-Wave Stick for the official Zooz update instructions.

Supported version: 7.18.1

Don't forget to unzip the download, which contains the actual gbl file.

MD5 checksum: 03b6939d350b14289ce7fdee250cfeca

Other Downloads

By Radio Board

If you know your device's radio board identifier you can download the file directory from Silicon Labs on GitHub, from the gbl directory. Use the file filter and filter by string zwave_ncp_serial_api_controller_.gbl. Do not use the files ending in v255, these are for developer testing purposes only.

With the 7.18 SDK, firmware files are no longer designated by chipset or module identifiers. Instead, the files are specific to radio boards. There are a variety of chipsets and radio boards a manufacturer can choose from. Verify with the vendor of your controller which radio board and firmware file is the correct one.

Latest (7.18.3) firmware downloads for common board IDs:

  • BRD4202A - MD5 checksum: d6fb7ca2f16a8884a4a92fcbd3e65e61
  • BRD4206A - MD5 checksum: 713e99c94d5d0eabe40554f90bfc6b38

Zip Archive Download

Download the demo-applications.zip archive for all of the firmware files.

Firmware Update Instructions

The firmware can be updated using a Docker container or manually on the controller host. Choose an update method:

  1. Docker
  2. Host

If you use Home Assistant OS (HAOS), see the special instructions.

Or skip directly to the bootloader upload instructions.

Docker Update Method

The kpine/zwave-js-server Docker image provides a configuration-free method to update the controller firmware.

  1. Download or copy the controller firmware file into the /tmp/fw directory on the host, or any other preferred location.

  2. Stop any running Z-Wave JS application so it doesn't interfere with the update process. Some users have reported that this step isn't necessary.

  3. Run the update-firmware command via Docker:

    docker pull ghcr.io/kpine/zwave-js-server:latest

docker run --rm -it \
   --device /dev/ttyUSB0:/dev/zwave \
   --volume /tmp/fw:/fw \
   ghcr.io/kpine/zwave-js-server:latest \
   update-firmware

  4. Approximately 10 seconds after the container starts, the bootloader menu will display. After it is displayed, continue to the bootloader update process instructions.

Notes:

  • The USB controller host device path must be mapped to /dev/zwave in the container (--device /dev/ttyUSB0:/dev/zwave).
  • The directory that contains the firmware file should be mapped to the /fw directory in the container (--volume /tmp/fw:/fw).
  • The update-firmware command uses minicom to connect to the controller's bootloader console
  • The docker run command must be interactive (-it) in order to interact with minicom and upload the firmware file.
  • The --rm argument deletes the container after the process is finished.

Host Update Method

The update can be performed with a script on the controller host using locally installed minicom and lrzsz packages. The script requires Bash.

  1. Download the firmware update script.

    curl -sLO https://github.com/kpine/zwave-js-server-docker/raw/d46d19f9088a11f739a35f30968c7c466d54445d/scripts/zfw-update.sh

  2. Download or copy the controller firmware file to the /tmp/fw directory, or any other preferred location.

  3. Run the zfw-update.sh script with the appropriate options. Use bash zfw-update.sh -h for help.

    # update /dev/ttyUSB0 with upload path /tmp/fw
bash zfw-update.sh

# update /dev/ttyACM0 with upload path $HOME/fw
bash zfw-update.sh -d /dev/ttyACM0 -f $HOME/fw

  4. Approximately 10 seconds after the script starts, the bootloader menu will display. After it is displayed, continue to the bootloader update process instructions.

Notes:

  • minicom and lrzsz packags are required and must be installed first. For example:

    Debian or Ubuntu:

    apt install -y minicom lrzsz

    Alpine:

    apk add minicom --no-cache && \
apk add lrzsz --no-cache --repository=https://dl-cdn.alpinelinux.org/alpine/edge/testing

  • The script must be run as the root user, or a regular user that has read/write access to the serial device (e.g. a member of the dialout group).

  • The script generates a minicom configuration file and saves it as $HOME/.minirc.zwave. This file is re-created everytime the script is run. minicom does not support non-file configurations, so it is required to use this file.

  • The xmodem binary (provided by lrzsz) is named differently depending on the OS. On Debian and Ubuntu it is called sx. On Alpine Linux and MacOS it is called lsx. The script attempts auto-detect one of these binaries and if not found, will report an error. In that case, be sure to install lrzsz, and provide one of sx or lsx in your PATH.

HAOS Instructions

If you are using Home Assistant OS (HAOS) with one of the Z-Wave JS add-ons you will still be able to update the firmware. To do so requires installing the SSH & Web Terminal community add-on (not to be confused with the Core Terminal add-on). This add-on allows access to USB serial devices and installing packages, but in order to do these you must disable Protection mode.

  1. Install and configure the SSH & Web Terminal add-on
  2. Disable Protection mode
  3. Start the add-on
  4. SSH into the add-on or use the Web UI
  5. Stop the Core Z-Wave JS or community Z-Wave JS UI add-ons

⚠️ If you use the SSH & Terminal Web UI, be aware that it starts tmux. Tmux and minicom both use CTRL-A to send commands. If you are updating inside tmux, you must send CTRL-A CTRL-A to execute any minicom commands. When you SSH from an external client, tmux is not started.

Once logged in, you should see your USB controller's device path, usually /dev/ttyUSB0. If not, you'll need to troubleshoot and determine why. Ensure protection mode is disabled.

Go back to the host update instructions to continue, the instructions are the same. Note that when the SSH add-on restarts, any file outside of the /config directory is lost. If you want the script or firmware files to persist, save them in /config.

It is recommended to re-enable Protection mode once you are done with the update.

Notes:

  • The update script automatically detects when it is running inside the community add-on and will silently install the necessary software (minicom and lrzsz)

Bootloader Update Process

Once the bootloader menu is displayed it is time to upload the firmware file. If the menu is not visible, try pressing Enter a few times. The menu will look something like this:

Gecko Bootloader v1.5.1
1. upload gbl
2. run
3. ebl info
BL >

  1. Press 1 to upload the firmware. The text begin upload will be printed followed by the character C repeatedly (CCCC...), which indicates that the controller is waiting for an upload. If you would like to abort the upload and return to the menu, press Enter.

  2. While the C character is being printed repeatedly, press CTRL-A s to open the file upload dialog. Select xmodem and press Enter. Navigate the file selector so that firmware file is highlighted and select it with Spacebar, then press Enter to upload.

  3. When the upload finishes, Press 2 in the bootloader menu to run the new firmware. Some garbage characters will appear, meaning the firmware is running. Exit minicom with CTRL-A q and select Yes to exit.

  4. Start your Z-Wave JS application. Confirm the controller firmware version has changed to the expected version, either in the application UI or driver logs.

Clone this wiki locally