SILICON LABS Z-Wave Pre-Certified Apps User Guide

User Guide

Instruction

How to Use Z-Wave Pre-Certified Apps

JROSEVALL; MALEDESM
Restrictions:| –

Approved by:
This document is the property of Silicon Labs. The data contained herein, in whole or in part, may not be duplicated, used, or disclosed outside the recipient for any purpose. This restriction does not limit the recipient’s right to use the information contained in the data if it is obtained from another source without restriction.

REVISION RECORD

Doc. Rev| Date| By| Pages Affected| Brief Description of Changes
---|---|---|---|---
1| 20210415| COSTUME| All| Initial release
2| 20210920| COSTUME| 5.2| Updated Multilevel Sensor
3| 20211224| JFR/SAGHASEM| 5.3| Added Portable Controller-based app
4| 20220602| JOROSEVA| 5.3| Updated Portable Controller to KeyFob

Abbreviations

Introduction
2.1 Purpose
The purpose of this document is to describe how to use the Z-Wave pre- certified applications, which come as part of the Z-Wave and Z-Wave Long Range SDK 7.1x. The Z-Wave pre-certified applications are not formally certified but pass CTT 3 test suite.
2.2 Audience and Prerequisites
The audience is Z-Wave Developers.
It is assumed that developers already have the development environment up and running, as per the instruction “INS14280 Z-Wave 700 Getting Started for End Devices” [10].
Be aware of the user guide describing Z-Wave certified applications “INS14278 How to use Z-Wave Certified Apps” [11].

Software and Hardware

This section will present the hardware that comes as part of the development kit and the needed software to start developing Z-Wave devices. For a guide on how to set up and connect the hardware, refer to [10].
3.1 Hardware Needed
The Z-Wave development kit contains the following:

• 2 pcs. BRD4001A – Wireless Starter Kit Mainboard (WSTK).
• 2 pcs. BRD4207A – Z-Wave and Z-Wave Long Range ZGM130S Radio Board intended end device development.
• 2 pcs. BRD8029A – Buttons and LEDs Expansion Board.
• 1 pc. SLUSB001A – UZB7 – Controller USB stick.
• 1 pc. UZB-S – (ACC-UZB3-S) UZB-S USB stick network sniffer.
• 2 pcs. ANT-SS900 – 868-915 MHz Compressed Whip Antenna.
• 2 pcs. ENRM002 – 1m USB A<-> USB Mini B cable.

3.1.1 Main Development Board
The Main Development Board connects to the PC using a USB. It features a coin cell holder, supports Advanced Energy Monitor for battery measurements and energy profiling, as well as expansion headers for easy expansion. It has an on-board SEGGER J-Link for debugging, a low-power 128×128 pixel LCD, user LEDs / pushbuttons, and breakout pads for attaching the Z-Wave development board.

3.1.2 Z-Wave Development Radio Boards
Two Z-Wave Development Radio Boards targeted for end device development are included in the kit. Another radio board targeted for controller development can be purchased as an add-on to the kit.

The possible options are:

• BRD4207A Radio Board with ZGM130S used for Z-Wave and Z-Wave Long Range end device development (included). Added additional harmonics filtering compared to BRD4200A Radio Board.
• BRD4206A Radio Board with EFR32ZG14 used for Z-Wave and Z-Wave Long Range controller development (add-on). Added additional harmonics filtering compared to BRD4201A Radio Board.

While BRD4207A boards are intended for end devices, they can also be used for Controller development. The difference is the BRD4207 comes as a SiP module, provides I/O, and as such, has a higher cost.
The boards include a Worldwide SAW filter configuration, so the same development boards can be used to test all regions.
3.1.3 Recommendation on SAW Filters
For Z-Wave gateways (outside EU freq.) with LTE embedded, it is recommended that one analyze the
specific need for a SAW filter in-depth. Optionally, a SAW filter bank can be added and controlled via the SAW0 and SAW1 output pins for operation in different regions. This means:
No SAW

