Z-Wave 700/800 series SiP module and SoC chip support to work as a Z-Wave Controller running SerialAPI controller firmware.

	Z-Wave 700		Z-Wave 800
	ZGM130S	EFR32ZG14	ZGM230S	EFR32ZG23
Z-Wave End Device	Applicable	N/A	Applicable	Applicable
Z-Wave Controller	Applicable	Applicable	Applicable	Applicable
Radio Board	BRD4207A	BRD4206A	BRD4205B (ZGM230SB)	BRD4204D +14 dBm BRD4210A +20dBm (EFR32ZG23B)

A host communicates with Z-Wave controller over a standard UART serial interface with 115,200 baud rate by default. The Z-Wave controller firmware can be upgraded by over the wire (OTW) from host through the same serial interface.

To perform OTW update, make sure OTW bootloader, signing/encryption keys have been flashed into the Z-Wave controller. The pre-work of Z-Wave controller OTW firmware update is similar to Z-Wave end device OTA update described at Z-Wave 700: OTA of End-Device and How to OTA a Z-Wave 800 series End-Device.

 

Bootloader

User can build a UART XMODEM bootloader based on Gecko SDK v4.x. There are some pre-compiled OTW bootloader binaries available for Z-Wave 700/800 series. With the current Gecko SDK v4.1.0 (Z-Wave SDK 7.18), please download the demo-applications.zip from Gecko SDK Release GitHub. Unzip the package and find the prebuilt bootloader binaries at:
\demo-applications\protocol\z-wave\Apps\bin\
For Z-Wave 700:

 

SerialAPI Controller Firmware

The source of SerialAPI is now available in Z-Wave SDK v7.18, user can build a SerialAPI controller project if neede. The pre-compiled Z-Wave 700/800 SerialAPI controller binaries can be found in the same demo-applications.zip package, under \demo-applications\protocol\z-wave\demos\zwave_ncp_serial_api_controller\
For Z-Wave 700:

zwave_ncp_serial_api_controller-brd4206a-*.hex
zwave_ncp_serial_api_controller-brd4207a-*.hex

For Z-Wave 800:

zwave_ncp_serial_api_controller-brd4204d-*.hex
zwave_ncp_serial_api_controller-brd4205b-*.hex

Note: The prebuilt SerialAPI controller binaries for Z-Wave 800 series have merged OTW bootloader.
 

Encryption Keys and GBL Files

Each vendor should create his own set of keys, and a signed firmware image in Gecko Bootloader (.gbl) format, these can be generated by Simplicity Commander, and will be used for Z-Wave 700/800 OTW/OTA firmware update.

More information about keys and GBL file creation, please see INS14259 Z-Wave Plus V2 Application Framework GSDK, chapter 10 Firmware Update Images and Bootloader.

Some signed GBL files are offered in the demo-applications.zip, under \demo-applications\protocol\z-wave\Apps\bin\gbl\
For Z-Wave 700:

zwave_ncp_serial_api_controller_BRD4206A.gbl
zwave_ncp_serial_api_controller_BRD4206A_v255.gbl
zwave_ncp_serial_api_controller_BRD4207A.gbl
zwave_ncp_serial_api_controller_BRD4207A_v255.gbl

For Z-Wave 800:

zwave_ncp_serial_api_controller_BRD4204D.gbl
zwave_ncp_serial_api_controller_BRD4204D_v255.gbl
zwave_ncp_serial_api_controller_BRD4205B.gbl
zwave_ncp_serial_api_controller_BRD4205B_v255.gbl

Note: The *_v255 version has a great firmware version value, and can only be used for firmware update test purpose.
 

Depending on which SoC is used for the Z-Wave controller, the signing and encryption keys used are different.

For ZGM130S, use \gecko_sdk\protocol\z-wave\platform\SiliconLabs\PAL\BootLoader\sample-keys\
For EFR32ZG14, Z-Wave 800 series ZGM230S and EFR32ZG23, use \gecko_sdk\protocol\z-wave\platform\SiliconLabs\PAL\BootLoader\controller-keys\

*_encrypt.key

*_sign.key-tokens.txt
 

Simplicity Commander

A programming tool we use to flash bootloader, keys, and initial application into Z-Wave 700/800 Series device via SWD interface. This tool is included in Simplicity Studio if installed, under \SiliconLabs\SimplicityStudio\v5\developer\adapter_packs\commander

A standalone installer of Simplicity Commander for Windows/Linux/Mac can be downloaded from here.

UG162 Simplicity Command Reference Guide.

Tip: add the path of your commander into the environment variable 'Path' on Windows machine, so you can run the commander in Command Prompt under any directory.

 

Z-Wave PC Controller

Z-Wave PC Controller is a user friendly GUI for Z-Wave Controller functionality evaluation, including OTA/OTW firmware update. It is distributed in Simplicity Studio as well.

\SiliconLabs\SimplicityStudio\v5\developer\tools\zwave\pc_controller

INS13114 Z-Wave PC based Controller v5 User Guide.

 

zw_programmer

A programming tool with source distributed in Z/IP Gateway SDK. It communicates with Z-Wave controller via UART interface, and can be used for Z-Wave controller OTW update. Please install the latest Z/IP Gateway SDK 7.18 from Simplicity Studio v5.

After installing Z/IP Gateway package on Linux, the zw_programmer is typically located at /usr/local/bin

The source is available in Z/IP Gateway SDK package:
C:\SiliconLabs\SimplicityStudio\v5\developer\sdks\zwave\zip_gateway\v7.18.0\Source\zipgateway-7.18.00-Source.tar\zipgateway-7.18.00-Source\usr\local\systools\zw_programmer

 

OTW Procedure

Step 1: Flash bootloader, keys and application firmware

Use Simplicity Commander with command-line interface to program OTW bootloader, signing/encryption keys, and SerialAPI controller hex file into Z-Wave 700/800 Controller via SWD interface.

To simplify programming, we can copy all relevant images into one folder as below, then open a Command Prompt and run a bat file directly to program all once time.

Here is an example for ZGM230S Controller OTW firmware update based on Z-Wave SDK v7.18.0.

The bat file contains the following commands. Each prebuilt Z-Wave 800 series hex image has merged bootloader, and there is no need to program bootloader in this situation.

commander device masserase

REM Prebuilt serial api controller hex files for Z-Wave 800 series contain bootloader, here no need to flash the bootloader.
REM commander flash otw-ZGM230S_BRD4205B-crc.s37 --device ZGM230S

commander flash --tokengroup znet --tokenfile controller_encrypt.key --tokenfile controller_sign.key-tokens.txt --device ZGM230S

commander flash zwave_ncp_serial_api_controller-brd4205b-eu.hex --device ZGM230S

 

Step 2: Perform OTW to transfer a GBL file via serial interface by using either PC Controller or zw_programmer

a. PC Controller

Launch PC Controller and connect to the detected Z-Wave controller running SerialAPI firmware. This can be done by opening the Settings button and Detect button to show the current Z-Wave controller.

Select the associated COM port device, click OK button, return to PC Controller Main menu view, Click [OTW Firmware Update], choose the proper SerialAPI GBL file to be loaded.

PC Controller will start to transfer the firmware meta data. When firmware update process has completed, the controller will be automatically reset and connect to the PC Controller again, check the final status on the bottom of PC Controller.

 

b. zw_programmer

Before executing the zw_programmer tool, if zipgateway is actively running, please stop the zipgateway and check its status by using the following commands.

$ sudo /etc/init.d/zipgateway stop
$ sudo /etc/init.d/zipgateway status 

To check the serial port attached to the Z-Wave Bridge Controller, use the following command with the USB device connection:

$ dmesg | grep tty

If using Z-Wave 700/800 series starter kit, the device is attached to 'ttyACM0'.

Use option '-t' to show the info of current controller, option '-p' to load the target GBL file.

Note:

1. If upgrading the firmware of a UZB-7 USB Controller stick (based on EFR32ZG14), assuming the bootloader and signing keys are in place when shipped, step 1 can be skipped, and just do step 2 OTW firmware update to transfer a GBL file via serial port.

2. If getting error 0x50 or 0x18 during firmware update, please make sure:
a. bootloader and encryption keys have already been flashed into the device via SWD interface before you perform the OTW/OTA update.
b. GBL file should have an increased firmware version comparing the one that the device is currently running.

3. It seems upgrading from the original version shipped with the UZB-7 device (7.11) to 7.21 renders the dongle unusable. The workaround is to update to an intermediate version (7.18 seems to work - available in Gecko SDK version - 4.1.3, for example) then upgrade to 7.21 from the intermediate version.
 

A Z-Wave controller or gateway lets you add/remove/control all the devices running on the Z-Wave network via the internet by bridging the Z-Wave PAN to the internet. Z/IP gateway alongside Z-Ware was the solution supplied by Silicon Labs prior to the existence of the Unify SDK. This guide helps users of the legacy solution considering migrating to Unify.

Key points:

• Z/IP gateway translates Z-Wave command classes to Z/IP encapsulated UDP packets whereas Unify uses MQTT topics based off of the ZCL (Zigbee cluster library) format
• Unify abstracts a lot more lower level functionality than Z/IP gateway and thus accelerates development time 
• Unify implements a subset of the functionality provided by Z/IP gateway
• The Unify dev UI provides similar functionality to the Z-Ware web interface 
• Both run on Z-Wave modules running the serial API firmware
• Unify doesn't just support Z-Wave and allows multiple protocols to run simultaneously, including Matter

System Requirements:

• Before migrating to Unify review the system requirements in the Unify documentation https://siliconlabs.github.io/UnifySDK/
• Check if your processor and operating system is supported by Unify

Getting started with Unify:

• Start by reviewing the documentation https://siliconlabs.github.io/UnifySDK/
• Test out Unify on a Raspberry Pi

Z-Wave Command Class support on Unify

Due to the abstraction layer in Unify there is a mapping that takes place between the lower level Z-Wave command classes and the MQTT topics. This mapping is done by the attribute mapper and the way Z-Wave command classes are mapped to MQTT  is defined in the .uam files in the applications/zpc/components/dotdot_mapper/rules directory. UCL is the format used for MQTT which is based on ZCL (see: the Zigbee cluster library spec  ). When creating a gateway using Unify it is necessary to become familiar with this process to be able to support all the device functionality required. See the guide in the Unify documentation for writing UAM files for the ZPC (Z-Wave protocol controller). Thus there are two steps to support command classes. First, ZPC must support the Z-Wave command class and then it must be mapped to ZCL in order to expose the functionality to the MQTT layer. A guide for adding support for new command classes is also in the Unify documentation. This step will be unfamiliar to Z/IP gateway users as there was no abstraction layer similiar to this.



 

supported.csv may need to be updated within the Z/IP gateway source tree from time to time to enable forwarding of all supported commands to the unsolicited destination. The file is located at: usr\local\src\analyzer\supported.csv

This file can be updated from https://z-wavealliance.org/development-resources-overview/specification-for-developers/ by downloading the Z-Wave specification package  

Once you download the zip file and extract it, there is an excel file in the Z-Wave Command Classes Specifications directory called List of defined Z-Wave Command Classes.xlsx

Export the 4th worksheet called Commands and to create supported.csv

To get the correct delimiter on a computer that is not set already to European, you will need to change the delimiter options in Excel.
 

1. Click File > Options > Advanced.
2. Under Editing options, uncheck the Use system separators check box.
3. Change the "Decimal separator". This will change the way decimal numbers are displayed in your worksheets, and choose a different "Thousands separator" to avoid confusion.

To export the Excel file to CSV semicolon delimited, set the default decimal separator to a comma. This will make Excel use a semicolon for the "List separator":

• Set Decimal separator to comma (,)
• Set Thousands separator to period (.)

Finally, export just the Commands worksheet and it will now be in the correct format which should match the format of the old supported.csv file to be replaced.