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

Brand: Silicon Labs

Model: Z-Wave Plus Application Framework v6.8x.0x

Type: Reference guide

Instruction

Z-Wave Plus Application Framework v6.8x.0x

Document No.:

INS13953

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.

INS13953-4 Z-Wave Plus Application Framework v6.8x.0x 2018-04-05

silabs.com | Building a more connected world.

Page ii of v

REVISION RECORD

Doc.

Rev

Date

Pages

affected

Brief description of changes

20170615

TRO

COLSEN

JFR

TRASMUSSEN

ALL

Based on INS13427– Z-Wave Plus Application Framework v6.71.0x

Initial revision.

20170621

TRO

5.2.5

Update protocol function calls for security flags.

20170719

JFR

Appendix D

Slave based application migration using 128KB external NVM

20170720

TRO

5.2.7

Smart Start

20170925

COLSEN

8.1

Porting guide

20171206

COLSEN

ALL

Updated references.

20171206

COLSEN

8.1

Updated porting guide.

20180115

COLSEN

Restructured and edited some of the document into the CC section.

20180405

BBR

All

Added Silicon Labs template

INS13953-4 Z-Wave Plus Application Framework v6.8x.0x 2018-04-05

silabs.com | Building a more connected world.

Page iii of v

Table of Contents

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

2 INTRODUCTION ................................................................................................................................... 6

3 PURPOSE ............................................................................................................................................. 6

4 ARCHITECTURE .................................................................................................................................. 7

4.1 Smart Start ......................................................................................................................................... 8

4.2 Power Management .........................................................................................................................10

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

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

5.2 Setting up config_app.h ....................................................................................................................11

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

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

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

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

5.2.5 Security ..................................................................................................................................13

5.2.6 Firmware upgrade ..................................................................................................................14

5.2.7 Smart Start Included Node Information Frame (INIF) configuration ......................................14

5.3 Setting up EEPROM files .................................................................................................................14

5.4 Source file .........................................................................................................................................15

5.4.1 Command class lists configuration ........................................................................................15

5.4.2 Endpoint configuration ...........................................................................................................15

6 COMMAND CLASSES .......................................................................................................................17

6.1 General interfacing to CCs ...............................................................................................................17

6.1.1 Unsolicited transmission ........................................................................................................17

6.1.2 Respond to received Command ............................................................................................17

6.2 Implementing a CC ...........................................................................................................................19

6.3 Association Group Information CC ...................................................................................................19

6.3.1 API ..........................................................................................................................................19

6.4 Battery CC ........................................................................................................................................20

6.5 Notification CC version 8 ..................................................................................................................20

6.6 Supervision CC.................................................................................................................................21

6.6.1 Configuration scenarios .........................................................................................................21

6.6.1.1 Default configuration ......................................................................................................21

6.6.1.2 Handle more Supervision Reports .................................................................................22

6.6.1.3 Control Supervision Reports ..........................................................................................23

7 UTILITIES ............................................................................................................................................25

7.1 AGI module .......................................................................................................................................25

7.1.1 Configuration of AGI ...............................................................................................................25

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

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

7.1.2 Using AGI ...............................................................................................................................28

7.2 Association module ..........................................................................................................................28

7.2.1 Setting up the NVM ................................................................................................................29

7.2.2 Initialization.............................................................................................................................30

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

7.3 Interfacing Firmware Update module “ota_util” ................................................................................32

7.4 GPIO Driver ......................................................................................................................................32

7.5 Key Driver .........................................................................................................................................32

7.6 Event Scheduler ...............................................................................................................................33

7.6.1 Simple event job handling ......................................................................................................33

INS13953-4 Z-Wave Plus Application Framework v6.8x.0x 2018-04-05

silabs.com | Building a more connected world.

Page iv of v

7.6.2 Multiple event jobs handling ...................................................................................................34

7.6.3 Coding example .....................................................................................................................35

7.7 Task pool ..........................................................................................................................................38

7.8 Test Interface....................................................................................................................................38

7.8.1 UART settings ........................................................................................................................39

7.8.2 Test Interface in the sample applications ...............................................................................39

7.8.3 Defined commands for the default ZAF channel ...................................................................39

8 PORTING GUIDE ................................................................................................................................41

8.1 Changes in 6.81.01 ..........................................................................................................................41

8.2 Porting from 6.71.0x to 6.8x.0x ........................................................................................................41

8.2.1 ZAF_pm replaces Battery_plus ..............................................................................................41

8.2.1.1 ApplicationIdle replaces AppPowerDownReady ............................................................41

8.2.1.2 No arguments for loadStatusPowerLevel and one less argument for

Transport_OnApplicationInitSW ..........................................................................................................41

8.2.1.3 ApplicationPoll takes an argument and return a value ...................................................41

