Silicon Labs Z-Wave Plus Application Framework v6.71.0x Reference guide

Brand: Silicon Labs

Model: Z-Wave Plus Application Framework v6.71.0x

Type: Reference guide

Instruction

Z-Wave Plus Application Framework v6.71.0x

Document No.:

INS13427

Version:

Description:

Written By:

JFR;COLSEN;SSE;BBR

Date:

Reviewed By:

NOBRIOT;LTHOMSEN;CST

Restrictions:

Public

Approved by:

This document is the property of Silicon Labs. The data contained herein, in whole

or in part, may not be duplicated, used or disclosed outside the recipient for any

purpose. This restriction does not limit the recipient's right to use information

contained in the data if it is obtained from another source without restriction.

INS13427-6 Z-Wave Plus Application Framework v6.71.0x 2018-03-02

silabs.com | Building a more connected world.

Page ii of iv

REVISION RECORD

Doc.

Rev

Date

Pages affected

Brief description of changes

20151104

TRO

COLSEN

JFR

TRASMUSSEN

ALL

Based on SDS13088 – Z-Wave Plus Application Framework v6.60.0x

Initial revision.

20160630

COLSEN

Section 7.9

Added section about Test Interface and supported commands.

20160703

TRO

Section 5.4.2

Added configuration of endpoints

20160811

TRO

Section 5.2.5

Updated security description by adding authentication description

20160811

TRO

Appendix D

Added porting guide

20170112

TRO

Section 7.4

API updated

20170112

TRO

Appendix B

Update function description

20170119

TRO

Section 6.3

Update section

20170615

TRO

Section 5.2.5

Update protocol function calls for security flags.

20170719

JFR

Appendix E

Slave based application migration using 128KB external NVM

20171206

COLSEN

All pages

Section 8.1

Updated references and removed “What’s new” section.

Updated porting guide.

20180302

BBR

All

Added Silicon Labs template

INS13427-6 Z-Wave Plus Application Framework v6.71.0x 2018-03-02

silabs.com | Building a more connected world.

Page iii of iv

Table of Contents

1 DEFINITIONS, ACRONYMS AND ABBREVIATIONS ......................................................................... 1

2 INTRODUCTION ................................................................................................................................... 1

3 PURPOSE ............................................................................................................................................. 1

4 ARCHITECTURE .................................................................................................................................. 2

5 HOW TO DEVELOP A Z-WAVE PLUS APPLICATION ...................................................................... 3

5.1 Create application folder and setup make environment ..................................................................... 3

5.2 Setting up config_app.h ...................................................................................................................... 3

5.2.1 Generic type, specific type and device options ........................................................................ 3

5.2.2 Role Type, node type, icon type and user icon type (Z-Wave Plus Info CC) .......................... 3

5.2.3 Manufacturer Specific CC / Firmware update .......................................................................... 4

5.2.4 Association Group Information (AGI) ....................................................................................... 4

5.2.5 Security .................................................................................................................................... 5

5.2.5.1 Authentication type ........................................................................................................... 5

5.2.5.2 Security keys .................................................................................................................... 6

5.2.6 Firmware upgrade .................................................................................................................... 6

5.3 Setting up EEPROM files ................................................................................................................... 6

5.4 Source file ........................................................................................................................................... 6

5.4.1 Command class lists configuration .......................................................................................... 7

5.4.2 Endpoint configuration ............................................................................................................. 7

6 COMMAND CLASSES ......................................................................................................................... 8

6.1 General interfacing to CCs ................................................................................................................. 8

6.1.1 Unsolicited transmission .......................................................................................................... 8

6.1.2 Respond to received Command .............................................................................................. 8

6.2 Battery CC ........................................................................................................................................10

6.3 Notification CC version 8 ..................................................................................................................10

6.4 Supervision CC.................................................................................................................................11

6.4.1 Configuration scenarios .........................................................................................................11

6.4.1.1 Default configuration ......................................................................................................11

