nrf_802154_ack_data_set()

bool nrf_802154_ack_data_set	(	const uint8_t *	p_addr,
		bool	extended,
		const void *	p_data,
		uint16_t	length,
		nrf_802154_ack_data_t	data_type
	)

#include <nrf_802154/common/include/nrf_802154.h>

Adds the address of a peer node for which the provided ACK data is to be injected into generated ACKs.

Data passed to this function can be either pending bit data or Header IE data.

The pending bit list works differently, depending on the upper layer for which the source address matching method is selected:

• For Thread, NRF_802154_SRC_ADDR_MATCH_THREAD
• For Zigbee, NRF_802154_SRC_ADDR_MATCH_ZIGBEE
• For Standard-compliant, NRF_802154_SRC_ADDR_MATCH_ALWAYS_1 For more information, see nrf_802154_src_addr_match_t.

For IE data, specific cases are supported, where additional data will be injected into the IE on pre-transmission:

• CSL IE - CSL phase will be injected if IE ID is set to IE_CSL_ID
• Thread link metrics - Link metrics will be injected if
  • IE ID is set to IE_VENDOR_ID
  • OUI is set to IE_VENDOR_THREAD_OUI
  • Thread IE subtype is set to IE_VENDOR_THREAD_ACK_PROBING_ID

For Link metrics to be injected, additional preparation is required. Each byte of injected link metrics needs to be filled with a token, indicating what type of data is to be injected pre-transmission. Supported tokens are:

• IE_VENDOR_THREAD_RSSI_TOKEN - RSSI of the last received frame will be injected,
• IE_VENDOR_THREAD_MARGIN_TOKEN - RSSI above sensitivity margin of the last received frame will be injected,
• IE_VENDOR_THREAD_LQI_TOKEN - LQI of the last received frame will be injected. Additionally, tokens must be unique in given IE, all bytes prepared for link metrics must be filled with tokens and no more than two bytes must be prepared for link metrics. If any of those conditions is not met, no data will be injected into the ACK pre-transmission.

To better illustrate, if RSSI is to be inserted into ACKs for specific address, following ie data needs to be prepared:

* +------------+----------------------+---------------------------------+-----------------------------+
* | Bytes: 0-1 |          2-4         |                5                |              6              |
* +------------+----------------------+---------------------------------+-----------------------------+
* | IE header  | IE_VENDOR_THREAD_OUI | IE_VENDOR_THREAD_ACK_PROBING_ID | IE_VENDOR_THREAD_RSSI_TOKEN |
* +------------+----------------------+---------------------------------+-----------------------------+
*                                     |                                                               |
*                                     | <------------------IE Vendor-specific data------------------> |
* 

When sending ACK with this data, before transmission, RSSI of the last received frame will be written into byte 6.

The method can be set during initialization phase by calling nrf_802154_src_addr_matching_method_set.

Parameters

[in]	p_addr	Array of bytes containing the address of the node (little-endian).
[in]	extended	If the given address is an extended MAC address or a short MAC address.
[in]	p_data	Pointer to the buffer containing data to be set.
[in]	length	Length of p_data.
[in]	data_type	Type of data to be set. Refer to the nrf_802154_ack_data_t type.

Return values

True	Address successfully added to the list.
False	Not enough memory to store this address in the list.