Zephyr API Documentation 4.0.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
Data Structures
ieee802154_radio.h File Reference

Public IEEE 802.15.4 Driver API. More...

#include <zephyr/device.h>
#include <zephyr/net/net_if.h>
#include <zephyr/net/net_pkt.h>
#include <zephyr/net/net_time.h>
#include <zephyr/net/ieee802154.h>
#include <zephyr/net/ieee802154_ie.h>
#include <zephyr/sys/util.h>

Go to the source code of this file.

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

Macros

IEEE 802.15.4-2020, Section 6: MAC functional description
#define IEEE802154_PHY_SYMBOLS_PER_SECOND(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)
 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)
 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.
 

Functions

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 10: General PHY requirements

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

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

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

IEEE 802.15.4 Driver API

#define IEEE802154_HW_CAPS_BITS_COMMON_COUNT   (14)
 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.
 
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) , IEEE802154_HW_SELECTIVE_TXCHANNEL = BIT(13)
}
 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.
 

Detailed Description

Public IEEE 802.15.4 Driver API.

Note
All references to the standard in this file cite IEEE 802.15.4-2020.