8.2.2 ApplicationInitSW must return node type ...............................................................................41

8.2.3 App must trigger Smart Start after initialization......................................................................42

8.2.4 The module slave_learn_plus is moved to the protocol .........................................................42

8.3 Porting from 6.61.0x to 6.71.0x ........................................................................................................42

8.3.1 Security configuration in Config_app.h ..................................................................................42

8.3.2 General changes in command classes ..................................................................................42

8.3.3 Utilities modules .....................................................................................................................43

APPENDIX A IMPLEMENTING A NEW COMMAND CLASS ...............................................................45

APPENDIX B SCENARIO RECEIVING A GET COMMAND .................................................................49

APPENDIX C DATA MIGRATION ..........................................................................................................50

APPENDIX D SLAVE MIGRATION USING 128KB EXTERNAL NVM ..................................................53

REFERENCES ...........................................................................................................................................54

Table of Figures

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

Figure 2, Smart Start state event machine for all applications. ................................................................... 9

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

Figure 4, Command Class Version Get implementation in SwitchOnOff.c. .............................................. 19

Figure 5, AGI behavior diagram ................................................................................................................ 25

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

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

Figure 7, extended with two endpoints and remove root group 2. ............................................................ 27

Figure 8, Association behavior diagram .................................................................................................... 29

Figure 9, Wall Controller with Root Device group mapping....................................................................... 31

Figure 10, State event machine handling an unsolicited job ..................................................................... 34

Figure 11, Using the FIFO queue in an application ................................................................................... 35

Figure 12, Module source code for a response job. .................................................................................. 46

Figure 13, Unsolicited event function declaration in the module header file. ............................................ 47

Figure 14, Unsolicited event function implementation in the module c-file. .............................................. 48

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

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

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

Figure 18, App migration process. ............................................................................................................. 53

INS13953-4 Z-Wave Plus Application Framework v6.8x.0x 2018-04-05

silabs.com | Building a more connected world.

Page v of v

INS13953-4 Z-Wave Plus Application Framework v6.8x.0x 2018-04-05

silabs.com | Building a more connected world.

Page 6 of 49

1 DEFINITIONS, ACRONYMS AND ABBREVIATIONS

Abbreviation

Explanation

AGI

Association Group Information

Command Class

NIF

Node Information Frame

OTA

Over The Air

Security 0 Command Class

Security 2 Command Class

SDK

Software Development Kit

ZAF

The Z-Wave Plus Application Framework

2 INTRODUCTION

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

3 PURPOSE

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

INS13953-4 Z-Wave Plus Application Framework v6.8x.0x 2018-04-05

silabs.com | Building a more connected world.

Page 7 of 49

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 single cast, 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.

The ZAF is split into the following two folders:

Hardware & Z-Wave protocol

Application

Z-Wave Framework

Transport Layer

Command Class Handlers

Utilities

INS13953-4 Z-Wave Plus Application Framework v6.8x.0x 2018-04-05

silabs.com | Building a more connected world.

Page 8 of 49

 /ApplicationCommandHandlers/ contains CC modules. All CC modules share a protected

transmit buffer provided by the ZW_tx_mutex module. The ZW_tx_mutex module implements

two transmit buffers, one for request calls and one for response calls. Protected transmit buffers

are described in chapter Appendix A.

 /ApplicationUtilities/ contains utility modules and interfaces to the transport layer.

Some of the modules are used for simple MMI-setup such as button and LED handling. Other

modules as association_plus, battery_monitor, battery_plus and ota_util are more complex utility

modules which interface to CC and the client application.

4.1 Smart Start

The Smart Start feature is part of the protocol and automatically handles the inclusion process without

having a user physically interact with a device. When powered on for the first time, the device tells the

world that it is ready for inclusion and most likely a controller nearby will hear this and include the device.

If inclusion process times out, it retries again after a given time. This connection process differs

dependent on whether a device is main powered or battery powered. A main powered device is active all

the time where a battery device sleeps between connection retries.

The Smart Start inclusion process starts when the application calls “ZW_NetworkLearnModeStart()” with

the parameter “E_NETWORK_LEARN_MODE_INCLUSION_SMARTSTART”.

The Protocol inform Classic and Smart Start learn process through function call

“ApplicationNetworkLearnModeCompleted()”. Function Node Id’s value description:

Node

Event

0x00

Exclusion was successful.

0xFD

APPLICATION_NETWORK_LEARN_MODE_COMPLETED_TIMEOUT

0xFE

APPLICATION_NETWORK_LEARN_MODE_COMPLETED_SMART_START_IN_PROGRESS

0xFF

APPLICATION_NETWORK_LEARN_MODE_COMPLETED_FAILED

Any other value will be an assigned node ID.