6.4.1.2 Handle more Supervision Reports .................................................................................12

6.4.1.3 Support Supervision Reports .........................................................................................13

6.5 Implementing a CC ...........................................................................................................................15

7 UTILITIES ............................................................................................................................................16

7.1 AGI module .......................................................................................................................................16

7.1.1 Configuration of AGI ...............................................................................................................16

7.1.1.1 Example 1: how to setup AGI for a Wall Controller. .......................................................17

7.1.1.2 Example 2: how to extend the Wall controller with 2 buttons .........................................18

7.1.2 Using AGI ...............................................................................................................................19

7.2 Association module ..........................................................................................................................19

7.2.1 Setting up the NVM ................................................................................................................20

7.2.2 Initialization.............................................................................................................................21

7.2.2.1 Example 3: How to use group mapping. ........................................................................21

7.3 Battery Plus ......................................................................................................................................23

7.3.1 Initialization.............................................................................................................................23

7.4 Interfacing Firmware Update module “ota_util” ................................................................................23

7.5 GPIO Driver ......................................................................................................................................24

7.6 Key Driver .........................................................................................................................................24

7.7 Event Scheduler ...............................................................................................................................24

7.7.1 Simple event job handling ......................................................................................................25

7.7.2 Multiple event jobs handling ...................................................................................................26

INS13427-6 Z-Wave Plus Application Framework v6.71.0x 2018-03-02

silabs.com | Building a more connected world.

Page iv of iv

7.7.3 Coding example .....................................................................................................................27

7.8 Task pool ..........................................................................................................................................29

7.9 Test Interface....................................................................................................................................30

7.9.1 UART settings ........................................................................................................................30

7.9.2 Test Interface in the sample applications ...............................................................................30

7.9.3 Defined commands for the default ZAF channel ...................................................................31

8 PORTING GUIDE ................................................................................................................................33

8.1 Changes to 6.71.03 ..........................................................................................................................33

8.2 Porting From SDK 6.61.0x To SDK 6.71.0X ....................................................................................33

8.2.1 Security configuration in Config_app.h ..................................................................................33

8.2.2 General changes in command classes ..................................................................................33

8.2.3 Utilities modules .....................................................................................................................34

APPENDIX A FOLDER STRUCTURE ....................................................................................................36

APPENDIX B IMPLEMENTING A NEW COMMAND CLASS ...............................................................37

APPENDIX C SCENARIO RECEIVING A GET COMMAND .................................................................41

APPENDIX D DATA MIGRATION ..........................................................................................................42

APPENDIX E SLAVE MIGRATION USING 128KB EXTERNAL NVM ..................................................45

REFERENCES ...........................................................................................................................................46

Table of Figures

Figure 1: The Z-Wave Plus Application Framework architecture ................................................................ 2

Figure 2, SwitchOnOff.c interface to BinarySwitch CC for incoming commands. ....................................... 9

Figure 3, Command Class Version Get implementation in SwitchOnOff.c. ................................................ 9

Figure 4, AGI behavior diagram ................................................................................................................ 16

Figure 5, Wall controller that sends Command Class Scene and Device Reset Locally over association

group 1 (lifeline) and Command Class Basic over association group 2. ........................................... 17

Figure 6, extended with two endpoints and remove root group 2. ............................................................ 18

Figure 7, Association behavior diagram .................................................................................................... 20

Figure 8, Wall Controller with Root Device group mapping....................................................................... 22

Figure 9, State event machine handling an unsolicited job ....................................................................... 25

Figure 10, Using the FIFO queue in an application ................................................................................... 26

Figure 11, Module source code for a response job. .................................................................................. 38

Figure 12, Unsolicited event function declaration in the module header file. ............................................ 39

Figure 13, Unsolicited event function implementation in the module c-file. .............................................. 40

Figure 14, Sequence diagram of how Z-Wave Plus Framework handle an incoming Get command....... 41

