Z-Wave Protocol Controller Reference
Initialization

Initialization of the Z-Wave API. More...

Collaboration diagram for Initialization:

Classes

struct  zwapi_chip_data_t
 
struct  _zwapi_protocol_version_information_t_
 
struct  zwapi_callbacks
 Structure holding the application callback functions. More...
 

Macros

#define ZWAPI_MAXIMUM_BITMASK_LENGTH   (255 / 8)
 
#define GIT_COMMIT_HASH_SIZE   16
 

Typedefs

typedef struct _zwapi_protocol_version_information_t_ zwapi_protocol_version_information_t
 
typedef void(* application_command_handler_function) (uint8_t rx_status, zwave_node_id_t destination_node_id, zwave_node_id_t source_node_id, const uint8_t *received_frame, uint8_t received_frame_length, int8_t rssi_value)
 Application command handler function type definition. More...
 
typedef void(* protocol_cc_encryption_command_handler_function) (zwave_node_id_t destination_node_id, uint8_t payload_length, const uint8_t *payload, uint8_t protocol_metadata_length, const uint8_t *const protocol_metadata, uint8_t use_supervision, uint8_t session_id)
 
typedef void(* application_controller_update_function) (uint8_t status, zwave_node_id_t node_id, const uint8_t *zwave_nif, uint8_t zwave_nif_length, zwave_home_id_t nwi_home_id)
 Application controller update function type definition. More...
 
typedef struct zwapi_callbacks zwapi_callbacks_t
 Structure holding the application callback functions. More...
 

Functions

sl_status_t zwapi_init (const char *serial_port, int *serial_fd, const zwapi_callbacks_t *callbacks)
 
void zwapi_destroy (void)
 Shut down the Z-Wave API and close the communication ports. More...
 
sl_status_t zwapi_log_to_file_enable (const char *filename)
 Enable logging of serial data to a file. More...
 
sl_status_t zwapi_log_to_file_disable ()
 Disable/stop logging serial data to file. More...
 
bool zwapi_poll (void)
 Main poll loop for the Z-Wave API. More...
 
bool zwapi_support_command_func (uint8_t func_id)
 Check if a command is supported by the connected Z-Wave module. More...
 
bool zwapi_support_setup_func (serial_api_setup_cmd_t setup_cmd)
 Check if one of the serial API setup commands is supported. More...
 
sl_status_t zwapi_refresh_capabilities (void)
 Refresh the whole zwapi_chip_data_t structure from the Z-Wave module. More...
 
sl_status_t zwapi_get_init_data (uint8_t *ver, uint8_t *capabilities, uint8_t *len, zwave_nodemask_t node_list, uint8_t *chip_type, uint8_t *chip_version)
 Get zwave_api initialization data from the remote side (Enhanced Z-Wave module). More...
 
sl_status_t zwapi_get_node_list (zwave_nodemask_t node_list)
 Refresh the node list from the Z-Wave protocol and copy in into the node_list pointer. More...
 
void zwapi_get_chip_type_version (uint8_t *type, uint8_t *version)
 Look up the cached chip type and chip version. More...
 
void zwapi_get_app_version (uint8_t *major, uint8_t *minor)
 Get the application version of the serial API on the Z-Wave module. More...
 
void zwapi_get_chip_data (zwapi_chip_data_t *user_chip_data)
 Return all information known about the chip after initialization. More...
 
zwapi_library_type_t zwapi_get_library_type ()
 returns the cached value of the library type for the module More...
 
sl_status_t zwapi_get_protocol_version (zwapi_protocol_version_information_t *protocol_version)
 Retrieves versioning data from the Z-Wave API Module. More...
 
zwave_lr_channel_t zwapi_get_zwave_lr_channel ()
 Reads the currently configured Z-Wave Long Range Channel. More...
 
sl_status_t zwapi_set_zwave_lr_channel (zwave_lr_channel_t new_channel)
 Sets the desired Z-Wave Long Range Channel configuration. More...
 
bool zwapi_is_awaiting_zwave_api_started ()
 Checks if we are waiting for a Z-Wave API started message. More...
 
void zwapi_set_awaiting_zwave_api_started (bool value)
 Sets the value of "awaiting a Z-Wave API started callback". More...
 
