IEEE 802.15.4 Drivers

IEEE 802.15.4 driver API. More...

Data Structures
struct	ieee802154_header_ie_vendor_specific
	Vendor Specific Header IE, see section 7.4.2.3. More...
struct	ieee802154_header_ie_csl_full
	Full CSL IE, see section 7.4.2.3. More...
struct	ieee802154_header_ie_csl_reduced
	Reduced CSL IE, see section 7.4.2.3. More...
struct	ieee802154_header_ie_csl
	Generic CSL IE, see section 7.4.2.3. More...
struct	ieee802154_header_ie_rit
	RIT IE, see section 7.4.2.4. More...
struct	ieee802154_header_ie_rendezvous_time_full
	Full Rendezvous Time IE, see section 7.4.2.6 (macCslInterval is nonzero). More...
struct	ieee802154_header_ie_rendezvous_time_reduced
	Reduced Rendezvous Time IE, see section 7.4.2.6 (macCslInterval is zero). More...
struct	ieee802154_header_ie_rendezvous_time
	Rendezvous Time IE, see section 7.4.2.6. More...
struct	ieee802154_header_ie_time_correction
	Time Correction IE, see section 7.4.2.7. More...
struct	ieee802154_phy_channel_range
	Represents a supported channel range, see ieee802154_phy_supported_channels. More...
struct	ieee802154_phy_supported_channels
	Represents a list channels supported by a driver for a given interface, see IEEE802154_ATTR_PHY_SUPPORTED_CHANNEL_RANGES. More...
struct	ieee802154_filter
	Filter value, see ieee802154_radio_api::filter. More...
struct	ieee802154_key
	Key configuration for transmit security offloading, see IEEE802154_CONFIG_MAC_KEYS. More...
struct	ieee802154_config
	IEEE 802.15.4 driver configuration data. More...
struct	ieee802154_attr_value
	IEEE 802.15.4 driver attribute values. More...
struct	ieee802154_radio_api
	IEEE 802.15.4 driver interface API. More...

IEEE 802.15.4, section 7.4.2: MAC header information elements
enum	ieee802154_ie_type { IEEE802154_IE_TYPE_HEADER = 0x0 , IEEE802154_IE_TYPE_PAYLOAD }
	Information Element Types. More...
enum	ieee802154_header_ie_element_id {   IEEE802154_HEADER_IE_ELEMENT_ID_VENDOR_SPECIFIC_IE = 0x00 , IEEE802154_HEADER_IE_ELEMENT_ID_CSL_IE = 0x1a , IEEE802154_HEADER_IE_ELEMENT_ID_RIT_IE = 0x1b , IEEE802154_HEADER_IE_ELEMENT_ID_RENDEZVOUS_TIME_IE = 0x1d ,   IEEE802154_HEADER_IE_ELEMENT_ID_TIME_CORRECTION_IE = 0x1e , IEEE802154_HEADER_IE_ELEMENT_ID_HEADER_TERMINATION_1 = 0x7e , IEEE802154_HEADER_IE_ELEMENT_ID_HEADER_TERMINATION_2 = 0x7f }
	Header Information Element IDs. More...
static int16_t	ieee802154_header_ie_get_time_correction_us (struct ieee802154_header_ie_time_correction *ie)
	Retrieve the time correction value in microseconds from a Time Correction IE, see section 7.4.2.7.
static void	ieee802154_header_ie_set_element_id (struct ieee802154_header_ie *ie, uint8_t element_id)
	Set the element ID of a header IE.
static uint8_t	ieee802154_header_ie_get_element_id (struct ieee802154_header_ie *ie)
	Get the element ID of a header IE.
#define	IEEE802154_HEADER_IE_HEADER_LENGTH   sizeof(uint16_t)
	The header IE's header length (2 bytes).
#define	IEEE802154_DEFINE_HEADER_IE_VENDOR_SPECIFIC(_vendor_oui, _vendor_specific_info, _vendor_specific_info_len)
	Define a vendor specific header IE, see section 7.4.2.3.
#define	IEEE802154_DEFINE_HEADER_IE_CSL_REDUCED(_csl_phase, _csl_period)
	Define a reduced CSL IE, see section 7.4.2.3.
#define	IEEE802154_DEFINE_HEADER_IE_CSL_FULL(_csl_phase, _csl_period, _csl_rendezvous_time)
	Define a full CSL IE, see section 7.4.2.3.
#define	IEEE802154_DEFINE_HEADER_IE_TIME_CORRECTION(_ack, _time_correction_us)
	Define a Time Correction IE, see section 7.4.2.7.
#define	IEEE802154_TIME_CORRECTION_HEADER_IE_LEN    (IEEE802154_HEADER_IE_HEADER_LENGTH + sizeof(struct ieee802154_header_ie_time_correction))
	The length in bytes of a "Time Correction" header IE.
#define	IEEE802154_HEADER_TERMINATION_1_HEADER_IE_LEN   IEEE802154_HEADER_IE_HEADER_LENGTH
	The length in bytes of a "Header Termination 1" header IE.

IEEE 802.15.4-2020, Section 10: General PHY requirements
enum	ieee802154_phy_channel_page {   IEEE802154_ATTR_PHY_CHANNEL_PAGE_ZERO_OQPSK_2450_BPSK_868_915 = BIT(0) , IEEE802154_ATTR_PHY_CHANNEL_PAGE_ONE_DEPRECATED = BIT(1) , IEEE802154_ATTR_PHY_CHANNEL_PAGE_TWO_OQPSK_868_915 = BIT(2) , IEEE802154_ATTR_PHY_CHANNEL_PAGE_THREE_CSS = BIT(3) ,   IEEE802154_ATTR_PHY_CHANNEL_PAGE_FOUR_HRP_UWB = BIT(4) , IEEE802154_ATTR_PHY_CHANNEL_PAGE_FIVE_OQPSK_780 = BIT(5) , IEEE802154_ATTR_PHY_CHANNEL_PAGE_SIX_RESERVED = BIT(6) , IEEE802154_ATTR_PHY_CHANNEL_PAGE_SEVEN_MSK = BIT(7) ,   IEEE802154_ATTR_PHY_CHANNEL_PAGE_EIGHT_LRP_UWB = BIT(8) , IEEE802154_ATTR_PHY_CHANNEL_PAGE_NINE_SUN_PREDEFINED = BIT(9) , IEEE802154_ATTR_PHY_CHANNEL_PAGE_TEN_SUN_FSK_GENERIC = BIT(10) , IEEE802154_ATTR_PHY_CHANNEL_PAGE_ELEVEN_OQPSK_2380 = BIT(11) ,   IEEE802154_ATTR_PHY_CHANNEL_PAGE_TWELVE_LECIM = BIT(12) , IEEE802154_ATTR_PHY_CHANNEL_PAGE_THIRTEEN_RCC = BIT(13) }
	PHY channel pages, see section 10.1.3. More...
#define	IEEE802154_DEFINE_PHY_SUPPORTED_CHANNELS(drv_attr, from, to)
	Allocate memory for the supported channels driver attribute with a single channel range constant across all driver instances.

IEEE 802.15.4-2020, Section 15: HRP UWB PHY
For HRP UWB the symbol period is derived from the preamble symbol period (T_psym), see section 11.3, table 11-1 and section 15.2.5, table 15-4 (confirmed in IEEE 802.15.4z, section 15.1). Choosing among those periods cannot be done based on channel page and channel alone. The mean pulse repetition frequency must also be known, see the 'UwbPrf' parameter of the MCPS-DATA.request primitive (section 8.3.2, table 8-88) and the preamble parameters for HRP-ERDEV length 91 codes (IEEE 802.15.4z, section 15.2.6.2, table 15-7b).
enum	ieee802154_phy_hrp_uwb_nominal_prf {   IEEE802154_PHY_HRP_UWB_PRF_OFF = 0 , IEEE802154_PHY_HRP_UWB_NOMINAL_4_M = BIT(0) , IEEE802154_PHY_HRP_UWB_NOMINAL_16_M = BIT(1) , IEEE802154_PHY_HRP_UWB_NOMINAL_64_M = BIT(2) ,   IEEE802154_PHY_HRP_UWB_NOMINAL_64_M_BPRF = BIT(3) , IEEE802154_PHY_HRP_UWB_NOMINAL_128_M_HPRF = BIT(4) , IEEE802154_PHY_HRP_UWB_NOMINAL_256_M_HPRF = BIT(5) }
	represents the nominal pulse rate frequency of an HRP UWB PHY More...
#define	IEEE802154_PHY_HRP_UWB_PRF4_TPSYM_SYMBOL_PERIOD_NS   3974.36F
	Nominal PRF 4MHz symbol period.
#define	IEEE802154_PHY_HRP_UWB_PRF16_TPSYM_SYMBOL_PERIOD_NS   993.59F
	Nominal PRF 16MHz symbol period.
#define	IEEE802154_PHY_HRP_UWB_PRF64_TPSYM_SYMBOL_PERIOD_NS   1017.63F
	Nominal PRF 64MHz symbol period.