Figure 15, NVM data migration from SDK 6.5x/6.6x with security to SDK 6.7x based application ........... 42

Figure 16,NVM data migration from SDK 6.5x/6.6x without security to SDK 6.7x based application ....... 43

Figure 17, App migration process. ............................................................................................................. 45

INS13427-6 Z-Wave Plus Application Framework v6.71.0x 2018-03-02

silabs.com | Building a more connected world.

Page 1 of 46

1 DEFINITIONS, ACRONYMS AND ABBREVIATIONS

Abbreviation

Explanation

Command Class

NIF

Node Information Frame

OTA

Over The Air

Security 0 Command Class

Security 2 Command Class

SDK

Software Development Kit

ZAF

Z-Wave Plus Application Framework

2 INTRODUCTION

This document describes the Z-Wave Plus Application Framework (ZAF) distributed on SDK 6.71.0x.

3 PURPOSE

The purpose of the ZAF is to facilitate the implementation of robust Z-Wave Plus compliant products.

The ZAF is the foundation for creating Z-Wave Plus compliant applications.

INS13427-6 Z-Wave Plus Application Framework v6.71.0x 2018-03-02

silabs.com | Building a more connected world.

Page 2 of 46

4 ARCHITECTURE

Figure 1 shows the architecture of the ZAF and its relation to the hardware and the Z-Wave protocol.

Figure 1: The Z-Wave Plus Application Framework architecture

The ZAF consists of three blocks:

 Transport Layer:

This layer handles all communication with the protocol, which includes singlecast, multicast, Multi

Channel encapsulation, delivery of bundled commands, etc.

 Command Class Handlers:

These handlers parse and compose Command Class frames.

 Utilities:

Utilities are composed of different modules. Among them, there are modules for handling I/O

communication specific for the ZDP03A board bundled with the SDK. Other modules are battery

monitoring and firmware updating, etc.

The framework implements an event-driven application design.

The framework provides built-in features for developing simpler applications. Transmit buffers are mutex-

protected to ensure that the application has only one transmit request job (unsolicited event) at a time.

The transmit buffer is released only when the transmit request job is completed or has timed out. The

Framework can handle one request job and one response job at the same time.

Hardware & Z-Wave protocol

Application

Z-Wave Framework

Transport Layer

Command Class Handlers

Utilities

INS13427-6 Z-Wave Plus Application Framework v6.71.0x 2018-03-02

silabs.com | Building a more connected world.

Page 3 of 46

5 HOW TO DEVELOP A Z-WAVE PLUS APPLICATION

The Z-Wave Plus applications basic functionality is defined by a Device Type and Role Type , which are

explained further in [1] and [2]. It is important to determine the right combination of Device Type and Role

Type for your Z-Wave Plus application.

When Device and Role Type are determined, the application development can start.

5.1 Create application folder and setup make environment

Follow these steps in order to setup a working directory for your application.

1. To get a general understanding of the build environment, please refer to [5].

2. Create a copy of the Z-Wave Plus application that fits your product best. If none of them does,

MyProductPlus is a generic application that can be included and excluded from a Z-Wave

network. It implements all the basic functionalities that are mandatory for a Z-Wave Plus

application.

3. Rename the copied folder to a suitable name for your application.

4. Enter the folder and rename MyProduct.c to a suitable name for your application.

5. Open Makefile and locate MyProduct.obj. Change MyProduct to match the name of your c file –

without file extension. For example, the result could be MyApplication.obj.

6. In Makefile, also change APP_NAME to a suitable name. E.g. MyApplication.

7. Build the application in order to verify that the changes did not break anything. It is also possible

to download the application to the chip to check that the application runs without any problems.

5.2 Setting up config_app.h

config_app.h contains the information required to recognize an application as a certain Z-Wave device.

The following sections cover the different areas.

5.2.1 Generic type, specific type and device options

A Z-Wave Plus device must specify a Generic Device Class and a Specific Device Class by using the