zwapi_callbacks_tzwave_api_get_callbacks ()
 Returns the pointer to the callbacks registered at init. More...
 
const char * zwapi_generate_sdk_version_from_protocol_version (const char *version_string)
 Convert protocol version string to Z-Wave SDK version string. More...
 
const char * zwapi_generate_nvm_id_from_sdk_version (const char *sdk_ver, zwapi_library_type_t library_type)
 Convert Z-Wave SDK version to the NVM ID. More...
 

zwapi_library_type_t

One of these defines are returned when requesting library type with zwapi_get_zw_library_type() / zwapi_get_library_type()

enum  zwapi_library_type_t {
  ZWAVE_LIBRARY_TYPE_CONTROLLER_STATIC = 0x01 , ZWAVE_LIBRARY_TYPE_CONTROLLER = 0x02 , ZWAVE_LIBRARY_TYPE_END_NODE_ENHANCED = 0x03 , ZWAVE_LIBRARY_TYPE_END_NODE = 0x04 ,
  ZWAVE_LIBRARY_TYPE_INSTALLER = 0x05 , ZWAVE_LIBRARY_TYPE_END_NODE_ROUTING = 0x06 , ZWAVE_LIBRARY_TYPE_CONTROLLER_BRIDGE = 0x07 , ZWAVE_LIBRARY_TYPE_DUT = 0x08 ,
  ZWAVE_LIBRARY_TYPE_AVREMOTE = 0x0A , ZWAVE_LIBRARY_TYPE_AVDEVICE = 0x0B
}
 

zwave_lr_channel_t

List of available Z-Wave Long Range Channels. Refer to zwapi_get_zwave_lr_channel() and zwapi_set_zwave_lr_channel

enum  zwave_lr_channel_t { ZWAVE_LONG_RANGE_CHANNEL_NOT_SUPPORTED = 0x00 , ZWAVE_LONG_RANGE_CHANNEL_A = 0x01 , ZWAVE_LONG_RANGE_CHANNEL_B = 0x02 }
 

Flags used in FUNC_ID_SERIAL_API_GET_INIT_DATA functionality

#define GET_INIT_DATA_FLAG_END_NODE_API   0x01
 
#define GET_INIT_DATA_FLAG_TIMER_SUPPORT   0x02
 
#define GET_INIT_DATA_FLAG_CONTROLLER_STATUS   0x04
 
#define GET_INIT_DATA_FLAG_SECONDARY_CTRL   0x04
 
#define GET_INIT_DATA_FLAG_IS_SUC   0x08
 

Detailed Description

Initialization of the Z-Wave API.

This module contains functions to both initialize and shut down the Z-Wave API and query the Z-Wave module about supported functions.

Macro Definition Documentation

◆ GET_INIT_DATA_FLAG_CONTROLLER_STATUS

#define GET_INIT_DATA_FLAG_CONTROLLER_STATUS   0x04
Deprecated:
Use GET_INIT_DATA_FLAG_SECONDARY_CTRL instead

◆ GET_INIT_DATA_FLAG_END_NODE_API

#define GET_INIT_DATA_FLAG_END_NODE_API   0x01

◆ GET_INIT_DATA_FLAG_IS_SUC

#define GET_INIT_DATA_FLAG_IS_SUC   0x08

◆ GET_INIT_DATA_FLAG_SECONDARY_CTRL

#define GET_INIT_DATA_FLAG_SECONDARY_CTRL   0x04

◆ GET_INIT_DATA_FLAG_TIMER_SUPPORT

#define GET_INIT_DATA_FLAG_TIMER_SUPPORT   0x02

◆ GIT_COMMIT_HASH_SIZE

#define GIT_COMMIT_HASH_SIZE   16

◆ ZWAPI_MAXIMUM_BITMASK_LENGTH

#define ZWAPI_MAXIMUM_BITMASK_LENGTH   (255 / 8)

Typedef Documentation

◆ application_command_handler_function

typedef void(* application_command_handler_function) (uint8_t rx_status, zwave_node_id_t destination_node_id, zwave_node_id_t source_node_id, const uint8_t *received_frame, uint8_t received_frame_length, int8_t rssi_value)