#define	IEEE802154_PHY_HRP_UWB_ERDEV_TPSYM_SYMBOL_PERIOD_NS   729.17F
	ERDEV symbol period.
#define	IEEE802154_PHY_HRP_UWB_RDEV
	RDEV device mask.
#define	IEEE802154_PHY_HRP_UWB_ERDEV
	ERDEV device mask.

IEEE 802.15.4 Driver API
enum	ieee802154_hw_caps {   IEEE802154_HW_ENERGY_SCAN = BIT(0) , IEEE802154_HW_FCS = BIT(1) , IEEE802154_HW_FILTER = BIT(2) , IEEE802154_HW_PROMISC = BIT(3) ,   IEEE802154_HW_CSMA = BIT(4) , IEEE802154_HW_TX_RX_ACK = BIT(5) , IEEE802154_HW_RETRANSMISSION = BIT(6) , IEEE802154_HW_RX_TX_ACK = BIT(7) ,   IEEE802154_HW_TXTIME = BIT(8) , IEEE802154_HW_SLEEP_TO_TX = BIT(9) , IEEE802154_HW_RXTIME = BIT(10) , IEEE802154_HW_TX_SEC = BIT(11) ,   IEEE802154_RX_ON_WHEN_IDLE = BIT(12) }
	IEEE 802.15.4 driver capabilities. More...
enum	ieee802154_filter_type {   IEEE802154_FILTER_TYPE_IEEE_ADDR , IEEE802154_FILTER_TYPE_SHORT_ADDR , IEEE802154_FILTER_TYPE_PAN_ID , IEEE802154_FILTER_TYPE_SRC_IEEE_ADDR ,   IEEE802154_FILTER_TYPE_SRC_SHORT_ADDR }
	Filter type, see ieee802154_radio_api::filter. More...
enum	ieee802154_event { IEEE802154_EVENT_TX_STARTED , IEEE802154_EVENT_RX_FAILED , IEEE802154_EVENT_RX_OFF }
	Driver events, see IEEE802154_CONFIG_EVENT_HANDLER. More...
enum	ieee802154_rx_fail_reason { IEEE802154_RX_FAIL_NOT_RECEIVED , IEEE802154_RX_FAIL_INVALID_FCS , IEEE802154_RX_FAIL_ADDR_FILTERED , IEEE802154_RX_FAIL_OTHER }
	RX failed event reasons, see IEEE802154_EVENT_RX_FAILED. More...
enum	ieee802154_tx_mode {   IEEE802154_TX_MODE_DIRECT , IEEE802154_TX_MODE_CCA , IEEE802154_TX_MODE_CSMA_CA , IEEE802154_TX_MODE_TXTIME ,   IEEE802154_TX_MODE_TXTIME_CCA , IEEE802154_TX_MODE_COMMON_COUNT , IEEE802154_TX_MODE_PRIV_START = IEEE802154_TX_MODE_COMMON_COUNT }
	IEEE 802.15.4 Transmission mode. More...
enum	ieee802154_fpb_mode { IEEE802154_FPB_ADDR_MATCH_THREAD , IEEE802154_FPB_ADDR_MATCH_ZIGBEE }
	IEEE 802.15.4 Frame Pending Bit table address matching mode. More...
enum	ieee802154_config_type {   IEEE802154_CONFIG_AUTO_ACK_FPB , IEEE802154_CONFIG_ACK_FPB , IEEE802154_CONFIG_PAN_COORDINATOR , IEEE802154_CONFIG_PROMISCUOUS ,   IEEE802154_CONFIG_EVENT_HANDLER , IEEE802154_CONFIG_MAC_KEYS , IEEE802154_CONFIG_FRAME_COUNTER , IEEE802154_CONFIG_FRAME_COUNTER_IF_LARGER ,   IEEE802154_CONFIG_RX_SLOT , IEEE802154_CONFIG_CSL_PERIOD , IEEE802154_CONFIG_EXPECTED_RX_TIME , IEEE802154_CONFIG_ENH_ACK_HEADER_IE ,   IEEE802154_CONFIG_RX_ON_WHEN_IDLE , IEEE802154_CONFIG_COMMON_COUNT , IEEE802154_CONFIG_PRIV_START = IEEE802154_CONFIG_COMMON_COUNT }
	IEEE 802.15.4 driver configuration types. More...
enum	ieee802154_attr {   IEEE802154_ATTR_PHY_SUPPORTED_CHANNEL_PAGES , IEEE802154_ATTR_PHY_SUPPORTED_CHANNEL_RANGES , IEEE802154_ATTR_PHY_HRP_UWB_SUPPORTED_PRFS , IEEE802154_ATTR_COMMON_COUNT ,   IEEE802154_ATTR_PRIV_START = IEEE802154_ATTR_COMMON_COUNT }
	IEEE 802.15.4 driver attributes. More...
typedef void(*	energy_scan_done_cb_t) (const struct device *dev, int16_t max_ed)
	Energy scan callback.
typedef void(*	ieee802154_event_cb_t) (const struct device *dev, enum ieee802154_event evt, void *event_params)
	Driver event callback.
static int	ieee802154_attr_get_channel_page_and_range (enum ieee802154_attr attr, const enum ieee802154_phy_channel_page phy_supported_channel_page, const struct ieee802154_phy_supported_channels *phy_supported_channels, struct ieee802154_attr_value *value)
	Helper function to handle channel page and range to be called from drivers' attr_get() implementation.
#define	IEEE802154_HW_CAPS_BITS_COMMON_COUNT   (13)
	Number of bits used by ieee802154_hw_caps type.
#define	IEEE802154_HW_CAPS_BITS_PRIV_START   IEEE802154_HW_CAPS_BITS_COMMON_COUNT
	This and higher values are specific to the protocol- or driver-specific extensions.
#define	IEEE802154_CONFIG_RX_SLOT_NONE   -1LL
	Configuring an RX slot with the start parameter set to this value will cancel and delete any previously configured RX slot.
#define	IEEE802154_CONFIG_RX_SLOT_OFF   0LL
	Configuring an RX slot with this start parameter while the driver is "down", will keep RX off when the driver is being started.

IEEE 802.15.4 driver utils
static bool	ieee802154_is_ar_flag_set (struct net_buf *frag)
	Check if the AR flag is set on the frame inside the given Network Packet Library.

IEEE 802.15.4 driver callbacks
enum net_verdict	ieee802154_handle_ack (struct net_if *iface, struct net_pkt *pkt)
	IEEE 802.15.4 driver ACK handling callback into L2 that drivers must call when receiving an ACK package.
void	ieee802154_init (struct net_if *iface)
	IEEE 802.15.4 driver initialization callback into L2 called by drivers to initialize the active L2 stack for a given interface.

IEEE 802.15.4-2020, Section 6: MAC functional description
#define	IEEE802154_PHY_SYMBOLS_PER_SECOND(symbol_period_ns)   (NSEC_PER_SEC / symbol_period_ns)
	The symbol period (and therefore symbol rate) is defined in section 6.1: "Some of the timing parameters in definition of the MAC are in units of PHY symbols.

IEEE 802.15.4-2020, Section 8: MAC services
#define	IEEE802154_MAC_A_BASE_SLOT_DURATION   60U
	The number of PHY symbols forming a superframe slot when the superframe order is equal to zero, see sections 8.4.2, table 8-93, aBaseSlotDuration and section 6.2.1.
#define	IEEE802154_MAC_A_NUM_SUPERFRAME_SLOTS   16U
	The number of slots contained in any superframe, see section 8.4.2, table 8-93, aNumSuperframeSlots.
#define	IEEE802154_MAC_A_BASE_SUPERFRAME_DURATION    (IEEE802154_MAC_A_BASE_SLOT_DURATION * IEEE802154_MAC_A_NUM_SUPERFRAME_SLOTS)
	The number of PHY symbols forming a superframe when the superframe order is equal to zero, see section 8.4.2, table 8-93, aBaseSuperframeDuration.
#define	IEEE802154_MAC_A_UNIT_BACKOFF_PERIOD(turnaround_time)    (turnaround_time + IEEE802154_PHY_A_CCA_TIME)
	MAC PIB attribute aUnitBackoffPeriod, see section 8.4.2, table 8-93, in symbol periods, valid for all PHYs except SUN PHY in the 920 MHz band.
#define	IEEE802154_MAC_RESPONSE_WAIT_TIME_DEFAULT   32U
	Default macResponseWaitTime in multiples of aBaseSuperframeDuration as defined in section 8.4.3.1, table 8-94.

IEEE 802.15.4-2020, Section 11: PHY services
#define	IEEE802154_PHY_A_TURNAROUND_TIME_DEFAULT   12U
	Default PHY PIB attribute aTurnaroundTime, in PHY symbols, see section 11.3, table 11-1.
#define	IEEE802154_PHY_A_TURNAROUND_TIME_1MS(symbol_period_ns)    DIV_ROUND_UP(NSEC_PER_MSEC, symbol_period_ns)
	PHY PIB attribute aTurnaroundTime for SUN, RS-GFSK, TVWS, and LECIM FSK PHY, in PHY symbols, see section 11.3, table 11-1.