• End devices and gateways without LTE modem embedded: no SAW filter is recommended.
• Gateways on EU frequency with LTE modem embedded: no SAW filter is recommended.

SAW recommended

• Gateways with LTE embedded on U and H-related frequencies: using a SAW filter is recommended.

3.1.4 EXP Board
The EXP Board is an adapter to be connected to the EXP header of the WSTK mainboard. The EXP Board enables the platform to run the provided Z-Wave certified application by expanding the available buttons and LEDs. The EXP Board offers the following features:

• 4 push buttons
• 1 slide switch
• 4 LEDs

LED0 on the expansion board is wired in parallel with LED0 on the mainboard (both will turn on/off at the same time).
BTN0 and BTN1 on the expansion board are wired in parallel with PB0 and PB1 on the mainboard.
3.2 Software Needed
All you need to start developing Z-Wave devices is Simplicity Studio.

Download the installer from silabs.com, where you will also find additional training material for how to develop, compile, debug, and measure energy consumption.
When connecting the development board with the Z-Wave Radio Development Board attached, the IDE will auto-discover the hardware and show the available Z-Wave certified applications.

SDK and Framework Introduction

4.1 SDK 7.1x Overview
With the release of Z-Wave 700, both hardware, software, and specifications have improved.
The hardware is now based on the Silicon Labs EFM32™ Gecko family, a 32-bit Microcontroller based on the powerful ARM® Cortex®-M3 core. This change has resulted in power consumption being reduced by 80%, the point-to-point range has been increased to over 100 meters, and the mesh range is increased to over 400 meters. With fast wake-up and back-to-sleep mode, battery-powered sensors can now last for ten years using a single coin cell.
To leverage the powerful hardware, the software has been redesigned. The software now uses a Real-Time Operating System to divide the Z-Wave protocol and the application into independent tasks, an event-driving architecture to ensure no direct function calls between protocol and application, and a power manager to automatically power down to the lowest possible power mode. While everything has been redesigned, existing customers will find the Z-Wave Framework has been kept, thereby ensuring easy development.
Specifications have been updated to the Z-Wave Plus v2 to ensure interoperability between all Z-Wave products and vendors, and backward compatibility with all existing products. Z-Wave 700 devices work seamlessly with the world’s largest ecosystem of interoperable smart products.
4.2 Z-Wave Plus v2 Specification
Each product must follow the Z-Wave Plus v2 specification to be able to pass the certification program and ensure interoperability in the ecosystem of existing products. The primary focus is the ease of use for consumers, which can be summarized into the following:

• Shopping does not require intensive knowledge about which products work with which other products.
• Installation is as simple as possible and intuitive.
• Operating the products does not require any technical knowledge.
• No tricky maintenance procedures, such as exclude/include, are needed.

To accomplish this vision, several new requirements are added to the original Z-Wave Plus specification. These additions include:

• Both Security-2 (S2) and SmartStart are now mandatory to increase security while keeping the inclusion process simple.
• Each product must support Identify functionality, i.e., must feature a visible LED for identification purposes, making it easy to identify a product.
• All actuators must support the Basic command class, guaranteeing that any controller can control any actuator.
• Any state change must now be reported, making sure the controller always knows the true status of a device.
• OTA Firmware update is mandatory to support all nodes, and dynamic capabilities are now allowed as a controller must have an option to re-interview a node to detect any new/changed capabilities.

For more information about the specifications, refer to [7] and [8].
4.3 Z-Wave Plus v2 Framework
The purpose of the Z-Wave Plus v2 Framework is to facilitate the implementation of robust Z-Wave Plus v2 Compliant products.
The framework is described in full detail in [9]. It is strongly recommended that you read this document before developing your own Z-Wave Application. You can read a short outline here to give you an overview.
The ZAF consists of three blocks:

• Transport Layer:
  This layer handles all communication with the protocol, which includes single cast, multicast, Multi-Channel encapsulation, delivery of bundled commands, etc.

• Command Class Handlers:
  These handlers parse and compose Command Class frames.

• Utilities (Utils):
  Utilities are composed of different modules. Among them, there are modules for handling I/O communication specific to the hardware bundled with the SDK. Other modules are battery monitoring and firmware updating, etc.

Figure 6 below outlines the Z-Wave Plus Framework modules.

4.4 Libraries
This section introduces the different libraries available in the SDK 7.1x. See [6], [9] for more information.
Overall, the SDK has 2 libraries: the controller library and the end device library. The controller library is used for controllers running the Z/IP Gateway and will not be used by end devices. The end device library is used by all the Z-Wave certified applications for end devices.
The end device library can be configured for always-on (mains powered) devices or for battery devices.

• Always on End Device (AOS): End devices that are main powered. They are always listening and acting as repeaters in the network. Example usages are on/off switches.
• Reporting Sleeping End Device (RSS): Battery-operated devices that remain in sleep mode until they are triggered; example usages are door/windows sensors and motion sensors.
• Listening Sleeping End Device (LSS): Also known as a Frequently Listening Routing End Device (FLiRS). A special variant of battery-operated devices provides a mechanism to wake up the device within one second, with the battery drain very close to that of a fully asleep device. The first device alternates between sleep mode and a partially awake mode in which it is listening for a special wakeup beam signal at the rate of once per second. When the first device receives this beam, it immediately fully wakes up. If the device does not hear a beam, it goes back to full sleep for another period until it partially awakes again and listens for a beam. It is this partially awake mode combined with the special beam that provides battery life on par with fully sleeping devices while providing communications latencies of around one second. An example of use is door locks.

4.5 Association Groups and Endpoints

An association is the creation of a logical connection between nodes. It provides the ability to instruct an end device to control another end device (s) upon activation directly. A device must support at least one association group (group 1), which is designated for “Lifeline Reporting” (as defined by the Z-Wave Plus v2 Device Type, see [8]). Each group is responsible for controlling and/or reporting specific commands, e.g., a temperature measurement. One group can hold multiple commands if needed.
Association Group Information (AGI) enables Machine-to-Machine interfacing as well as human user interpretation of available association groups, thus eliminating the need for paper-based documentation.
All device-centric events are mapped to the Lifeline group; this includes events such as Battery Low, Tamper Alarm, and Device Reset Locally. The Lifeline concept allows a gateway to set up just one association from a device to get all it needs.
In the example of a motion sensor, the sensor reading is mapped to the Lifeline group. In contrast, another association group targets local application functionality, such as turning on a lamp based on movement.
Endpoints are the ability of a device to support multiple controllable endpoints within one device. Each endpoint specifies device and command classes supported and can be controlled individually.
4.6 Security
Security 0 was the first version of security. This command class provides a framework for establishing encrypted communications within a Z-Wave network. However, the key exchange at inclusion is vulnerable to interception.
Security 2 is the latest Security Command Class and is required for all Z-Wave 700 devices. S2 defines three types of security layers:

• S2 Access Control
• S2 Authenticated
• S2 Unauthenticated

S2 security operates with the concept of a network key. All nodes may use this key to communicate with each other. S2 divides the logical Z-Wave network into three dedicated security classes, with each one having a unique network key. A given S2 security class not only identifies the network key to use but also dictates the rules applying to the authentication of a new node during inclusion. The “S2 Access Control” class is the most trusted class, intended for access control devices like door locks and garage doors. The “S2 Authenticated” class is used for all normal household devices such as sensors and light dimmers. The “S2 Unauthenticated” class is the least trusted class. It is only intended for the most constrained controllers that, due to a limited user interface, are not capable of authenticating a node joining the network.
In a wireless environment, there is a real risk that a foreign node is included accidentally or due to malicious intent. The S2 authentication process allows an a controller to verify that a joining node is indeed the physical device that it claims to be. Depending on the UI, an including controller may allow the user to enter a Device-Specific Key (DSK) string of decimal digits that can be read visually or scanned as a QR code.
Given that SmartStart is mandatory for Z-Wave 700 devices, all Z-Wave 700-based devices must request either S2 Access Control or S2 Authenticated. If requesting S2 Authenticated, a node must also request S2 Unauthenticated for backward combability. All Z-Wave Long Range 700-based devices only support SmartStart as an inclusion method and S2 Authenticated is the lowest class key allowed.
Refer to [3] and [8] for more information.