Application command handler function type definition.

Parameters
rx_statusreceived frame status flags:
Flag Name Flag Mask Flag description
{RECEIVE_STATUS_ROUTED_BUSY} xxxxxxx1 A response route is locked by the application
{RECEIVE_STATUS_LOW_POWER} xxxxxx1x Received at low output power level
{RECEIVE_STATUS_TYPE_SINGLE} xxxx00xx Received a single cast frame
{RECEIVE_STATUS_TYPE_BROAD} xxxx01xx Received a broadcast frame
{RECEIVE_STATUS_TYPE_MULTI} xxxx10xx Received a multicast frame
{RECEIVE_STATUS_FOREIGN_FRAME} x1xxxxxx The received frame is not addressed to this node (Only valid in promiscuous mode)
Parameters
destination_node_idcommand destination Node ID. Only valid in promiscuous mode and in singlecast frames. Else it will be set to 0 and indicates that it was sent to the Z-Wave module current NodeID
source_node_idcommand sender Node ID
received_framePayload of the received frame (The command class identifier is is the very first byte)
received_frame_lengthis the length of the received command class frame.
rssi_valueis the RSSI measurement for the frame that was received.

Rx: {REQ | 0x04 | rxStatus | sourceNode | cmdLength | pCmd[ ] | rxRSSIVal }

When a foreign frame is received in promiscuous mode: Rx: {REQ | 0xD1 | rxStatus | sourceNode | cmdLength | pCmd[ ] | destNode} The destNode parameter is only valid for singlecast frames.

The Z-Wave API will call the application_command_handler_function function registered with zwapi_init() when an application command or request has been received from another node. The receive buffer is released when returning from this function. The type of frame used by the request can be determined (single cast, multicast, or broadcast frame). This is used to avoid flooding the network by responding on a multicast or broadcast. In order not to disrupt the radio communication and the protocol, no application function must execute code for more than 5 ms without returning.

◆ application_controller_update_function

typedef void(* application_controller_update_function) (uint8_t status, zwave_node_id_t node_id, const uint8_t *zwave_nif, uint8_t zwave_nif_length, zwave_home_id_t nwi_home_id)

Application controller update function type definition.

Parameters
statusThe status of the update process, value could be one of the following:
node_idis the updated node's node ID (1..232).
zwave_nifis pointer of the updated node's node info.
zwave_nif_lengthis the length of the pCmd parameter.
nwi_home_idis the NWI HomeID of the node issuing the NIF / INIF / SmartStart Prime Command

A controller application MAY use the information provided by application_controller_update_function to update local data structures.

The Z-Wave protocol MUST notify a controller application by calling application_controller_update_function when a new node has been added or deleted from the controller through the network management features.

The Z-Wave protocol MUST call application_controller_update_function in response to zwapi_request_node_info() being called by the controller application. The Z-Wave protocol MAY notify a controller application by calling application_controller_update_function when a Node Information Frame has been received. The Z-Wave protocol MAY refrain from calling the function if the protocol is currently expecting a Node Information frame.

application_controller_update_function MUST be called in a controller node operating as SIS each time a node is added or deleted by the primary controller. application_controller_update_function MUST be called in a controller node operating as SIS each time a node is added/deleted by an inclusion controller.

The Z Wave protocol may notify a controller application by calling application_controller_update_function when a Node Information Frame has been received. The Z-Wave protocol may not call the function if the protocol is currently expecting node information.

A controller application may send a zwapi_request_network_update() command to a SIS or SIS node. In response, the SIS MUST return update information for each node change since the last update handled by the requesting controller node. The application of the requesting controller node may receive multiple calls to application_controller_update_function in response to zwapi_request_network_update().

The Z Wave protocol most not call application_controller_update_function in a controller node acting as primary controller or inclusion controller when a node is added or deleted.

Any controller application MUST implement this function.

Rx: {REQ | 0x49 | bStatus | bNodeID | bLen | basic | generic | specific | commandclasses[ ]}

application_controller_update_function via the Z-Wave API also have the possibility for receiving the status UPDATE_STATE_NODE_INFO_REQ_FAILED, which means that a node did not acknowledge a zwapi_request_node_info() call.

◆ protocol_cc_encryption_command_handler_function

