Z-Wave Protocol Controller Reference

Functions used to send data to Z-Wave nodes. More...

Collaboration diagram for Transport API:

Modules

 Z-Wave API send_data return codes
 

Classes

struct  rssi_val
 
struct  _S_ROUTE_LINK_
 
struct  _protocol_metadata_
 
struct  zwapi_tx_report
 Detailed report and data about Z-Wave transmissions. More...
 

Macros

#define NODEPARM_MAX   35
 Max. number of parameters. More...
 
#define ZW_MAX_CACHED_RETURN_ROUTE_DESTINATIONS   5
 
#define ZW_RF_TEST_SIGNAL_CARRIER   0x00
 
#define ZW_RF_TEST_SIGNAL_CARRIER_MODULATED   0x01
 
#define MAX_REPEATERS   4
 Max hops in route. More...
 
#define PROTOCOL_METADATA_LENGTH
 rf_speed | tx_power | tx_options | callback_id More...
 

Typedefs

typedef struct _S_ROUTE_LINK_ S_ROUTE_LINK
 
typedef struct _protocol_metadata_ protocol_metadata_t
 
typedef enum _E_ROUTING_SCHEME_ e_routing_scheme_t
 Transport routing scheme state define definitions. More...
 
typedef enum last_route_speed last_route_speed_t
 List of possible link speeds / protocols. More...
 
typedef struct zwapi_tx_report zwapi_tx_report_t
 Detailed report and data about Z-Wave transmissions. More...
 

Enumerations

enum  _E_ROUTING_SCHEME_ {
  ROUTINGSCHEME_IDLE = 0 , ROUTINGSCHEME_DIRECT = 1 , ROUTINGSCHEME_CACHED_ROUTE_SR = 2 , ROUTINGSCHEME_CACHED_ROUTE = 3 ,
  ROUTINGSCHEME_CACHED_ROUTE_NLWR = 4 , ROUTINGSCHEME_ROUTE = 5 , ROUTINGSCHEME_RESORT_DIRECT = 6 , ROUTINGSCHEME_RESORT_EXPLORE = 7
}
 Transport routing scheme state define definitions. More...
 
enum  last_route_speed {
  UNKNOWN_SPEED = 0 , ZWAVE_9_6_KBITS_S = 1 , ZWAVE_40_KBITS_S = 2 , ZWAVE_100_KBITS_S = 3 ,
  ZWAVE_LONG_RANGE_100_KBITS_S = 4
}
 List of possible link speeds / protocols. More...
 

Functions

sl_status_t zwapi_lock_route (bool lock)
 Lock and unlock a response route for a specific node. More...
 
sl_status_t zwapi_send_data_bridge (zwave_node_id_t source_node_id, zwave_node_id_t destination_node_id, const uint8_t *data, uint8_t data_length, uint8_t tx_options, void(*callback_function)(uint8_t, zwapi_tx_report_t *))
 Transmit data buffer to a single ZW-node or all ZW-nodes (broadcast) in bridge mode. More...
 
sl_status_t zwapi_send_data (zwave_node_id_t destination_node_id, const uint8_t *data, uint8_t data_length, uint8_t tx_options, void(*callback_function)(uint8_t, zwapi_tx_report_t *))
 Send data to a Z-Wave node or to the broadcast destination. More...
 
sl_status_t zwapi_send_protocol_data (zwave_node_id_t destination_node_id, const uint8_t *data, uint8_t data_length, void *metadata, void(*callback_function)(uint8_t, zwapi_tx_report_t *))
 Send protocol data to a Z-Wave node. More...
 
sl_status_t zwapi_abort_send_data (void)
 Abort the ongoing transmit started with zwapi_send_data() or zwapi_send_data_bridge() More...
 
sl_status_t zwapi_send_data_multi (zwave_nodemask_t destination_node_mask, const uint8_t *data, uint8_t data_length, uint8_t tx_options, void(*callback_function)(uint8_t tx_status))
 Send data to a list of Z-Wave Nodes (multicast frame). More...
 
sl_status_t zwapi_send_data_multi_bridge (zwave_node_id_t source_node_id, zwave_nodemask_t destination_node_mask, const uint8_t *data, uint8_t data_length, uint8_t tx_options, void(*callback_function)(uint8_t tx_status))
 Send data to a list of Z-Wave Nodes (multicast frame) in bridge mode. More...
 
sl_status_t zwapi_send_nop (zwave_node_id_t destination, uint8_t tx_options, void(*callback_function)(uint8_t, zwapi_tx_report_t *))
 Sends a NOP to a NodeID destination. More...
 

