|
Z-Wave Protocol Controller Reference
|
Initialization of the Z-Wave API. More...
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_t * | zwave_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 |
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.
| #define GET_INIT_DATA_FLAG_CONTROLLER_STATUS 0x04 |
| #define GET_INIT_DATA_FLAG_END_NODE_API 0x01 |
| #define GET_INIT_DATA_FLAG_IS_SUC 0x08 |
| #define GET_INIT_DATA_FLAG_SECONDARY_CTRL 0x04 |
| #define GET_INIT_DATA_FLAG_TIMER_SUPPORT 0x02 |
| #define GIT_COMMIT_HASH_SIZE 16 |
| #define ZWAPI_MAXIMUM_BITMASK_LENGTH (255 / 8) |
| 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.
| rx_status | received 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) |
| destination_node_id | command 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_id | command sender Node ID |
| received_frame | Payload of the received frame (The command class identifier is is the very first byte) |
| received_frame_length | is the length of the received command class frame. |
| rssi_value | is 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.
| 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.
| status | The status of the update process, value could be one of the following:
|
| node_id | is the updated node's node ID (1..232). |
| zwave_nif | is pointer of the updated node's node info. |
| zwave_nif_length | is the length of the pCmd parameter. |
| nwi_home_id | is 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.
| 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 struct zwapi_callbacks 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
| enum zwapi_library_type_t |
| enum zwave_lr_channel_t |
| void zwapi_destroy | ( | void | ) |
Shut down the Z-Wave API and close the communication ports.
aka SerialAPI_Destroy
| 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.
| sdk_ver | returned by zwapi_generate_sdk_version_from_protocol_version() |
| library_type | returned by zwapi_get_zw_library_version() |
aka GenerateNvmIdFromSdkVersion
| const char * zwapi_generate_sdk_version_from_protocol_version | ( | const char * | version_string | ) |
Convert protocol version string to Z-Wave SDK version string.
| version_string | string created by (first argument of) zwapi_get_zw_library_version(version_string) |
aka GenerateSdkVersionFromProtocolVersion
| void zwapi_get_app_version | ( | uint8_t * | major, |
| uint8_t * | minor | ||
| ) |
Get the application version of the serial API on the Z-Wave module.
| major | pointer to variable that should contain the major version. |
| minor | pointer to variable that should contain the minor version. |
aka Get_SerialAPI_AppVersion
| void zwapi_get_chip_data | ( | zwapi_chip_data_t * | user_chip_data | ) |
Return all information known about the chip after initialization.
| user_chip_data | address of the zwapi_chip_data_t to copy the data returned by the module. |
| void zwapi_get_chip_type_version | ( | uint8_t * | type, |
| uint8_t * | version | ||
| ) |
Look up the cached chip type and chip version.
| type | returns argument for the chip type. |
| version | returns argument for the chip version. |
aka SerialAPI_GetChipTypeAndVersion
| 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).
| ver | is the zwave_api version |
| capabilities | is the capabilities flag (GET_INIT_DATA_FLAG_xxx):
|
| len | is the number of bytes in nodesList |
| node_list | is the Bitmask list with nodes known by Z-Wave module |
| chip_type | is the Z-Wave radio module type |
| chip_version | is the Z-Wave radio module version |
aka SerialAPI_GetInitData
| zwapi_library_type_t zwapi_get_library_type | ( | ) |
returns the cached value of the library type for the module
| zwapi_library_type_t | value of the library type for the chip |
| 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.
| node_list | is 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 |
| sl_status_t zwapi_get_protocol_version | ( | zwapi_protocol_version_information_t * | protocol_version | ) |
Retrieves versioning data from the Z-Wave API Module.
aka ZW_GetProtocolVersion
| zwave_lr_channel_t zwapi_get_zwave_lr_channel | ( | ) |
Reads the currently configured Z-Wave Long Range Channel.
| 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.
| serial_port | is the name of the serial port to use (on Linux i.e., "/dev/ttyS1") |
| serial_fd | pointer where the serial file descriptor will be written |
| callbacks | is a callback function to be used by the Z-Wave API. |
aka SerialAPI_Init
| bool zwapi_is_awaiting_zwave_api_started | ( | ) |
Checks if we are waiting for a Z-Wave API started message.
| 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.
| 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.
| filename | file to log serial trace to, log will append to this file. |
| bool zwapi_poll | ( | void | ) |
Main poll loop for the Z-Wave API.
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
| 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.
| void zwapi_set_awaiting_zwave_api_started | ( | bool | value | ) |
Sets the value of "awaiting a Z-Wave API started callback".
| value | Value to set. True if we are expecting/waiting for a Z-Wave API started message, false if not. |
| sl_status_t zwapi_set_zwave_lr_channel | ( | zwave_lr_channel_t | new_channel | ) |
Sets the desired Z-Wave Long Range Channel configuration.
| new_channel | value of the desired Z-Wave Long Range channel. |
| bool zwapi_support_command_func | ( | uint8_t | func_id | ) |
Check if a command is supported by the connected Z-Wave module.
| func_id | The FUNC_ID of the command to check, see zwapi_func_ids.h |
aka SerialAPI_SupportsCommand_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.
| setup_cmd | The command from serial_api_setup_cmd_t to check. |
aka SupportsSerialAPISetup_func
| zwapi_callbacks_t * zwave_api_get_callbacks | ( | ) |
Returns the pointer to the callbacks registered at init.