IEEE 802.15.4 Drivers

IEEE 802.15.4 driver API. More...

Data Structures
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-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) }
	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_SLEEP }
	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_CSL_RX_TIME , IEEE802154_CONFIG_ENH_ACK_HEADER_IE ,   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   (12)
	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.

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_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_HW_CAPS_BITS_COMMON_COUNT

#define IEEE802154_HW_CAPS_BITS_COMMON_COUNT   (12)

#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.

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 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 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 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.
IEEE802154_CONFIG_CSL_PERIOD	Configure CSL receiver (Endpoint) period. In order to configure a CSL receiver the upper layer should combine several configuration options in the following way: Use IEEE802154_CONFIG_ENH_ACK_HEADER_IE once to inform the driver of the short and extended addresses of the peer to which it should inject CSL IEs. Use IEEE802154_CONFIG_CSL_RX_TIME periodically, before each use of IEEE802154_CONFIG_CSL_PERIOD setting parameters of the nearest CSL RX window, and before each use of IEEE_CONFIG_RX_SLOT setting parameters of the following (not the nearest one) CSL RX window, to allow the driver to calculate the proper CSL phase to the nearest CSL window to inject in the CSL IEs for both transmitted data and ACK frames. Use IEEE802154_CONFIG_CSL_PERIOD on each value change to update the current CSL period value which will be injected in the CSL IEs together with the CSL phase based on IEEE802154_CONFIG_CSL_RX_TIME. Use IEEE802154_CONFIG_RX_SLOT periodically to schedule the immediate receive window early enough before the expected window start time, taking into account possible clock drifts and scheduling uncertainties. This diagram shows the usage of the four options over time: Start CSL Schedule CSL window ENH_ACK_HEADER_IE CSL_RX_TIME (following window) | | | CSL_RX_TIME (nearest window) | RX_SLOT (nearest window) | | | | | | CSL_PERIOD | | | | | | | v v v v v ----------------------------------------------------------[ CSL window ]-----+ ^ | | | +--------------------- loop ---------+ Note Available in any interface operational state. Warning This configuration option does not conform to the requirements specified in #61227 as it is incompatible with standard primitives and may therefore be deprecated in the future.
IEEE802154_CONFIG_CSL_RX_TIME	Configure the next CSL receive window (i.e. "channel sample") center, in units of nanoseconds relative to the network subsystem's local clock. Note Available in any interface operational state. Warning This configuration option does not conform to the requirements specified in #61227 as it is incompatible with standard primitives and may therefore be deprecated in the future.
IEEE802154_CONFIG_ENH_ACK_HEADER_IE	Indicates whether to inject IE into ENH ACK Frame for specific address or not. Disabling the ENH ACK with no address provided (NULL pointer) should disable it for all enabled addresses. Note Available in any interface operational state. Warning This configuration option does not conform to the requirements specified in #61227 as it is incompatible with standard primitives and may therefore be modified in the future.
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_SLEEP	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
IEEE802154_FILTER_TYPE_SHORT_ADDR
IEEE802154_FILTER_TYPE_PAN_ID
IEEE802154_FILTER_TYPE_SRC_IEEE_ADDR
IEEE802154_FILTER_TYPE_SRC_SHORT_ADDR

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_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.
IEEE802154_HW_RXTIME	Timed RX window scheduling supported.
IEEE802154_HW_TX_SEC	TX security supported (key management, encryption and authentication)

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.
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_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