Transmit frame option flags

request acknowledge from destination node

#define TRANSMIT_OPTION_ACK   0x01
 transmit at low output power level (1/3 of normal RF range) More...
 
#define TRANSMIT_OPTION_LOW_POWER   0x02
 The multicast frame should be send as a broadcast. More...
 
#define TRANSMIT_OPTION_MULTICAST_AS_BROADCAST   0x02
 
#define TRANSMIT_OPTION_AUTO_ROUTE   0x04
 request retransmission via repeater nodes More...
 
#define TRANSMIT_OPTION_NO_ROUTE   0x10
 do not use response route - Even if available More...
 
#define TRANSMIT_OPTION_EXPLORE   0x20
 Use explore frame if needed. More...
 
#define TRANSMIT_OPTION_MULTICAST   0x40
 The the frame as a multicast frame. More...
 

Transmit frame option flag which are valid when sending explore frames

#define TRANSMIT_EXPLORE_OPTION_ACK   TRANSMIT_OPTION_ACK
 
#define TRANSMIT_EXPLORE_OPTION_LOW_POWER   TRANSMIT_OPTION_LOW_POWER
 

Allow Transport Service segmentation of long messages

#define TRANSMIT_OPTION_2_TRANSPORT_SERVICE   0x01
 
#define TRANSMIT_OPTION_2_FOLLOWUP   0x08
 

Received frame status flags

A response route is locked by the application

#define RECEIVE_STATUS_ROUTED_BUSY   0x01
 
#define RECEIVE_STATUS_LOW_POWER   0x02
 
#define RECEIVE_STATUS_TYPE_MASK   0x0C
 Mask for masking out the received frametype bits. More...
 
#define RECEIVE_STATUS_TYPE_SINGLE   0x00
 Received frame is singlecast frame (rxOptions == xxxx00xx) More...
 
#define RECEIVE_STATUS_TYPE_BROAD   0x04
 Received frame is broadcast frame (rxOptions == xxxx01xx) More...
 
#define RECEIVE_STATUS_TYPE_MULTI   0x08
 Received frame is multicast frame (rxOptions == xxxx10xx) More...
 
#define RECEIVE_STATUS_TYPE_EXPLORE   0x10
 
#define RECEIVE_STATUS_FOREIGN_FRAME   0x40
 
#define RECEIVE_STATUS_FOREIGN_HOMEID   0x80
 

ZW_REDISCOVERY_NEEDED callback values

Note that they are different from zwapi_request_network_update() callbacks

#define ZW_ROUTE_LOST_FAILED   0x04
 Node Asked wont help us. More...
 
#define ZW_ROUTE_LOST_ACCEPT   0x05
 Accepted to help. More...
 

zwapi_tx_report_t Last Used Route array size definitions

#define LAST_USED_ROUTE_CONF_SIZE   1
 
#define LAST_USED_ROUTE_SIZE   (MAX_REPEATERS + LAST_USED_ROUTE_CONF_SIZE)
 

zwapi_tx_report_t Last Used Route array index definitions

#define LAST_USED_ROUTE_REPEATER_0_INDEX   0
 
#define LAST_USED_ROUTE_REPEATER_1_INDEX   1
 
#define LAST_USED_ROUTE_REPEATER_2_INDEX   2
 
#define LAST_USED_ROUTE_REPEATER_3_INDEX   3
 

RSSI feedback constants

This is a signed 8-bit value. Note that values from RSSI_RESERVED_START to 124 are reserved. All values below RSSI_RESERVED_START are received power in dBms. Other values are defined below.

RSSI measurement not available

#define RSSI_NOT_AVAILABLE   127
 
#define RSSI_MAX_POWER_SATURATED   126
 Receiver saturated. RSSI too high to measure precisely. More...
 
#define RSSI_BELOW_SENSITIVITY   125
 No signal detected. The RSSI is too low to measure precisely. More...
 
#define RSSI_RESERVED_START   11
 

Detailed Description

Functions used to send data to Z-Wave nodes.

Functions in this module are used to transmit commands to Z-Wave nodes using single-cast and multi-cast.

Macro Definition Documentation

◆ LAST_USED_ROUTE_CONF_SIZE

#define LAST_USED_ROUTE_CONF_SIZE   1

◆ LAST_USED_ROUTE_REPEATER_0_INDEX

#define LAST_USED_ROUTE_REPEATER_0_INDEX   0

◆ LAST_USED_ROUTE_REPEATER_1_INDEX

#define LAST_USED_ROUTE_REPEATER_1_INDEX   1