Z-Wave Plus v2 Applications

Because starting application development from scratch is difficult, the Z-Wave and Z-Wave Long Range SDK come with several Z-Wave certified applications covering the most frequent use cases.
The Z-Wave and Z-Wave Long Range SDK 7 includes Z-Wave Plus v2 end device applications which are implemented according to the Z-Wave Plus v2 specifications [1], [2], [3], [4], [5], [6], [7] and [8]. All the Z-Wave specifications can be found on the Z-Wave Alliance website (Member login – Select ‘Specifications’ under the ‘Home’ tab).
5.1 Overview of Z-Wave Pre-Certified Applications
The SDK comes with the following Z-Wave pre-certified applications:

• Multilevel Sensor
  Shows the ability to advertise numerical sensor readings, such as temperature, and humidity. Multiple parameters can be set for the minimum and maximum values, and a basic set will be sent if the measured temperature value is out of the range.

• Key Fob Application
  Shows how a simple portable controller can be implemented. The Key Fob can include and exclude Z-Wave end devices to its network and do simple control (Basic On/OFF). The Key Fob can furthermore be included in a network as a secondary controller.

All applications are built on the Z-Wave Plus v2 Framework [9].
All Z-Wave pre-certified applications can be operated in any Z-Wave network with other Z-Wave-certified devices from other manufacturers. All main operated nodes within the network will act as repeaters, regardless of vendor, to increase the reliability of the network.
Notice that SoC on radio boards must be completely erased before downloading a new app. Data from a previous app may jeopardize the operation of a new app.
Refer to Table 1 for an overview of the functionality covered by the applications.
Table 1. Functionality Covered by the Z-Wave Plus v2 Applications

Note 1: S2 Authenticated is the lowest class key allowed for Z-Wave Long Range 700-based devices. ???
5.1.1 General User Interface
The following user interface applies to all the Z-Wave Plus v2 certified applications.
Table 2. General User Interface

Resets the firmware of an application (like losing power). All
volatile memory will be cleared.
BTN1| Press| Enter “learn mode” (sending node info frame) to add/remove
the device.
Removing the device from a network will reset it.
Hold for at least 5
seconds and release| Perform a reset to factory default operation of the device, and a
Device Reset Locally Notification Command is sent via Lifeline.
LED1| n/a| Blinks with 1 Hz when learn mode is active.
Used for Indicator Command Class.

5.1.2 SmartStart
SmartStart-enabled products can be added to a Z-Wave network by scanning the Z-Wave QR Code present on the product with a controller providing SmartStart inclusion. No further action is required, and the SmartStart product will be added automatically within 10 minutes of being switched on in the network vicinity. The Z-Wave certified applications are not labeled with a QR Code. However, QR Codes are generated internally in the 700 SoC and can be retrieved via Simplicity Studio. Right-click on your connected hardware in the ‘Debug Adapters’ section in Simplicity Studio, then right-click and select ‘Device Configuration’ from this menu, and select ‘Z-Wave Device Settings.’

In this view, the entire QR Code Value and the corresponding QR Code Image is shown. In addition, the Device Specific Key (DSK) is shown.
This DSK can be compared against the Z-Ware UI, PC Controller dialog box, or other Controller UI. If needed, the first decimal group of the DSK can be typed in for S2 secure inclusion.
5.2 Multilevel Sensor
Shows the ability to advertise numerical sensor readings, such as temperature, and humidity. Multiple parameters can be set for the minimum and maximum values, and a basic set will be sent if the measured temperature value is out of the range.
The Multilevel Sensor application is based on:

• Role Type:
• Supporting Device Type:
• Device Type:
• Generic Type:
• Specific Type:
• Requested security keys:| Reporting Sleeping End Device (RSS)
Data reporting
Notification sensor
Sensor Notification
Notification Sensor
S2_UNAUTHENTICATED and S2_AUTHENTICATED
---|---

Graphical representation (Icon Types):
 Multilevel Sensor transmits the following events:

• Environment monitoring
  • temperature, and humidity measure

5.2.1 Supported Command Classes
Multilevel Sensor implements mandatory and some optional command classes. The table below lists the supported Command Classes, their version, and their required Security class if any.
Table 3. MultilevelSensor Supported Command Classes

5.2.2 Basic Command Class Mapping
Basic Command Class is not mapped to any of the supported command classes.
5.2.3 Association Groups
Table 4 shows the available association groups.
Table 4. Association Groups Available in MultilevelSensor

Device Reset Locally: triggered upon reset.
Basic Set On/Off: triggered upon a movement detection (simulated by button BTN2).
Indicator Report: Triggered when LED1 changes state.
Configuring parameters: Minimum and maximum temperature levels can be set, and errors can be detected if the measured temperature is out of range
Environmental measurements: Temperature and humidity values can be read, and triggered from other Z-Wave devices
2| Basic Set| 5| Upon a movement detection (simulated by button BTN2), nodes associated in this group will first receive a Basic Set with 0xFF (turn on) and after a while receive a Basic Set with 0x00 (turn off).

5.2.4 Usage of Buttons and LED Status
Besides the general functionality described in Table 2, the following buttons shown in Table 5 are also used. No LEDs are used.
Table 5. MultilevelSensor Buttons Interface

5.2.5 Firmware Update
This section will describe backward compatibility when upgrading the MultilevelSensor application from one SDK to a newer version.
SDK 7.1x is the first SDK running on Z-Wave 700.
5.3 Key Fob Application
The Key Fob application is an example of how a simple portable controller can be implemented. The Key Fob can include and exclude Z-Wave nodes (not Z-Wave Long Range) to its network and do simple control (Basic On/OFF) of one group of nodes. It supports non-secure, S0 and S2-unauthenticated
encryption. NOTICE: The current version of the Key Fob cannot be Z-Wave certified.
The Key Fob can furthermore be included in a network as a secondary controller.
Graphical representation (Icon Types):

5.3.1 Supported Command Classes
Key Fob implements mandatory and some optional command classes. The table below lists the supported Command Classes, their version, and their required Security class if any.
Table 6 Key Fob Supported Command Classes

The Key Fob does not yet implement the Association Command Class but groups are locally maintained by the application.
5.3.2 Controlling Command Class
The Basic Command Class is supported as a controlling command class. Basic Set (On/Off) commands can be sent to associated end devices by pressing buttons on the development board.
5.3.3 Usage of Buttons and LED Status
The buttons described in Table 7 are used for controlling the Key Fob application.
Table 7 Key Fob buttons interface