#define	IEEE802154_PHY_A_CCA_TIME   8U
	PHY PIB attribute aCcaTime, in PHY symbols, all PHYs except for SUN O-QPSK, see section 11.3, table 11-1.

IEEE 802.15.4-2020, Section 12: O-QPSK PHY
#define	IEEE802154_PHY_OQPSK_868MHZ_SYMBOL_PERIOD_NS   40000LL
	O-QPSK 868Mhz band symbol period, see section 12.3.3.
#define	IEEE802154_PHY_OQPSK_780_TO_2450MHZ_SYMBOL_PERIOD_NS   16000LL
	O-QPSK 780MHz, 915MHz, 2380MHz and 2450MHz bands symbol period, see section 12.3.3.

IEEE 802.15.4-2020, Section 13: BPSK PHY
#define	IEEE802154_PHY_BPSK_868MHZ_SYMBOL_PERIOD_NS   50000LL
	BPSK 868MHz band symbol period, see section 13.3.3.
#define	IEEE802154_PHY_BPSK_915MHZ_SYMBOL_PERIOD_NS   25000LL
	BPSK 915MHz band symbol period, see section 13.3.3.

IEEE 802.15.4-2020, Section 19: SUN FSK PHY
#define	IEEE802154_PHY_SUN_FSK_863MHZ_915MHZ_SYMBOL_PERIOD_NS   20000LL
	SUN FSK 863Mhz and 915MHz band symbol periods, see section 19.1, table 19-1.
#define	IEEE802154_PHY_SUN_FSK_PHR_LEN   2
	SUN FSK PHY header length, in bytes, see section 19.2.4.

Detailed Description

IEEE 802.15.4 driver API.

Since

1.0

Version

0.8.0

This API provides a common representation of vendor-specific hardware and firmware to the native IEEE 802.15.4 L2 and OpenThread stacks. Application developers should never interface directly with this API. It is of interest to driver maintainers only.

The IEEE 802.15.4 driver API consists of two separate parts:

• a basic, mostly PHY-level driver API to be implemented by all drivers,
• several optional MAC-level extension points to offload performance critical or timing sensitive aspects at MAC level to the driver hardware or firmware ("hard" MAC).

Implementing the basic driver API will ensure integration with the native L2 stack as well as basic support for OpenThread. Depending on the hardware, offloading to vendor-specific hardware or firmware features may be required to achieve full compliance with the Thread protocol or IEEE 802.15.4 subprotocols (e.g. fast enough ACK packages, precise timing of timed TX/RX in the TSCH or CSL subprotocols).

Whether or not MAC-level offloading extension points need to be implemented is to be decided by individual driver maintainers. Upper layers SHOULD provide a "soft" MAC fallback whenever possible.

Note

All section, table and figure references are to the IEEE 802.15.4-2020 standard.

Macro Definition Documentation

IEEE802154_CONFIG_RX_SLOT_NONE

#define IEEE802154_CONFIG_RX_SLOT_NONE   -1LL

#include <zephyr/net/ieee802154_radio.h>

Configuring an RX slot with the start parameter set to this value will cancel and delete any previously configured RX slot.

IEEE802154_CONFIG_RX_SLOT_OFF

#define IEEE802154_CONFIG_RX_SLOT_OFF   0LL

#include <zephyr/net/ieee802154_radio.h>

Configuring an RX slot with this start parameter while the driver is "down", will keep RX off when the driver is being started.

Configuring an RX slot with this start value while the driver is "up" will immediately switch RX off until either the slot is deleted, see IEEE802154_CONFIG_RX_SLOT_NONE or a slot with a future start parameter is configured and that start time arrives.

IEEE802154_DEFINE_HEADER_IE_CSL_FULL

#define IEEE802154_DEFINE_HEADER_IE_CSL_FULL	(		_csl_phase,
			_csl_period,
			_csl_rendezvous_time
	)

#include <zephyr/net/ieee802154_ie.h>

Value:

        IEEE802154_DEFINE_HEADER_IE(IEEE802154_HEADER_IE_ELEMENT_ID_CSL_IE,                        \
                                    sizeof(struct ieee802154_header_ie_csl_full),                  \
                                    IEEE802154_DEFINE_HEADER_IE_CSL_FULL_CONTENT(                  \
                                            _csl_phase, _csl_period, _csl_rendezvous_time),        \
                                    csl.full)

Define a full CSL IE, see section 7.4.2.3.

Example usage (all parameters in CPU byte order):

uint16_t csl_phase = ...;
uint16_t csl_period = ...;
uint16_t csl_rendezvous_time = ...;
struct ieee802154_header_ie header_ie =
    IEEE802154_DEFINE_HEADER_IE_CSL_REDUCED(csl_phase, csl_period, csl_rendezvous_time);

Parameters

_csl_phase	CSL phase in CPU byte order
_csl_period	CSL period in CPU byte order
_csl_rendezvous_time	CSL rendezvous time in CPU byte order

IEEE802154_DEFINE_HEADER_IE_CSL_REDUCED

#define IEEE802154_DEFINE_HEADER_IE_CSL_REDUCED	(		_csl_phase,
			_csl_period
	)

#include <zephyr/net/ieee802154_ie.h>

Value:

        IEEE802154_DEFINE_HEADER_IE(                                                               \
                IEEE802154_HEADER_IE_ELEMENT_ID_CSL_IE,                                            \
                sizeof(struct ieee802154_header_ie_csl_reduced),                                   \
                IEEE802154_DEFINE_HEADER_IE_CSL_REDUCED_CONTENT(_csl_phase, _csl_period),          \
                csl.reduced)

Define a reduced CSL IE, see section 7.4.2.3.

Example usage (all parameters in CPU byte order):

uint16_t csl_phase = ...;
uint16_t csl_period = ...;
struct ieee802154_header_ie header_ie =
    IEEE802154_DEFINE_HEADER_IE_CSL_REDUCED(csl_phase, csl_period);

Parameters

_csl_phase	CSL phase in CPU byte order
_csl_period	CSL period in CPU byte order

IEEE802154_DEFINE_HEADER_IE_TIME_CORRECTION

#define IEEE802154_DEFINE_HEADER_IE_TIME_CORRECTION	(		_ack,
			_time_correction_us
	)

#include <zephyr/net/ieee802154_ie.h>

Value:

        IEEE802154_DEFINE_HEADER_IE(                                                               \
                IEEE802154_HEADER_IE_ELEMENT_ID_TIME_CORRECTION_IE,                                \
                sizeof(struct ieee802154_header_ie_time_correction),                               \
                IEEE802154_DEFINE_HEADER_IE_TIME_CORRECTION_CONTENT(_ack, _time_correction_us),    \
                time_correction)

Define a Time Correction IE, see section 7.4.2.7.

Example usage (parameter in CPU byte order):

uint16_t time_sync_info = ...;
struct ieee802154_header_ie header_ie =
    IEEE802154_DEFINE_HEADER_IE_TIME_CORRECTION(true, time_sync_info);

Parameters

_ack	whether or not the enhanced ACK frame that receives this IE is an ACK (true) or NACK (false)
_time_correction_us	the positive or negative deviation from expected RX time in microseconds

IEEE802154_DEFINE_HEADER_IE_VENDOR_SPECIFIC

#define IEEE802154_DEFINE_HEADER_IE_VENDOR_SPECIFIC	(		_vendor_oui,
			_vendor_specific_info,
			_vendor_specific_info_len
	)

#include <zephyr/net/ieee802154_ie.h>

Value:

        IEEE802154_DEFINE_HEADER_IE(IEEE802154_HEADER_IE_ELEMENT_ID_VENDOR_SPECIFIC_IE,            \
                                    IEEE802154_DEFINE_HEADER_IE_VENDOR_SPECIFIC_CONTENT_LEN(       \
                                            _vendor_specific_info_len),                            \
                                    IEEE802154_DEFINE_HEADER_IE_VENDOR_SPECIFIC_CONTENT(           \
                                            _vendor_oui, _vendor_specific_info),                   \
                                    vendor_specific)

Define a vendor specific header IE, see section 7.4.2.3.

Example usage (all parameters in little endian):

uint8_t vendor_specific_info[] = {...some vendor specific IE content...};
struct ieee802154_header_ie header_ie = IEEE802154_DEFINE_HEADER_IE_VENDOR_SPECIFIC(
    {0x9b, 0xb8, 0xea}, vendor_specific_info, sizeof(vendor_specific_info));

Parameters

_vendor_oui	an initializer for a 3 byte vendor oui array in little endian
_vendor_specific_info	pointer to a variable length uint8_t array with the vendor specific IE content
_vendor_specific_info_len	the length of the vendor specific IE content (in bytes)

IEEE802154_DEFINE_PHY_SUPPORTED_CHANNELS

#define IEEE802154_DEFINE_PHY_SUPPORTED_CHANNELS	(		drv_attr,
			from,
			to
	)

#include <zephyr/net/ieee802154_radio.h>

