SILICON LABS Z Wave Long Range 700 800 SDK User Guide

SILICON LABS Z Wave Long Range 700 800 SDK

Product Information

The Z-Wave and Z-Wave Long Range 700/800 SDK 7.20.1.0 GA is a software development kit designed for smart home devices. It is specifically optimized to meet the demands of the future smart home, where increasing needs for more sensors and battery-operated devices require long range and low power capabilities. The SDK provides a suite of tools and resources for developers to create interoperable and secure smart home products.

Key Features:

• 100% Interoperable: Every product in the Z-Wave ecosystem works with every other product, regardless of type, brand, manufacturer, or version.
• Best-In-Class Security: Z-Wave’s Security 2 (S2) framework provides end-to-end encryption and advanced security for smart home devices and controllers.
• SmartStart Easy Installation: SmartStart simplifies the installation of smart devices by using QR code scans for uniform, trouble-free setup.
• Backwards-Compatible: Z-Wave certification mandates backward-compatibility, ensuring older Z-Wave devices can still work with the latest technologies.

Product Usage Instructions

To use the Z-Wave and Z-Wave Long Range 700/800 SDK 7.20.1.0 GA, follow these steps:

1. Ensure that you have installed the Gecko SDK Suite 4.3 on your development environment.
2. If you are new to the Z-Wave 700/800 SDK, refer to section 10 “Using This Release” in the documentation for detailed instructions on getting started.
3. For compatibility and use notices, refer to the Security chapter of the Gecko Platform Release notes installed with this SDK or visit the Silicon Labs Release Notes page for more information.
4. Subscribe to Security Advisories to receive up-to-date information on security updates and notices.
5. Refer to section 11 “Product Life Cycle and Certification” for information about the certification status of Z-Wave and Z-Wave Long Range 700/800 SDK v7.20.0.0 Pre-Certified GA.
6. Review the supported radio boards listed in the documentation to ensure compatibility.

For more information and detailed instructions, refer to the user manual or documentation provided with the Z-Wave and Z-Wave Long Range 700/800 SDK 7.20.1.0 GA.

Z-Wave and Z-Wave Long Range 700/800
SDK 7.20.1.0 GA
Gecko SDK Suite 4.3
July 26, 2023

Z-Wave and Z-Wave Long Range 700/800 are designed to meet the demands of the future smart home, where increasing needs for more sensors and battery- operated devices require both long-range and low power. Context-aware environments are the next evolution in the smart home market, and they require technologies that have been optimized specifically for these applications.
100% Interoperable: Every product in the Z-Wave ecosystem works with every other product, regardless of type, brand, manufacturer or version. No other smart home/IoT protocol can make this claim.
Best-In-Class Security: Z-Wave’s Security 2 (S2) framework provides end-to-end encryption and the most advanced security for smart home devices and controllers. Homes with S2 Z-Wave devices are virtually un-hackable.
SmartStart Easy Installation: SmartStart radically simplifies the installation of smart devices by using QR code scans for uniform, trouble-free setup. Devices and systems can be pre-configured dramatically easing deployments.
Backwards-Compatible: Z-Wave certification mandates backward-compatibility. The first Z-Wave devices on the market, more than ten years old, still perform as intended in networks with the latest Z-Wave technologies.
For more information about the certification status of Z-Wave and Z-Wave Long Range 700/800 SDK v7.20.0.0 Pre-Certified GA, see section 11 Product Life Cycle and Certification.

These release notes cover SDK version(s):

• 7.20.1.0 GA released July 26, 2023
• 7.20.0.0 Pre-Certified GA released June 7, 2023

KEY FEATURES

• FG28/ZG28-based radio boards BRD4401A/B supported
• Z-Wave FLiRS inclusion performance improved in large networks
• Z-Wave Long Range wakeup beam performance improved
• Simplified application development by moving logic from the Apps to ZAF
• 800 DevKit (BRD2603) includes new applications and Multilevelsensor extended with new features
• Improved documentation to better support development from idea to certification
• Z-Wave Simulator available for Z-Wave Alliance members
• Z-Wave PC-based Zniffer v4.67 released

Compatibility and Use Notices
For more information about security updates and notices, see the Security chapter of the Gecko Platform Release notes installed with this SDK or on the Silicon Labs Release Notes page. Silicon Labs also strongly recommends that you subscribe to Security Advisories for up-to-date information. For instructions, or if you are new to the Z-Wave 700/800 SDK, see section 10 Using This Release.