following two definitions:

 GENERIC_TYPE

 SPECIFIC_TYPE

Refer to [10] and [1] to select appropriate Generic and Specific Device Classes for your product. Generic

and specific device class values are defined in ZW_classcmd.h.

DEVICE_OPTIONS_MASK is a bitmask used to specify a set of device options. See the ZW_basic_api.h

file for details.

5.2.2 Role Type, node type, icon type and user icon type (Z-Wave Plus Info CC)

The Role Type, node type, icon type and user icon type are all values used by the Z-Wave Plus CC.

They are set using the following definitions:

 APP_ROLE_TYPE

 APP_NODE_TYPE

INS13427-6 Z-Wave Plus Application Framework v6.71.0x 2018-03-02

silabs.com | Building a more connected world.

Page 4 of 46

 APP_ICON_TYPE

 APP_USER_ICON_TYPE

For further information about the Icon Types used in the Z-Wave Plus Info CC, refer to [6]. Please

contact the Z-Wave Alliance to acquire new Icon Types.

5.2.3 Manufacturer Specific CC / Firmware update

The Manufacturer specific CC requires some product specific values to be defined. Refer to the

Manufacturer Specific Command Class in [12] for more information. The ZAF uses the following macros

for these values:

 APP_MANUFACTURER_ID

 APP_PRODUCT_TYPE_ID

 APP_PRODUCT_ID

 APP_DEVICE_ID_TYPE

 APP_DEVICE_ID_FORMAT

The Firmware Update Command Class uses this definition:

 APP_FIRMWARE_ID: The firmware ID consists of the product type ID and the product ID.

The manufacturer and product ID’s are used to identify a Z-Wave product from a manufacturer point of

view. Other applications can also use this information to show a company logo, type of product, user

guide, etc. on the user interface. This information is exchanged via the Manufacturer Specific CC and

currently allocated manufacturer IDs are listed in the ZW_classcmd.h file. See [12] for more information

about these two Command Classes.

5.2.4 Association Group Information (AGI)

Refer to [12] and [8] for a general understanding of AGI and Associations.

In an application, the AGI must be configured in config_app.h.

For Z-Wave Plus products, the Lifeline group is mandatory. It can be defined using the following

declaration:

#define AGITABLE_LIFELINE_GROUP \

{<command class X>, <command A>}, \

{<command class Y>, <command B>}, \

{<command class Z>, <command C>}

Refer to [1] to find out what events and Command Classes have to be used in the Lifeline group.

Definitions for Command Classes and Commands are found in ZW_classcmd.h.

Other groups (apart from Lifeline) must be defined using the following format if the application is not

implementing Multi Channel endpoints:

#define AGITABLE_ROOTDEVICE_GROUPS \

{<profile 1 MSB>, <profile 1 LSB>, {<command class X, command A}, "<group 2 name>"}\

{<profile 2 MSB>, <profile 2 LSB>, {<command class Y, command A}, "<group 3 name>"}\

If the application is implementing Multi Channel endpoints, the AGI definition must be filled out using the

endpoint groups.

INS13427-6 Z-Wave Plus Application Framework v6.71.0x 2018-03-02

silabs.com | Building a more connected world.

Page 5 of 46

#define AGITABLE_ROOTDEVICE_GROUPS \

AGITABLE_ENDPOINT_1_GROUPS, \

AGITABLE_ENDPOINT_2_GROUPS, \

AGITABLE_ENDPOINT_3_GROUPS, \

AGITABLE_ENDPOINT_4_GROUPS

AGITABLE_ENDPOINT_X_GROUPS represents the non-lifeline groups for endpoint X. Each of the

endpoint groups are defined as the Root Device groups defined by

AGITABLE_ROOTDEVICE_GROUPS, but with a matching definition name, other profiles, Command

Classes, etc.

#define AGITABLE_ENDPOINT_1_GROUPS \

{<profile 1 MSB>, <profile 1 LSB>, {<command class X>, <command A>}, "group 2 name"}, \