Value:

        static const struct {                                                                      \
                const struct ieee802154_phy_channel_range phy_channel_range;                       \
                const struct ieee802154_phy_supported_channels phy_supported_channels;             \
        } drv_attr = {                                                                             \
                .phy_channel_range = {.from_channel = (from), .to_channel = (to)},                 \
                .phy_supported_channels =                                                          \
                        {                                                                          \
                                .ranges = &drv_attr.phy_channel_range,                             \
                                .num_ranges = 1U,                                                  \
                        },                                                                         \
        }

Allocate memory for the supported channels driver attribute with a single channel range constant across all driver instances.

This is what most IEEE 802.15.4 drivers need.

Example usage:

IEEE802154_DEFINE_PHY_SUPPORTED_CHANNELS(drv_attr, 11, 26);

The attribute may then be referenced like this:

... &drv_attr.phy_supported_channels ...

See ieee802154_attr_get_channel_page_and_range() for a further shortcut that can be combined with this macro.

Parameters

drv_attr	name of the local static variable to be declared for the local attributes structure
from	the first channel to be supported
to	the last channel to be supported

IEEE802154_HEADER_IE_HEADER_LENGTH

#define IEEE802154_HEADER_IE_HEADER_LENGTH   sizeof(uint16_t)

#include <zephyr/net/ieee802154_ie.h>

The header IE's header length (2 bytes).

IEEE802154_HEADER_TERMINATION_1_HEADER_IE_LEN

#define IEEE802154_HEADER_TERMINATION_1_HEADER_IE_LEN   IEEE802154_HEADER_IE_HEADER_LENGTH

#include <zephyr/net/ieee802154_ie.h>

The length in bytes of a "Header Termination 1" header IE.

IEEE802154_HW_CAPS_BITS_COMMON_COUNT

#define IEEE802154_HW_CAPS_BITS_COMMON_COUNT   (13)

#include <zephyr/net/ieee802154_radio.h>

Number of bits used by ieee802154_hw_caps type.

IEEE802154_HW_CAPS_BITS_PRIV_START

#define IEEE802154_HW_CAPS_BITS_PRIV_START   IEEE802154_HW_CAPS_BITS_COMMON_COUNT

#include <zephyr/net/ieee802154_radio.h>

This and higher values are specific to the protocol- or driver-specific extensions.

IEEE802154_MAC_A_BASE_SLOT_DURATION

#define IEEE802154_MAC_A_BASE_SLOT_DURATION   60U

#include <zephyr/net/ieee802154_radio.h>

The number of PHY symbols forming a superframe slot when the superframe order is equal to zero, see sections 8.4.2, table 8-93, aBaseSlotDuration and section 6.2.1.

IEEE802154_MAC_A_BASE_SUPERFRAME_DURATION

#define IEEE802154_MAC_A_BASE_SUPERFRAME_DURATION    (IEEE802154_MAC_A_BASE_SLOT_DURATION * IEEE802154_MAC_A_NUM_SUPERFRAME_SLOTS)

#include <zephyr/net/ieee802154_radio.h>

The number of PHY symbols forming a superframe when the superframe order is equal to zero, see section 8.4.2, table 8-93, aBaseSuperframeDuration.

IEEE802154_MAC_A_NUM_SUPERFRAME_SLOTS

#define IEEE802154_MAC_A_NUM_SUPERFRAME_SLOTS   16U

#include <zephyr/net/ieee802154_radio.h>

The number of slots contained in any superframe, see section 8.4.2, table 8-93, aNumSuperframeSlots.

IEEE802154_MAC_A_UNIT_BACKOFF_PERIOD

#define IEEE802154_MAC_A_UNIT_BACKOFF_PERIOD

(

turnaround_time

)

(turnaround_time + IEEE802154_PHY_A_CCA_TIME)

#include <zephyr/net/ieee802154_radio.h>

MAC PIB attribute aUnitBackoffPeriod, see section 8.4.2, table 8-93, in symbol periods, valid for all PHYs except SUN PHY in the 920 MHz band.

IEEE802154_MAC_RESPONSE_WAIT_TIME_DEFAULT

#define IEEE802154_MAC_RESPONSE_WAIT_TIME_DEFAULT   32U

#include <zephyr/net/ieee802154_radio.h>

Default macResponseWaitTime in multiples of aBaseSuperframeDuration as defined in section 8.4.3.1, table 8-94.

IEEE802154_PHY_A_CCA_TIME

#define IEEE802154_PHY_A_CCA_TIME   8U

#include <zephyr/net/ieee802154_radio.h>

PHY PIB attribute aCcaTime, in PHY symbols, all PHYs except for SUN O-QPSK, see section 11.3, table 11-1.

IEEE802154_PHY_A_TURNAROUND_TIME_1MS

#define IEEE802154_PHY_A_TURNAROUND_TIME_1MS

(

symbol_period_ns

)

DIV_ROUND_UP(NSEC_PER_MSEC, symbol_period_ns)

#include <zephyr/net/ieee802154_radio.h>

PHY PIB attribute aTurnaroundTime for SUN, RS-GFSK, TVWS, and LECIM FSK PHY, in PHY symbols, see section 11.3, table 11-1.

IEEE802154_PHY_A_TURNAROUND_TIME_DEFAULT

#define IEEE802154_PHY_A_TURNAROUND_TIME_DEFAULT   12U

#include <zephyr/net/ieee802154_radio.h>

Default PHY PIB attribute aTurnaroundTime, in PHY symbols, see section 11.3, table 11-1.

IEEE802154_PHY_BPSK_868MHZ_SYMBOL_PERIOD_NS

#define IEEE802154_PHY_BPSK_868MHZ_SYMBOL_PERIOD_NS   50000LL

#include <zephyr/net/ieee802154_radio.h>

BPSK 868MHz band symbol period, see section 13.3.3.

IEEE802154_PHY_BPSK_915MHZ_SYMBOL_PERIOD_NS

#define IEEE802154_PHY_BPSK_915MHZ_SYMBOL_PERIOD_NS   25000LL

#include <zephyr/net/ieee802154_radio.h>

BPSK 915MHz band symbol period, see section 13.3.3.

IEEE802154_PHY_HRP_UWB_ERDEV

#define IEEE802154_PHY_HRP_UWB_ERDEV

#include <zephyr/net/ieee802154_radio.h>

Value:

        (IEEE802154_PHY_HRP_UWB_NOMINAL_64_M_BPRF | IEEE802154_PHY_HRP_UWB_NOMINAL_128_M_HPRF |    \
         IEEE802154_PHY_HRP_UWB_NOMINAL_256_M_HPRF)

ERDEV device mask.

IEEE802154_PHY_HRP_UWB_ERDEV_TPSYM_SYMBOL_PERIOD_NS

#define IEEE802154_PHY_HRP_UWB_ERDEV_TPSYM_SYMBOL_PERIOD_NS   729.17F

#include <zephyr/net/ieee802154_radio.h>

ERDEV symbol period.

IEEE802154_PHY_HRP_UWB_PRF16_TPSYM_SYMBOL_PERIOD_NS

#define IEEE802154_PHY_HRP_UWB_PRF16_TPSYM_SYMBOL_PERIOD_NS   993.59F

#include <zephyr/net/ieee802154_radio.h>

Nominal PRF 16MHz symbol period.

IEEE802154_PHY_HRP_UWB_PRF4_TPSYM_SYMBOL_PERIOD_NS

#define IEEE802154_PHY_HRP_UWB_PRF4_TPSYM_SYMBOL_PERIOD_NS   3974.36F

#include <zephyr/net/ieee802154_radio.h>

Nominal PRF 4MHz symbol period.

IEEE802154_PHY_HRP_UWB_PRF64_TPSYM_SYMBOL_PERIOD_NS

#define IEEE802154_PHY_HRP_UWB_PRF64_TPSYM_SYMBOL_PERIOD_NS   1017.63F

#include <zephyr/net/ieee802154_radio.h>

Nominal PRF 64MHz symbol period.

IEEE802154_PHY_HRP_UWB_RDEV

#define IEEE802154_PHY_HRP_UWB_RDEV

#include <zephyr/net/ieee802154_radio.h>

Value:

        (IEEE802154_PHY_HRP_UWB_NOMINAL_4_M | IEEE802154_PHY_HRP_UWB_NOMINAL_16_M |                \
         IEEE802154_PHY_HRP_UWB_NOMINAL_64_M)

RDEV device mask.

IEEE802154_PHY_OQPSK_780_TO_2450MHZ_SYMBOL_PERIOD_NS

#define IEEE802154_PHY_OQPSK_780_TO_2450MHZ_SYMBOL_PERIOD_NS   16000LL

#include <zephyr/net/ieee802154_radio.h>

O-QPSK 780MHz, 915MHz, 2380MHz and 2450MHz bands symbol period, see section 12.3.3.

IEEE802154_PHY_OQPSK_868MHZ_SYMBOL_PERIOD_NS

#define IEEE802154_PHY_OQPSK_868MHZ_SYMBOL_PERIOD_NS   40000LL

#include <zephyr/net/ieee802154_radio.h>

O-QPSK 868Mhz band symbol period, see section 12.3.3.

IEEE802154_PHY_SUN_FSK_863MHZ_915MHZ_SYMBOL_PERIOD_NS