◆ LAST_USED_ROUTE_REPEATER_2_INDEX

#define LAST_USED_ROUTE_REPEATER_2_INDEX   2

◆ LAST_USED_ROUTE_REPEATER_3_INDEX

#define LAST_USED_ROUTE_REPEATER_3_INDEX   3

◆ LAST_USED_ROUTE_SIZE

#define LAST_USED_ROUTE_SIZE   (MAX_REPEATERS + LAST_USED_ROUTE_CONF_SIZE)

◆ MAX_REPEATERS

#define MAX_REPEATERS   4

Max hops in route.

◆ NODEPARM_MAX

#define NODEPARM_MAX   35

Max. number of parameters.

The Z Wave transport layer controls transfer of data between Z Wave nodes including retransmission, frame check, and acknowledgment. The Z Wave transport interface includes functions for transfer of data to other Z Wave nodes. Application data received from other nodes is handed over to the application via the application_command_handler_function function. The ZW_MAX_NODES define defines the maximum of nodes possible in a Z Wave network.

◆ PROTOCOL_METADATA_LENGTH

#define PROTOCOL_METADATA_LENGTH
Value:
(sizeof(uint8_t) + sizeof(uint8_t) + sizeof(uint32_t) \
+ sizeof(uint8_t))

rf_speed | tx_power | tx_options | callback_id

◆ RECEIVE_STATUS_FOREIGN_FRAME

#define RECEIVE_STATUS_FOREIGN_FRAME   0x40

Received frame is not send to me (rxOptions == x1xxxxxx). Useful only in promiscuous mode

◆ RECEIVE_STATUS_FOREIGN_HOMEID

#define RECEIVE_STATUS_FOREIGN_HOMEID   0x80

Received frame is send on another network (rxOptions == 1xxxxxxx). Useful only in SmartStart - used when receiving INIF from another network

◆ RECEIVE_STATUS_LOW_POWER

#define RECEIVE_STATUS_LOW_POWER   0x02

Received at low output power level, this must have the same value as TRANSMIT_OPTION_LOW_POWER

◆ RECEIVE_STATUS_ROUTED_BUSY

#define RECEIVE_STATUS_ROUTED_BUSY   0x01

◆ RECEIVE_STATUS_TYPE_BROAD

#define RECEIVE_STATUS_TYPE_BROAD   0x04

Received frame is broadcast frame (rxOptions == xxxx01xx)

◆ RECEIVE_STATUS_TYPE_EXPLORE

#define RECEIVE_STATUS_TYPE_EXPLORE   0x10

Received frame is an explore frame (rxOptions == xxx1xxxx). Only TYPE_BROAD can be active at the same time as TYPE_EXPLORE

◆ RECEIVE_STATUS_TYPE_MASK

#define RECEIVE_STATUS_TYPE_MASK   0x0C

Mask for masking out the received frametype bits.

◆ RECEIVE_STATUS_TYPE_MULTI

#define RECEIVE_STATUS_TYPE_MULTI   0x08

Received frame is multicast frame (rxOptions == xxxx10xx)

◆ RECEIVE_STATUS_TYPE_SINGLE

#define RECEIVE_STATUS_TYPE_SINGLE   0x00

Received frame is singlecast frame (rxOptions == xxxx00xx)

◆ RSSI_BELOW_SENSITIVITY

#define RSSI_BELOW_SENSITIVITY   125

No signal detected. The RSSI is too low to measure precisely.

◆ RSSI_MAX_POWER_SATURATED

#define RSSI_MAX_POWER_SATURATED   126

Receiver saturated. RSSI too high to measure precisely.

◆ RSSI_NOT_AVAILABLE

#define RSSI_NOT_AVAILABLE   127

◆ RSSI_RESERVED_START

#define RSSI_RESERVED_START   11

All values above and including RSSI_RESERVED_START are reserved, except those defined above.

◆ TRANSMIT_EXPLORE_OPTION_ACK

#define TRANSMIT_EXPLORE_OPTION_ACK   TRANSMIT_OPTION_ACK

◆ TRANSMIT_EXPLORE_OPTION_LOW_POWER

#define TRANSMIT_EXPLORE_OPTION_LOW_POWER   TRANSMIT_OPTION_LOW_POWER

◆ TRANSMIT_OPTION_2_FOLLOWUP

#define TRANSMIT_OPTION_2_FOLLOWUP   0x08

◆ TRANSMIT_OPTION_2_TRANSPORT_SERVICE

#define TRANSMIT_OPTION_2_TRANSPORT_SERVICE   0x01

◆ TRANSMIT_OPTION_ACK