{<profile 2 MSB>, <profile 2 LSB>, {<command class Y>, <command A>}, "group 3 name"}

When the product implements Multi Channel endpoints, it is recommended to map the groups of an

endpoint to the root association groups. The mapping provides backwards compatibility because devices

that do not support Multi Channel must be able to ask the Root Device which groups are supported. Root

group mapping defines groups in the Root Device mapping to endpoints’ groups. An example is given in

Table 1.

Table 1, Root Device and Endpoint Group mapping

Root Device group

Endpoint ID

Endpoint group ID

Root Device group 2

Endpoint 1

Endpoint 1 group 2

Root Device group 3

Endpoint 2

Endpoint 2 group 2

The following shows how root group mapping is configured in config_app.h. The details of the root group

mapping setup depend on the application.

#define ASSOCIATION_ROOT_GROUP_MAPPING_CONFIG \

{<ROOT DEVICE GROUP 2>, <ENDPOINT ID 1>, <ENDPOINT GROUP 2>}, \

{<ROOT DEVICE GROUP 3>, <ENDPOINT ID 2>, <ENDPOINT GROUP 2>}

Refer to the config_app.h file in the Wall Controller sample application for a group mapping example. The

SensorPIR and DoorLockKeyPad applications also show how AGI can be set up.

Group definitions are used to initialize the AGI in the main source file of the application.

5.2.5 Security

Security authentication and security levels are configured using a couple of defintions and functions. See

[13] for more information about security.

5.2.5.1 Authentication type

An application can be configured for Server Side Authentication (SSA) or Client Side Authentication

(CSA). For CSA, the user must input a 10-digit code via an input interface on the device, like a keyboard.

For the applications in the SDK, this is done using the test interface. Both options are defined in

ZW_security_api.h. See the following example.

INS13427-6 Z-Wave Plus Application Framework v6.71.0x 2018-03-02

silabs.com | Building a more connected world.

Page 6 of 46

#define REQUESTED_SECURITY_AUTHENTICATION SECURITY_AUTHENTICATION_SSA

5.2.5.2 Security keys

An application can request multiple security keys. The keys must be specified using

REQUESTED_SECURITY_KEYS. See the following example.

#define REQUESTED_SECURITY_KEYS (SECURITY_KEY_S0_BIT | SECURITY_KEY_S2_UNAUTHENTICATED_BIT)

The above definition is used in the external function ApplicationSecureKeysRequested() that must be

implemented by the application. It is declared in ZW_security_api.h.

5.2.6 Firmware upgrade

The definition FIRMWARE_UPGRADABLE is used by the Firmware Upgrade CC. It determines whether

your application is upgradable or not. See description of the Firmware Meta Data Report Command in

[12].

5.3 Setting up EEPROM files

The EEPROM is set up in two files: eeprom.c and eeprom.h. Each file must contain a list of the

application’s variables. Some of these variables belong to the ZAF.

For a new application, the variables can be initialized in the following manner:

BYTE far variable_name = 0xAA;

With performing a firmware update, only variables that were not in the previous firmware are initialized.

Existing variables added in earlier versions of the firmware do not get initialized again.

When developing a newer version of the firmware where new variables are needed, it is very important

that these variables are appended to the list. This is done in order to keep the device included in the Z-

Wave network and to preserve all associations’ data. In other words, if the order of the variables is

changed in a newer version, the firmware update will corrupt the EEPROM data and the device will no

longer be included in the network.

5.4 Source file

The application must implement two functions for initialization: ApplicationInitHW(..) and

ApplicationInitSW(..). The functions are called by the protocol in that order. For details about their

arguments and return values, see the ZW_basis_api.h file. All initialization for the application should be

done in these two functions:

NvmInit(..) must be called at the beginning of ApplicationInitSW(..).

Transport_OnApplicationInitSW(..) must be called at the end of ApplicationInitSW(..).