#define IEEE802154_PHY_SUN_FSK_863MHZ_915MHZ_SYMBOL_PERIOD_NS   20000LL

#include <zephyr/net/ieee802154_radio.h>

SUN FSK 863Mhz and 915MHz band symbol periods, see section 19.1, table 19-1.

IEEE802154_PHY_SUN_FSK_PHR_LEN

#define IEEE802154_PHY_SUN_FSK_PHR_LEN   2

#include <zephyr/net/ieee802154_radio.h>

SUN FSK PHY header length, in bytes, see section 19.2.4.

IEEE802154_PHY_SYMBOLS_PER_SECOND

#define IEEE802154_PHY_SYMBOLS_PER_SECOND

(

symbol_period_ns

)

(NSEC_PER_SEC / symbol_period_ns)

#include <zephyr/net/ieee802154_radio.h>

The symbol period (and therefore symbol rate) is defined in section 6.1: "Some of the timing parameters in definition of the MAC are in units of PHY symbols.

For PHYs that have multiple symbol periods, the duration to be used for the MAC parameters is defined in that PHY clause."

This is not necessarily the true physical symbol period, so take care to use this macro only when either the symbol period used for MAC timing is the same as the physical symbol period or if you actually mean the MAC timing symbol period.

PHY specific symbol periods are defined in PHY specific sections below.

IEEE802154_TIME_CORRECTION_HEADER_IE_LEN

#define IEEE802154_TIME_CORRECTION_HEADER_IE_LEN    (IEEE802154_HEADER_IE_HEADER_LENGTH + sizeof(struct ieee802154_header_ie_time_correction))

#include <zephyr/net/ieee802154_ie.h>

The length in bytes of a "Time Correction" header IE.

Typedef Documentation

energy_scan_done_cb_t

typedef void(* energy_scan_done_cb_t) (const struct device *dev, int16_t max_ed)

#include <zephyr/net/ieee802154_radio.h>

Energy scan callback.

ieee802154_event_cb_t

typedef void(* ieee802154_event_cb_t) (const struct device *dev, enum ieee802154_event evt, void *event_params)

#include <zephyr/net/ieee802154_radio.h>

Driver event callback.

Enumeration Type Documentation

ieee802154_attr

enum ieee802154_attr

#include <zephyr/net/ieee802154_radio.h>

IEEE 802.15.4 driver attributes.

See ieee802154_attr_value and ieee802154_radio_api for usage details.

Enumerator
IEEE802154_ATTR_PHY_SUPPORTED_CHANNEL_PAGES	Retrieves a bit field with supported channel pages. This attribute SHALL be implemented by all drivers.
IEEE802154_ATTR_PHY_SUPPORTED_CHANNEL_RANGES	Retrieves a pointer to the array of supported channel ranges within the currently configured channel page. This attribute SHALL be implemented by all drivers.
IEEE802154_ATTR_PHY_HRP_UWB_SUPPORTED_PRFS	Retrieves a bit field with supported HRP UWB nominal pulse repetition frequencies. This attribute SHALL be implemented by all devices that support channel page four (HRP UWB).
IEEE802154_ATTR_COMMON_COUNT	Number of attributes defined in ieee802154_attr.
IEEE802154_ATTR_PRIV_START	This and higher values are specific to the protocol- or driver-specific extensions.

ieee802154_config_type

enum ieee802154_config_type

#include <zephyr/net/ieee802154_radio.h>

IEEE 802.15.4 driver configuration types.

Enumerator
IEEE802154_CONFIG_AUTO_ACK_FPB	Indicates how the driver should set the Frame Pending bit in ACK responses for Data Requests. If enabled, the driver should determine whether to set the bit or not based on the information provided with IEEE802154_CONFIG_ACK_FPB config and FPB address matching mode specified. Otherwise, Frame Pending bit should be set to 1 (see section 6.7.3). Note requires IEEE802154_HW_TX_RX_ACK capability and is available in any interface operational state.
IEEE802154_CONFIG_ACK_FPB	Indicates whether to set ACK Frame Pending bit for specific address or not. Disabling the Frame Pending bit with no address provided (NULL pointer) should disable it for all enabled addresses. Note requires IEEE802154_HW_TX_RX_ACK capability and is available in any interface operational state.
IEEE802154_CONFIG_PAN_COORDINATOR	Indicates whether the device is a PAN coordinator. This influences packet filtering. Note Available in any interface operational state.
IEEE802154_CONFIG_PROMISCUOUS	Enable/disable promiscuous mode. Note Available in any interface operational state.
IEEE802154_CONFIG_EVENT_HANDLER	Specifies new IEEE 802.15.4 driver event handler. Specifying NULL as a handler will disable events notification. Note Available in any interface operational state.
IEEE802154_CONFIG_MAC_KEYS	Updates MAC keys, key index and the per-key frame counter for drivers supporting transmit security offloading, see section 9.5, tables 9-9 and 9-10. The key configuration SHALL NOT be accepted if the frame counter (in case frame counter per key is true) is not strictly larger than the current frame counter associated with the same key, see sections 8.2.2, 9.2.4 g/h) and 9.4.3. Note Requires IEEE802154_HW_TX_SEC capability and is available in any interface operational state.
IEEE802154_CONFIG_FRAME_COUNTER	Sets the current MAC frame counter value associated with the interface for drivers supporting transmit security offloading, see section 9.5, table 9-8, secFrameCounter. Warning The frame counter MUST NOT be accepted if it is not strictly greater than the current frame counter associated with the interface, see sections 8.2.2, 9.2.4 g/h) and 9.4.3. Otherwise the replay protection provided by the frame counter may be compromised. Drivers SHALL return -EINVAL in case the configured frame counter does not conform to this requirement. Note Requires IEEE802154_HW_TX_SEC capability and is available in any interface operational state.
IEEE802154_CONFIG_FRAME_COUNTER_IF_LARGER	Sets the current MAC frame counter value if the provided value is greater than the current one. Note Requires IEEE802154_HW_TX_SEC capability and is available in any interface operational state. Warning This configuration option does not conform to the requirements specified in #61227 as it is redundant with IEEE802154_CONFIG_FRAME_COUNTER, and will therefore be deprecated in the future.
IEEE802154_CONFIG_RX_SLOT	Set or unset a radio reception window (RX slot). This can be used for any scheduled reception, e.g.: Zigbee GP device, CSL, TSCH, etc. The start and duration parameters of the RX slot are relative to the network subsystem's local clock. If the start parameter of the RX slot is -1 then any previously configured RX slot SHALL be canceled immediately. If the start parameter is any value in the past (including 0) or the duration parameter is zero then the receiver SHALL remain off forever until the RX slot has either been removed or re-configured to point to a future start time. If an RX slot is configured while the previous RX slot is still scheduled, then the previous slot SHALL be cancelled and the new slot scheduled instead. RX slots MAY be programmed while the driver is "DOWN". If any past or future RX slot is configured when calling start() then the interface SHALL be placed in "UP" state but the receiver SHALL not be started. The driver SHALL take care to start/stop the receiver autonomously, asynchronously and automatically around the RX slot. The driver SHALL resume power just before the RX slot and suspend it again after the slot unless another programmed event forces the driver not to suspend. The driver SHALL switch to the programmed channel before the RX slot and back to the channel set with set_channel() after the RX slot. If the driver interface is "DOWN" when the start time of an RX slot arrives, then the RX slot SHALL not be observed and the receiver SHALL remain off. If the driver is "UP" while configuring an RX slot, the driver SHALL turn off the receiver immediately and (possibly asynchronously) put the driver into the lowest possible power saving mode until the start of the RX slot. If the driver is "UP" while the RX slot is deleted, then the driver SHALL enable the receiver immediately. The receiver MUST be ready to receive packets before returning from the configure() operation in this case. This behavior means that setting an RX slot implicitly sets the MAC PIB attribute macRxOnWhenIdle (see section 8.4.3.1, table 8-94) to "false" while deleting the RX slot implicitly sets macRxOnWhenIdle to "true". Note requires IEEE802154_HW_RXTIME capability and is available in any interface operational state. Required for Thread 1.2 Coordinated Sampled Listening feature (see Thread specification 1.2.0, ch. 3.2.6.3).
IEEE802154_CONFIG_CSL_PERIOD	Enables or disables a device as a CSL receiver and configures its CSL period. Configures the CSL period in units of 10 symbol periods. Values greater than zero enable CSL if the driver supports it and the device starts to operate as a CSL receiver. Setting this to zero disables CSL on the device. If the driver does not support CSL, the configuration call SHALL return -ENOTSUP. See section 7.4.2.3 and section 8.4.3.6, table 8-104, macCslPeriod. Note Confusingly the standard calls the CSL receiver "CSL coordinator" (i.e. "coordinating the CSL protocol timing", see section 6.12.2.2), although, typically, a CSL coordinator is NOT also an IEEE 802.15.4 FFD coordinator or PAN coordintor but a simple RFD end device (compare the device roles outlined in sections 5.1, 5.3, 5.5 and 6.1). To avoid confusion we therefore prefer calling CSL coordinators (typically an RFD end device) "CSL receivers" and CSL peer devices (typically FFD coordinators or PAN coordinators) "CSL transmitters". Also note that at this time, we do NOT support unsynchronized transmission with CSL wake up frames as specified in section 6.12.2.4.4. To offload CSL receiver timing to the driver the upper layer SHALL combine several configuration options in the following way: Use IEEE802154_CONFIG_ENH_ACK_HEADER_IE once with an appropriate pre-filled CSL IE and the CSL phase set to an arbitrary value or left uninitialized. The CSL phase SHALL be injected on-the-fly by the driver at runtime as outlined in 2. below. Adding a short and extended address will inform the driver of the specific CSL receiver to which it SHALL inject CSL IEs. If no addresses are given then the CSL IE will be injected into all enhanced ACK frames as soon as CSL is enabled. This configuration SHALL be done before enabling CSL by setting a CSL period greater than zero. Configure IEEE802154_CONFIG_EXPECTED_RX_TIME immediately followed by IEEE802154_CONFIG_CSL_PERIOD. To prevent race conditions, the upper layer SHALL ensure that the receiver is not enabled during or between the two calls (e.g. by a previously configured RX slot) nor SHALL a frame be transmitted concurrently. The expected RX time SHALL point to the end of SFD of an ideally timed RX frame in an arbitrary past or future CSL channel sample, i.e. whose "end of SFD" arrives exactly at the locally predicted time inside the CSL channel sample. The driver SHALL derive CSL anchor points and the CSL phase from the given expected RX time as follows: cslAnchorPointNs = last expected RX time + PHY-specific PHR duration in ns startOfMhrNs = start of MHR of the frame containing the CSL IE relative to the local network clock cslPhase = (startOfMhrNs - cslAnchorPointNs) / (10 * PHY specific symbol period in ns) % cslPeriod The driver SHALL set the CSL phase in the IE configured in 1. and inject that IE on-the-fly into outgoing enhanced ACK frames if the destination address conforms to the IE's address filter. Use IEEE802154_CONFIG_RX_SLOT periodically to schedule each CSL channel sample early enough before its start time. The size of the CSL channel sample SHALL take relative clock drift and scheduling uncertainties with respect to CSL transmitters into account as specified by the standard such that at least the full SHR of a legitimate RX frame is guaranteed to land inside the channel sample. To this avail, the last configured expected RX time plus an integer number of CSL periods SHALL point to a fixed offset of the RX slot (not necessarily its center): expectedRxTimeNs_N = last expected RX time + N * (cslPeriod * 10 * PHY-specific symbol period in ns) expectedRxTimeNs_N - rxSlot_N.start == const for all N While the configured CSL period is greater than zero, drivers SHOULD validate the offset of the expected RX time inside each RX slot accordingly. If the driver finds that the offset varies from slot to slot, drivers SHOULD log the difference but SHALL nevertheless accept and schedule the RX slot with a zero success value to work around minor implementation or rounding errors in upper layers. Configure and start a CSL receiver: ENH_ACK_HEADER_IE | | EXPECTED_RX_TIME (end of SFD of a perfectly timed RX frame | | in any past or future channel sample) | | | | CSL_PERIOD (>0) RX_SLOT | | | | v v v v -----------------------------------------------[-CSL channel sample ]----+ ^ | | | +--------------------- loop ---------+ Disable CSL on the receiver: CSL_PERIOD (=0) | v --------------------- Update the CSL period to a new value: EXPECTED_RX_TIME (based on updated period) | | CSL_PERIOD (>0, updated) RX_SLOT | | | v v v -----------------------------------------------[-CSL channel sample ]----+ ^ | | | +--------------------- loop ---------+ Note Available in any interface operational state. Required for Thread 1.2 Coordinated Sampled Listening feature (see Thread specification 1.2.0, ch. 3.2.6.3).
IEEE802154_CONFIG_EXPECTED_RX_TIME	Configure a timepoint at which an RX frame is expected to arrive. Configure the nanosecond resolution timepoint relative to the network subsystem's local clock at which an RX frame's end of SFD (i.e. equivalently its end of SHR, start of PHR, or in the case of PHYs with RDEV or ERDEV capability the RMARKER) is expected to arrive at the local antenna assuming perfectly synchronized local and remote network clocks and zero distance between antennas. This parameter MAY be used to offload parts of timing sensitive TDMA (e.g. TSCH, beacon-enabled PAN including DSME), low-energy (e.g. CSL, RIT) or ranging (TDoA) protocols to the driver. In these protocols, medium access is tightly controlled such that the expected arrival time of a frame can be predicted within a well-defined time window. This feature will typically be combined with IEEE802154_CONFIG_RX_SLOT although this is not a hard requirement. The "expected RX time" MAY be interpreted slightly differently depending on the protocol context: CSL phase (i.e. time to the next expected CSL transmission) or anchor time (i.e. any arbitrary timepoint with "zero CSL phase") SHALL be derived by adding the PHY header duration to the expected RX time to calculate the "start of MHR" ("first symbol of MAC", see section 6.12.2.1) required by the CSL protocol, compare IEEE802154_CONFIG_CSL_PERIOD. In TSCH the expected RX time MAY be set to macTsRxOffset + macTsRxWait / 2. Then the time correction SHALL be calculated as the expected RX time minus actual arrival timestamp, see section 6.5.4.3. In ranging applications, time difference of arrival (TDOA) MAY be calculated inside the driver comparing actual RMARKER timestamps against the assumed synchronized time at which the ranging frame was sent, see IEEE 802.15.4z. In case of periodic protocols (e.g. CSL channel samples, periodic beacons of a single PAN, periodic ranging "blinks"), a single timestamp at any time in the past or in the future may be given from which other expected timestamps can be derived by adding or subtracting multiples of the RX period. See e.g. the CSL documentation in this API. Additionally this parameter MAY be used by drivers to discipline their local representation of a distributed network clock by deriving synchronization instants related to a remote representation of the same clock (as in PTP). Note Available in any interface operational state. Required for Thread 1.2 Coordinated Sampled Listening feature (see Thread specification 1.2.0, ch. 3.2.6.3).
IEEE802154_CONFIG_ENH_ACK_HEADER_IE	Adds a header information element (IE) to be injected into enhanced ACK frames generated by the driver if the given destination address filter matches. Drivers implementing the IEEE802154_HW_RX_TX_ACK capability generate ACK frames autonomously. Setting this configuration will ask the driver to inject the given preconfigured header IE when generating enhanced ACK frames where appropriate by the standard. IEs for all other frame types SHALL be provided by L2. The driver shall return -ENOTSUP in the following cases: It does not support the IEEE802154_HW_RX_TX_ACK, It does not support header IE injection, It cannot inject the runtime fields on-the-fly required for the given IE element ID (see list below). Enhanced ACK header IEs (element IDs in parentheses) that either need to be rejected or explicitly supported and parsed by the driver because they require on-the-fly timing information injection are: CSL IE (0x1a) Rendezvous Time IE (0x1d) Time Correction IE (0x1e) Drivers accepting this configuration option SHALL check the list of configured IEs for each outgoing enhanced ACK frame, select the ones appropriate for the received frame based on their element ID, inject any required runtime information on-the-fly and include the selected IEs into the enhanced ACK frame's MAC header. Drivers supporting enhanced ACK header IE injection SHALL autonomously inject header termination IEs as required by the standard. A destination short address and extended address MAY be given by L2 to filter the devices to which the given IE is included. Setting the short address to the broadcast address and the extended address to NULL will inject the given IE into all ACK frames unless a more specific filter is also present for any given destination device (fallback configuration). L2 SHALL take care to either set both address fields to valid device addresses or none. This configuration type may be called several times with distinct element IDs and/or addresses. The driver SHALL either store all configured IE/address combinations or return -ENOMEM if no additional configuration can be stored. Configuring a header IE with a previously configured element ID and address filter SHALL override the previous configuration. This implies that repetition of the same header IE/address combination is NOT supported. Configuring an existing element ID/address filter combination with the header IE's length field set to zero SHALL remove that configuration. SHALL remove the fallback configuration if no address is given. Configuring a header IE for an address filter with the header IE pointer set to NULL SHALL remove all header IE's for that address filter. SHALL remove ALL header IE configuration (including but not limited to fallbacks) if no address is given. If any of the deleted configurations didn't previously exist, then the call SHALL be ignored. Whenever the length field is set to zero, the content fields MUST NOT be accessed by the driver. L2 SHALL minimize the space required to keep IE configuration inside the driver by consolidating address filters and by removing configuration that is no longer required. Note requires IEEE802154_HW_RX_TX_ACK capability and is available in any interface operational state. Currently we only support header IEs but that may change in the future. Required for Thread 1.2 Coordinated Sampled Listening feature (see Thread specification 1.2.0, ch. 3.2.6.3). Required for Thread 1.2 Link Metrics feature (see Thread specification 1.2.0, ch. 4.11.3.3).
IEEE802154_CONFIG_RX_ON_WHEN_IDLE	Enable/disable RxOnWhenIdle MAC PIB attribute (Table 8-94). Since there is no clear guidance in IEEE 802.15.4 specification about the definition of an "idle period", this implementation expects that drivers use the RxOnWhenIdle attribute to determine next radio state (false --> off, true --> receive) in the following scenarios: Finalization of a regular frame reception task, provided that: The frame is received without errors and passes the filtering and it's not an spurious ACK. ACK is not requested or transmission of ACK is not possible due to internal conditions. Finalization of a frame transmission or transmission of an ACK frame, when ACK is not requested in the transmitted frame. Finalization of the reception operation of a requested ACK due to: ACK timeout expiration. Reception of an invalid ACK or not an ACK frame. Reception of the proper ACK, unless the transmitted frame was a Data Request Command and the frame pending bit on the received ACK is set to true. In this case the radio platform implementation SHOULD keep the receiver on until a determined timeout which triggers an idle period start. Finalization of a stand alone CCA task. Finalization of a CCA operation with busy result during CSMA/CA procedure. Finalization of an Energy Detection task. Finalization of a scheduled radio reception window (see IEEE802154_CONFIG_RX_SLOT).
IEEE802154_CONFIG_COMMON_COUNT	Number of types defined in ieee802154_config_type.
IEEE802154_CONFIG_PRIV_START	This and higher values are specific to the protocol- or driver-specific extensions.

ieee802154_event

enum ieee802154_event

#include <zephyr/net/ieee802154_radio.h>

Driver events, see IEEE802154_CONFIG_EVENT_HANDLER.

Enumerator
IEEE802154_EVENT_TX_STARTED	Data transmission started.
IEEE802154_EVENT_RX_FAILED	Data reception failed.
IEEE802154_EVENT_RX_OFF	An RX slot ended, requires IEEE802154_HW_RXTIME. Note This event SHALL not be triggered by drivers when RX is synchronously switched of due to a call to stop() or an RX slot being configured.

ieee802154_filter_type

enum ieee802154_filter_type

#include <zephyr/net/ieee802154_radio.h>

Filter type, see ieee802154_radio_api::filter.

Enumerator
IEEE802154_FILTER_TYPE_IEEE_ADDR	Address type filter.
IEEE802154_FILTER_TYPE_SHORT_ADDR	Short address type filter.
IEEE802154_FILTER_TYPE_PAN_ID	PAN id type filter.
IEEE802154_FILTER_TYPE_SRC_IEEE_ADDR	Source address type filter.
IEEE802154_FILTER_TYPE_SRC_SHORT_ADDR	Source short address type filter.

ieee802154_fpb_mode

enum ieee802154_fpb_mode

#include <zephyr/net/ieee802154_radio.h>

IEEE 802.15.4 Frame Pending Bit table address matching mode.

Enumerator
IEEE802154_FPB_ADDR_MATCH_THREAD	The pending bit shall be set only for addresses found in the list.
IEEE802154_FPB_ADDR_MATCH_ZIGBEE	The pending bit shall be cleared for short addresses found in the list.

ieee802154_header_ie_element_id

enum ieee802154_header_ie_element_id

#include <zephyr/net/ieee802154_ie.h>

Header Information Element IDs.

See section 7.4.2.1, table 7-7, partial list, only IEs actually used are implemented.

Enumerator
IEEE802154_HEADER_IE_ELEMENT_ID_VENDOR_SPECIFIC_IE	Vendor specific IE.
IEEE802154_HEADER_IE_ELEMENT_ID_CSL_IE	CSL IE.
IEEE802154_HEADER_IE_ELEMENT_ID_RIT_IE	RIT IE.
IEEE802154_HEADER_IE_ELEMENT_ID_RENDEZVOUS_TIME_IE	Rendezvous time IE.
IEEE802154_HEADER_IE_ELEMENT_ID_TIME_CORRECTION_IE	Time correction IE.
IEEE802154_HEADER_IE_ELEMENT_ID_HEADER_TERMINATION_1	Header termination 1.
IEEE802154_HEADER_IE_ELEMENT_ID_HEADER_TERMINATION_2	Header termination 2.

ieee802154_hw_caps

enum ieee802154_hw_caps

#include <zephyr/net/ieee802154_radio.h>

IEEE 802.15.4 driver capabilities.

Any driver properties that can be represented in binary form should be modeled as capabilities. These are called "hardware" capabilities for historical reasons but may also represent driver firmware capabilities (e.g. MAC offloading features).

Enumerator
IEEE802154_HW_ENERGY_SCAN	Energy detection (ED) supported (optional)
IEEE802154_HW_FCS	Frame checksum verification supported.
IEEE802154_HW_FILTER	Filtering of PAN ID, extended and short address supported.
IEEE802154_HW_PROMISC	Promiscuous mode supported.
IEEE802154_HW_CSMA	CSMA-CA procedure supported on TX.
IEEE802154_HW_TX_RX_ACK	Waits for ACK on TX if AR bit is set in TX pkt.
IEEE802154_HW_RETRANSMISSION	Supports retransmission on TX ACK timeout.
IEEE802154_HW_RX_TX_ACK	Sends ACK on RX if AR bit is set in RX pkt.
IEEE802154_HW_TXTIME	TX at specified time supported.
IEEE802154_HW_SLEEP_TO_TX	TX directly from sleep supported. @note This HW capability does not conform to the requirements specified in #61227 as it closely couples the driver to OpenThread's capability and device model which is different from Zephyr's: - "Sleeping" is a well defined term in Zephyr related to internal power and thread management and different from "RX off" as defined in OT. - Currently all OT-capable drivers have the "sleep to TX" capability anyway plus we expect future drivers to implement it ootb as well, so no information is actually conveyed by this capability. - The `start()`/`stop()` API of a net device controls the interface's operational state. Drivers MUST respond with -ENETDOWN when calling `tx()` while their operational state is "DOWN", only devices in the "UP" state MAY transmit packets (RFC 2863). - A migration path has been defined in #63670 for actual removal of this capability in favor of a standard compliant `configure(rx_on/rx_off)` call, see there for details. @deprecated Drivers and L2 SHALL not introduce additional references to this capability and remove existing ones as outlined in #63670.
IEEE802154_HW_RXTIME	Timed RX window scheduling supported.
IEEE802154_HW_TX_SEC	TX security supported (key management, encryption and authentication)
IEEE802154_RX_ON_WHEN_IDLE	RxOnWhenIdle handling supported.

ieee802154_ie_type

enum ieee802154_ie_type

#include <zephyr/net/ieee802154_ie.h>

Information Element Types.

See sections 7.4.2.1 and 7.4.3.1.

Enumerator
IEEE802154_IE_TYPE_HEADER	Header type.
IEEE802154_IE_TYPE_PAYLOAD	Payload type.

ieee802154_phy_channel_page

enum ieee802154_phy_channel_page

#include <zephyr/net/ieee802154_radio.h>

PHY channel pages, see section 10.1.3.

A device driver must support the mandatory channel pages, frequency bands and channels of at least one IEEE 802.15.4 PHY.

Channel page and number assignments have developed over several versions of the standard and are not particularly well documented. Therefore some notes about peculiarities of channel pages and channel numbering:

• The 2006 version of the standard had a read-only phyChannelsSupported PHY PIB attribute that represented channel page/number combinations as a bitmap. This attribute was removed in later versions of the standard as the number of channels increased beyond what could be represented by a bit map. That's the reason why it was decided to represent supported channels as a combination of channel pages and ranges instead.
• In the 2020 version of the standard, 13 channel pages are explicitly defined, but up to 32 pages could in principle be supported. This was a hard requirement in the 2006 standard. In later standards it is implicit from field specifications, e.g. the MAC PIB attribute macChannelPage (section 8.4.3.4, table 8-100) or channel page fields used in the SRM protocol (see section 8.2.26.5).
• ASK PHY (channel page one) was deprecated in the 2015 version of the standard. The 2020 version of the standard is a bit ambivalent whether channel page one disappeared as well or should be interpreted as O-QPSK now (see section 10.1.3.3). In Zephyr this ambivalence is resolved by deprecating channel page one.
• For some PHYs the standard doesn't clearly specify a channel page, namely the GFSK, RS-GFSK, CMB and TASK PHYs. These are all rather new and left out in our list as long as no driver wants to implement them.

Warning

The bit numbers are not arbitrary but represent the channel page numbers as defined by the standard. Therefore do not change the bit numbering.

Enumerator
IEEE802154_ATTR_PHY_CHANNEL_PAGE_ZERO_OQPSK_2450_BPSK_868_915	Channel page zero supports the 2.4G channels of the O-QPSK PHY and all channels from the BPSK PHYs initially defined in the 2003 editions of the standard. For channel page zero, 16 channels are available in the 2450 MHz band (channels 11-26, O-QPSK), 10 in the 915 MHz band (channels 1-10, BPSK), and 1 in the 868 MHz band (channel 0, BPSK). You can retrieve the channels supported by a specific driver on this page via IEEE802154_ATTR_PHY_SUPPORTED_CHANNEL_RANGES attribute. see section 10.1.3.3
IEEE802154_ATTR_PHY_CHANNEL_PAGE_ONE_DEPRECATED	Formerly ASK PHY - deprecated in IEEE 802.15.4-2015.
IEEE802154_ATTR_PHY_CHANNEL_PAGE_TWO_OQPSK_868_915	O-QPSK PHY - 868 MHz and 915 MHz bands, see section 10.1.3.3.
IEEE802154_ATTR_PHY_CHANNEL_PAGE_THREE_CSS	CSS PHY - 2450 MHz band, see section 10.1.3.4.
IEEE802154_ATTR_PHY_CHANNEL_PAGE_FOUR_HRP_UWB	UWB PHY - SubG, low and high bands, see section 10.1.3.5.
IEEE802154_ATTR_PHY_CHANNEL_PAGE_FIVE_OQPSK_780	O-QPSK PHY - 780 MHz band, see section 10.1.3.2.
IEEE802154_ATTR_PHY_CHANNEL_PAGE_SIX_RESERVED	reserved - not currently assigned
IEEE802154_ATTR_PHY_CHANNEL_PAGE_SEVEN_MSK	MSK PHY - 780 MHz and 2450 MHz bands, see sections 10.1.3.6, 10.1.3.7.
IEEE802154_ATTR_PHY_CHANNEL_PAGE_EIGHT_LRP_UWB	LRP UWB PHY, see sections 10.1.3.8.
IEEE802154_ATTR_PHY_CHANNEL_PAGE_NINE_SUN_PREDEFINED	SUN FSK/OFDM/O-QPSK PHYs - predefined bands, operating modes and channels, see sections 10.1.3.9.
IEEE802154_ATTR_PHY_CHANNEL_PAGE_TEN_SUN_FSK_GENERIC	SUN FSK/OFDM/O-QPSK PHYs - generic modulation and channel description, see sections 10.1.3.9, 7.4.4.11.
IEEE802154_ATTR_PHY_CHANNEL_PAGE_ELEVEN_OQPSK_2380	O-QPSK PHY - 2380 MHz band, see section 10.1.3.10.
IEEE802154_ATTR_PHY_CHANNEL_PAGE_TWELVE_LECIM	LECIM DSSS/FSK PHYs, see section 10.1.3.11.
IEEE802154_ATTR_PHY_CHANNEL_PAGE_THIRTEEN_RCC	RCC PHY, see section 10.1.3.12.

ieee802154_phy_hrp_uwb_nominal_prf

enum ieee802154_phy_hrp_uwb_nominal_prf

#include <zephyr/net/ieee802154_radio.h>

represents the nominal pulse rate frequency of an HRP UWB PHY

Enumerator
IEEE802154_PHY_HRP_UWB_PRF_OFF	standard modes, see section 8.3.2, table 8-88.
IEEE802154_PHY_HRP_UWB_NOMINAL_4_M
IEEE802154_PHY_HRP_UWB_NOMINAL_16_M
IEEE802154_PHY_HRP_UWB_NOMINAL_64_M
IEEE802154_PHY_HRP_UWB_NOMINAL_64_M_BPRF	enhanced ranging device (ERDEV) modes not specified in table 8-88, see IEEE 802.15.4z, section 15.1, section 15.2.6.2, table 15-7b, section 15.3.4.2 and section 15.3.4.3.
IEEE802154_PHY_HRP_UWB_NOMINAL_128_M_HPRF
IEEE802154_PHY_HRP_UWB_NOMINAL_256_M_HPRF

ieee802154_rx_fail_reason

enum ieee802154_rx_fail_reason

#include <zephyr/net/ieee802154_radio.h>

RX failed event reasons, see IEEE802154_EVENT_RX_FAILED.

Enumerator
IEEE802154_RX_FAIL_NOT_RECEIVED	Nothing received.
IEEE802154_RX_FAIL_INVALID_FCS	Frame had invalid checksum.
IEEE802154_RX_FAIL_ADDR_FILTERED	Address did not match.
IEEE802154_RX_FAIL_OTHER	General reason.

ieee802154_tx_mode

enum ieee802154_tx_mode

#include <zephyr/net/ieee802154_radio.h>

IEEE 802.15.4 Transmission mode.

Enumerator
IEEE802154_TX_MODE_DIRECT	Transmit packet immediately, no CCA.
IEEE802154_TX_MODE_CCA	Perform CCA before packet transmission.
IEEE802154_TX_MODE_CSMA_CA	Perform full CSMA/CA procedure before packet transmission. Note requires IEEE802154_HW_CSMA capability.
IEEE802154_TX_MODE_TXTIME	Transmit packet in the future, at the specified time, no CCA. Note requires IEEE802154_HW_TXTIME capability.
IEEE802154_TX_MODE_TXTIME_CCA	Transmit packet in the future, perform CCA before transmission. Note requires IEEE802154_HW_TXTIME capability. Required for Thread 1.2 Coordinated Sampled Listening feature (see Thread specification 1.2.0, ch. 3.2.6.3).
IEEE802154_TX_MODE_COMMON_COUNT	Number of modes defined in ieee802154_tx_mode.
IEEE802154_TX_MODE_PRIV_START	This and higher values are specific to the protocol- or driver-specific extensions.

Function Documentation

ieee802154_attr_get_channel_page_and_range()

static int ieee802154_attr_get_channel_page_and_range ( enum ieee802154_attr  attr, const enum ieee802154_phy_channel_page  phy_supported_channel_page, const struct ieee802154_phy_supported_channels *  phy_supported_channels, struct ieee802154_attr_value *  value  )

inlinestatic

#include <zephyr/net/ieee802154_radio.h>

Helper function to handle channel page and range to be called from drivers' attr_get() implementation.

This only applies to drivers with a single channel page.

Parameters

attr	The attribute to be retrieved.
phy_supported_channel_page	The driver's unique channel page.
phy_supported_channels	Pointer to the structure that contains the driver's channel range or ranges.
value	The pointer to the value struct provided by the user.

Return values

0	if the attribute could be resolved
-ENOENT	if the attribute could not be resolved

ieee802154_handle_ack()

enum net_verdict ieee802154_handle_ack	(	struct net_if *	iface,
		struct net_pkt *	pkt
	)

#include <zephyr/net/ieee802154_radio.h>

IEEE 802.15.4 driver ACK handling callback into L2 that drivers must call when receiving an ACK package.

The IEEE 802.15.4 standard prescribes generic procedures for ACK handling on L2 (MAC) level. L2 stacks therefore have to provides a fast and re-usable generic implementation of this callback for drivers to call when receiving an ACK packet.

Note: This function is part of Zephyr's 802.15.4 stack driver -> L2 "inversion-of-control" adaptation API and must be implemented by all IEEE 802.15.4 L2 stacks.

Parameters

iface	A valid pointer on a network interface that received the packet
pkt	A valid pointer on a packet to check

Returns

NET_OK if L2 handles the ACK package, NET_CONTINUE or NET_DROP otherwise.

Warning

Deviating from other functions in the net stack returning net_verdict, this function will not unref the package even if it returns NET_OK.

ieee802154_header_ie_get_element_id()

static uint8_t ieee802154_header_ie_get_element_id ( struct ieee802154_header_ie *  ie )

inlinestatic

#include <zephyr/net/ieee802154_ie.h>

Get the element ID of a header IE.

Parameters

[in]

ie

pointer to a header IE

Returns

header IE element id in CPU byte order

ieee802154_header_ie_get_time_correction_us()

static int16_t ieee802154_header_ie_get_time_correction_us ( struct ieee802154_header_ie_time_correction *  ie )

inlinestatic

#include <zephyr/net/ieee802154_ie.h>

Retrieve the time correction value in microseconds from a Time Correction IE, see section 7.4.2.7.

Parameters

[in]

ie

pointer to the Time Correction IE structure

Returns

The time correction value in microseconds.

ieee802154_header_ie_set_element_id()

static void ieee802154_header_ie_set_element_id ( struct ieee802154_header_ie *  ie, uint8_t  element_id  )

inlinestatic

#include <zephyr/net/ieee802154_ie.h>

Set the element ID of a header IE.

Parameters

[in]	ie	pointer to a header IE
[in]	element_id	IE element id in CPU byte order

ieee802154_init()

void ieee802154_init

(

struct net_if *

iface

)

#include <zephyr/net/ieee802154_radio.h>

IEEE 802.15.4 driver initialization callback into L2 called by drivers to initialize the active L2 stack for a given interface.

Drivers must call this function as part of their own initialization routine.

Note: This function is part of Zephyr's 802.15.4 stack driver -> L2 "inversion-of-control" adaptation API and must be implemented by all IEEE 802.15.4 L2 stacks.

Parameters

iface

A valid pointer on a network interface

ieee802154_is_ar_flag_set()

static bool ieee802154_is_ar_flag_set ( struct net_buf *  frag )

inlinestatic

#include <zephyr/net/ieee802154_radio.h>

Check if the AR flag is set on the frame inside the given Network Packet Library.

Parameters

frag	A valid pointer on a net_buf structure, must not be NULL, and its length should be at least 1 byte (ImmAck frames are the shortest supported frames with 3 bytes excluding FCS).

Returns

true if AR flag is set, false otherwise