The following state machine (Figure 1) applies to all Z-Wave+ applications in the SDK.

INS13953-4 Z-Wave Plus Application Framework v6.8x.0x 2018-04-05

silabs.com | Building a more connected world.

Page 9 of 49

Figure 2, Smart Start state event machine for all applications.

Smart Start description:

 Powering On: Smart Start is per default started.

o If not included, smart Start inclusion can be started by Controller.

o If included, powering on reason is “power on reset”. Protocol sends out INIF.

 STATE_APP_IDLE:

o ApplicationNetworkLearnModeCompleted called with:

APPLICATION_NETWORK_LEARN_MODE_COMPLETED_SMART_START_IN_PROGRESS.

 The protocol informs the application that an inclusion process has started.

o ApplicationPoll called with E_PROTOCOL_STATE_READY_FOR_SHUTDOWN:

 The protocol informs the application that it’s ready to powerdown. Since the

application is in STATE_APP_IDLE, the device will power down. This applies to

battery nodes only.

 STATE_APP_LEARN_MODE:

o ApplicationNetworkLearnModeCompleted called with valid node ID:

 Inclusion succeeded and application changes to STATE_APP_IDLE.

o ApplicationNetworkLearnModeCompleted called with:

APPLICATION_NETWORK_LEARN_MODE_COMPLETED_FAILED.

 Inclusion process failed and application change to reboot state.

o ApplicationNetworkLearnModeCompleted called with:

Node ID zero.

 Exclusion process succeeded and application change to reboot state.

 STATE_APP_WATCHDOG_RESET

o Reset device and reboot to start Smart Start Inclusion.

 STATE_APP_REBOOT:

o Protocol handles Smart Start time out to power off.

o Protocol handles next powering on time (WUT timer) if not included.

o Protocol handles powering off if no active jobs.

INS13953-4 Z-Wave Plus Application Framework v6.8x.0x 2018-04-05

silabs.com | Building a more connected world.

Page 10 of 49

4.2 Power Management

Compared to earlier versions of the SDK, the Z-Wave protocol now handles power management. We

have introduced a new module in the ZAF called ZAF_pm where pm is the abbreviation of power

management. This module tells the protocol if the application or the ZAF wants to stay awake for a given

time.

Besides this module ApplicationInitSW and ApplicationPoll now includes power management related

code.

Function

Description

BYTE

ApplicationInitSW(ZW_NVM_STATUS

nvmStatus)

ApplicationInitSW must return whether the device is a

listening or non-listening device.

- APPLICATION_FREQ_LISTENING_MODE_250ms

- APPLICATION_FREQ_LISTENING_MODE_1000ms

- APPLICATION_NODEINFO_NOT_LISTENING

E_APPLICATION_STATE

ApplicationPoll(E_PROTOCOL_STATE

bProtocolState)

ApplicationPoll must whether the application is ready to sleep.

Main powered applications do not need to power off and can in “ApplicationPoll()” return

E_APPLICATION_STATE_ACTIVE.

Battery powered applications must wait for a list of things to finish before informing the protocol that it

can go to sleep. ApplicationIdle() implements this.

INS13953-4 Z-Wave Plus Application Framework v6.8x.0x 2018-04-05

silabs.com | Building a more connected world.

Page 11 of 49

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 MyProductPlus folder in the ProductPlus folder. MyProductPlus is a simple

application which 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 error.

5.2 Setting up config_app.h

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. The

identifiers 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

Command Class. They are set using the following definitions:

 APP_ROLE_TYPE

 APP_NODE_TYPE

 APP_ICON_TYPE

 APP_USER_ICON_TYPE

INS13953-4 Z-Wave Plus Application Framework v6.8x.0x 2018-04-05

silabs.com | Building a more connected world.

Page 12 of 49

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 [14] 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 [14] for more information

about these two Command Classes.

5.2.4 Association Group Information (AGI)

Refer to [14] 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 X, command A}, "<group 3 name>"}\

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

endpoint groups.

#define AGITABLE_ROOTDEVICE_GROUPS \

INS13953-4 Z-Wave Plus Application Framework v6.8x.0x 2018-04-05

silabs.com | Building a more connected world.

Page 13 of 49

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 X MSB>, <profile X LSB>, {<command class>, <command>}, "group name"}, \

{ASSOCIATION_GROUP_INFO_REPORT_PROFILE_CONTROL,

ASSOCIATION_GROUP_INFO_REPORT_PROFILE_CONTROL_KEY01, {COMMAND_CLASS_SWITCH_MULTILEVEL_V4,

SWITCH_MULTILEVEL_SET_V4}, "Button 1"}

When the product implements Multi Channel endpoints, there must be a mapping to the root association