#define TRANSMIT_OPTION_ACK   0x01

transmit at low output power level (1/3 of normal RF range)

◆ TRANSMIT_OPTION_AUTO_ROUTE

#define TRANSMIT_OPTION_AUTO_ROUTE   0x04

request retransmission via repeater nodes

◆ TRANSMIT_OPTION_EXPLORE

#define TRANSMIT_OPTION_EXPLORE   0x20

Use explore frame if needed.

◆ TRANSMIT_OPTION_LOW_POWER

#define TRANSMIT_OPTION_LOW_POWER   0x02

The multicast frame should be send as a broadcast.

◆ TRANSMIT_OPTION_MULTICAST

#define TRANSMIT_OPTION_MULTICAST   0x40

The the frame as a multicast frame.

◆ TRANSMIT_OPTION_MULTICAST_AS_BROADCAST

#define TRANSMIT_OPTION_MULTICAST_AS_BROADCAST   0x02

◆ TRANSMIT_OPTION_NO_ROUTE

#define TRANSMIT_OPTION_NO_ROUTE   0x10

do not use response route - Even if available

◆ ZW_MAX_CACHED_RETURN_ROUTE_DESTINATIONS

#define ZW_MAX_CACHED_RETURN_ROUTE_DESTINATIONS   5

◆ ZW_RF_TEST_SIGNAL_CARRIER

#define ZW_RF_TEST_SIGNAL_CARRIER   0x00

◆ ZW_RF_TEST_SIGNAL_CARRIER_MODULATED

#define ZW_RF_TEST_SIGNAL_CARRIER_MODULATED   0x01

◆ ZW_ROUTE_LOST_ACCEPT

#define ZW_ROUTE_LOST_ACCEPT   0x05

Accepted to help.

◆ ZW_ROUTE_LOST_FAILED

#define ZW_ROUTE_LOST_FAILED   0x04

Node Asked wont help us.

Typedef Documentation

◆ e_routing_scheme_t

Transport routing scheme state define definitions.

◆ last_route_speed_t

List of possible link speeds / protocols.

◆ protocol_metadata_t

◆ S_ROUTE_LINK

typedef struct _S_ROUTE_LINK_ S_ROUTE_LINK

◆ zwapi_tx_report_t

Detailed report and data about Z-Wave transmissions.

Enumeration Type Documentation

◆ _E_ROUTING_SCHEME_

Transport routing scheme state define definitions.

Enumerator
ROUTINGSCHEME_IDLE 
ROUTINGSCHEME_DIRECT 

Direct.

ROUTINGSCHEME_CACHED_ROUTE_SR 

ApplicationStaticRoute.

ROUTINGSCHEME_CACHED_ROUTE 

ResponseRoute/lastworkingRoute.

ROUTINGSCHEME_CACHED_ROUTE_NLWR 

Next to LastWorkingRoute(controller)

ROUTINGSCHEME_ROUTE 

ReturnRoute/controllerAutoRoute.

ROUTINGSCHEME_RESORT_DIRECT 

directResort

ROUTINGSCHEME_RESORT_EXPLORE 

Explore.

◆ last_route_speed

List of possible link speeds / protocols.

Enumerator
UNKNOWN_SPEED 
ZWAVE_9_6_KBITS_S 

Z-Wave 9.6 kbits/s.

ZWAVE_40_KBITS_S 

Z-Wave 40 kbits/s.

ZWAVE_100_KBITS_S 

Z-Wave 100 kbits/s.

ZWAVE_LONG_RANGE_100_KBITS_S 

Z-Wave Long Range 100 kbits/s.

Function Documentation

◆ zwapi_abort_send_data()

sl_status_t zwapi_abort_send_data ( void  )

Abort the ongoing transmit started with zwapi_send_data() or zwapi_send_data_bridge()

Returns
sl_status_t
Note
If an ongoing transmission is aborted, the callback function from the send call will return with the status TRANSMIT_COMPLETE_NO_ACK.

aka ZW_SendDataAbort

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

◆ zwapi_lock_route()

sl_status_t zwapi_lock_route ( bool  lock)

Lock and unlock a response route for a specific node.

Parameters
lockbool true for lock entry, if false unlock entry
Returns
sl_status_t

aka ZW_LockRoute

Here is the call graph for this function:

◆ zwapi_send_data()

sl_status_t zwapi_send_data ( zwave_node_id_t  destination_node_id,
const uint8_t *  data,
uint8_t  data_length,
uint8_t  tx_options,
void(*)(uint8_t, zwapi_tx_report_t *)  callback_function 
)