INS13427-6 Z-Wave Plus Application Framework v6.71.0x 2018-03-02

silabs.com | Building a more connected world.

Page 7 of 46

5.4.1 Command class lists configuration

The application uses three CC lists to send out the node information frame (NIF) depending on the

inclusion status. These three lists define the NIF for:

- Not included

- Non-securely included

- Securely included

The following CC list is used when the node is not included or non-securely included.

static code BYTE cmdClassListNonSecureNotIncluded[]

The following CC list is used when the node is securely included. It represents the CCs that are

supported non-securely even though the device has been securely included.

static code BYTE cmdClassListNonSecureIncludedSecure[]

The following CC list is used when node is securely included. It contains the CCs that are supported

securely only. This CC list is advertised through the Security CC, Security Commands Supported Report

Command.

static BYTE cmdClassListSecure[]

5.4.2 Endpoint configuration

If your device must implement endpoints, the AGI and association group mapping must be set up in the

config_app.h file. After configuring each endpoint in AGI (see section 5.2.4 )

AssociationInitEndpointSupport() must be called instead of AssociationInit() for association group

mapping (see chapter 7.2.2 for the different initializations).

Finally, the transport layer needs to be initialized for endpoints by calling the

Transport_AddEndpointSupport() function. This function sets up endpoints’ functionalities and Command

Class lists. Please read [13] for information about individual and aggregated endpoints.

void Transport_AddEndpointSupport(

EP_FUNCTIONALITY_DATA* pFunctionality,

EP_NIF* pList, BYTE sizeList);

INS13427-6 Z-Wave Plus Application Framework v6.71.0x 2018-03-02

silabs.com | Building a more connected world.

Page 8 of 46

6 COMMAND CLASSES

An essential feature of the ZAF is the communication through Command Classes. For this purpose, each

of the Command Classes has a C module where incoming commands are handled and outgoing

commands are transmitted.

6.1 General interfacing to CCs

The application will typically use CCs in one of the following ways:

- Send unsolicited Commands

- Respond to received Commands.

6.1.1 Unsolicited transmission

See the following example of a CC API definition. Although none of the CCs complies with that naming

scheme yet, it is the plan that more and more CCs will comply for every future version of the ZAF.

JOB_STATUS ZAF_CC_Basic_Set_tx(

AGI_PROFILE* pProfile,

BYTE sourceEndpoint,

BYTE bValue,

VOID_CALLBACKFUNC(pCallback)(TRANSMISSION_RESULT * pTransmissionResult));

A controlling device, e.g. a wall switch, may want to send a Basic Set command. It is the purpose of the

function given in the above example. Three of the four arguments are generic arguments found in all CC

APIs: pProfile, sourceEndpoint and pCallback. Those arguments are detailed below. The argument

bValue is specific for the Basic Set Command. To find out information about Basic Set or other

application CCs and their commands, see [11].

 pProfile

The pProfile points to an AGI profile. The AGI profile used must be configured in config_app.h.

 sourceEndpoint

If the application is implementing endpoints, the source endpoint must be set to ENDPOINT_X

where X is the number of the endpoint, e.g. ENDPOINT_1. If the application does not have

endpoints, the source endpoint must be set to ENDPOINT_ROOT. The enumeration for

ENDPOINT_ROOT and ENDPOINT_X can be found in the ZW_TransportEndpoint.h file.

 pCallback

This argument is a pointer to a callback function with one argument of the type

TRANSMISSION_RESULT. The definition of this type can be found in the CommandClass.h file.

The given callback function will be called once for each node found in the Associations. When

transmission for the last node is done, the isFinished value will be set to

TRANSMISSION_RESULT_FINISHED.

6.1.2 Respond to received Command

Each CC implementation has a handleCommandClass…() function that extracts the received frame for a

given Command Class. This function needs to be added into the application’s

Transport_ApplicationCommandHandler() function switch-case block. Normally, the frame is carrying a