groups. Root groups mapping provides backwards compatibility because devices which 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 levels are configured in the config_app.h file with the definition of

REQUESTED_SECURITY_AUTHENTICATION and REQUESTED_SECURITY_KEYS flags. Definitions

can be found in the ZW_security_api.h file and see [7] for more information about security.

Application can be configured for security S2 authentication type controller-side (SSA) or client-side

(CSA). For client-side authentication need the user to input a 10 digits code via an input interface on the

device, like a keyboard.

#define REQUESTED_SECURITY_AUTHENTICATION SECURITY_AUTHENTICATION_SSA

INS13953-4 Z-Wave Plus Application Framework v6.8x.0x 2018-04-05

silabs.com | Building a more connected world.

Page 14 of 49

Application security level bits must be added to this flag when developing a product. Secure level “No-

secure” is the default value.

#define REQUESTED_SECURITY_KEYS \

(SECURITY_KEY_S2_UNAUTHENTICATED_BIT|SECURITY_KEY_S0_BIT)

Added functionality:

 ApplicationSecureAuthenticationRequested () includes security authentication flag

REQUESTED_SECURITY_AUTHENTICATION.

 ApplicationSecureKeysRequested() includes security keys flag

REQUESTED_SECURITY_KEYS..

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

[14].

5.2.7 Smart Start Included Node Information Frame (INIF) configuration

Setting up INIF for advertising included nodes [11] [12]:

#define USER_INPUT_IDENTIFICATION

#define USER_INPUT_LOCAL_RESET

Please see the source for more info regarding this.

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.

INS13953-4 Z-Wave Plus Application Framework v6.8x.0x 2018-04-05

silabs.com | Building a more connected world.

Page 15 of 49

5.4 Source file

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

ApplicationInitSW(..). The protocol calls the functions in the mentioned order. For details about their

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

done from these two functions.

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

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

5.4.1 Command class lists configuration

The application uses 3 Command Class 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 Command Class list is used when the node is not included or non-securely included. When

the device is included, Security and Security_2 Command Classes are removed by the ZAF. This

Command Class list is present in node information frame (NIF):

static code BYTE cmdClassListNonSecureNotIncluded[]

The following Command Class list is used when node is securely included. It represents the Command

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

static code BYTE cmdClassListNonSecureIncludedSecure[]

The following Command Class list is used when node is securely included. It contains the Command

Classes that are supported securely only. This Command Class list is advertised through the Security

Command Class, 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 [15] for information about individual and aggregated endpoints.

INS13953-4 Z-Wave Plus Application Framework v6.8x.0x 2018-04-05

silabs.com | Building a more connected world.

Page 16 of 49

void Transport_AddEndpointSupport(

EP_FUNCTIONALITY_DATA* pFunctionality,

EP_NIF* pList, BYTE sizeList);

INS13953-4 Z-Wave Plus Application Framework v6.8x.0x 2018-04-05

silabs.com | Building a more connected world.

Page 17 of 49

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 the two following ways:

 Send an unsolicited command, or

 Respond to a received command

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_t ZAF_CC_Basic_Set_tx(

agi_profile_t * pProfile,

uint8_t sourceEndpoint,

uint8_t value,

VOID_CALLBACKFUNC(pCallback)(transmission_result_t * 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

Command Class APIs: pProfile, sourceEndpoint and pCbFunc. 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 [13].

 pProfile

The pProfile points to a AGI profile. This must be one of the profiles that is set up in the AGI

section in your application’s config_app.h file.

 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.

 pCbFunc

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

INS13953-4 Z-Wave Plus Application Framework v6.8x.0x 2018-04-05

silabs.com | Building a more connected world.

Page 18 of 49

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.

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

Figure 3, 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.

INS13953-4 Z-Wave Plus Application Framework v6.8x.0x 2018-04-05

silabs.com | Building a more connected world.

Page 19 of 49

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

6.2 Implementing a CC

Not all CCs have been implemented in the ZAF yet. Hence, in some cases the required Command Class

must be developed for the application. For details, see Appendix A.

6.3 Association Group Information CC

For a general introduction to AGI CC, please refer to [14].

AGI CC is implemented in two C modules:

 CommandClassAssociationGroupInfo

 Agi

Together, these modules serve two purposes:

 Advertise capabilities of each association group, and

 Find associated nodes to which the application wants to send an unsolicited command.

6.3.1 API

 CC_AGI_Init()

 CC_AGI_LifeLineGroupSetup()

 CC_AGI_ResourceGroupSetup()

INS13953-4 Z-Wave Plus Application Framework v6.8x.0x 2018-04-05

silabs.com | Building a more connected world.

Page 20 of 49

6.4 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.5 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 [13].

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.

Page is loading ...

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

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

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

Related papers

Other documents