Instruction - Silicon Labs€¦ · 1 20160209 TRO Section 4.5.3 Describe Basic Set values 0x00 and...

Instruction

Z-Wave 500 Series SDK Contents v6.71.03

Document No.: INS13477

Version: 12

Description: -

Written By: JFR;COLSEN;PSH;JSI;SSE;EFH;BBR

Date: 2018-03-02

Reviewed By: JFR;EFH;SSE;COLSEN;JKA;LTHOMSEN;CRASMUSSEN

Restrictions: {Public

Approved by:

Date CET Initials Name Justification

2018-03-02 15:49:30 JFR Jørgen Franck on behalf of NTJ

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 information contained in the data if it is obtained from another source without restriction.

INS13477-12 Z-Wave 500 Series SDK Contents v6.71.03 2018-03-02

silabs.com | Building a more connected world. Page ii of vi

REVISION RECORD

Doc. Rev

Date By Pages affected

Brief description of changes

1 20160107 JFR ALL Initial draft based on INS13050-5 Z-Wave 500 Series SDK Contents v6.60.00

1 20160128 TRO JFR

Section 3 & 4 Updated to SDK 6.70.00

1 20160209 TRO Section 4.5.3 Describe Basic Set values 0x00 and 0xff

1 20160210 TRO Section 4 Add command class version to sample apps

2 20160303 JFR Section 3 Obsoleted PC Bridge Controller

3 20160416 TRO Section 4 Change CC Firmware update from V3 to V4

3 20160416 TRO Section 3.4.1 Change NVM to 128 KB for slave enhanced 232 targets

3 20160427 TRO Section 4.2 Change role type

3 20160616 TRO Section 4.2 Change key S5 to S6 (Test interface disable S5) Remove support for ZDB5202

3 20160728 TRO Section 4 In all sub sections change CC switch binary version from 2 to 1

3 20160818 JFR Section 3.1 Section 3.4.1

Added SDK 6.61.00 with modified Door Lock Key Pad using new bootloader Supporting compressed hex file format (*.otz)

4 20161108 TRO Section 4 Add new sub-subsection for applications “Documentation related to devices from multiple manufacturers”

4 20161122 TRO Section 4 Update NIF list and AGI group 2 naming “Doorlock Op” Add CC security + cc security 2 in all NIF tables

4 20161202 TRO Sections 4.2.1, 4.3.1, 4.4.1, 4.5.1, 4.6.1 & 4.10.1

Move CC Power Level from list, securely added, non-secure-CC to secure-CC.

4 20161202 TRO Section 4.1.3 Change CC notification from 4 -> 8

4 20161212 COLSEN Section 4.5 Removed Firmware Update CC and removed section about firmware update.

4 20161213 JFR Section 4.5 Section 4.10

Sensor PIR changed to S2_UNAUTHENTICATION only Wall Controller changed to S0 and S2_UNAUTHENTICATION and S2_AUTHENTICATION

4 20170102 TRO Section 4 Change mapping for CC Basic

4 20170104 SSE Section 4.8 Correct the description of the production test generator SW

4 20170111 JFR Section 3.1, 3.4 & 4

Removed On/Off Switch, PIR Sensor, Power Strip and Wall Controller because these Z-Wave Plus Apps are not certified yet.

5 20170124 JFR Section 3.1, 3.4 & 4

Added On/Off Switch, PIR Sensor, Power Strip and Wall Controller. Notice that applications are not certified yet.

5 20170127 TRO Section 4.6.1 Added endpoint command class list.

5 20170130 TRO Section 4.10.1 Change CC Central Scene to supported.

6 20170130 COLSEN Section 4 Added an overview of primary application features.

7 20170206 JFR Section 3.1 & 3.5.6

Added PUK and PRK keypair generation based on Curve 25519.

7 20170206 JFR Section 4 Apps now certified

8 20170220 TRO Section 4.2.1 Update NIF’s for Door Lock Key Pad

9 20170615 TRO Section 4.10.1 Update NIF’s for Wall Controller

9 20170619 TRO Section 4.6.3 Add notification description

9 20170710 COLSEN Section 4.6 Updated supported boards for Power Strip.

9 20170712 COLSEN Section 4.1.3 Changed Central Scene CC version from 2 to 3.

9 20170712 PSH Section 3 & 4 Removed intermediate apps

10 20170728 JFR Section 4.1.3 Changed Version CC version from 2 to 3.

10 20170801 TRO Section 4.10.4 Remove LED indication from Wall Controller

10 20170815 TRO Section 4 Add PC controller V5 for secure inclusion of applications

10 20170816 TRO Section 4.5.5, Section 4.6.6

Add Notification event descriptions for Sensor PIR and Power Strip applications

10 20171002 COLSEN Section 4.5.1 Added Basic CC to list of command classes.

10 20171121 COLSEN Section 4.1.3, 4.5 & 4.6

Added information about supported mode of Notification.

11 20171123 COLSEN JFR

Section 4 Section 3.4.1

Updated NIF tables for all apps. Removed txt files showing enable serial API calls

11 20170105 COLSEN Section 4 References

Updated NIF tables. Corrected references.

12 20180302 BBR All Added Silicon Labs template

https://www.silabs.com/


silabs.com | Building a more connected world. Page iii of vi

Table of Contents

1 ABBREVIATIONS ................................................................................................................................. 1

2 INTRODUCTION ................................................................................................................................... 2

2.1 Purpose .............................................................................................................................................. 2 2.2 Audience and prerequisites ................................................................................................................ 2

3 SOFTWARE COMPONENTS ............................................................................................................... 3

3.1 Directory Structure SDK 6.71.0x ........................................................................................................ 3 3.2 Boards Supported .............................................................................................................................. 5 3.3 Z-Wave ............................................................................................................................................... 6

3.3.1 Include ...................................................................................................................................... 6 3.3.2 I/O Defines ............................................................................................................................... 7 3.3.3 Libraries.................................................................................................................................... 7

3.3.3.1 Bootloader ........................................................................................................................ 8 3.3.3.2 Bridge Controller............................................................................................................... 9 3.3.3.3 Portable Controller ........................................................................................................... 9 3.3.3.4 Static Controller ................................................................................................................ 9 3.3.3.5 Static Controller Single ..................................................................................................... 9 3.3.3.6 Enhanced 232 Slave ......................................................................................................10 3.3.3.7 Production Test DUT ......................................................................................................10 3.3.3.8 Production Test Generator .............................................................................................10 3.3.3.9 Routing Slave .................................................................................................................10 3.3.3.10 External non-volatile memory .........................................................................................11 3.3.3.11 Variable initialization .......................................................................................................11 3.3.3.12 Library S2 .......................................................................................................................11 3.3.3.13 RF frequency ..................................................................................................................11

3.4 ProductPlus ......................................................................................................................................12 3.4.1 Bin ..........................................................................................................................................12

3.4.1.1 DoorLockKeyPad ...........................................................................................................12 3.4.1.2 PowerStrip ......................................................................................................................13 3.4.1.3 ProdTestDUT ..................................................................................................................13 3.4.1.4 ProdTestGen ..................................................................................................................13 3.4.1.5 SensorPIR ......................................................................................................................13 3.4.1.6 SerialAPI_Controller_Bridge ..........................................................................................14 3.4.1.7 SerialAPI_Controller_Portable .......................................................................................14 3.4.1.8 SerialAPI_Controller_Static ............................................................................................15 3.4.1.9 SerialAPI_Controller_Static_Single ................................................................................15 3.4.1.10 SerialAPI_Slave_Enhanced_232 ...................................................................................16 3.4.1.11 SerialAPI_Slave_Routing ...............................................................................................16 3.4.1.12 SwitchOnOff ...................................................................................................................16 3.4.1.13 WallController .................................................................................................................17

3.4.2 ApplicationCommandHandlers ..............................................................................................18 3.4.3 ApplicationUtilities ..................................................................................................................20 3.4.4 DoorLockKeyPad ...................................................................................................................21 3.4.5 MyProductPlus .......................................................................................................................21 3.4.6 PowerStrip ..............................................................................................................................21 3.4.7 SensorPIR ..............................................................................................................................21 3.4.8 SerialAPIPlus .........................................................................................................................21 3.4.9 SwitchOnOff ...........................................................................................................................22 3.4.10 WallController .........................................................................................................................22

3.5 Tools .................................................................................................................................................23 3.5.1 FixBootCRC ...........................................................................................................................23



silabs.com | Building a more connected world. Page iv of vi

3.5.2 FixPatchCRC .........................................................................................................................23 3.5.3 HexTools ................................................................................................................................23 3.5.4 IMAToolBox ............................................................................................................................23 3.5.5 IncDep ....................................................................................................................................23 3.5.6 KeypairGeneration .................................................................................................................23 3.5.7 Make .......................................................................................................................................23 3.5.8 Mergehex ...............................................................................................................................23 3.5.9 Python ....................................................................................................................................24 3.5.10 TextTools................................................................................................................................24 3.5.11 uVisionProjectGenerator ........................................................................................................24

4 Z-WAVE PLUS APPLICATIONS ........................................................................................................25

4.1 Z-Wave Plus Framework ..................................................................................................................26 4.1.1 Application Command Handlers ............................................................................................27 4.1.2 Transport Layer ......................................................................................................................27 4.1.3 Supported command classes .................................................................................................28 4.1.4 General user interface ............................................................................................................28

4.2 Door Lock Key Pad ..........................................................................................................................29 4.2.1 Announced Command Classes in NIF ...................................................................................30 4.2.2 Basic Command Class mapping ............................................................................................30 4.2.3 Association groups .................................................................................................................31 4.2.4 Usage of buttons on ZDP03A ................................................................................................31 4.2.5 LED status on ZDP03A ..........................................................................................................31 4.2.6 Firmware update and external NVM ......................................................................................31 4.2.7 Z-Wave Certification ...............................................................................................................32 4.2.8 Documentation related to devices from multiple manufacturers ............................................32

4.3 My Product Plus ...............................................................................................................................33 4.3.1 Announced Command Classes in NIF ...................................................................................33 4.3.2 Basic Command Class mapping ............................................................................................34 4.3.3 Association groups .................................................................................................................34 4.3.4 MyProduct Files .....................................................................................................................34 4.3.5 Firmware update and external NVM ......................................................................................35 4.3.6 Z-Wave Certification ...............................................................................................................35 4.3.7 Documentation related to devices from multiple manufacturers ............................................35

4.4 Switch On/Off ...................................................................................................................................36 4.4.1 Announced Command Classes in NIF ...................................................................................37 4.4.2 Basic Command Class mapping ............................................................................................37 4.4.3 Association groups .................................................................................................................37 4.4.4 Usage of buttons on ZDP03A ................................................................................................38 4.4.5 LED status on ZDP03A ..........................................................................................................38 4.4.6 Firmware update and external NVM ......................................................................................38 4.4.7 Z-Wave Certification ...............................................................................................................38 4.4.8 Documentation related to devices from multiple manufacturers ............................................38

4.5 Sensor PIR .......................................................................................................................................39 4.5.1 Announced Command Classes in NIF ...................................................................................40 4.5.2 Basic Command Class mapping ............................................................................................40 4.5.3 Association groups .................................................................................................................41 4.5.4 Usage of buttons on ZDP03A ................................................................................................41 4.5.5 LED status on ZDP03A ..........................................................................................................41 4.5.6 Z-Wave Certification ...............................................................................................................41 4.5.7 Documentation related to devices from multiple manufacturers ............................................41

4.6 Power Strip .......................................................................................................................................42 4.6.1 Announced Command Classes in NIF ...................................................................................43 4.6.2 Basic Command Class mapping ............................................................................................45 4.6.3 Notification over load detection ..............................................................................................45 4.6.4 Association groups .................................................................................................................46 4.6.5 Usage of buttons on ZDP03A ................................................................................................47



silabs.com | Building a more connected world. Page v of vi

4.6.6 LED status on ZDP03A ..........................................................................................................47 4.6.7 Z-Wave Certification ...............................................................................................................47 4.6.8 Documentation related to devices from multiple manufacturers ............................................47

4.7 Production Test DUT ........................................................................................................................48 4.7.1 Production Test DUT Files .....................................................................................................49

4.8 Production Test Generator ...............................................................................................................50 4.8.1 Production Test Generator Files ............................................................................................52

4.9 Serial API Applications .....................................................................................................................52 4.10 Wall Controller ..................................................................................................................................53

4.10.1 Announced Command Classes in NIF ...................................................................................54 4.10.2 Basic Command Class mapping ............................................................................................56 4.10.3 Association groups .................................................................................................................57 4.10.4 Usage on ZDP03A .................................................................................................................59 4.10.5 How to configure associations to Wall Controller...................................................................60

4.10.5.1 Non-multi-channel encapsulated configuration ..............................................................60 4.10.5.2 Encapsulated configuration ............................................................................................61

4.10.6 Z-Wave Certification ...............................................................................................................61 4.10.7 Documentation related to devices from multiple manufacturers ............................................61

5 DEVELOPMENT COMPONENTS ......................................................................................................62

5.1 Z-Wave Development Platform ZDP03A .........................................................................................62 5.2 Hardware development components for 500 Series ........................................................................63

REFERENCES ...........................................................................................................................................64

INDEX .........................................................................................................................................................65

List of Figures

Figure 1, Z-Wave Plus Application Framework. ........................................................................................ 26 Figure 2. Prod_Test_DUT test program flow. ............................................................................................ 48 Figure 3. Wall Controller endpoints/buttons on ZDP03A. .......................................................................... 56 Figure 4. The Z-Wave Development Platform ZDP03A. ........................................................................... 62

List of Tables

Table 1. 500 Series development boards hex files naming......................................................................... 5 Table 2. Functionality covered by the Z-Wave Plus applications. ............................................................. 25 Table 3: NIF for Door Lock Key Pad .......................................................................................................... 30 Table 4. Door Lock Key Pad buttons interface .......................................................................................... 31 Table 5. Door Lock Key Pad LED status interface .................................................................................... 31 Table 6. Door Lock Key Pad external NVM data backward compatibility ................................................. 32 Table 7: NIF for My Product Plus .............................................................................................................. 33 Table 8. My Product Plus external NVM data backward compatibility ...................................................... 35 Table 9: NIF for Switch On/Off .................................................................................................................. 37 Table 10. On/Off Switch push buttons interface ........................................................................................ 38 Table 11. On/Off Switch LED status interface ........................................................................................... 38 Table 12: NIF for Sensor PIR .................................................................................................................... 40 Table 13. PIR Sensor buttons interface..................................................................................................... 41 Table 14. PIR Sensor LED status interface ............................................................................................... 41 Table 15: NIF for root device of Power Strip ............................................................................................. 43 Table 16: NIF for endpoint 1-2 of Power Strip ........................................................................................... 44



silabs.com | Building a more connected world. Page vi of vi

Table 17: NIF for endpoint 3 of Power Strip .............................................................................................. 45 Table 18. Power Strip push buttons interface ........................................................................................... 47 Table 19. Power Strip LED status interface .............................................................................................. 47 Table 20. Production Test Generator LED interface ................................................................................. 50 Table 21: NIF for root device of Wall Controller ........................................................................................ 54 Table 22: NIF for endpoint 1-4 of Wall Controller ...................................................................................... 55 Table 23. Wall Controller push buttons interface ...................................................................................... 59 Table 24. 500 Series development boards and interfaces ........................................................................ 63



silabs.com | Building a more connected world. Page 1 of 65

1 ABBREVIATIONS

Abbreviation Explanation

ACK Acknowledge

AES The Advanced Encryption Standard is a symmetric block cipher algorithm.

AGI Association Group Information command class

ANZ Australia/New Zealand

API Application Programming Interface

ASIC Application Specific Integrated Circuit

CSA Client-Side Authentication

DLL Dynamic Link Library

DUT Device Under Test

ERTT Enhanced Reliability Test Tool

EU Europe

GNU An organization devoted to the creation and support of Open Source software

HEX S-Record hex file extension (*.hex) for programs to be downloaded the first time using a programmer because it contains both bootloader and Firmware Update Meta Data Command Class implementation. The bootloader can support S-Record hex file or compressed hex file format.

HK Hong Kong

HW Hardware

IL Israel

IMA Installation and Maintenance Application that typical resides on the gateway

IN India

IR Infrared

JP Japan

KR South Korea

LBT Listen Before Talk

NVM Non-volatile memory

OTA Over the air (e.g. making a firmware update wireless). Also used as S-Record hex file extension (*.ota) for programs to be sent over the air achieving a firmware update of the device in question. The device must of course have a bootloader supporting the S-Record hex file format.

OTW Over the wire (e.g. making a firmware update via the serial API interface)

OTZ Used as compressed hex file extension (*.otz) for programs to be sent over the air (OTA) achieving a firmware update of the device in question. The device must of course have a bootloader supporting the compressed hex file format.

RF Radio Frequency

RSSI Received Signal Strength Indicator

RU Russia

S0 Security Command Class

S2 Security 2 Command Class

SDK Z-Wave Software Developer’s Kit includes software and related software documentation.

SSA Server-Side Authentication

TI Test Interface for test and debugging purposes.

UPnP Universal Plug and Play

US United States

USB Universal Serial Bus

UZB USB v2.0 full speed low power CDC-ACM compliant Z-Wave adapter

VCP Virtual COM Port

XML eXtensible Markup Language

ZDK Z-Wave Developer’s Kit includes hardware, software and documentation.




2 INTRODUCTION

2.1 Purpose

The purpose of this document is to describe the contents on the Z-Wave Software Developer’s Kit (SDK). Document contains also a description of all embedded applications including user guide or reference to relevant document.

2.2 Audience and prerequisites

The audience is Z-Wave Partners.




3 SOFTWARE COMPONENTS

The Z-Wave development software packet consists of a protocol part, applications and a number of tools used for developing and building the code.

3.1 Directory Structure SDK 6.71.0x

The development software is organized in the following directory structure:

/ - ProductPlus

- ApplicationCommandHandlers - ApplicationUtilities - Bin

- DoorLockKeyPad - PowerStrip - ProdTestDUT - ProdTestGen - SensorPIR - SerialAPI_Controller_Bridge - SerialAPI_Controller_Portable - SerialAPI_Controller_Static - SerialAPI_Controller_Static_Single - SerialAPI_Slave_Enhanced_232 - SerialAPI_Slave_Routing - SwitchOnOff - WallController

- DoorLockKeyPad - MyProductPlus - PowerStrip - ProdTestDUT - ProdTestGen - SensorPIR - SerialAPIPlus - SwitchOnOff - WallController

- Tools - FixBootCRC - FixPatchCRC - HexTools - IMAToolbox

- PC - Source

- IncDep - KeypairGeneration - Make - Mergehex - Python - TextTools

- sed-1-4-5 - uVisionProjectGenerator




- Z-Wave - include - IO_defines - lib

- bootloader_ZW050x - controller_bridge_ZW050x - controller_bridge_ZW050x_3CH - controller_portable_ZW050x - controller_portable_ZW050x_3CH - controller_static_single_ZW050x - controller_static_single_ZW050x_3CH - controller_static_ZW050x - controller_static_ZW050x_3CH - ext_nvm - init_vars - lib2 - rf_freq - slave_enhanced_232_ZW050x - slave_enhanced_232_ZW050x_3CH - slave_prodtest_dut_ZW050x - slave_prodtest_dut_ZW050x_3CH - slave_prodtest_gen_ZW050x - slave_prodtest_gen_ZW050x_3CH - slave_routing_ZW050x - slave_routing_ZW050x_3CH

This directory structure contains all the tools and applications needed, except the recommended Keil software, which must be purchased separately. More information about where and how to buy the Keil software development components are described in [12].

Note! Recommending leaving the directory structure as is due to compiler and linker issues.

The majority of the above mentioned Z-Wave specific tools and application are briefly described in the following sections.




3.2 Boards Supported

The SDK support a number of different boards as shown in the table below.

Table 1. 500 Series development boards hex files naming

Development board Module/chip used Hex file name

ZDB5101

ZM5101 *_ZW050x_y*.hex

*_ZW050x_USBVCP_y*.hex

ZDB3502

SD3502 *_ZW050x_y*.hex

*_ZW050x_USBVCP_y*.hex

ZDB5202

ZM5202/SD3502 (300 series interface)

*_ZW050x_y*.hex (See note below)

Note: USBVCP hex files do not support ZM5202. Calibration hex files for Z-Wave have dedicated ZM5202 hex files.




3.3 Z-Wave

The Z-Wave header files and libraries are the software files needed for building a Z-Wave enabled product. The files are organized in directories used for building Z-Wave controllers and slaves respectively.

3.3.1 Include

The Z-Wave\include directory contains Z-Wave header files needed for interfacing to the Z-Wave protocol and hardware peripherals that reside on the 500 Series Single Chip.

The Z-Wave protocol related header files are as follows:

ZW_controller_api.h Portable Controller interface. This header should be used together with the Controller Library.

Macro defines.

Include all necessary header files.

ZW_controller_bridge_api.h Bridge controller interface. This header should be used together with the Bridge Controller Library.

Macro defines.

Includes all necessary header files.

ZW_controller_static_api.h Static Controller interface. This header should be used together with the Static Controller Library.

Macro defines.

Includes all necessary header files.

ZW_sensor_api.h Sensor interface.

Macro defines.

Includes all other necessary header files.

ZW_slave_32_api.h Slave interface for ZMXXXX-RE Z-Wave module.

Macro defines.

Include all header files.

ZW_slave_api.h Slave interface.

Macro defines.


ZW_slave_routing_api.h Routing and Enhanced 232 slave nodes interface.

Macro definitions.


ZW_basis_api.h Z-Wave Application general software interface.

Interface to common Z-Wave functions.

ZW_transport_api.h Transfer of data via Z-Wave protocol.

ZW_classcmd.h Defines for device and command classes used to obtain interoperability between Z-Wave enabled products from different vendors, for a detailed description refer to [4], [5], [6], [7], [8], [15], [16] and [11].




The hardware peripherals related header files are as follows:

config_lib.h This header file contains defines for library version in a generalized way.

ISD51.h This header file contains defines and functions for the In-System Debugger for 8051 based microcontrollers modified for Silicon Labs ZW050x.

ZW_adcdriv_api.h This header file contains defines and functions interfacing to the 500 Series Single Chip built-in analog to digital converter.

ZW_aes_api.h This header file contains defines and functions interfacing to the 500 Series Single Chip built-in AES-128 engine.

… See comments in header files.

ZW050x.h Inventra 8051 SFR defines for the Z-Wave ZW050x RF transceiver.

3.3.2 I/O Defines

The Z-Wave\IO_defines directory contains hardware definition files needed for building an application e.g. the development controller application.

AppRFSetup.c This file defines the normal and low power transmission levels. Change levels here if necessary.

ZW_app_version.a51 Makes the version for the application accessible from the library file during linking.

ZW_evaldefs.h This file contains definitions of the connector pins on the controller board.

ZW_L51_BANK.a51 This file enables code bank switching.

ZW_pindefs.h This file contains definitions of the connector pins on the Z-Wave module, and macros for accessing the I/O pins. Refer to [10] regarding a detail description.

ZW_portdefs.h This file contains I/O port initialization vectors on the Z-Wave ASIC.

ZW_segment_tail.a51 This file enables use of XDATA located in SRAM part of the code area.

ZW_strings_rf050x.h/c Attributes for RF table.

3.3.3 Libraries

The Z-Wave\lib directory structure contains all the supported libraries.




3.3.3.1 Bootloader

The lib\bootloader_ZW050x directory contains a bootloader that is used in connection with OTA firmware update. The directory contains the following file:

ZW_bootloader_ZW050x.lib This file is linked together with the Z-Wave protocol and API library.




3.3.3.2 Bridge Controller

The lib\controller_bridge_ZW050x… directory contains all files needed for building a non-secure Z-Wave bridge controller application. The directory contains the following files:

ZW_controller_bridge_ZW050x.lib ZW_controller_bridge_ZW050x_3CH.lib

These files are the compiled Z-Wave protocol and API library for a 500 Series based module that a Z-Wave bridge controller application should be linked together with. JP and KR use the 3CH variant.

3.3.3.3 Portable Controller

The lib\controller_portable_ZW050x… directory contains all files needed for building a non-secure Z-Wave controller application. The directory contains the following files:

ZW_controller_portable_ZW050x.lib ZW_controller_portable_ZW050x_3CH.lib

These files are the compiled Z-Wave protocol and API library for a 500 Series based module that a Z-Wave portable controller application should be linked together with. JP and KR use the 3CH variant.

3.3.3.4 Static Controller

The lib\controller_static_ZW050x… directory contains all files needed for building a non-secure Z-Wave static controller application. The directory contains the following files:

ZW_controller_static_ZW050x.lib ZW_controller_static_ZW050x_3CH.lib

These files are the compiled Z-Wave protocol and API library for a 500 Series based module that a Z-Wave static controller application should be linked together with. JP and KR use the 3CH variant.

3.3.3.5 Static Controller Single

The lib\controller_static_single_ZW050x… directory contains all files needed for building a Z-Wave static single controller application. ERTT application uses this library because it supports suppression of retransmission. Notice that the PC based Controller now supports the ERTT functionality.

WARNING: Do not use this library in product applications

The directory contains the following files:

ZW_controller_static_single_ZW050x.lib ZW_controller_static_single_ZW050x_3CH.lib

These files are the compiled Z-Wave protocol and API library for a 500 Series based module that a Z-Wave static controller single application should be linked together with. JP and KR use the 3CH variant.




3.3.3.6 Enhanced 232 Slave

The lib\slave_enhanced_232_ZW050x… directory contains all files needed for building a non-secure and secure S0/S2 Z-Wave enhanced 232 slave node application. The directory contains the following files:

ZW_slave_enhanced_232_ZW050x.lib ZW_slave_enhanced_232_ZW050x_3CH.lib

These files are the compiled Z-Wave protocol and API library for a 500 Series based module that a Z-Wave enhanced 232 slave application should be linked together with. JP and KR use the 3CH variant.

3.3.3.7 Production Test DUT

The lib\slave_prodtest_dut_ZW050x… directory contains all files needed for building a production test DUT application on a Z-Wave module. The directory contains the following files:

ZW_slave_prodtest_dut_ZW050x.lib ZW_slave_prodtest_dut_ZW050x_3CH.lib

These files are the compiled Z-Wave protocol and API library for a 500 Series based module modules that a Z-Wave production test DUT application should be linked together with. JP and KR use the 3CH variant.

3.3.3.8 Production Test Generator

The lib\slave_prodtest_gen_ZW050x… directory contains all files needed for building a production test generator application on a Z-Wave module. The directory contains the following files:

ZW_slave_prodtest_gen_ZW050x.lib ZW_slave_prodtest_gen_ZW050x_3CH.lib

These files are the compiled Z-Wave protocol and API library for a 500 Series based module modules that a Z-Wave production test generator application should be linked together with. JP and KR use the 3CH variant.

3.3.3.9 Routing Slave

The lib\slave_routing_ZW050x… directory contains all files needed for building a non-secure Z-Wave routing slave node application on a Z-Wave module. The directory contains the following files:

ZW_slave_routing_ZW050x.lib ZW_slave_routing_ZW050x_3CH.lib

These files are the compiled Z-Wave protocol and API library for a 500 Series based module that a Z-Wave routing slave application should be linked together with. JP and KR use the 3CH variant.




3.3.3.10 External non-volatile memory

The lib\ext_nvm directory contains external non-volatile memory (NVM) drivers, which can be used to substitute default driver in library.

The default driver uses SPI1 and P2.5 to access external NVM. The driver adapt automatically to the external NVM in question or uses data in NVR. Regarding supported NVMs, refer to [17]

WARNING: Currently it is not possible to substitute default driver in library/bootloader by linking one of the object files.

3.3.3.11 Variable initialization

The lib\init_vars directory contains an init_vars.obj object file, which replaces the standard Keil initialization procedure. This reduces the time to detect whether a wakeup beam is present or not by postponing initialization. Initialization happens only in case the wakeup beam is addressed to the node in question.

3.3.3.12 Library S2

The lib\libs2 directory contains the S2 Security-specific libraries. These libraries are linked into all S2 enabled targets.


LIBS2CRYPTO.LIB: Cryptographic functions used by S2.

LIBS2_SLAVE.LIB: S2 transport system and inclusion state machine for slave libraries.

3.3.3.13 RF frequency

The lib\rf_freq directory contains all the possible RF initialization object files ZW_rf_050x_xx.obj:

ZW_rf_050x_ALL.obj – Contains all frequencies (Used by Zniffer and Production TestGenerator)

ZW_rf_050x_ANZ.obj – Australia/New Zealand

ZW_rf_050x_CN.obj – China

ZW_rf_050x_EU.obj – Europe

ZW_rf_050x_HK.obj – Hong Kong

ZW_rf_050x_IL.obj – Israel

ZW_rf_050x_IN.obj – India

ZW_rf_050x_JP.obj – Japan

ZW_rf_050x_KR.obj – South Korea

ZW_rf_050x_MY.obj – Malaysia

ZW_rf_050x_RU.obj – Russia

ZW_rf_050x_US.obj – US




3.4 ProductPlus

The ProductPlus directory contains Z-Wave Plus applications for a number of different product examples. Both source code and precompiled files ready for download are supplied.

3.4.1 Bin

The ProductPlus\Bin directory structure contains the precompiled code of the Z-Wave Plus applications and the hex files needed to download to the Z-Wave 500 Series Single Chip via the Z-Wave Programmer.

The table in section 3.1 show the hex files naming for Z-Wave Development Boards used in conjunction with the Z-Wave Development Platform ZDP03A. Refer to section 5.1 regarding RS232 and USB numbering on ZDP03A. Refer to section 3.3.3.11 regarding frequency notation y.

3.4.1.1 DoorLockKeyPad

The ProductPlus\Bin\DoorLockKeyPad directory contains all files needed for running a Z-Wave Plus Door Lock with Keypad (both non-secure and secure S0/S2) application on a Z-Wave module. The Z-Wave Plus application is based on the enhanced 232 slave library. The directory contains the following files:

DoorLockKeyPad_slave_enhanced_232_OTA_SSA _ZW050x_y_TI_WITH_BOOTLOADER.hex

Door Lock with Keypad hex files for y frequency versions. Download this file first time using ZWaveProgrammer because it contains both bootloader supporting OTZ hex files and Firmware Update Meta Data Command Class implementation. The OTW functionality requires an external NVM equal to or bigger than 128 KB. TI denotes that Test Interface is enabled. SSA denotes that server-side authentication is used, which is the highest security level in S2.

DoorLockKeyPad_slave_enhanced_232_OTA_SSA _ZW050x_y_TI.otz

Door Lock with Keypad OTZ hex files for y frequency versions. Download this file over the air (OTA) subsequent because it contains not the bootloader.

DoorLockKeyPad_slave_enhanced_232_OTA_CSA _ZW050x_y_TI_WITH_BOOTLOADER.hex

Door Lock with Keypad hex files for y frequency versions. Download this file first time using ZWaveProgrammer because it contains both bootloader supporting OTZ hex files and Firmware Update Meta Data Command Class implementation. The OTW functionality requires an external NVM equal to or bigger than 128 KB. TI denotes that Test Interface is enabled. CSA denotes that client-side authentication, which is used when upgrading devices to support S2.

DoorLockKeyPad_slave_enhanced_232_OTA_CSA _ZW050x_y_TI.otz

Door Lock with Keypad OTZ hex files for y frequency versions. Download this file over the air (OTA) subsequent because it contains not the bootloader.




3.4.1.2 PowerStrip

The ProductPlus\Bin\PowerStrip directory contains all files needed for running a Z-Wave Plus Power Strip (both non-secure and secure S0/S2) application on a Z-Wave module. The Z-Wave Plus application is based on the enhanced 232 slave library. The directory contains the following files:

PowerStrip_slave_enhanced_232_OTA _ZW050x_y_TI_WITH_BOOTLOADER.hex

Power Strip hex files for y frequency versions. Download this file first time using ZWaveProgrammer because it contains both bootloader supporting OTZ hex files and Firmware Update Meta Data Command Class implementation. The OTW functionality requires an external NVM equal to or bigger than 128 KB. TI denotes that Test Interface is enabled.

PowerStrip_slave_enhanced_232_OTA _ZW050x_y_TI.otz

Power Strip OTZ hex files for y frequency versions. Download this file over the air (OTA) subsequent because it contains not the bootloader.

3.4.1.3 ProdTestDUT

The ProductPlus\Bin\ProdTestDUT directory contains all files needed for running a production test device under test (DUT) application on a Z-Wave module. The directory contains the following files:

prodtestdut_ZW050x_y.hex Production test DUT hex files for y frequency versions.

3.4.1.4 ProdTestGen

The ProductPlus\Bin\ProdTestGen directory contains all files needed for running a production test generator application on a Z-Wave module. The directory contains the following files:

prodtestgen_ZW050x_ALL.hex prodtestgen_ZW050x_ALL_3CH.hex

Production test generator hex files for all frequency versions. JP and KR uses 3CH.

3.4.1.5 SensorPIR

The ProductPlus\Bin\SensorPIR directory contains all files needed for running a Z-Wave Plus PIR Sensor (both non-secure and secure S0/S2) application on a Z-Wave module. The Z-Wave Plus application is based on the routing slave library and supports therefore not OTA firmware update. The directory contains the following files:

SensorPIR_Battery_slave_routing _ZW050x_y.hex

PIR Sensor hex files for y frequency versions.




3.4.1.6 SerialAPI_Controller_Bridge

The ProductPlus\Bin\SerialAPI_Controller_Bridge directory contains all files needed for running a serial API based bridge controller (both non-secure and secure S0/S2) application on a Z-Wave module. The directory contains the following files:

serialapi_controller_bridge_ZW050x_y.hex RS232 1 port (ZDP03A) based serial API hex files for y frequency versions.

serialapi_controller_bridge_ZW050x_USBVCP _y.hex

USB 2 port (ZDP03A) based serial API hex files for y frequency versions. USBVCP hex files do not support ZM5202.

serialapi_controller_bridge_OTW_ZW050x _y_WITH_BOOTLOADER.hex serialapi_controller_bridge_OTW_ZW050x _USBVCP_y_WITH_BOOTLOADER.hex

RS232 1 / USB 2 port (ZDP03A) based serial API hex files supporting OTW firmware update for y frequency versions. Hex file comprises of application and bootloader supporting OTZ hex files. This hex file MUST be used first time when programming the device. The OTW functionality requires an external NVM equal to or bigger than 256 KB.

serialapi_controller_bridge_OTW_ZW050x _y.otz serialapi_controller_bridge_OTW_ZW050x _USBVCP_y.otz

RS232 1 / USB 2 port (ZDP03A) based serial API OTZ hex files supporting OTW firmware update for y frequency versions. Hex file comprises of only application. This hex file MUST be used when doing OTW firmware update.

3.4.1.7 SerialAPI_Controller_Portable

The ProductPlus\Bin\SerialAPI_Controller_Portable directory contains all files needed for running a serial API based portable controller (both non-secure and secure S0/S2) application on a Z-Wave module. The directory contains the following files:

serialapi_controller_portable_ZW050x_y.hex RS232 1 port (ZDP03A) based serial API hex files for y frequency versions.

serialapi_controller_portable_ZW050x_USBVCP _y.hex


serialapi_controller_portable_OTW_ZW050x _y_WITH_BOOTLOADER.hex serialapi_controller_portable_OTW_ZW050x _USBVCP_y_WITH_BOOTLOADER.hex


serialapi_controller_portable_OTW_ZW050x _y.otz serialapi_controller_portable_OTW_ZW050x

RS232 1 / USB 2 port (ZDP03A) based serial API OTZ hex files supporting OTW firmware update for y frequency versions. Hex file comprises of only application. This hex file MUST be used




_USBVCP_y.otz when doing OTW firmware update.

3.4.1.8 SerialAPI_Controller_Static

The ProductPlus\Bin\SerialAPI_Controller_Static directory contains all files needed for running a serial API based static controller (both non-secure and secure S0/S2) application on a Z-Wave module. The directory contains the following files:

serialapi_controller_static_ZW050x_y.hex RS232 1 port (ZDP03A) based serial API hex files for y frequency versions.

serialapi_controller_static_ZW050x_USBVCP _y.hex


serialapi_controller_static_OTW_ZW050x _y_WITH_BOOTLOADER.hex serialapi_controller_static_OTW_ZW050x _USBVCP_y_WITH_BOOTLOADER.hex


serialapi_controller_static_OTW_ZW050x _y.otz serialapi_controller_static_OTW_ZW050x _USBVCP_y.otz


3.4.1.9 SerialAPI_Controller_Static_Single

The ProductPlus\Bin\SerialAPI_Controller_Static_Single directory contains the embedded code for the Enhanced Reliability Test Tool (ERTT). Notice that the PC based Controller now supports the ERTT functionality.

WARNING: Do not use this Serial API application in product applications


serialapi_controller_static_single_ZW050x_y.hex RS232 1 port (ZDP03A) based serial API hex files for y frequency versions.

serialapi_controller_static_single_ZW050x_USBVCP _y.hex





3.4.1.10 SerialAPI_Slave_Enhanced_232

The ProductPlus\Bin\SerialAPI_Slave_Enhanced_232 directory contains all files needed for running a serial API based enhanced 232 slave (both non-secure and secure S0/S2) application on a Z-Wave module. The directory contains the following files:

serialapi_slave_enhanced_232_ZW050x_y.hex RS232 1 port (ZDP03A) based serial API hex files for y frequency versions.

serialapi_slave_enhanced_232_ZW050x_USBVCP _y.hex


serialapi_slave_enhanced_232_OTW_ZW050x _y_WITH_BOOTLOADER.hex serialapi_slave_enhanced_232_OTW_ZW050x _USBVCP_y_WITH_BOOTLOADER.hex


serialapi_slave_enhanced_232_OTW_ZW050x _y.otz serialapi_slave_enhanced_232_OTW_ZW050x _USBVCP_y.otz


3.4.1.11 SerialAPI_Slave_Routing

The ProductPlus\Bin\SerialAPI_Slave_Routing directory contains all files needed for running a serial API based routing slave (both non-secure and secure S0/S2) application on a Z-Wave module. The routing slave does not use external NVM. The directory contains the following files:

serialapi_slave_routing_ZW050x_y.hex RS232 1 port (ZDP03A) based serial API hex files for y frequency versions.

serialapi_slave_routing_ZW050x_USBVCP _y.hex


3.4.1.12 SwitchOnOff

The ProductPlus\Bin\SensorPIR directory contains all files needed for running a Z-Wave Plus On/Off Switch (both non-secure and secure S0/S2) application on a Z-Wave module. The Z-Wave Plus application is based on the enhanced 232 slave library. The directory contains the following files:

SwitchOnOff_slave_enhanced_232_OTA _ZW050x_y_TI_WITH_BOOTLOADER.hex

On/Off Switch hex files for y frequency versions. Download this file first time using ZWaveProgrammer because it contains both bootloader supporting OTZ hex files and Firmware




Update Meta Data Command Class implementation. The OTW functionality requires an external NVM equal to or bigger than 128 KB. TI denotes that Test Interface is enabled.

SwitchOnOff_slave_enhanced_232_OTA _ZW050x_y_TI.otz

On/Off Switch OTZ hex files for y frequency versions. Download this file over the air (OTA) subsequent because it contains not the bootloader.

3.4.1.13 WallController

The ProductPlus\Bin\WallController directory contains all files needed for running a Z-Wave Plus Wall Controller (both non-secure and secure S0/S2) application on a Z-Wave module. The Z-Wave Plus application is based on the enhanced 232 slave library. The directory contains the following files:

WallController_slave_enhanced_232 _ZW050x_y_TI.otz

Wall Controller hex files for y frequency versions. TI denotes that Test Interface is enabled.

WallController_slave_enhanced_232_OTA _ZW050x_y_TI_WITH_BOOTLOADER.hex

Wall Controller hex files for y frequency versions. Download this file first time using ZWaveProgrammer because it contains both bootloader supporting OTZ hex files and Firmware Update Meta Data Command Class implementation. The OTW functionality requires an external NVM equal to or bigger than 128 KB. TI denotes that Test Interface is enabled.

WallController_slave_enhanced_232_OTA _ZW050x_y_TI.otz

Wall Controller OTZ hex files for y frequency versions. Download this file over the air (OTA) subsequent because it contains not the bootloader.




3.4.2 ApplicationCommandHandlers

In addition to Command Class specific modules, the folder “ProductPlus\ApplicationCommandHandlers” contains general purpose functions by the ApplicationCommandHandler function.

Files Description

config_app.h This header file contains definitions saved in NVM. It is used for Firmware Update (APP_MANUFACTURER_ID and APP_FIRMWARE_ID) and Application version handling.

config_release.bat The BAT file is a helper file for the build environment. Instead of using “make xx” use “mk xx”.




ZW_tx_mutex.h ZW_tx_mutex.c

This module allocates protected transmit-buffers used to send data. The mutex buffer MUST be used correctly to ensure safe access to the transmit buffer. All Command class handler modules use mutex buffers to send data.

There are two types of buffers, one for Set/Get commands (Request commands) and one for Response commands.

Example of using a Response buffer: GetResponseBuffer()

returns a pointer to the buffer and ZCB_ResponseJobStatus()releases the buffer again. It is possible for the application to

get status of the SendData() by calling

GetResponseBufferCb( pCB). If Transport_SendResponse() failed is it up to the user to free the buffer

{

/*Get pointer to buffer and check it is not NULL*/

ZW_APPLICATION_TX_BUFFER *pTxBuf =

GetResponseBuffer();

If(NULL != pTxBuf)

{

/*Fill out buffer*/

pTxBuf->ZW_BasicReportFrame.cmdClass =

COMMAND_CLASS_BASIC;

pTxBuf->ZW_BasicReportFrame.cmd = BASIC_REPORT;

pTxBuf->ZW_BasicReportFrame.value = 0;

/*Send data through transport layer. Remember to

free

Buffer if Transport_SendResponse failed!*/

if(FALSE == Transport_SendResponse(

sourceNode,

(BYTE *)pTxBuf,

sizeof(ZW_BASIC_REPORT_FRAME),

option,

ZCB_ResponseJobStatus))

{

/*Job failed, free transmit-buffer pTxBuf */

FreeResponseBuffer();

}

}

}

CommandClassXxx.c CommandClassXxx.h

The files contain code for command class Xxx implementation. Add new command class implementations using the same framework.

ZW_plus_version.h Z-Wave Plus Framework version and revision.




3.4.3 ApplicationUtilities

The ProductPlus\ApplicationUtilities directory contains some helpful functions that are used by several of the applications.

Files Description

ota_util.c/h OTA module for firmware update

one_button.c/h

p_button.c/h

keyman.c/h

Buttons utilities

ZW_TransportLayer.h

ZW_TransportEndpoint.c/h

ZW_TransportMulticast.c/h

ZW_TransportSecProtocol.c/h

ZW_classcmd_ex.h

endpoint_lookup.c/h

Transport layer

association_plus.c/h Association manager module for ZWave+ apps.

battery_monitor.c/h

battery_non_zero_vars.c

battery_plus.c/h

Battery module.

-Low battery monitoring module

-Non zero Memory for Battery module

-Handling sleep timeout and wakeup

config_app.h ApplicationUtilities version and revision

ctrl_learn.c/h

slave_learn_plus.c

Connection module:

-Handle Learn-mode for Controller device

-Handle Learn-mode for Slave device




ZW_bootloader_descriptor.c

ZW_firmware_bank1_mark.c



ZW_nvm_descriptor.c

ZW_firmware_descriptor_addr.c

ZW_firmware_size.c

ZW_product_id_enum.h

Boot loader module

manufacturer_specific_device_id.c/h Manufacturer specific device ID

ZW_cmd_class_list.c/h Node Info List utilities

ZW_ev_scheduler.c/h

port_monitor.c/h

ZW_portpin_api.h

Event scheduler tools.

multilevel_switch.c/h Multilevel-switch utility module

notification.c/h Notification utility module

3.4.4 DoorLockKeyPad

The ProductPlus\DoorLockKeyPad directory contains source code for a Z-Wave Plus Door Lock with Key Pad application on a Z-Wave module. For further information, refer to section 4.2.

3.4.5 MyProductPlus

The ProductPlus\MyProductPlus directory contains source code for a Z-Wave module. For further information, refer to section 4.3.

3.4.6 PowerStrip

The ProductPlus\PowerStrip directory contains source code for a Z-Wave Plus Power Strip application. For further information, refer to section 4.6.

3.4.7 SensorPIR

The ProductPlus\SensorPIR directory contains source code for a Z-Wave Plus PIR Sensor application on a Z-Wave module. For further information, refer to section 4.5.

3.4.8 SerialAPIPlus

The ProductPlus\SerialAPIPlus directory contains source code for the Serial API applications. For further information about the Serial API, refer to section 4.9.




3.4.9 SwitchOnOff

The ProductPlus\SwitchOnOff directory contains source code for a Z-Wave Plus On/Off Switch application. For further information, refer to section 4.4.

3.4.10 WallController

The ProductPlus\WallController directory contains source code for a Z-Wave Plus Wall Controller application. For further information, refer to section 4.9.




3.5 Tools

The Tools directory contains various tools needed for building and debugging the applications. All tools in this directory can freely be used for building Z-Wave applications.

3.5.1 FixBootCRC

This directory contains a tool used when building bootable applications.

3.5.2 FixPatchCRC

This directory contains a tool used when building patchable applications.

3.5.3 HexTools

This directory contains a tool used when building patchable applications.

3.5.4 IMAToolBox

This directory contains the IMA Tool Box supports an installation and maintenance procedure, which can ensure an easy installation and provide an operational qualification of the installation. This tool is used in combination with the SerialAPI_Controller_Static_IMA_... hex file. For detailed information, refer to [1].

The IMAToolBox directory contains the following files:

PC\IMAtoolbox.exe IMA Tool Box application.

PC\Source\... IMAtoolbox PC source code.

3.5.5 IncDep

This directory contains a python script that is used for making dependency files when building the applications.

3.5.6 KeypairGeneration

This directory contains Linux source code showing how to generate a keypair (PUK and PRK) based on curve25519. For implementation details refer to [18] and here is keypair generation to other platforms also described.

3.5.7 Make

This directory contains a DOS/Windows version of the GNU make utility. The make utility is used for building the applications.

3.5.8 Mergehex

This directory contains a tool used for merging two files in Intel hex format. The tool is used for building external non-volatile memory files in the code.




3.5.9 Python

This directory contains a python scripting language interpreter. Python is used for various purposes in the code build process.

3.5.10 TextTools

This directory contains the sed stream editor used to modify text strings during the make process.

3.5.11 uVisionProjectGenerator

This directory contains uVision Project Generator program; the program generate uVision projects when running the makefile from a DOS prompt.

The uVisionProjectGenerator directory contains the following files:

__init__.py j.pyMakePatch.bat och51.bat uv-find-segment-end.bat uVisionProjectGenerator.exe

uVision Project Generator application files.




4 Z-WAVE PLUS APPLICATIONS

The SDK includes Z-Wave Plus slave applications which are implemented according to the Z-Wave Plus specifications [4], [5], [6], [7], [8], [15] and [16]:

Door Lock with Key Pad

My Product

On/Off Switch

PIR Sensor

Power Strip

Wall controller

All applications are built on the Z-Wave Plus Framework [13]. For secure inclusion use a PC Based Controller v5 and SerialAPI dongle firmware delivered in SDK. Associations must be configured to examine all the features in the Z-Wave Plus embedded applications. Setting up associations is supported fully by the PC based Controller v5 and not older versions of the PC based Controller.

Please see the following table for an overview of the functionality covered by the applications.

Table 2. Functionality covered by the Z-Wave Plus applications.

Functionality Door Lock Key Pad

Power Strip

Sensor PIR

Switch On/Off

Wall Controller

Primary Func.

Always On Slave (AOS)

Listening Sleeping Slave (LSS)

Reporting Sleeping Slave (RSS)

Routing Slave

Enhanced 232 Slave

Battery

Endpoints

Security

S2 Access V

S2 Authenticated

S2 Unauthenticated

S2 SSA

S2 CSA

S0

Primary CCs

Door Lock

User Code

Binary Switch

Multilevel Switch

Notification

Central Scene

Firmware Update




In Devkit v6.7x.0x is the Framework updated to handle multicast addressing and a device can both be non-securely and securely added to a network. This feature has an impact on Framework API’s with respect to single-cast addressing and addressing a group for nodes. Association module is update to handle security level for each association and to deliver group addressing. Security S0 module in Transport-layer is moved to the Z-Wave protocol.

Because of development board ZDP03A pin layout is button S3 removed from all sample applications. Port 23 is used to both key S3 and SPI communication to external NVM. Button S5 is removed from WallController. Port 21 is used for S5 button and UART 0 communication.

4.1 Z-Wave Plus Framework

The purpose of the Z-Wave Plus Framework is to facilitate the implementation of robust Z-Wave Plus Compliant products. The framework provides a number of modules:

“Transport Layer” handles multicast and endpoint encapsulation.

“Application command class handlers” handle parsing and frame composition for theapplication.

“Utils” provides helper modules for association, AGI, I/O handling, battery monitoring andfirmware update “OTA”

The figure below outlines the Z-Wave Plus Framework modules.

Figure 1, Z-Wave Plus Application Framework.




4.1.1 Application Command Handlers

The Z-Wave Plus Framework simplifies command processing as parsing and transmission of Z-Wave frames is no longer handled directly by the application.

The folder “/ApplicationCommandHandlers/” provides modules for handle parsing and frame

composition for each individual Command Class. Each module provides a command class specific API for the application.

API Request Calls return a status code JOB_STATUS, indicating if the call was successful. The value JOB_STATUS_BUSY is returned if the transmit buffer was occupied or if the

ZW_SendData() call failed. The value JOB_STATUS_SUCCESS is returned if the frame was sent. A function callback pointer must be specified when issuing certain API calls.

Example of a request API call:

JOB_STATUS CmdClassBasicSetSend(…,VOID_CALLBACKFUNC(pCbFunc)(BYTE val));

The Application command handlers use the ZW_tx_mutex module to allocate a protected transmit buffer for composition of frames. Please read chapter 3.4.1.12, ZW_tx_mutex.c/h for protected transmit buffers.

The application must define proper mappings to relevant Application command handlers in the SDK

function Transport_ApplicationCommandHandler.

4.1.2 Transport Layer

Transport Layer encapsulates Z-Wave protocol API for handling secure and non-secure data traffic, and endpoint encapsulation. It also handles which command classes should send secure and non-secure frames dependent of security level. For Battery devices is timeout extended dependent for the in/out- going traffic. Transport layer module includes files:

ZW_TransportLayer.h

ZW_TransportEndpoint.c/h

ZW_TransportMulticast.c/h

ZW_TransportSecProtocol.c/h

ZW_classcmd_ex.h

Endpoint_lookup.h/c




4.1.3 Supported command classes

The following table lists all command classes and their versions currently supported by the Z-Wave+ Application Framework.

Name Version Name Version

Association Command Class 2 Multilevel Switch 4

Association Group Information (AGI) 1 Notification 8

Basic 2 Powerlevel 1

Battery 1 Security 1

Binary Switch 1 Security 2 1

Central Scene 3 Supervision 1

Device Reset Locally 1 Transport Service 2

Door Lock 2 User Code 1

Firmware Update Meta Data 4 Version 3

Manufacturer Specific 2 Wake Up 2

Multi Channel 4 Z-Wave Plus Info 2

Multi Channel Association 3

Only the “push mode” of Notification Command Class is tested.

4.1.4 General user interface

The following user interface applies to all the Z-Wave+ sample applications.

Button Action Description

RST Press Resets the firmware of an application (like losing power). All volatile memory will be cleared.

S1 Triple press Enter learn mode (sending node info frame) to add/remove the device.

Removing the device from a network will reset it.

Hold for 10 seconds Device is reset and a Device Reset Locally Notification is sent via Lifeline.




4.2 Door Lock Key Pad

The Door Lock with Key Pad application shows a lock implementation that has a built-in keypad. It will support user codes to open a door and thereby eliminate the need for traditional keys. Typically, it is possible to both lock and unlock the door remotely through the Z-Wave protocol.

The Door Lock with Key Pad application is based on:

Role Type: Listening Sleeping Slave (LSS)

Device Type: Door Lock Keypad

Supported security keys: S0 and S2 Access

Z-Wave protocol library: Enhanced 232 Slave

Supported module(s): ZDP03A configured with a ZDB5101 module

The full set of features only work when securely added to a network by a controller supporting security.

Graphical representation (Icon Types):




4.2.1 Announced Command Classes in NIF

The Door Lock with Keypad application implements a number of mandatory and optional command classes. The table below show announced command classes in NIF depending on state of device.

Table 3: NIF for Door Lock Key Pad

Command Class Not added Non-secure added Securely added

Non-secure CC Secure CC

ZWAVEPLUS_INFO Support Support Support

TRANSPORT_SERVICE Support Support Support

MANUFACTURER_SPECIFIC Support

DEVICE_RESET_LOCALLY Support

SECURITY Support Support Support

SECURITY_2 Support Support Support

BATTERY Support

POWERLEVEL Support

VERSION Support

DOOR_LOCK Support

USER_CODE Support

ASSOCIATION Support

MULTI_CHANNEL_ASSOCIATION Support

ASSOCIATION_GRP_INFO Support

SUPERVISION Support Support Support

FIRMWARE_UPDATE_MD Support

Not implemented Door lock functionality: o Operation modeo Door Lock conditiono Inside Door Handle Modeo Inside Door Handle Stateo Functionality handling Lock timeout.

4.2.2 Basic Command Class mapping

Basic Command Class is not mapped to any of the supported command classes.




4.2.3 Association groups

ID Name Node count

Description

1 Lifeline 5 Supports the following command classes:

Device Reset Locally: triggered upon reset.

Battery: triggered upon low battery.

Door Lock: triggered upon a change in door lock operation.

2 Doorlock Op

5 Nodes associated will receive a Door Lock Operation report upon Door Lock Operations.

4.2.4 Usage of buttons on ZDP03A

Table 4. Door Lock Key Pad buttons interface

Button Action Description

S2 Button up/down If the outside door handle state is active:

Button down sets the outside door handle mode active.

Button up sets the outside door handle mode inactive.

S4 Press Activates the keypad which in real is the Test Interface. If connected to the Test Interface, a terminal will show when and how to input the user code. The default user code is “0000”.

4.2.5 LED status on ZDP03A

Table 5. Door Lock Key Pad LED status interface

LED Description

D1 Latch, (Led on -> latch closed [bit 1])/ (Led off -> latch open[bit 0])

D2 Bolt, (Led on -> Bolt locked [bit 0])/ (Led off -> bolt unlocked [bit 1])

D3 User code input is active, (4 key presses) [not supported on ZM5202]

4.2.6 Firmware update and external NVM

When upgrading the old firmware on the Z-Wave module it is important to understand that old data (both protocol and application) in external NVM is unchanged. The new firmware must therefore be able to use the same data in external NVM to avoid re-installation of the device. New data fields must be appended to the existing ones to assure backward compatibility.

The table below show backward compatibility of data in external NVM when upgrading Door Lock Keypad from one SDK to another one.




Table 6. Door Lock Key Pad external NVM data backward compatibility

New Firmware

Old Firmware

SDK 6.51.00 SDK 6.51.01 SDK 6.51.02 SDK 6.51.03 SDK 6.51.05

Prot. Appl. Prot. Appl. Prot. Appl. Prot. Appl. Prot. Appl.

SDK 6.51.00 Yes Yes No No No No No No No No

SDK 6.51.01 - - Yes Yes Yes Yes Yes No Yes No

SDK 6.51.02 - - - - Yes Yes Yes No Yes No

SDK 6.51.03 - - - - - - Yes Yes Yes No

SDK 6.51.05 - - - - - - - - Yes Yes

For SDKs 6.51.00-02 application data definitions in external NVM was located in multiple files (association_plus.h and battery_plus.h). During linking the files could be shuffled around breaking backward compatibility wrt. application data layout in external NVM. This defect was registered as TO #5277.

SDK 6.51.03 fixed TO #5277 by moving all external NVM far variables to eeprom.h file in a common struct s_nvmApplDescriptor_. Appending new variables to struct ensured backward compatibility.

Array size in BYTE EEOFFSET_ASSOCIATION_START_far[ASSOCIATION_SIZE]; was changed in the common struct s_nvmApplDescriptor_.for SDK 6.51.05. This broke backward compatibility because EEOFFSET_ASSOCIATION_START_far was not located at the end of the struct.

4.2.7 Z-Wave Certification

The Door Lock with Key Pad passes certification. However, the key pad functionality is very simple due to lack of push buttons on the ZDP03A hardware.

4.2.8 Documentation related to devices from multiple manufacturers

This product can be operated in any Z-Wave network with other Z-Wave certified devices from other manufacturers. All non-battery operated nodes within the network will act as repeaters regardless of vendor to increase reliability of the network.




4.3 My Product Plus

The My Product Plus contains the minimum framework to begin developing a Z-Wave Plus application. This application supports a broad range of libraries and boards. Check first if one of the product specific applications suite your needs better because it is often easier to modify the existing code than building one from scratch based on My Product.

The My Product Plus application is based on:

Role Type: -

Device Type: -

Supported security keys: S0 and S2_UNAUTHENTICATION

Library: Enhanced 232 slave


This device supports no other command classes than the mandatory ones. The table below show announced command classes in NIF depending on state of device.

Table 7: NIF for My Product Plus





MANUFACTURER_SPECIFIC Support Support Support

DEVICE_RESET_LOCALLY Support Support Support



POWERLEVEL Support Support Support

VERSION Support Support Support

ASSOCIATION Support Support Support

MULTI_CHANNEL_ASSOCIATION Support Support Support

ASSOCIATION_GRP_INFO Support Support Support

SUPERVISION Support Support Support

FIRMWARE_UPDATE_MD Support Support Support




4.3.2 Basic Command Class mapping

Basic Command Class is not mapped to any of the supported command classes.

4.3.3 Association groups

ID Name Node count Description

1 Lifeline 5 Supports the following command classes:

Device Reset Locally: triggered upon reset.

4.3.4 MyProduct Files

The ProductPlus\MyProductPlus directory contains source code on a Z-Wave module. The application uses also a number of utility functions described in section 4.1.

MK.BAT

Make bat file for building the application in question. To only build applications using EU frequency enter: MK “FREQUENCY=EU” in command prompt.

Makefile

This is the Makefile for the application in question defining the targets built.

config_app.h

This header file contains defines for application version.

eeprom.c / eeprom.h

The eeprom source/header files contains the NVM variable definitions.

MyProduct.h / MyProduct.c

This file contains the source code for the MYProduct. The common API functions such as ApplicationInitHW, ApplicationInitSW, ApplicationNodeInformation, ApplicationPoll, ApplicationSlaveUpdate and ApplicationCommandHandler are defined here.

MyProduct_ZW050x_....Uv2

uVision4 *.Uv2 project files created by makefile system using uVisionProjectGenerator software.




4.3.5 Firmware update and external NVM

When upgrading the old firmware on the Z-Wave module it is important to understand that old data (both protocol and application) in external NVM is unchanged. The new firmware must therefore be able to use the same data in external NVM to avoid re-installation of the device. New data fields must be appended to the existing ones to assure backward compatibility.

The table below show backward compatibility of data in external NVM when upgrading MyProduct application from one SDK to another one.

Table 8. My Product Plus external NVM data backward compatibility

New Firmware

Old Firmware

SDK 6.51.00 SDK 6.51.01 SDK 6.51.02 SDK 6.51.03 SDK 6.51.05

Prot. Appl. Prot. Appl. Prot. Appl. Prot. Appl. Prot. Appl.

SDK 6.51.00 Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes

SDK 6.51.01 - - Yes Yes Yes Yes Yes Yes Yes Yes

SDK 6.51.02 - - - - Yes Yes Yes Yes Yes Yes

SDK 6.51.03 - - - - - - Yes Yes Yes Yes

SDK 6.51.05 - - - - - - - - Yes Yes

For SDKs 6.51.00-02 application data definitions in external NVM was located in multiple files (association_plus.h and battery_plus.h). During linking the files could be shuffled around breaking backward compatibility wrt. application data layout in external NVM. This defect was registered as TO #5277.

SDK 6.51.03 fixed TO #5277 by moving all external NVM far variables to eeprom.h file in a common struct s_nvmApplDescriptor_. Appending new variables to struct ensured backward compatibility.

4.3.6 Z-Wave Certification

The My Product cannot pass certification because it is not a real product at this stage.

4.3.7 Documentation related to devices from multiple manufacturers

This product can be operated in any Z-Wave network with other Z-Wave certified devices from other manufacturers. All non-battery operated nodes within the network will act as repeaters regardless of vendor to increase reliability of the network.




4.4 Switch On/Off

The On/Off Power Switch application shows a switch implementation to turn on any device that is connected to power. Examples include lights, appliances etc.

The On/Off Switch application is based on:

Role Type: Always On Slave (AOS)

Device Type: On/Off Power switch

Supported security keys: S0 and S2 Unauthenticated

Z-Wave protocol library: Enhanced 232 Slave

Supported module(s): ZDP03A configured with either a ZDB5101 or ZDB5202 module

Graphical representation (Icon Types):





The On/Off Switch application implements a number of mandatory and optional command classes. The table below show announced command classes in NIF depending on state of device.

Table 9: NIF for Switch On/Off





MANUFACTURER_SPECIFIC Support Support Support

DEVICE_RESET_LOCALLY Support Support Support



POWERLEVEL Support Support Support

VERSION Support Support Support

ASSOCIATION Support Support Support

MULTI_CHANNEL_ASSOCIATION Support Support Support

ASSOCIATION_GRP_INFO Support Support Support

SUPERVISION S

Date post:	05-Feb-2021
Category:	Documents
Upload:	others
View:	0 times
Download:	0 times

Instruction - Silicon Labs€¦ · 1 20160209 TRO Section 4.5.3 Describe Basic Set values 0x00 and...

Documents