typedef void(* protocol_cc_encryption_command_handler_function) (zwave_node_id_t destination_node_id, uint8_t payload_length, const uint8_t *payload, uint8_t protocol_metadata_length, const uint8_t *const protocol_metadata, uint8_t use_supervision, uint8_t session_id)

◆ zwapi_callbacks_t

Structure holding the application callback functions.

The application callback functions must be registered to the Z-Wave API with zwapi_init(). The functions will be invoked by the Z-Wave API at specific times.

aka SerialAPI_Callbacks

◆ zwapi_protocol_version_information_t

Enumeration Type Documentation

◆ zwapi_library_type_t

Enumerator
ZWAVE_LIBRARY_TYPE_CONTROLLER_STATIC 

aka ZW_LIB_CONTROLLER_STATIC

ZWAVE_LIBRARY_TYPE_CONTROLLER 

aka ZW_LIB_CONTROLLER

ZWAVE_LIBRARY_TYPE_END_NODE_ENHANCED 

aka ZW_LIB_SLAVE_ENHANCED

ZWAVE_LIBRARY_TYPE_END_NODE 

aka ZW_LIB_SLAVE

ZWAVE_LIBRARY_TYPE_INSTALLER 

aka ZW_LIB_INSTALLER

ZWAVE_LIBRARY_TYPE_END_NODE_ROUTING 

aka ZW_LIB_SLAVE_ROUTING

ZWAVE_LIBRARY_TYPE_CONTROLLER_BRIDGE 

aka ZW_LIB_CONTROLLER_BRIDGE

ZWAVE_LIBRARY_TYPE_DUT 

aka ZW_LIB_DUT

ZWAVE_LIBRARY_TYPE_AVREMOTE 

aka ZW_LIB_AVREMOTE

ZWAVE_LIBRARY_TYPE_AVDEVICE 

aka ZW_LIB_AVDEVICE

◆ zwave_lr_channel_t

Enumerator
ZWAVE_LONG_RANGE_CHANNEL_NOT_SUPPORTED 

Z-Wave LR is not supported.

ZWAVE_LONG_RANGE_CHANNEL_A 

Z-Wave Long Range Channel A.

ZWAVE_LONG_RANGE_CHANNEL_B 

Z-Wave Long Range Channel B.

Function Documentation

◆ zwapi_destroy()

void zwapi_destroy ( void  )

Shut down the Z-Wave API and close the communication ports.

aka SerialAPI_Destroy

Here is the call graph for this function:
Here is the caller graph for this function:

◆ zwapi_generate_nvm_id_from_sdk_version()

const char * zwapi_generate_nvm_id_from_sdk_version ( const char *  sdk_ver,
zwapi_library_type_t  library_type 
)

Convert Z-Wave SDK version to the NVM ID.

Parameters
sdk_verreturned by zwapi_generate_sdk_version_from_protocol_version()
library_typereturned by zwapi_get_zw_library_version()
Returns
nvm_id (e.g., bridge6.81)

aka GenerateNvmIdFromSdkVersion

◆ zwapi_generate_sdk_version_from_protocol_version()

const char * zwapi_generate_sdk_version_from_protocol_version ( const char *  version_string)

Convert protocol version string to Z-Wave SDK version string.

Parameters
version_stringstring created by (first argument of) zwapi_get_zw_library_version(version_string)
Returns
returns SDK version (e.g., "6.81.00")

aka GenerateSdkVersionFromProtocolVersion

◆ zwapi_get_app_version()

void zwapi_get_app_version ( uint8_t *  major,
uint8_t *  minor 
)

Get the application version of the serial API on the Z-Wave module.

Parameters
majorpointer to variable that should contain the major version.
minorpointer to variable that should contain the minor version.

aka Get_SerialAPI_AppVersion

Here is the caller graph for this function:

◆ zwapi_get_chip_data()

void zwapi_get_chip_data ( zwapi_chip_data_t user_chip_data)

Return all information known about the chip after initialization.

Note
Only valid after zwapi_init() has returned SL_STATUS_OK
Parameters
user_chip_dataaddress of the zwapi_chip_data_t to copy the data returned by the module.
Here is the caller graph for this function:

◆ zwapi_get_chip_type_version()

void zwapi_get_chip_type_version ( uint8_t *  type,
uint8_t *  version 
)

Look up the cached chip type and chip version.

Note
Only valid after zwapi_get_init_data() has been called.
Parameters
typereturns argument for the chip type.
versionreturns argument for the chip version.

aka SerialAPI_GetChipTypeAndVersion

Here is the caller graph for this function:

◆ zwapi_get_init_data()

sl_status_t zwapi_get_init_data ( uint8_t *  ver,
uint8_t *  capabilities,
uint8_t *  len,
zwave_nodemask_t  node_list,
uint8_t *  chip_type,
uint8_t *  chip_version 
)

Get zwave_api initialization data from the remote side (Enhanced Z-Wave module).

Parameters
veris the zwave_api version
capabilitiesis the capabilities flag (GET_INIT_DATA_FLAG_xxx):
lenis the number of bytes in nodesList
node_listis the Bitmask list with nodes known by Z-Wave module
chip_typeis the Z-Wave radio module type
chip_versionis the Z-Wave radio module version
Returns
SL_STATUS_OK if the initialization data was retrieved and parsed correctly. SL_STATUS_FAIL otherwise

aka SerialAPI_GetInitData

Here is the call graph for this function:
Here is the caller graph for this function:

◆ zwapi_get_library_type()

zwapi_library_type_t zwapi_get_library_type ( )

returns the cached value of the library type for the module

Note
Only valid after zwapi_init() has returned SL_STATUS_OK
Parameters
zwapi_library_type_tvalue of the library type for the chip
Here is the caller graph for this function:

◆ zwapi_get_node_list()

sl_status_t zwapi_get_node_list ( zwave_nodemask_t  node_list)

Refresh the node list from the Z-Wave protocol and copy in into the node_list pointer.

Parameters
node_listis a zwapi_nodemask_t, where the data will be copied. If this parameter is set to NULL, the node list will still be refreshed from the Z-Wave module and can be retrieved subsequently with zwapi_get_chip_data
Returns
SL_STATUS_OK if the node list was retrieved from the Z-Wave module. SL_STATUS_FAIL otherwise
Here is the call graph for this function:
Here is the caller graph for this function:

◆ zwapi_get_protocol_version()

sl_status_t zwapi_get_protocol_version ( zwapi_protocol_version_information_t protocol_version)

Retrieves versioning data from the Z-Wave API Module.

Returns
SL_STATUS_OK or SL_STATUS_FAIL.

aka ZW_GetProtocolVersion

Here is the call graph for this function:
Here is the caller graph for this function:

◆ zwapi_get_zwave_lr_channel()

zwave_lr_channel_t zwapi_get_zwave_lr_channel ( )

Reads the currently configured Z-Wave Long Range Channel.

Returns
zwave_lr_channel_t value for the configured Z-Wave Long Range channel.
Here is the call graph for this function:

◆ zwapi_init()

sl_status_t zwapi_init ( const char *  serial_port,
int *  serial_fd,
const zwapi_callbacks_t callbacks 
)

Initialize the Z-Wave API module with all the callbacks needed for operation.

Parameters
serial_portis the name of the serial port to use (on Linux i.e., "/dev/ttyS1")
serial_fdpointer where the serial file descriptor will be written
callbacksis a callback function to be used by the Z-Wave API.
Returns
SL_STATUS_OK if all initialization was successfully completed. It includes initializing the Z-Wave module serial port, reading the module's capabilities and its version. SL_STATUS_FAIL otherwise

aka SerialAPI_Init

Here is the call graph for this function:
Here is the caller graph for this function:

◆ zwapi_is_awaiting_zwave_api_started()

bool zwapi_is_awaiting_zwave_api_started ( )

Checks if we are waiting for a Z-Wave API started message.

Returns
true if we are awaiting for it, false otherwise
Here is the caller graph for this function:

◆ zwapi_log_to_file_disable()

sl_status_t zwapi_log_to_file_disable ( )

Disable/stop logging serial data to file.

This will stop the logging of serial data to file.

Returns
SL_STATUS_OK on success
Here is the call graph for this function:
Here is the caller graph for this function:

◆ zwapi_log_to_file_enable()