“Set” or “Get” Command that results in a function call for reading or writing data. It is up to the application

to implement these functions provided as extern functions in the CC header file.

INS13427-6 Z-Wave Plus Application Framework v6.71.0x 2018-03-02

silabs.com | Building a more connected world.

Page 9 of 46

An example is shown in Figure 2 where the SwitchOnOff application interfaces to Binary Switch CC.

Figure 2, SwitchOnOff.c interface to BinarySwitch CC for incoming commands.

Version CC has a function called handleCommandClassVersionAppl() into the application to read a

specific CC version. It is the application's responsibility to implement this function and make the function

able to return the version number for any CC used in the application.

Figure 3, Command Class Version Get implementation in SwitchOnOff.c.

INS13427-6 Z-Wave Plus Application Framework v6.71.0x 2018-03-02

silabs.com | Building a more connected world.

Page 10 of 46

6.2 Battery CC

Battery CC is implemented in two C modules:

 CommandClassBattery

 battery_monitor

Together, these modules can measure and report the battery level of a device. The API consists of the

following functions. For information about what they do, arguments and return values, please refer to the

source header files for each of the modules.

 InitBatteryMonitor()

 BatterySensorRead()

 BatteryMonitorState()

 TimeToSendBattReport()

 SendBattReport()

 ActivateBattNotificationTrigger()

InitBatteryMonitor() must be called as the first function of the above six to initialize the Battery CC.

6.3 Notification CC version 8

Notification CC is typically used in sensor applications because it supports many different

notification/sensor types. For general information related to Notification CC, please see [11].

Historically, this CC supported both push and pull mode and the ZAF implementation has tried to cover

both modes. However, push and pull mode have been separated in version 8 of the CC and the ZAF now

supports and tests only push mode because supporting both modes at the same time will conflict in

certification.

Notification CC is implemented by two C modules:

 CommandClassNotification

 notification

The Notification CC API consists of the following functions. For information about what they do,

arguments and return values, please refer to the source header files of notification.h.

 InitNofication()

 AddNotification()

 DefaultNotificationStatus()

 NotificationEventTrigger()

 UnsolicitedNotificationAction()

The typical call order is showed below:

1. Initialize the Notification CC by calling InitNofication().

2. Set the notification status for all available notifications (limited by the definition

MAX_NOTIFICATIONS in config_app.h) by calling DefaultNotificationStatus().

3. Call AddNotification() a number of times depending on how many different notification types the

application implements.

4. Trigger an event by calling NotificationEventTrigger() and transmit it by calling

UnsolicitedNotificationAction().

INS13427-6 Z-Wave Plus Application Framework v6.71.0x 2018-03-02

silabs.com | Building a more connected world.

Page 11 of 46

5. If a state was triggered contrary to an event, the state can be cancelled by calling

NotificationEventTrigger() with cancelling arguments and then transmitting the cancellation by

calling UnsolicitedNotificationAction().

6.4 Supervision CC

Please refer to [13] for the definition of the Supervision Command Class.

CC Supervision is built into the ZAF and handles Supervision communication on S2 encapsulated

frames. Supervision is only supported for Set and Report commands.

The default is that CC Supervision supports only one Supervision Report per Supervision Get command.

In Supervision Get command is 'more status updates' field set to

CC_SUPERVISION_STATUS_UPDATES_NOT_SUPPORTED. The application does not need to

initialize CC Supervision if the default configuration fulfills application demands (see 0).

Initialization for CC Supervision:

void

CommandClassSupervisionInit(

cc_supervision_status_updates_t status_updates,

VOID_CALLBACKFUNC(pGetReceivedHandler)(SUPERVISION_GET_RECEIVED_HANDLER_ARGS * pArgs),

VOID_CALLBACKFUNC(pReportReceivedHandler)(cc_supervision_status_t status, BYTE

duration));

6.4.1 Configuration scenarios

6.4.1.1 Default configuration

The application does not handle more than one Supervision report. The device receives a Supervision

Get and replies with a Supervision Report containing CC_SUPERVISION_STATUS_SUCCESS. There’s

no need to call CommandClassSupervisionInit() for initialization.

INS13427-6 Z-Wave Plus Application Framework v6.71.0x 2018-03-02

silabs.com | Building a more connected world.

Page 12 of 46

6.4.1.2 Handle more Supervision Reports

The application has the possibility to display that a destination node is processing the transmitted

command. An example is that a Wall Controller with a display shows a device is working

(CC_SUPERVISION_STATUS_WORKING) until a given command has been performed

(CC_SUPERVISION_STATUS_SUCCESS).

void ApplicationInitSW(..)

{

CommandClassSupervisionInit(

CC_SUPERVISION_STATUS_UPDATES_NOT_SUPPORTED,

NULL,

ZCB_CommandClassSupervisionReportReceivedHandler);

}

void ZCB_CommandClassSupervisionReportReceivedHandler(cc_supervision_status_t status, BYTE duration)

{

}

INS13427-6 Z-Wave Plus Application Framework v6.71.0x 2018-03-02

silabs.com | Building a more connected world.

Page 13 of 46

6.4.1.3 Support Supervision Reports

The application has the possibility to send several Supervision Reports to report on an ongoing activity.

An example is that a Door Lock Key Pad reports that a Door Lock Operation is started and a report when

it is finished.

INS13427-6 Z-Wave Plus Application Framework v6.71.0x 2018-03-02

silabs.com | Building a more connected world.

Page 14 of 46

void ApplicationInitSW(..)

{

CommandClassSupervisionInit(

CC_SUPERVISION_STATUS_UPDATES_NOT_SUPPORTED,

ZCB_CommandClassSupervisionGetReceived,

NULL);

}

void ZCB_CommandClassSupervisionGetReceived(SUPERVISION_GET_RECEIVED_HANDLER_ARGS * pArgs)

{

}

INS13427-6 Z-Wave Plus Application Framework v6.71.0x 2018-03-02

silabs.com | Building a more connected world.

Page 15 of 46

6.5 Implementing a CC

All mandatory CCs are implemented by Silicon Labs. But many other CCs are not implemented in the

ZAF yet. Hence, in some cases the required CC must be developed for the application. For details, see

Appendix B.

INS13427-6 Z-Wave Plus Application Framework v6.71.0x 2018-03-02

silabs.com | Building a more connected world.

Page 16 of 46

7 UTILITIES

Some of the common used functionalities are handled by utilities, which can be adapted by the developer

for a particular application.

7.1 AGI module

The AGI module works with the Association Plus module in order to provide a general API for handling

the setup and use of associations between multiple Z-Wave nodes. The AGI module interfaces to

“CommandClassAssociationGroupInfo.h” for external access to AGI tables.

Figure 4, AGI behavior diagram

The AGI module contains a configuration part and an API to extract destination nodes for a specific

association group.

7.1.1 Configuration of AGI

The AGI module has a constructer called AGI_Init(), which needs to be called before the AGI groups are

configured. The constructer call resets the module parameters.

void AGI_Init(void);

The configuration of the group 1 (Lifeline) is done when calling the AGI_LifeLineGroupSetup

function to setup the profile, Command Class groups and group name. This function is also used to

configure each endpoint group 1 (endpoint Lifeline). For the Root Device configuration, the endpoint

parameter must be set to ENDPOINT_ROOT (0):

void AGI_LifeLineGroupSetup(

CMD_CLASS_GRP* pCmdGrpList,

BYTE listSize,

const BYTE* pGrpName,

BYTE endpoint);

Page is loading ...

Silicon Labs Z-Wave Plus Application Framework v6.71.0x Reference guide

Silicon Labs Z-Wave Plus Application Framework v6.71.0x Reference guide

Silicon Labs Z-Wave Plus Application Framework v6.71.0x Reference guide

Related papers

Other documents