This component is responsible transmission of application frames. More...

Collaboration diagram for Z-Wave TX:

Modules
	Z-Wave TX Options QoS priority
	QoS Priority for Z-Wave TX Options.

	Z-Wave TX Interface
	This is the public interface for the Z-Wave TX component.

	Z-Wave TX Fixture
	Z-Wave TX fixture starts the Z-Wave TX process.

	Z-Wave TX Callbacks
	Z-Wave TX Callbacks registered to other components.

	Z-Wave Tx Incoming frames
	Small module that helps keeping track of incoming frames from remote NodeIDs.

	Z-Wave TX Process
	Z-Wave TX process taking care of the TX Queue and interfaces with the Z-Wave API.

	Z-Wave TX queue
	Data model definition for the Z-Wave TX Queue and its elements.

	Z-Wave Tx Route cache
	Caches route data with NodeID destinations.

Typedefs
typedef void(*	on_zwave_tx_send_data_complete_t) (uint8_t status, const zwapi_tx_report_t tx_info, void user)
	Function signature for callbacks invoked when send data has completed. More...

Functions
sl_status_t	zwave_tx_send_data (const zwave_controller_connection_info_t connection, uint16_t data_length, const uint8_t data, const zwave_tx_options_t tx_options, const on_zwave_tx_send_data_complete_t on_send_complete, void user, zwave_tx_session_id_t *session)
	Queue and send frames to Z-Wave nodes. More...

sl_status_t	zwave_tx_send_test_frame (zwave_node_id_t destination_node_id, rf_power_level_t power_level, const on_zwave_tx_send_data_complete_t on_send_complete, void user, zwave_tx_session_id_t session_id)
	Queues and send a test frame to a Z-Wave node. More...

sl_status_t	zwave_tx_abort_transmission (zwave_tx_session_id_t session_id)
	Abort a queued or ongoing transmission. More...

uint8_t	zwave_tx_get_number_of_responses (zwave_tx_session_id_t session_id)
	Returns the total number of responses that a frame (and its parent) will generate *. More...

void	zwave_tx_set_expected_frames (zwave_node_id_t remote_node_id, uint8_t number_of_incoming_frames)
	Tell the Tx Queue that a remote NodeID is about to send some frames and we should back-off a little more. More...

const uint8_t *	zwave_tx_get_frame (zwave_tx_session_id_t session_id)
	Returns a pointer to frame data for a given Z-Wave Tx session ID. More...

uint16_t	zwave_tx_get_frame_length (zwave_tx_session_id_t session_id)
	Returns the length of a frame in the Z-Wave Tx Queue. More...

bool	zwave_tx_has_frames_for_node (zwave_node_id_t node_id)
	Verifies if we have frames in the queue to send to a NodeID. More...

sl_status_t	zwave_tx_init ()
	Initialize the zwave_tx component. More...

void	zwave_tx_log_queue (bool with_contents)
	Log the contents of the TX Queue. More...

void	zwave_tx_log_element (zwave_tx_session_id_t session_id, bool log_frame_payload)
	Log the details about an element in the Tx Queue. More...

int	zwave_tx_get_queue_size ()
	Returns the current number of elements in the Tx Queue. More...

Detailed Description

This component is responsible transmission of application frames.

This component handles all the queuing logic regarding Z-Wave frames transmissions, including back-off to wait for responses.

The component features a prioritized queue by QoS. Frames with the highest QoS are transmitted first. There is no guarantee over the order of elements with identical QoS. The low-level encapsulation control frames, such as nonce report etc, must be given the highest priority.

When frames need encapsulation, they are passed to the Z-Wave Transports, which in turns will either send the frame (e.g. Z-Wave API) or re-queue an "encapsulated version/copy" of the original frame. The original frame is called a parent frame, while the new version is a child frame.

When a frame transmission is initiated, the frame and all its children frames will be processed first, even if a higher QoS frame is placed in the queue in the meantime.

The external interface is described in Z-Wave TX Interface.

There are a few internal sub-modules:

Z-Wave TX Callbacks is a list of callbacks registered to other components.
Z-Wave TX Process takes care of processing the queue and interfacing with Z-Wave Transports.
Z-Wave TX queue is the data model definition for the Z-Wave TX queue ands its elements.

The component interactions during frame transmission is depicted in the figure below:

An example where frames need to be encapsulated or require other frames to be sent first is shown in the diagram below:

Typedef Documentation

◆ on_zwave_tx_send_data_complete_t

typedef void(* on_zwave_tx_send_data_complete_t) (uint8_t status, const zwapi_tx_report_t *tx_info, void *user)

Function signature for callbacks invoked when send data has completed.

Function Documentation

◆ zwave_tx_abort_transmission()

sl_status_t zwave_tx_abort_transmission ( zwave_tx_session_id_t session_id )

Abort a queued or ongoing transmission.

Calling this function will attempt to cancel/abort a queued transmission.

Parameters

session_id Session id returned by zwave_tx_send_data

Returns

SL_STATUS_OK if the frame transmission has been aborted (removed from the queue and not sent)
SL_STATUS_NOT_FOUND if the session_id is not valid.

Here is the caller graph for this function:

◆ zwave_tx_get_frame()

const uint8_t * zwave_tx_get_frame ( zwave_tx_session_id_t session_id )

Returns a pointer to frame data for a given Z-Wave Tx session ID.

Parameters

session_id Session id returned by zwave_tx_send_data for a queue element

Returns: NULL if the session ID is not found, else a pointer to a payload.

Here is the caller graph for this function:

◆ zwave_tx_get_frame_length()

uint16_t zwave_tx_get_frame_length ( zwave_tx_session_id_t session_id )