sl_status_t zwapi_log_to_file_enable ( const char *  filename)

Enable logging of serial data to a file.

The log will append to the file, it is up to the user to handle log rotation, free disk space monitoring etc.

Parameters
filenamefile to log serial trace to, log will append to this file.
Returns
SL_STATUS_OK on success.
SL_STATUS_ALREADY_INITIALIZED if log to file is already enabled.
SL_STATUS_FAIL if other failure (e.g. folder doesn't exist, lacking permissions, etc.).
Here is the call graph for this function:
Here is the caller graph for this function:

◆ zwapi_poll()

bool zwapi_poll ( void  )

Main poll loop for the Z-Wave API.

Returns
returns true if there are still more frames to process in the receive queue.

This function must be called from some application main loop. This is what drives the serial data receive handling. zwapi_poll() checks the serial port for new data and handles timers and all other async callbacks. I.e., all Z-Wave API callbacks are called from within this function.

TODO: It would be nice to have zwapi_poll return the minimum number of system ticks to parse before a timer times out. In this way we don't need to call zwapi_poll unless we got a receive interrupt from the uart or if a timer has timed out. This means that the system would be able to go into low power mode between zwapi_poll calls.

aka SerialAPI_Poll

Here is the call graph for this function:
Here is the caller graph for this function:

◆ zwapi_refresh_capabilities()

sl_status_t zwapi_refresh_capabilities ( void  )

Refresh the whole zwapi_chip_data_t structure from the Z-Wave module.

This function is called at initialization, but should also be called if the Z-Wave module may change capabilities, for example after firmware update or network inclusion.

Returns
SL_STATUS_OK if the refresh operation was successful.
SL_STATUS_FAIL otherwise
Here is the call graph for this function:
Here is the caller graph for this function:

◆ zwapi_set_awaiting_zwave_api_started()

void zwapi_set_awaiting_zwave_api_started ( bool  value)

Sets the value of "awaiting a Z-Wave API started callback".

Parameters
valueValue to set. True if we are expecting/waiting for a Z-Wave API started message, false if not.
Here is the caller graph for this function:

◆ zwapi_set_zwave_lr_channel()

sl_status_t zwapi_set_zwave_lr_channel ( zwave_lr_channel_t  new_channel)

Sets the desired Z-Wave Long Range Channel configuration.

Parameters
new_channelvalue of the desired Z-Wave Long Range channel.
Returns
sl_status_t indicating the outcome of the command. SL_STATUS_OK if the command was delivered to the Z-Wave API (but it does guarantee that the channel setting was accepted) SL_STATUS_NOT_SUPPORTED if the Z-Wave API command is not supported.
Note
zwapi_get_zwave_lr_channel should be called subsequently to verify if the channel configuration was accepted
Here is the call graph for this function:

◆ zwapi_support_command_func()

bool zwapi_support_command_func ( uint8_t  func_id)

Check if a command is supported by the connected Z-Wave module.

Parameters
func_idThe FUNC_ID of the command to check, see zwapi_func_ids.h
Returns
true if the command is supported
false if the command is NOT supported
Note
A Z-Wave API session must have been opened with zwapi_init() before calling this function.

aka SerialAPI_SupportsCommand_func

Here is the caller graph for this function:

◆ zwapi_support_setup_func()

bool zwapi_support_setup_func ( serial_api_setup_cmd_t  setup_cmd)

Check if one of the serial API setup commands is supported.

If the setup command is not bit flag which means it is not part of the one byte in Z-Wave API Setup Supported Sub Commands flags, then the command will be checked in Extended Z-Wave API Setup Supported Sub Commands bitmask. Please note that checking of only one byte of Extended Z-Wave API Setup Supported Sub Commands bitmask is supported right now.

Parameters
setup_cmdThe command from serial_api_setup_cmd_t to check.
Returns
true if the command is supported, false otherwise.

aka SupportsSerialAPISetup_func

Here is the call graph for this function:
Here is the caller graph for this function:

◆ zwave_api_get_callbacks()

zwapi_callbacks_t * zwave_api_get_callbacks ( )

Returns the pointer to the callbacks registered at init.

Returns
zwapi_callbacks_t*
Here is the caller graph for this function: