Zephyr API Documentation 3.7.99
A Scalable Open Source RTOS
|
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 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 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) |
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. | |
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:
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.
#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.
#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.
#define IEEE802154_DEFINE_HEADER_IE_CSL_FULL | ( | _csl_phase, | |
_csl_period, | |||
_csl_rendezvous_time ) |
#include <zephyr/net/ieee802154_ie.h>
Define a full CSL IE, see section 7.4.2.3.
Example usage (all parameters in CPU byte order):
_csl_phase | CSL phase in CPU byte order |
_csl_period | CSL period in CPU byte order |
_csl_rendezvous_time | CSL rendezvous time in CPU byte order |
#define IEEE802154_DEFINE_HEADER_IE_CSL_REDUCED | ( | _csl_phase, | |
_csl_period ) |
#include <zephyr/net/ieee802154_ie.h>
Define a reduced CSL IE, see section 7.4.2.3.
Example usage (all parameters in CPU byte order):
_csl_phase | CSL phase in CPU byte order |
_csl_period | CSL period in CPU byte order |
#define IEEE802154_DEFINE_HEADER_IE_TIME_CORRECTION | ( | _ack, | |
_time_correction_us ) |
#include <zephyr/net/ieee802154_ie.h>
Define a Time Correction IE, see section 7.4.2.7.
Example usage (parameter in CPU byte order):
_ack | whether or not the enhanced ACK frame that receives this IE is an ACK (true) or NACK (false) |
_time_correction_us | the positive or negative deviation from expected RX time in microseconds |
#define IEEE802154_DEFINE_HEADER_IE_VENDOR_SPECIFIC | ( | _vendor_oui, | |
_vendor_specific_info, | |||
_vendor_specific_info_len ) |
#include <zephyr/net/ieee802154_ie.h>
Define a vendor specific header IE, see section 7.4.2.3.
Example usage (all parameters in little endian):
_vendor_oui | an initializer for a 3 byte vendor oui array in little endian |
_vendor_specific_info | pointer to a variable length uint8_t array with the vendor specific IE content |
_vendor_specific_info_len | the length of the vendor specific IE content (in bytes) |
#define IEEE802154_DEFINE_PHY_SUPPORTED_CHANNELS | ( | drv_attr, | |
from, | |||
to ) |
#include <zephyr/net/ieee802154_radio.h>
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:
The attribute may then be referenced like this:
See ieee802154_attr_get_channel_page_and_range() for a further shortcut that can be combined with this macro.
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 |
#include <zephyr/net/ieee802154_ie.h>
The header IE's header length (2 bytes).
#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.
#define IEEE802154_HW_CAPS_BITS_COMMON_COUNT (13) |
#include <zephyr/net/ieee802154_radio.h>
Number of bits used by ieee802154_hw_caps type.
#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.
#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.
#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.
#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.
#define IEEE802154_MAC_A_UNIT_BACKOFF_PERIOD | ( | turnaround_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.
#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.
#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.
#define IEEE802154_PHY_A_TURNAROUND_TIME_1MS | ( | 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.
#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.
#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.
#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.
#define IEEE802154_PHY_HRP_UWB_ERDEV |
#include <zephyr/net/ieee802154_radio.h>
ERDEV device mask.
#define IEEE802154_PHY_HRP_UWB_ERDEV_TPSYM_SYMBOL_PERIOD_NS 729.17F |
#include <zephyr/net/ieee802154_radio.h>
ERDEV symbol period.
#define IEEE802154_PHY_HRP_UWB_PRF16_TPSYM_SYMBOL_PERIOD_NS 993.59F |
#include <zephyr/net/ieee802154_radio.h>
Nominal PRF 16MHz symbol period.
#define IEEE802154_PHY_HRP_UWB_PRF4_TPSYM_SYMBOL_PERIOD_NS 3974.36F |
#include <zephyr/net/ieee802154_radio.h>
Nominal PRF 4MHz symbol period.
#define IEEE802154_PHY_HRP_UWB_PRF64_TPSYM_SYMBOL_PERIOD_NS 1017.63F |
#include <zephyr/net/ieee802154_radio.h>
Nominal PRF 64MHz symbol period.
#define IEEE802154_PHY_HRP_UWB_RDEV |
#include <zephyr/net/ieee802154_radio.h>
RDEV device mask.
#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.
#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.
#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.
#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.
#define IEEE802154_PHY_SYMBOLS_PER_SECOND | ( | 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.
#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.
#include <zephyr/net/ieee802154_radio.h>
Energy scan callback.
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.
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.
#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
|
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.
|
IEEE802154_CONFIG_PAN_COORDINATOR | Indicates whether the device is a PAN coordinator. This influences packet filtering.
|
IEEE802154_CONFIG_PROMISCUOUS | Enable/disable promiscuous mode.
|
IEEE802154_CONFIG_EVENT_HANDLER | Specifies new IEEE 802.15.4 driver event handler. Specifying NULL as a handler will disable events notification.
|
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.
|
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.
|
IEEE802154_CONFIG_FRAME_COUNTER_IF_LARGER | Sets the current MAC frame counter value if the provided value is greater than the current one.
|
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 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 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".
|
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.
To offload CSL receiver timing to the driver the upper layer SHALL combine several configuration options in the following way:
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 ---------+
|
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:
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).
|
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:
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:
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.
|
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:
|
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. |
enum ieee802154_event |
#include <zephyr/net/ieee802154_radio.h>
Driver events, see IEEE802154_CONFIG_EVENT_HANDLER.
Enumerator | |
---|---|
IEEE802154_EVENT_TX_STARTED | Data transmission started. |
IEEE802154_EVENT_RX_FAILED | Data reception failed. |
IEEE802154_EVENT_RX_OFF | An RX slot ended, requires IEEE802154_HW_RXTIME.
|
#include <zephyr/net/ieee802154_radio.h>
Filter type, see ieee802154_radio_api::filter.
enum ieee802154_fpb_mode |
#include <zephyr/net/ieee802154_radio.h>
IEEE 802.15.4 Frame Pending Bit table address matching mode.
#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.
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_RX_ON_WHEN_IDLE | RxOnWhenIdle handling supported. |
enum ieee802154_ie_type |
#include <zephyr/net/ieee802154_ie.h>
Information Element Types.
See sections 7.4.2.1 and 7.4.3.1.
Enumerator | |
---|---|
IEEE802154_IE_TYPE_HEADER | Header type. |
IEEE802154_IE_TYPE_PAYLOAD | Payload type. |
#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:
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. |
#include <zephyr/net/ieee802154_radio.h>
represents the nominal pulse rate frequency of an HRP UWB PHY
#include <zephyr/net/ieee802154_radio.h>
RX failed event reasons, see IEEE802154_EVENT_RX_FAILED.
enum ieee802154_tx_mode |
#include <zephyr/net/ieee802154_radio.h>
IEEE 802.15.4 Transmission mode.
|
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.
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. |
0 | if the attribute could be resolved |
-ENOENT | if the attribute could not be resolved |
|
extern |
#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.
iface | A valid pointer on a network interface that received the packet |
pkt | A valid pointer on a packet to check |
|
inlinestatic |
#include <zephyr/net/ieee802154_ie.h>
Get the element ID of a header IE.
[in] | ie | pointer to a header 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.
[in] | ie | pointer to the Time Correction IE structure |
|
inlinestatic |
#include <zephyr/net/ieee802154_ie.h>
Set the element ID of a header IE.
[in] | ie | pointer to a header IE |
[in] | element_id | IE element id in CPU byte order |
|
extern |
#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.
iface | A valid pointer on a network interface |
#include <zephyr/net/ieee802154_radio.h>
Check if the AR flag is set on the frame inside the given Network Packet Library.
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). |