Zephyr API Documentation  3.7.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches

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:

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, \
IEEE802154_DEFINE_HEADER_IE_CSL_FULL_CONTENT( \
_csl_phase, _csl_period, _csl_rendezvous_time), \
csl.full)
@ IEEE802154_HEADER_IE_ELEMENT_ID_CSL_IE
CSL IE.
Definition: ieee802154_ie.h:55
Full CSL IE, see section 7.4.2.3.
Definition: ieee802154_ie.h:77

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);
#define IEEE802154_DEFINE_HEADER_IE_CSL_REDUCED(_csl_phase, _csl_period)
Define a reduced CSL IE, see section 7.4.2.3.
Definition: ieee802154_ie.h:254
__UINT16_TYPE__ uint16_t
Definition: stdint.h:89
Parameters
_csl_phaseCSL phase in CPU byte order
_csl_periodCSL period in CPU byte order
_csl_rendezvous_timeCSL 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_DEFINE_HEADER_IE_CSL_REDUCED_CONTENT(_csl_phase, _csl_period), \
csl.reduced)
Reduced CSL IE, see section 7.4.2.3.
Definition: ieee802154_ie.h:84

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 =
Parameters
_csl_phaseCSL phase in CPU byte order
_csl_periodCSL 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_DEFINE_HEADER_IE_TIME_CORRECTION_CONTENT(_ack, _time_correction_us), \
time_correction)
@ IEEE802154_HEADER_IE_ELEMENT_ID_TIME_CORRECTION_IE
Time correction IE.
Definition: ieee802154_ie.h:58
Time Correction IE, see section 7.4.2.7.
Definition: ieee802154_ie.h:134

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 =
#define IEEE802154_DEFINE_HEADER_IE_TIME_CORRECTION(_ack, _time_correction_us)
Define a Time Correction IE, see section 7.4.2.7.
Definition: ieee802154_ie.h:301
Parameters
_ackwhether or not the enhanced ACK frame that receives this IE is an ACK (true) or NACK (false)
_time_correction_usthe 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_VENDOR_SPECIFIC_CONTENT_LEN( \
_vendor_specific_info_len), \
IEEE802154_DEFINE_HEADER_IE_VENDOR_SPECIFIC_CONTENT( \
_vendor_oui, _vendor_specific_info), \
vendor_specific)
@ IEEE802154_HEADER_IE_ELEMENT_ID_VENDOR_SPECIFIC_IE
Vendor specific IE.
Definition: ieee802154_ie.h:54

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));
#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.
Definition: ieee802154_ie.h:230
__UINT8_TYPE__ uint8_t
Definition: stdint.h:88
Parameters
_vendor_ouian initializer for a 3 byte vendor oui array in little endian
_vendor_specific_infopointer to a variable length uint8_t array with the vendor specific IE content
_vendor_specific_info_lenthe 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, \
}, \
}
Represents a supported channel range, see ieee802154_phy_supported_channels.
Definition: ieee802154_radio.h:235
Represents a list channels supported by a driver for a given interface, see IEEE802154_ATTR_PHY_SUPPO...
Definition: ieee802154_radio.h:244
const struct ieee802154_phy_channel_range *const ranges
Pointer to an array of channel range structures.
Definition: ieee802154_radio.h:251

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:

#define IEEE802154_DEFINE_PHY_SUPPORTED_CHANNELS(drv_attr, from, to)
Allocate memory for the supported channels driver attribute with a single channel range constant acro...
Definition: ieee802154_radio.h:282

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_attrname of the local static variable to be declared for the local attributes structure
fromthe first channel to be supported
tothe 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_256_M_HPRF
Definition: ieee802154_radio.h:395
@ IEEE802154_PHY_HRP_UWB_NOMINAL_64_M_BPRF
enhanced ranging device (ERDEV) modes not specified in table 8-88, see IEEE 802.15....
Definition: ieee802154_radio.h:393
@ IEEE802154_PHY_HRP_UWB_NOMINAL_128_M_HPRF
Definition: ieee802154_radio.h:394

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_64_M
Definition: ieee802154_radio.h:386
@ IEEE802154_PHY_HRP_UWB_NOMINAL_4_M
Definition: ieee802154_radio.h:384
@ IEEE802154_PHY_HRP_UWB_NOMINAL_16_M
Definition: ieee802154_radio.h:385

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

#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

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

  1. 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.
  2. 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.

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

#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

#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

#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

#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

#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

#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

#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

#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

#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

#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
attrThe attribute to be retrieved.
phy_supported_channel_pageThe driver's unique channel page.
phy_supported_channelsPointer to the structure that contains the driver's channel range or ranges.
valueThe pointer to the value struct provided by the user.
Return values
0if the attribute could be resolved
-ENOENTif 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
ifaceA valid pointer on a network interface that received the packet
pktA 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]iepointer 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]iepointer 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]iepointer to a header IE
[in]element_idIE 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
ifaceA 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
fragA 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