Returns the length of a frame in the Z-Wave Tx Queue.

Parameters

session_id Session id returned by zwave_tx_send_data for a queue element

Returns: 0 if the session ID is not found, the length of the frame in bytes.

Here is the caller graph for this function:

◆ zwave_tx_get_number_of_responses()

uint8_t zwave_tx_get_number_of_responses ( zwave_tx_session_id_t session_id )

Returns the total number of responses that a frame (and its parent) will generate *.

Parameters

session_id Session id returned by zwave_tx_send_data for a queue element

Returns: The number of expected responses for the element identified by the Session ID. 0 if the Session ID does not exist or has been removed from the Tx Queue.

Here is the caller graph for this function:

◆ zwave_tx_get_queue_size()

int zwave_tx_get_queue_size ( )

Returns the current number of elements in the Tx Queue.

Returns: int

◆ zwave_tx_has_frames_for_node()

bool zwave_tx_has_frames_for_node ( zwave_node_id_t node_id )

Verifies if we have frames in the queue to send to a NodeID.

Parameters

node_id NodeID to check for in the queue

Note that this function will return true when we are backing off waiting for an answer following a frame we have just sent, because the frame is still in the queue.

Returns: true if we have frames to send to the NodeID, false otherwise.

Here is the caller graph for this function:

◆ zwave_tx_init()

sl_status_t zwave_tx_init ( )

Initialize the zwave_tx component.

Z-Wave Tx will register an on_frame_received() callback to the Z-Wave Controller

Returns: SL_STATUS_OK on success.

◆ zwave_tx_log_element()

void zwave_tx_log_element	(	zwave_tx_session_id_t	session_id,
		bool	log_frame_payload
	)

Log the details about an element in the Tx Queue.

Parameters

session_id	Session id returned by zwave_tx_send_data
log_frame_payload	Display the frame payload in the logs

◆ zwave_tx_log_queue()

void zwave_tx_log_queue ( bool with_contents )

Log the contents of the TX Queue.

Parameters

with_contents will print out the content of each queue element

◆ zwave_tx_send_data()

sl_status_t zwave_tx_send_data	(	const zwave_controller_connection_info_t *	connection,
		uint16_t	data_length,
		const uint8_t *	data,
		const zwave_tx_options_t *	tx_options,
		const on_zwave_tx_send_data_complete_t	on_send_complete,
		void *	user,
		zwave_tx_session_id_t *	session
	)

Queue and send frames to Z-Wave nodes.

This function is used to transmitting Z-Wave frames. The provided payload will be encapsulated into the format described in connection->encapsulation. This module does not verify if the destination actually supports the requested encapsulation, or if the destination exists at all (NodeID / Endpoint).

This module will put all frames on a queue. The frames with the highest qos_priority will be send first. the tx_options and connection parameters allow all kind of frames to be transmitted, including multicast/broadcast.

Parameters

connection	Connection object describing the source and destination. If either the source or destination endpoints ID are not null, the frame will be Multi Channel encapsulated.
data_length	Length of the frame to send
data	Points to the payload to send
tx_options	Transmit options to use.
on_send_complete	Callback function that will be called when the send operation has completed
user	User pointer passed in argument of the on_send_complete callback function
session	Pointer to location where to write the session id of the queued message. If this is set NULL the session id will not be written

Returns

SL_STATUS_OK The transmission request has been accepted and callback will be triggered when the operation is completed.
SL_STATUS_FAIL The transmission request has been rejected, callback will not be called.

Here is the caller graph for this function:

◆ zwave_tx_send_test_frame()

sl_status_t zwave_tx_send_test_frame	(	zwave_node_id_t	destination_node_id,
		rf_power_level_t	power_level,
		const on_zwave_tx_send_data_complete_t	on_send_complete,
		void *	user,
		zwave_tx_session_id_t *	session_id
	)

Queues and send a test frame to a Z-Wave node.

This function is used for sending a special test frame that will be testing the direct range connectivity of a remote Z-Wave Node.

Test frame are automatically send with the lowest priority.

Parameters

destination_node_id	Z-Wave NodeID of the destination.
power_level	Powerlevel setting to apply for the transmission. Refer to rf_power_level_t
on_send_complete	Callback function that will be called when the send operation is completed
user	User pointer passed in argument of the on_send_complete callback function
session_id	Pointer to location where to write the session id of the queued message. If this is set NULL the session id will not be written

Returns

SL_STATUS_OK The transmission request has been accepted and callback will be triggered when the operation is completed.
SL_STATUS_FAIL The transmission request has been rejected, callback will not be called.

Here is the caller graph for this function:

◆ zwave_tx_set_expected_frames()

void zwave_tx_set_expected_frames	(	zwave_node_id_t	remote_node_id,
		uint8_t	number_of_incoming_frames
	)

Tell the Tx Queue that a remote NodeID is about to send some frames and we should back-off a little more.

Calling this function back-to-back with the same NodeID will update the number of frames that we are expecting from a given NodeID.

Parameters

remote_node_id	The NodeID that is about to send us something.
number_of_incoming_frames	The number of expected frames

Here is the caller graph for this function:

Modules

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ on_zwave_tx_send_data_complete_t

Function Documentation

◆ zwave_tx_abort_transmission()

◆ zwave_tx_get_frame()

◆ zwave_tx_get_frame_length()

◆ zwave_tx_get_number_of_responses()

◆ zwave_tx_get_queue_size()

◆ zwave_tx_has_frames_for_node()

◆ zwave_tx_init()

◆ zwave_tx_log_element()

◆ zwave_tx_log_queue()

◆ zwave_tx_send_data()

◆ zwave_tx_send_test_frame()

◆ zwave_tx_set_expected_frames()