Silicon Laboratories Z-Wave 800 Series User manual

QSG185: Z-Wave 800 Dev Kit
Thunderboard Quick Start Guide with
Unify
The Z-Wave 800 Thunderboard BRD2603A Radio Board is an excellent starting
point to get familiar with the ZGM230S Z-Wave 800 SiP Module. The board is a
small and cost-effective, feature-rich prototype and development platform based
on the ZGM230S SiP Module.
It has been designed to inspire customers to make energy-friendly, battery-oper-
ated and secure connected IoT devices using Z-Wave MESH and Z-Wave Long
Range protocols. Customers can develop wide range command, control, and
monitoring applications utilizing numerous sensors, buttons, and LEDs on this
board. A built-in SEGGER J-Link debugger ensures easy debugging using a
USB Type-C cable.
The Z-Wave 800 Dev Kit is supported in Simplicity Studio and it ships with Unify
SDK, a portable environment that works with any Z-Wave end device and pro-
vides a flying start, out-of-box experience for Z-Wave applications. This Quick
Start Guide describes the steps to get up and running quickly with the Dev Kit
with Unify environment. The portable runtime comes as an executable CLI, to-
gether with Unify, a docker-compose file, and a tool which can map a Silicon
Labs device with a docker environment on Windows, MacOS, or Linux.
KEY FEATURES
• ZGM230S Z-Wave SiP Module with 512 kB Flash,
64 kB RAM
• +14 dBm TX power
•SMA antenna connector (863-925 MHz)
• Advanced Energy Monitor
• Virtual COM port
• SEGGER J-Link on-board debugger
• RGB LED, two single color LEDs, and two push
buttons
• CR2032 coin cell battery support
• 20-pin 2.54 mm breakout pads
• Mini Simplicity connector
ON-BOARD SENSORS
• Relative humidity and temperature sensor
• Passive Infrared sensor
•Hall effect sensor
• Ambient light sensor
• Pressure sensor
• LESENSE LC-sensor
• 6-axis Inertial sensor
SOFTWARE SUPPORT
• Simplicity Studio
• Unify SDK Z-Wave Protocol Controller
REQUIRED COMPONENTS
• Two Z-Wave Thunderboard Kits pre-programmed
and labelled with "Z-Wave - NCP Serial API
Controller"
• USB-C cable for controller (not included)
•Optional coin cell battery for end device (not
included)
• Docker version > 20.10.12 installed.
• Docker-compose version > 2.5.1
silabs.com | Building a more connected world. Copyright © 2023 by Silicon Laboratories Rev. 0.7

1. Setting Up Your Z-Wave 800 Dev Kit
Step 1: Unboxing
1. Unbox Z-Wave 800 Dev Kit.
2. Connect the USB Type-C connector to the PC using the USB-C cable.
Step 2: Software Preparation
1. Download and install Docker Desktop:
•Windows - https://docs.docker.com/desktop/windows/install/
• MAC - https://docs.docker.com/desktop/mac/install/
• Linux - https://docs.docker.com/desktop/linux/install/
2. Download and unzip the Unify Portable Environment, which enables the Z-Wave demo by running sample applications on 800 Dev
Kit devices. This is a containerized Unify environment that can manage a Z-Wave controller, form a network with end devices, and
provide a way to try the features of the applications.
• Windows: http://www.silabs.com/documents/public/software/portable_runtime_windows.zip
• Linux: http://www.silabs.com/documents/public/software/portable_runtime_linux.zip
• Mac OS: http://www.silabs.com/documents/public/software/portable_runtime_macos.zip
QSG185: Z-Wave 800 Dev Kit Thunderboard Quick Start Guide with Unify
Setting Up Your Z-Wave 800 Dev Kit
silabs.com | Building a more connected world. Rev. 0.7 | 2

Step 3: Flash Application
The development kit devices are shipped with the NCP Serial API Controller firmware by default. To try the demo, at least one control-
ler (SerialAPI) and one end device application is needed. Therefore, one of the devices must be re-programmed before first use. The
Unify Portable Runtime Environment package contains three built-in sample applications:
• SwitchOn/Off – End device application
• Multilevel Sensor – End device application
• SerialAPI – Controller NCP application
Follow these steps to flash the new application firmware to the dev kit:
1. Connect the device to the PC via USB-C cable.
2. Open a new terminal window in the unzipped Unify Portable Environment folder.
3. Run the command to flash SwitchOn/Off application:
unify_portable_cli.exe flash-app -n switch-on-off
or this command to flash the Multilevel Sensor application:
unify_portable_cli.exe flash-app -n multilevel-sensor
or this command to flash the Serial API Controller NCP application:
unify_portable_cli.exe flash-app -n serial-api
The environment performs some actions in the background, like resetting the device, flashing the new firmware, and setting the regional
radio frequency.
If there are multiple devices connected via USB, the J-Link Serial number must be provided in the command line interface. The device's
board number can be found printed on the bottom of the Thunderboard.
QSG185: Z-Wave 800 Dev Kit Thunderboard Quick Start Guide with Unify
Setting Up Your Z-Wave 800 Dev Kit
silabs.com | Building a more connected world. Rev. 0.7 | 3

Step 3.1: Read Device Specific Key
To perform a secure inclusion, it is necessary to provide the device specific key (DSK) of the end device. It can be read by running the
following command:
unify_portable_cli.exe read-dsk
Select the end device from the list. The board can be identified by its board number.
QSG185: Z-Wave 800 Dev Kit Thunderboard Quick Start Guide with Unify
Setting Up Your Z-Wave 800 Dev Kit
silabs.com | Building a more connected world. Rev. 0.7 | 4

Step 3.2: List Connected Devices
To get more information about the connected devices, run the following command:
unify_portable_cli.exe list-devices
The output contains the serialNumber and boardSerial of each device. The boardSerial is also printed on the back of the develop-
ment kit, next to the SMA antenna. The connected boards can be distinguished from each other by this number.
QSG185: Z-Wave 800 Dev Kit Thunderboard Quick Start Guide with Unify
Setting Up Your Z-Wave 800 Dev Kit
silabs.com | Building a more connected world. Rev. 0.7 | 5

Step 4: Start Unify Portable Environment
1. Connect only the Controller device (Dev Kit with the Z-Wave - NCP Serial API Controller firmware) to the PC.
2. Run unify_portable_cli.exe in a terminal inside folder where you have extracted the Unify Portable Environment. It will start the
environment with the default frequency for the EU region.
Note: You may need to run the executable from an elevated terminal.
3. If there are more devices connected via USB, the J-Link serial number must be provided for the executable:
unify_portable_cli.exe -s <SERIAL_NO>
4. The serial number of the devices can be identified based on Step 3.2 List Connected Devices.
5. Firewall access must be granted for the application, Docker, and USB connection.
QSG185: Z-Wave 800 Dev Kit Thunderboard Quick Start Guide with Unify
Setting Up Your Z-Wave 800 Dev Kit
silabs.com | Building a more connected world. Rev. 0.7 | 6

6. Allow Docker access to the required files (mosquito-config location) if prompted in the Action Center.
7. Launch the GUI in your browser using the URL http://localhost:3080.
8. Click the header at the top of the page to enter your credentials. Set the Host to mqtt-broker and the Port to 1883and click Con-
nect.
9. In the Node List, the Controller device should now appear.
QSG185: Z-Wave 800 Dev Kit Thunderboard Quick Start Guide with Unify
Setting Up Your Z-Wave 800 Dev Kit
silabs.com | Building a more connected world. Rev. 0.7 | 7

Step 5: Include the End Device in the Z-Wave Network
1. Power on the end device by connecting it via a USB-C cable or by inserting a battery.
2. In the Node list, click the States button on the right side of the Controller’s row and select Add Node from the drop-down list.
3. Activate inclusion mode on the end device by pressing the button labelled BTN1 on the Thunderboard.
4. Input the first five digits of the DSK key from the label in the pop-up window or click Reject to perform an insecure inclusion.
5. A popup warning message is displayed in the lower right corner when a non-secure inclusion is performed:
6. After a successful inclusion, the end device appears below the Controller row.
The icons under the Type category indicate the supported functionalities of the nodes.
QSG185: Z-Wave 800 Dev Kit Thunderboard Quick Start Guide with Unify
Setting Up Your Z-Wave 800 Dev Kit
silabs.com | Building a more connected world. Rev. 0.7 | 8

Step 6: Try the Application
• For a "Z-Wave - SoC Switch On/Off" end device, the capabilities are as shown below:
• The capabilities of the connected node can be seen by clicking the icons:
• Clicking the On/Off icon navigates to a new view where the LED can be controlled on the Thunderboard:
QSG185: Z-Wave 800 Dev Kit Thunderboard Quick Start Guide with Unify
Setting Up Your Z-Wave 800 Dev Kit
silabs.com | Building a more connected world. Rev. 0.7 | 9

• For the "Z-Wave - SoC Multilevel Sensor" end device, the capabilities are:
• The capabilities of the connected node can be seen by clicking the icons:
• Clicking the Thermostat button brings us to the window where the temperature value measured by the onboard thermostat can be
read out.
• In the Configuration window, a minimum and maximum temperature threshold can be set:
QSG185: Z-Wave 800 Dev Kit Thunderboard Quick Start Guide with Unify
Setting Up Your Z-Wave 800 Dev Kit
silabs.com | Building a more connected world. Rev. 0.7 | 10

Step 7: Exclusion of the Device
1. Press the States button on the right side of the controller’s row and select Remove node in the drop-down list. Next, press the
button labelled BTN1 on the end device’s board.
2. If using a Multilevel Sensor application, the device may be in a deep-sleeping state after the Remove node has been pressed. If
this is the case, press the RESET button on the board to wake it up, then BTN1 to perform the exclusion.
Step 8: Stop the Unify Portable Runtime Environment
1. On the web-based GUI, click the Disconnect button.
2. To stop the Unify Portable Environment, go back to the terminal and press Ctrl+C. The terminal will show the default prompt when
the shut-down process is complete.
QSG185: Z-Wave 800 Dev Kit Thunderboard Quick Start Guide with Unify
Setting Up Your Z-Wave 800 Dev Kit
silabs.com | Building a more connected world. Rev. 0.7 | 11

2. Advanced Options
Descriptions for all the available commands and subcommands in the Unify Portable CLI can be accessed by using the -h option.
unify_portable_cli.exe -h
unify_portable_cli.exe flash-app -h
unify_portable_cli.exe read-dsk -h
unify_portable_cli.exe list-devices -h
Some additional options are described in the following subsections.
2.1 Using Custom Region Frequency
The Quick Start Guide assumes that the EU Z-Wave frequency region is used. It is possible to use different region frequencies by re-
flashing the end device and starting the Unify Portable Environment with a specified region.
2.1.1 Start Unify Portable Environment with Specified Region Frequency
When no region frequency is specified, the Unify Environment sets the controller to use the EU region frequency by default. It is possi-
ble to specify the region by using -zwave-rf-region option.
unify_portable_cli.exe -s <SERIAL_NO> --zwave-rf-region <REGION>
The supported options for <REGION> are EU, US, US_LR, ANZ, HK, MA, IN, IS, RU, CN, JP, and KR.
2.1.2 Flashing Device with Specified Region Frequency
When no region frequency is specified, the end devices are flashed with the EU region frequency by default. It is possible to specify the
region to be used on end devices by using the -zwave-rf-region option with the flash-app subcommand.
unify_portable_cli.exe --zwave-rf-region <REGION> flash-app -n <APP_NAME>
The supported options for <REGION> are EU, US, US_LR, ANZ, HK, MA, IN, IS, RU, CN, JP, and KR.
QSG185: Z-Wave 800 Dev Kit Thunderboard Quick Start Guide with Unify
Advanced Options
silabs.com | Building a more connected world. Rev. 0.7 | 12

2.2 Read DSK Value
To perform a secure inclusion, it is necessary to provide the DSK of the end device. It can be read by running the following command:
unify_portable_cli.exe -s <SERIAL_NO> read-dsk
Where the SERIAL_NO can be determined using the list-devices subcommand.
2.3 Flash Custom Application Firmware
It is possible to flash custom-built firmware to the Thunderboard. Currently, the Thunderboard supports three kinds of applications:
• SwitchOn/Off – End Device application
•Multilevel Sensor – End Device application
• SerialAPI – Controller NCP application
It is possible to build these applications using Simplicity Studio. Specify the path to the custom-built application’s binary by using the -p
switch.
unify_portable_cli.exe flash-app -s <SERIAL_NO> -p custom_firmware.hex
2.4 Flash to Other Silicon Labs Z-Wave Board
The Unify Portable Environment can also be used to control and flash other types of Silicon Labs Z-Wave compatible development kits
and radio boards.
If the processor type is not specified with the flash-app subcommand, the default parameter is ZGM230. If the processor type on the
desired target is different, it can be specified with the -c option.
unify_portable_cli.exe -s <SERIAL_NUMBER> flash-app -p <FIRMWARE_PATH> -c <PROCESSOR_TYPE>
For different boards, the corresponding application firmware should be downloaded and used instead of the built-in app firmware. See
the “Flash custom application firmware” section.
QSG185: Z-Wave 800 Dev Kit Thunderboard Quick Start Guide with Unify
Advanced Options
silabs.com | Building a more connected world. Rev. 0.7 | 13

3. Troubleshooting
3.1 Docker Settings – Filesharing to Mosquitto Configuration
After starting the Unify Portable Environment for the first time, Docker needs access to the mosquito-config folder. This must be gran-
ted.
If you do not see a pop-up window requesting access to this folder, try looking for this notification in the Action Center and grant the
access.
3.2 Docker Settings – Disk Space
The portable environment may fail to start properly when it cannot allocate enough resources for itself.
If this is the case, open Docker Desktop’s settings by clicking the gear icon on the top right. In this window, select the Resources view
on the left, and increase the availability of resources to the minimum recommended values, as shown on the screenshots below.
QSG185: Z-Wave 800 Dev Kit Thunderboard Quick Start Guide with Unify
Troubleshooting
silabs.com | Building a more connected world. Rev. 0.7 | 14

3.3 Devices Not Detected by Unify
If the Unify GUI is not able to detect the connected devices, try the following:
1. Press Disconnect in the web GUI.
2. Stop the Portable Environment.
3. Press the RESET button on the devices.
4. Start the Portable Environment again.
3.4 The Environment Freezes
If the Unify Portable Environment becomes unresponsive, try the following:
1. Open Docker Desktop.
2. In the Containers view, Stop the environment’s container if it is still running.
3. Select the Volumes view and Delete the volumes related to the portable environment.
QSG185: Z-Wave 800 Dev Kit Thunderboard Quick Start Guide with Unify
Troubleshooting
silabs.com | Building a more connected world. Rev. 0.7 | 15

Silicon Laboratories Inc.
400 West Cesar Chavez
Austin, TX 78701
USA
www.silabs.com
IoT Portfolio
www.silabs.com/IoT
SW/HW
www.silabs.com/simplicity
Quality
www.silabs.com/quality
Support & Community
www.silabs.com/community
Simplicity Studio
One-click access to MCU and wireless
tools, documentation, software,
source code libraries & more. Available
for Windows, Mac and Linux!
Disclaimer
Silicon Labs intends to provide customers with the latest, accurate, and in-depth documentation of all peripherals and modules available for system and software imple-
menters using or intending to use the Silicon Labs products. Characterization data, available modules and peripherals, memory sizes and memory addresses refer to each
specic device, and “Typical” parameters provided can and do vary in dierent applications. Application examples described herein are for illustrative purposes only. Silicon
Labs reserves the right to make changes without further notice to the product information, specications, and descriptions herein, and does not give warranties as to the
accuracy or completeness of the included information. Without prior notication, Silicon Labs may update product rmware during the manufacturing process for security or
reliabilit y reasons. Such changes will not alter the specications or the performance of the product. Silicon Labs shall have no liability for the consequences of use of the infor-
mation supplied in this document. This document does not imply or expressly grant any license to design or fabricate any integrated circuits. The products are not designed or
authorized to be used within any FDA Class III devices, applications for which FDA premarket approval is required or Life Support Systems without the specic written consent
of Silicon Labs. A “Life Support System” is any product or system intended to support or sustain life and/or health, which, if it fails, can be reasonably expected to result in
signicant personal injury or death. Silicon Labs products are not designed or authorized for military applications. Silicon Labs products shall under no circumstances be used
in weapons of mass destruction including (but not limited to) nuclear, biological or chemical weapons, or missiles capable of delivering such weapons. Silicon Labs disclaims
all express and implied warranties and shall not be responsible or liable for any injuries or damages related to use of a Silicon Labs product in such unauthorized applications.
Note: This content may contain oensive terminology that is now obsolete. Silicon Lab s is replacing these terms with inclusive language wherever possible. For more
information, visit www.silabs.com/about-us/inclusive-lexicon-project
Trademark Information
Silicon Laboratories Inc.®, Silicon Laboratories®, Silicon Labs®, SiLabs®and the Silicon Labs logo®, Bluegiga®, Bluegiga Logo®, EFM®, EFM32®, EFR, Ember®, Energy Micro, Energy
Micro logo and combinations thereof, “the world’s most energy friendly microcontrollers”, Redpine Signals®, WiSeConnect , n-Link, ThreadArch®, EZLink®, EZRadio®, EZRadioPRO®,
Gecko®, Gecko OS, Gecko OS Studio, Precision32®, Simplicity Studio®, Telegesis, the Telegesis Logo®, USBXpress®, Zentri, the Zentri logo and Zentri DMS, Z-Wave®, and others
are trademarks or registered trademarks of Silicon Labs. ARM, CORTEX, Cortex-M3 and THUMB are trademarks or registered trademarks of ARM Holdings. Keil is a registered
trademark of ARM Limited. Wi-Fi is a registered trademark of the Wi-Fi Alliance. All other products or brand names mentioned herein are trademarks of their respective holders.