Send data to a Z-Wave node or to the broadcast destination.

Parameters
destination_node_iddestination node ID (0xFF == broadcast)
datadata buffer pointer
data_lengthlength of data in data buffer
tx_optionstransmit option flags:
callback_functionpointer to callback function for when the radio transmission is completed. The callback function has 2 arguments: tx_status (uint8_t) that represents the transmission status. tx_status_report (zwapi_tx_report_t) is the transmit status report.
Returns
sl_status_t
Note
: A bridge controller library MUST NOT send to a virtual node that belongs to the bridge itself.

aka ZW_SendData

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

◆ zwapi_send_data_bridge()

sl_status_t zwapi_send_data_bridge ( zwave_node_id_t  source_node_id,
zwave_node_id_t  destination_node_id,
const uint8_t *  data,
uint8_t  data_length,
uint8_t  tx_options,
void(*)(uint8_t, zwapi_tx_report_t *)  callback_function 
)

Transmit data buffer to a single ZW-node or all ZW-nodes (broadcast) in bridge mode.

Parameters
source_node_idsource NodeID. If set to 0xFF then controller ID is set as source
destination_node_iddestination node ID (0xFF == broadcast)
datadata buffer pointer
data_lengthlength of data in data buffer
tx_optionstransmit option flags:
callback_functionpointer to callback function for when the radio transmission is completed. The callback function has 2 arguments: tx_status (uint8_t) that represents the transmission status. (zwapi_tx_report_t) is the transmit status report.
Returns
sl_status_t

aka ZW_SendData_Bridge

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

◆ zwapi_send_data_multi()

sl_status_t zwapi_send_data_multi ( zwave_nodemask_t  destination_node_mask,
const uint8_t *  data,
uint8_t  data_length,
uint8_t  tx_options,
void(*)(uint8_t tx_status)  callback_function 
)

Send data to a list of Z-Wave Nodes (multicast frame).

Parameters
destination_node_masknode mask where the bits corresponding to the destination node IDs must be set.
datadata buffer pointer
data_lengthlength of data in data buffer
tx_optionstransmit option flags
callback_functiontransmit completed call back function
Returns
sl_status_t
Note
This function has been adapted so that both bridge and non-bridge Z-Wave API libraries can call it. In case of a bridge library, the function will send from its actual NodeID.

aka SerialAPI_ZW_SendDataMulti

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

◆ zwapi_send_data_multi_bridge()

sl_status_t zwapi_send_data_multi_bridge ( zwave_node_id_t  source_node_id,
zwave_nodemask_t  destination_node_mask,
const uint8_t *  data,
uint8_t  data_length,
uint8_t  tx_options,
void(*)(uint8_t tx_status)  callback_function 
)

Send data to a list of Z-Wave Nodes (multicast frame) in bridge mode.

Parameters
source_node_idsource nodeID. If set to 0xFF then controller is set as source
destination_node_masknode mask where the bits corresponding to the destination node IDs must be set.
datadata buffer pointer
data_lengthlength of data in data buffer
tx_optionstransmit option flags
callback_functiontransmit completed call back function
Returns
sl_status_t
Note
This function should be used also when the ZPC is the source node because the function zwapi_send_data_multi() is not available on a chip with bridge controller library (which is what the ZPC uses).

aka SerialAPI_ZW_SendDataMulti_Bridge

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

◆ zwapi_send_nop()

sl_status_t zwapi_send_nop ( zwave_node_id_t  destination,
uint8_t  tx_options,
void(*)(uint8_t, zwapi_tx_report_t *)  callback_function 
)

Sends a NOP to a NodeID destination.

Returns
SL_STATUS_OK if the send_data was initiated. SL_STATUS_FAIL if the send_data was rejected. SL_STATUS_NOT_SUPPORTED if the Z-Wave API command is not supported.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ zwapi_send_protocol_data()

sl_status_t zwapi_send_protocol_data ( zwave_node_id_t  destination_node_id,
const uint8_t *  data,
uint8_t  data_length,
void *  metadata,
void(*)(uint8_t, zwapi_tx_report_t *)  callback_function 
)

Send protocol data to a Z-Wave node.

Parameters
destination_node_iddestination node ID
datadata buffer pointer
data_lengthlength of data in data buffer
metadatametadata buffer pointer
callback_functionpointer to callback function for when the radio transmission is completed. The callback function has 2 arguments: tx_status (uint8_t) that represents the transmission status. tx_status_report (zwapi_tx_report_t) is the transmit status report.
Returns
sl_status_t

aka ZW_SendProtocolData

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