Supported Radio Boards

This section describes the radio boards supported by the certified and pre- certified applications for the 700 and 800 Series, respectively.

Table 1-1. Supported Radio Boards.

Vault Mid

| Serial API using BRD4002A
800| BRD4204B| EFR32ZG23: ZW-LR, SoC, 14 dBm & Secure

Vault Mid

| Serial API using BRD4002A
800| BRD4204C| EFR32ZG23: ZW-LR, SoC, 14 dBm & Secure

Vault High

| Serial API using BRD4002A
800| BRD4204D| EFR32ZG23: ZW-LR, SoC, 14 dBm, Secure Vault High & external 32kHz crystal mounted| Serial API using BRD4002A
800| BRD4205A| ZGM230SA: ZW-LR, SiP, 14 dBm & Secure Vault Mid| Applications using BRD4002A/BRD8029A
800| BRD4205B| ZGM230SB: ZW-LR, SiP, 14 dBm & Secure Vault High.| Applications using BRD4002A/BRD8029A
800| BRD4210A| EFR32ZG23: ZW-LR, SoC, 20 dBm & Secure Vault High| Applications using BRD4002A/BRD8029A
800| BRD2603A| ZGM230SB: ZW-LR, SiP, 14 dBm & Secure Vault High.| Applications using BRD2603A
800| BRD4400B| EFR32ZG28B: ZW-LR, SoC, 14 dBm & Secure

Vault High

| Applications using BRD4400B/BRD8029A
800| BRD4401B| EFR32ZG28B: ZW-LR, SoC, 20 dBm & Secure

Vault High

| Applications using BRD4401B/BRD8029A
700| BRD4200A| ZGM130S: SiP & 14 dBm| Applications using BRD4002A/BRD8029A
700| BRD4201A| EFR32ZG14: SoC & 14 dBm| Serial API using BRD4002A
700| BRD4202A| ZGM130S: SiP, 14 dBm & no SAW filters| Applications using BRD4002A/BRD8029A
700| BRD4206A| EFR32ZG14: ZW-LR, SoC & 14 dBm| Serial API using BRD4002A
700| BRD4207A| ZGM130S: ZW-LR, SiP & 14 dBm| Applications using BRD4002A/BRD8029A
700| BRD4208A| EFR32ZG14: ZW-LR, SoC & 20 dBm| Serial API using BRD4002A
700| BRD4209A| ZGM130S: ZW-LR, SoC & 20 dBm| Applications using BRD4002A/BRD8029A

The applications in the above table need a radio board in combination with BRD4002A – Wireless Starter Kit Mainboard (WSTK) and BRD8029A – Buttons and LEDs Expansion Board. Notice that BRD4002A is compatible with the old BRD4001A mainboard that is going to be deprecated. The Serial APIs in the above table only need a radio board and a BRD4002A – Wireless Starter Kit Mainboard (WSTK). Refer to INS14278: How to Use Certified Apps and INS14816: How to Use Pre-Certified Apps, for details.

ZW-LR indicates that the radio board supports both Z-Wave and Z-Wave Long Range. 14/20 dBm indicates the transmit power of the radio board. Secure Vault is an industry-leading suite of state-of-the-art security features that address escalating Internet of Things (IoT) threats.
Please note that the radio board BRD2603A is supplied in an independent development kit called the Z-Wave 800 Series Develop-ment Kit.

Table 1-2. Radio Boards versus OPNs.

The table above shows the Radio Boards and OPN relation. This table can be used to clarify the compatibility of the prebuilt binaries offered in the GSDK. The prebuilt binaries are built targeting boards and not OPNs. More OPNs are available than the ones listed above. For those OPNs the prebuilt binaries will not work. The desired application must be built targeting the specific OPN instead.

Z-Wave Protocol

Be aware that 800 products based on SDK v7.17.x do not support upgrade of Secure Element firmware over the air (OTA). However, a migration path exists to upgrade both main bootloader and Secure Element firmware to enable support of this feature. See INS14895: Instruction for How to Use Tiny App regarding the upgrade path. The 800-based SDK v7.18.x supports upgrade of Secure Element firmware over the air (OTA).
The 8 kB reduction of the Z-Wave protocol NVM3 file system has an impact when making OTA firmware update on 800-based ap-plications deployed on version 7.17.2 and earlier. To make an OTA firmware update from 7.17.2 to 7.18.1/2 requires that 7.18.1/2 is modified to keep the same NVM3 protocol size as 7.17.2. This can be configured by the define NVM3_DEFAULT_NVM_SIZE when building 7.18.1/2.
The 800 series based end device will hang in a boot loop if security keys are manually written in Manufacturer Tokens.
Note that due to the introduction of Secure Key Storage on the 800 series, having externally supplied key pairs is no longer sup-ported. To ensure that security is not compromised, keys are generated internally on first boot and kept only in secure storage. The public key and the QR code can be read out in production.

New Items
None

Improvements
None

Fixed Issues
Fixed in release 7.20.1 GA

S2_UniqueAuthLearnModeECDHKeyPair_Rev01.

Fixed in release 7.20.0 Pre-Certified GA

update is aborted shortly after it was initiated.
1112625| Occasional long wakeup beams (up to 9 seconds) on Z-Wave Long Range devices.
1112282| Additional large S0 frame verifications to discard invalid frames.
1111658| Register the Application Status CC (using the REGISTER_CC_V4(…)) and include the device securely, then the Node Info Frame (NIF) does not contain this CC.
1109024| Controller can receive INIF frame from a foreign network without the RECEIVE_STATUS_FOREIGN_HOMEID bit in the ApplicationControllerUpdate callback.
753759| The end device radio can become unresponsive during an OTA firmware update if a message is transmitted during the OTA transactions.

Known Issues in the Current Release
Issues in bold were added since the previous release. If you have missed a release, recent release notes are available on Silicon Labs Release Notes page

defines ZAF_CONFIG_GENERIC_TYPE and ZAF_CONFIG_SPECIFIC_TYPE in**

config/zaf_config.h should be changed to the value 0.

Deprecated Items
None

Removed Items
None

Z-Wave Plus V2 Application Framework

1. New Items
   Z-Wave workspaces introduced solutions in Simplicity Studio 5, where the application and the bootloader projects can be handled together within solutions.
   Improved Ux/Dx, simplified the sample applications by moving logic from the Apps to ZAF and Command Classes.

2. Improvements
   For a detailed description of application development using the Z-Wave Plus V2 Framework, refer to INS14259: Z-Wave Plus V2 Application Framework GSDK.
   A porting guide is also available for customers who want to migrate 800 hardware. The guide contains a detailed example of how to port a non- component/700-based Switch On/Off App (7.16.3) to a component/800-based Switch On/Off App (7.17.0). See APL14836: Application Note for Porting Z-Wave Appl. SW from 700 to 800 hardware.
   More mandatory logic was moved from the application to ZAF. This contributed to bringing down the total number of lines in the application. This should decrease time to market for new products.

3. Fixed Issues
   Fixed in release 7.20.1 GA. ID #| Description
   ---|---
   1145454| CTT Test: CCN_PowerlevelCmdClassTestNode_Rev01 test case failed.
   1148476| CTT Test: ZWavePlusInfoCmdClassV2_Rev08_Orig testcase failed.
   1148478| CTT Test: DoorLockCmdClassV4_Rev08_Orig testcase failed.
   1148479| CTT Test: BinarySwitchCmdClassV2_Rev10_Orig testcase failed.
   1148619| CTT Test: MultiChannelCmdClassV4_Rev05_Orig testcase failed.
   1148626| CTT Test: CentralSceneCmdClassV3_Rev06_Orig testcase failed.
   1150623| CTT Test: PowerStrip ZWavePlusInfo EP2.
   1174728| Don’t advertise S0 in Multi-Channel Capability Report on LR.
   1176935| Certification: Transport CC must not be present in Multi-Channel Capability Report for EP0
   1086946| Z-Wave ZAF Component does not display the default setting for Icon Type and Device Type.
   1130584| List of Command Classes for Endpoints is incomplete in PC Controller.
   1131528| LED Bulb: default values of Multilevel Switch and Color Switch.
   1124411| Same header guards in multiple header files.
   1160192| Sensor PIR has no demo on BRD2603A.
   1106238| cc_configuration_set returns ok in out-of-range value case.
   1174729| Power Strip doesn’t advertise S0 security level in case of long-range network.

4. Known Issues in the Current Release
   Issues in bold were added since the previous release. If you have missed a release, recent release notes are available on the Silicon Labs Release Notes page ID #| Description| Workaround
   ---|---|---
   369430| All S2 multicast frames are sent using verified delivery S2_TXOPTION_VERIFY_DELIVERY whether or not a response is expected.| Change source code depending on the frame sent.
   1086946| The Z-Wave ZAF Component does not display the default setting for Icon Type and Device Type.| Currently not available.
   1062482| OTA firmware update gets stuck when a Timer interrupt is triggered to toggle a GPIO frequently.| Currently not available.
   1080416| The ASSERT macro does not print the file and line when it is used in the ApplicationTask function.| Prints after disabling all interrupts.
   711346| Sensor PIR throws some undefined garbage to the connected port.| Currently not available.
   1172849| On series 800, sleep will no longer take advantage of EM1P current savings.| Currently not available.

5. Deprecated Items
   None

6. Removed Items
   None

Certified Applications

The certified applications based on v7.x.1+ will be formally certified by a certification house. However, the first release (v7.x.0) will only contain pre-certified applications based on a certification test using CTT v3. Refer to INS14278: How to Use Certified Apps for details.

Door Lock Key Pad

1. New Items
   None

2. Improvements
   None

3. Fixed Issues
   None

4. Known Issues in the Current Release
   None

5. Deprecated Items
   None

6. Removed Items
   None

LED Bulb

1. New Items
   None

2. Improvements
   None

3. Fixed Issues
   None

4. Known Issues in the Current Release
   None

5. Deprecated Items
   None

6. Removed Items
   None

Power Strip

1. New Items
   None

2. Improvements
   None

3. Fixed Issues
   None

4. Known Issues in the Current Release
   None

5. Deprecated Items
   None

6. Removed Items
   None

Sensor PIR

1. New Items
   None

2. Improvements
   None

3. Fixed Issues
   None

4. Known Issues in the Current Release
   Issues in bold were added since the previous release. If you have missed a release, recent release notes are available on the Silicon Labs Release Notes page

5. Deprecated Items
   None

6. Removed Items
   None

Switch On/Off

1. New Items
   None

2. Improvements
   None

3. Fixed Issues
   None

4. Known Issues in the Current Release
   None

5. Deprecated Items
   None

6. Removed Items
   None

Wall Controller

1. New Items
   None

2. Improvements
   None

3. Fixed Issues
   None

4. Known Issues in the Current Release
   None

5. Deprecated Items
   None

6. Removed Items
   None

Pre-Certified Applications

The pre-certified applications will not be formally certified but certification tests have been performed based on CTT v3. Refer to INS14816: How to Use Pre-Certified Apps for details.

Multilevel Sensor

1. New Items
   None

2. Improvements
   None

3. Fixed Issues
   None

4. Known Issues in the Current Release
   None

5. Deprecated Items
   None

6. Removed Items
   None

Key Fob Controller
This application is new as of 7.18.x. It offers an example of how to create a key fob that is able to include and control other Z-Wave nodes. One use case could be a kit consisting of a key fob and a battery-driven shade. As the key fob can add more devices to its network, it opens the possibility for adding additional shades.

1. New Items
   None

2. Improvements
   None

3. Fixed Issues
   None

4. Known Issues in the Current Release
   None

5. Deprecated Items
   None

6. Removed Items
   None

Serial API Applications

Beginning with version 7.16, when backing up and restoring a SerialAPI via the FUNC_ID_NVM_BACKUP_RESTORE, the SerialAPI will automatically upgrade the protocol non-volatile memory (NVM) to the latest version. Any backup made of a 7.16 or later SerialAPI can be restored to its original version or to a later version of the SerialAPI without any manual upgrade of the protocol NVM being necessary.
The serial interface is unchanged in version 8.
As of SDK version 7.18.x, Serial API is available as source code as well as binary. This opens the possibility for building customized versions of Serial API with different pin configuration or additional hardware utilization. A use case might be to use SPI instead of UART for serial communication.
No application using Serial API End Device is available in the GSDK.

Serial API Controller

1. New Items
   None

2. Improvements
   None

3. Fixed Issues
   None

4. Known Issues in the Current Release
   ID #| Description| Workaround
   ---|---|---
   1065157| Multilevel Sensor can’t send Multilevel Sensor Report based on auto report timer.| Currently not available.

None

5. Deprecated Items
   None

6. Removed Items
   None

800 SDK – BRD2603

800 SDK improvements:

• MultilevelSensor App improved by supporting ambient light sensor and motion sensor. The periodic timer for sensor data re-ports is configurable.
• Supported new apps on 800 DevKit: SensorPIR, WallController, PowerStrip, Zniffer
• Improved the usage of the 800 DevKit demo with the Unify Portable Environment by adding the ability to identify the application firmware on the boards. This makes preparation of the Dev Kit for the demo simpler and faster.

Important Changes
Starting in version 7.19, API-breaking changes have been documented in the document “Important_changes.md” available in GSDK. Please check it for a detailed description of changes introduced in the latest release.
HTML documentation has been added to GSDK and can be found in Simplicity Studio, Documentation section, under “Z-Wave zipped doxygen documentation”. Location of this document is /protocol/z-wave/studio-docs/z-wave-html- docs.zip.

Open Source Software
Z-Wave is using FreeRTOS as the underlying OS, and it is based on FreeRTOS Kernel V10.4.3.

Using This Release

This release contains the following

• Z-Wave Plus V2 Application Framework
• Z-Wave Certified Applications for a broad range of smart home applications
• Z-Wave Protocol and Serial API Applications
  If you are a first-time user, Z-Wave documentation is installed with the SDK. See INS14280: Z-Wave Getting Started for End Devices, INS14278: How to Use Certified Apps in Z-Wave, and INS14281: Z-Wave Getting Started for Controller Devices for instructions.

This SDK depends on a Gecko Platform. The Gecko Platform code provides functionality that supports protocol plugins and APIs in the form of drivers and other lower layer features that interact directly with Silicon Labs chips and modules. Gecko Platform compo-nents include EMLIB, EMDRV, RAIL Library, NVM3, PSA, and mbedTLS. Gecko Platform release notes are available through Sim-plicity Studio’s Launcher Perspective.

Installation and Use
Order a Z-Wave Wireless Starter kit. The kit offers the easiest and fastest way to start evaluation and development of your own Z-Wave mesh application. It provides a single world-wide development kit for both end devices and gateways with multiple radio boards, with which developers can create a mesh network and evaluate the Z-Wave module.
The Z-Wave and Z-Wave Long Range 700/800 SDK is provided as part of the Gecko SDK (GSDK), the suite of Silicon Labs SDKs. To quickly get started with the GSDK, install Simplicity Studio 5, which will set up your development environment and walk you through GSDK installation. Simplicity Studio 5 includes everything needed for IoT product development with Silicon Labs devices, including a resource and project launcher, software configuration tools, full IDE with GNU toolchain, and analysis tools. Installation instructions are provided in the online Simplicity Studio 5 User’s Guide.
Alternatively, Gecko SDK may be installed manually by downloading or cloning the latest from GitHub. See https://github.com/Sili-conLabs/gecko_sdk for more information.

Simplicity Studio installs the GSDK by default in:

• (Windows): C:\Users\\SimplicityStudio\SDKs\gecko_sdk
• (MacOS): /Users//SimplicityStudio/SDKs/gecko_sdk

To implement a specific application, Silicon Labs recommends starting with one of the existing pre-certified apps with the desired Role Type.

Security Information
Secure Vault Integration
This version of the stack are using secure vault interface for key management of asymmetric keys (ECC Curve 25519) and Symmetric keys (AES).

Security Advisories
To subscribe to Security Advisories, log in to the Silicon Labs customer portal, then select Account Home. Click HOME to go to the portal home page and then click the Manage Notifications tile. Make sure that ‘Software/Security Advisory Notices & Product Change Notices (PCNs)’ is checked, and that you are subscribed at minimum for your platform and protocol. Click Save to save any changes.

Support
Development Kit customers are eligible for training and technical support.
See support resources and contact Silicon Laboratories support at https://www.silabs.com/support.

Product Life Cycle and Certification

Silicon Labs will add new features based on market requirements and continuously improve the Z-Wave Protocol to position the Z-Wave Ecosystem. The Z-Wave Protocol Life Cycle is a process to provide rapid innovation, new features and robust matured protocol release to Z-Wave Partners. The Z-Wave Protocol Life Cycle defines the maturation process of Z-Wave Protocol generations and consist of three phases divided in five Life Cycle stages. A change in the Z-Wave SDK utilized for a specific device does require recertification; however, the type of certification required, the amount of testing needed, and the associated fees depend on the scope of the change. Refer to Z-Wave Alliance home page https://z-wavealliance.org/ for details.

Table 11-1. Z-Wave SDK Release History

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 the 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 liability 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 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.

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
• Overview - latest - Simplicity Studio 5 Users Guide Silicon Labs
• Technical Support - Silicon Labs
• The Internet of Things is Powered by Z-Wave - Z-Wave Alliance

Read User Manual Online (PDF format)

Download This Manual (PDF format)

Download this manual  >>