while inclusion is in progress.
BTN0| Hold (1 sec)| REMOVE end device from the KeyFobs network – LED1 blinks while exclusion is in progress.
BTN0| Long Press (>5 sec)| Reset all settings to default.
BTN1| Short press| Transmit BASIC SET ON to associated devices – LED1 is on until the transfer completes or is timed out.
BTN1| Hold (1 sec)| Associate an end device to the BASIC SET Group – LED1 blinks and LED0 is ON while in progress.
Press the learn-mode button on the end device so it gets associated.(Press once more to deactivate learn-mode)
BTN2| Short press| Transmit BASIC SET OFF to associated devices – LED2 on until transfer completes or is timed out.
BTN2| Hold (1 sec)| Remove the device from BASIC SET Group. Group – LED1 blinks and LED2 is ON while in progress.
Press the learn-mode button on the end device so it is removed. (Press once more to deactivate learn-mode
BTN3| Short press| Enter Network Wide Inclusion (NWI) learn-mode so the KeyFob can be included as a secondary controller – LED3 is on while in NWI.
BTN3| Hold (1 sec)| Enter Network Wide Exclusion (NWE) learn-mode so the KeyFob can be excluded from being a secondary controller.

For example, to control SwitchOnOff end devices using a KeyFob controller. Follow the steps below for each end device.

1. Include the end device: Press BTN0 on the KeyFob, then press BTN1 on the SwitchOnOff. LED1 will blink until inclusion has finished.
2. Associate the end device to the BASIC SET group: Hold BTN1 on the KeyFob, then press BTN1 on the SwitchOnOff. Press BTN1 once more on the SwitchOnOff to take it out of learning mode.
3. Control LED0 on the SwitchOnOff: Press BTN1 or BTN2 on the KeyFob to turn LED0 On or Off.

5.3.4 Firmware Update
Currently, the Key Fob application does not support OTA firmware update

References

[1] Z-Wave Alliance, Software Design Specification, Z-Wave Application Command Class Specification.
[2] Z-Wave Alliance, Software Design Specification, Z-Wave Management Command Class Specification.
[3] Z-Wave Alliance, Software Design Specification, Z-Wave Transport- Encapsulation Command Class Specification.
[4] Z-Wave Alliance, Software Design Specification, Z-Wave Network-Protocol Command Class Specification.
[5] Z-Wave Alliance, Software Design Specification, List of Defined Z-Wave Command Classes.
[6] Z-Wave Alliance, Software Design Specification, Z-Wave Plus Role Type Specification.
[7] Z-Wave Alliance, Software Design Specification, Z-Wave Command Class Control Specification.
[8] Z-Wave Alliance, Software Design Specification, Z-Wave Plus v2 Device Types Specification.
[9] Silicon Labs, INS14259, Instruction, Application Framework Z-Wave Plus V2 SDK7.
[10] Silicon Labs, INS14280, Instruction, Z-Wave 700 Getting Started for End Devices.
[11] Silicon Labs, INS14278, Instruction, How to use Z-Wave Certified Apps.

Simplicity Studio

One-click access to MCU and wireless tools, documentation, software, source code libraries & more. Available for Windows, Mac and Linux!

IoT Portfolio
www.silabs.com/IoT| SW/HW
www.silabs.com/simplicity| Quality
www.silabs.com/quality| Support & Community
www.silabs.com/community

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 implementers using or intending to use Silicon Labs products. Characterization data, available modules and peripherals, memory sizes, and memory addresses refer to each specific device, and “Typical” parameters provided can and do vary in different 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, specifications, and descriptions herein, and does not give warranties as to the accuracy or completeness of the included information. Without prior notification, Silicon Labs may update product firmware during the manufacturing process for security or reliability reasons. Such changes will not alter the specifications or the performance of the product. Silicon Labs shall have no liabilit y for the consequences of use of the information 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 specific 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 significant 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 offensive terminology that is now obsolete. Silicon Labs 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 thumbs 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.

Silicon Laboratories Inc.
400 West Cesar Chavez
Austin, TX 78701
USA
www.silabs.com

References

• Silicon Labs
• Silicon Labs
• About Us - Silicon Labs
• Silicon Labs Community
• Internet of Things (IoT) - Silicon Labs
• Simplicity Studio - Silicon Labs
• Silicon Labs
• Simplicity Studio - Silicon Labs

Read User Manual Online (PDF format)

Download This Manual (PDF format)

Download this manual  >>