IEEE 802.15.4

Introduction

IEEE 802.15.4 is a technical standard which defines the operation of low-rate wireless personal area networks (LR-WPANs). For a more detailed overview of this standard, see the IEEE 802.15.4 Wikipedia article.

The most recent version of the standard is accessible through the IEEE GET Program. You need to create a free IEEE account and can then downloading it.

We’re currently following the IEEE 802.15.4-2020 specification. This version is backwards compatible with IEEE 802.15.4-2015, parts of which are contained in the Thread protocol stack. The 2020 version also includes prior extensions that were accepted into the standard, namely IEEE 802.15.4g (SUN FSK) and IEEE 802.15.4e (TSCH) which are of relevance to industrial IoT and automation. For recent developments in UWB ranging technology, see IEEE 802.15.4z which is not yet integrated into the standard’s mainline.

Whenever sections from the standard are cited in the documentation, they refer to IEEE 802.15.4-2020 section, table and figure numbering - unless otherwise specified.

Zephyr supports both, native IEEE 802.15.4 and Thread, with 6LoWPAN. Zephyr’s Thread protocol implementation is based on OpenThread. The IPv6 header compression in 6LoWPAN is shared among native IEEE 802.15.4 and the Bluetooth IPSP (IP support profile).

API Reference

IEEE 802.15.4 API Overview

Gives an introduction and overview over the whole IEEE 802.15.4 subsystem and all of its APIs, configuration and user interfaces for all audiences.

Related code samples

group ieee802154

IEEE 802.15.4 native and OpenThread L2, configuration, management and driver APIs.

The IEEE 802.15.4 and Thread subsystems comprise the OpenThread L2 subsystem, the native IEEE 802.15.4 L2 subsystem (“Soft” MAC), a mostly vendor and protocol agnostic driver API shared between the OpenThread and native L2 stacks (“Hard” MAC and PHY) as well as several APIs to configure the subsystem (shell, net management, Kconfig, devicetree, etc.).

The OpenThread subsystem API integrates the external OpenThread stack into Zephyr. It builds upon Zephyr’s native IEEE 802.15.4 driver API.

The native IEEE 802.15.4 subsystem APIs are exposed at different levels and address several audiences:

  • shell (end users, application developers):

    • a set of IEEE 802.15.4 shell commands (see shell> ieee802154 help)

  • application API (application developers):

    • IPv6, DGRAM and RAW sockets for actual peer-to-peer, multicast and broadcast data exchange between nodes including connection specific configuration (sample coming soon, see https://github.com/linux-wpan/wpan-tools/tree/master/examples for now which inspired our API and therefore has a similar socket API),

    • Kconfig and devicetree configuration options (net config library extension, subsystem-wide MAC and PHY Kconfig/DT options, driver/vendor specific Kconfig/DT options, watch out for options prefixed with IEEE802154/ieee802154),

    • Network Management: runtime configuration of the IEEE 802.15.4 protocols stack at the MAC (L2) and PHY (L1) levels (see IEEE 802.15.4 Net Management),

  • L2 integration (subsystem contributors):

  • OpenThread and native IEEE 802.15.4 share a common driver API (driver maintainers/contributors):

    • see IEEE 802.15.4 Drivers

    • a basic, mostly PHY-level driver API to be implemented by all drivers,

    • several “hard MAC” (hardware/firmware offloading) extension points for performance critical or timing sensitive aspects of the protocol

IEEE 802.15.4 Management API

This is the main subsystem-specific API of interest to IEEE 802.15.4 application developers as it allows to configure the IEEE 802.15.4 subsystem at runtime. Other relevant interfaces for application developers are the typical shell, socket, Kconfig and devicetree APIs that can be accessed through Zephyr’s generic subsystem-independent documentation. Look out for IEEE802154/ieee802154 prefixes there.

group ieee802154_mgmt

IEEE 802.15.4 net management library.

The IEEE 802.15.4 net management library provides runtime configuration features that applications can interface with directly.

Most of these commands are also accessible via shell commands. See the shell’s help feature (shell> ieee802154 help).

Note

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

Command Macros

IEEE 802.15.4 net management commands.

These IEEE 802.15.4 subsystem net management commands can be called by applications via Network Management macro.

All attributes and parameters are given in CPU byte order (scalars) or big endian (byte arrays) unless otherwise specified.

The following IEEE 802.15.4 MAC management service primitives are referenced in this enumeration:

  • MLME-ASSOCIATE.request, see section 8.2.3

  • MLME-DISASSOCIATE.request, see section 8.2.4

  • MLME-SET/GET.request, see section 8.2.6

  • MLME-SCAN.request, see section 8.2.11

The following IEEE 802.15.4 MAC data service primitives are referenced in this enumeration:

  • MLME-DATA.request, see section 8.3.2

MAC PIB attributes (mac…/sec…): see sections 8.4.3 and 9.5. PHY PIB attributes (phy…): see section 11.3. Both are accessed through MLME-SET/GET primitives.

NET_REQUEST_IEEE802154_SET_ACK

Sets AckTx for all subsequent MLME-DATA (aka TX) requests.

NET_REQUEST_IEEE802154_UNSET_ACK

Unsets AckTx for all subsequent MLME-DATA requests.

NET_REQUEST_IEEE802154_PASSIVE_SCAN

MLME-SCAN(PASSIVE, …) request.

See ieee802154_req_params for associated command parameters.

NET_REQUEST_IEEE802154_ACTIVE_SCAN

MLME-SCAN(ACTIVE, …) request.

See ieee802154_req_params for associated command parameters.

NET_REQUEST_IEEE802154_CANCEL_SCAN

Cancels an ongoing MLME-SCAN(…) command (non-standard).

NET_REQUEST_IEEE802154_ASSOCIATE

MLME-ASSOCIATE(…) request.

NET_REQUEST_IEEE802154_DISASSOCIATE

MLME-DISASSOCIATE(…) request.

NET_REQUEST_IEEE802154_SET_CHANNEL

MLME-SET(phyCurrentChannel) request.

NET_REQUEST_IEEE802154_GET_CHANNEL

MLME-GET(phyCurrentChannel) request.

NET_REQUEST_IEEE802154_SET_PAN_ID

MLME-SET(macPanId) request.

NET_REQUEST_IEEE802154_GET_PAN_ID

MLME-GET(macPanId) request.

NET_REQUEST_IEEE802154_SET_EXT_ADDR

Sets the extended interface address (non-standard), see sections 7.1 and 8.4.3.1, in big endian byte order.

NET_REQUEST_IEEE802154_GET_EXT_ADDR

like MLME-GET(macExtendedAddress) but in big endian byte order

NET_REQUEST_IEEE802154_SET_SHORT_ADDR

MLME-SET(macShortAddress) request, only allowed for co-ordinators.

NET_REQUEST_IEEE802154_GET_SHORT_ADDR

MLME-GET(macShortAddress) request.

NET_REQUEST_IEEE802154_GET_TX_POWER

MLME-SET(phyUnicastTxPower/phyBroadcastTxPower) request (currently not distinguished)

NET_REQUEST_IEEE802154_SET_TX_POWER

MLME-GET(phyUnicastTxPower/phyBroadcastTxPower) request.

NET_REQUEST_IEEE802154_SET_SECURITY_SETTINGS

Configures basic sec* MAC PIB attributes, implies macSecurityEnabled=true.

See ieee802154_security_params for associated command parameters.

NET_REQUEST_IEEE802154_GET_SECURITY_SETTINGS

Gets the configured sec* attributes.

See ieee802154_security_params for associated command parameters.

Event Macros

IEEE 802.15.4 net management events.

These IEEE 802.15.4 subsystem net management events can be subscribed to by applications via net_mgmt_init_event_callback, net_mgmt_add_event_callback and net_mgmt_del_event_callback.

NET_EVENT_IEEE802154_SCAN_RESULT

Signals the result of the NET_REQUEST_IEEE802154_ACTIVE_SCAN or NET_REQUEST_IEEE802154_PASSIVE_SCAN net management commands.

See ieee802154_req_params for associated event parameters.

struct ieee802154_req_params
#include <ieee802154_mgmt.h>

Scanning parameters.

Used to request a scan and get results as well, see section 8.2.11.2

Public Members

uint32_t channel_set

The set of channels to scan, use above macros to manage it.

uint32_t duration

Duration of scan, per-channel, in milliseconds.

uint16_t channel

Current channel in use as a result.

uint16_t pan_id

Current pan_id in use as a result.

union ieee802154_req_params

Result address.

uint8_t len

length of address

uint8_t lqi

Link quality information, between 0 and 255.

struct ieee802154_security_params
#include <ieee802154_mgmt.h>

Security parameters.

Used to setup the link-layer security settings, see tables 9-9 and 9-10 in section 9.5.

IEEE 802.15.4 Driver API

This is the main API of interest to IEEE 802.15.4 driver developers.

group ieee802154_driver

IEEE 802.15.4 driver API.

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

The IEEE 802.15.4 driver API consists of two separate parts:

  • a basic, mostly PHY-level driver API to be implemented by all drivers,

  • several optional MAC-level extension points to offload performance critical or timing sensitive aspects at MAC level to the driver hardware or firmware (“hard” MAC).

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

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

Note

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

IEEE 802.15.4-2020, Section 10: General PHY requirements

enum ieee802154_phy_channel_page

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.

Values:

enumerator IEEE802154_ATTR_PHY_CHANNEL_PAGE_ZERO_OQPSK_2450_BPSK_868_915 = BIT(0)

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

enumerator IEEE802154_ATTR_PHY_CHANNEL_PAGE_ONE_DEPRECATED = BIT(1)

Formerly ASK PHY - deprecated in IEEE 802.15.4-2015.

enumerator IEEE802154_ATTR_PHY_CHANNEL_PAGE_TWO_OQPSK_868_915 = BIT(2)

O-QPSK PHY - 868 MHz and 915 MHz bands, see section 10.1.3.3.

enumerator IEEE802154_ATTR_PHY_CHANNEL_PAGE_THREE_CSS = BIT(3)

CSS PHY - 2450 MHz band, see section 10.1.3.4.

enumerator IEEE802154_ATTR_PHY_CHANNEL_PAGE_FOUR_HRP_UWB = BIT(4)

UWB PHY - SubG, low and high bands, see section 10.1.3.5.

enumerator IEEE802154_ATTR_PHY_CHANNEL_PAGE_FIVE_OQPSK_780 = BIT(5)

O-QPSK PHY - 780 MHz band, see section 10.1.3.2.

enumerator IEEE802154_ATTR_PHY_CHANNEL_PAGE_SIX_RESERVED = BIT(6)

reserved - not currently assigned

enumerator IEEE802154_ATTR_PHY_CHANNEL_PAGE_SEVEN_MSK = BIT(7)

MSK PHY - 780 MHz and 2450 MHz bands, see sections 10.1.3.6, 10.1.3.7.

enumerator IEEE802154_ATTR_PHY_CHANNEL_PAGE_EIGHT_LRP_UWB = BIT(8)

LRP UWB PHY, see sections 10.1.3.8.

enumerator IEEE802154_ATTR_PHY_CHANNEL_PAGE_NINE_SUN_PREDEFINED = BIT(9)

SUN FSK/OFDM/O-QPSK PHYs - predefined bands, operating modes and channels, see sections 10.1.3.9.

enumerator IEEE802154_ATTR_PHY_CHANNEL_PAGE_TEN_SUN_FSK_GENERIC = BIT(10)

SUN FSK/OFDM/O-QPSK PHYs - generic modulation and channel description, see sections 10.1.3.9, 7.4.4.11.

enumerator IEEE802154_ATTR_PHY_CHANNEL_PAGE_ELEVEN_OQPSK_2380 = BIT(11)

O-QPSK PHY - 2380 MHz band, see section 10.1.3.10.

enumerator IEEE802154_ATTR_PHY_CHANNEL_PAGE_TWELVE_LECIM = BIT(12)

LECIM DSSS/FSK PHYs, see section 10.1.3.11.

enumerator IEEE802154_ATTR_PHY_CHANNEL_PAGE_THIRTEEN_RCC = BIT(13)

RCC PHY, see section 10.1.3.12.

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.

This is what most IEEE 802.15.4 drivers need.

Example usage:

IEEE802154_DEFINE_PHY_SUPPORTED_CHANNELS(drv_attr, 11, 26);

The attribute may then be referenced like this:

... &drv_attr.phy_supported_channels ...

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

Parameters:

  • drv_attr – name of the local static variable to be declared for the local attributes structure

  • from – the first channel to be supported

  • to – the last channel to be supported

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

represents the nominal pulse rate frequency of an HRP UWB PHY

Values:

enumerator IEEE802154_PHY_HRP_UWB_PRF_OFF = 0

standard modes, see section 8.3.2, table 8-88.

enumerator IEEE802154_PHY_HRP_UWB_NOMINAL_4_M = BIT(0)
enumerator IEEE802154_PHY_HRP_UWB_NOMINAL_16_M = BIT(1)
enumerator IEEE802154_PHY_HRP_UWB_NOMINAL_64_M = BIT(2)
enumerator IEEE802154_PHY_HRP_UWB_NOMINAL_64_M_BPRF = BIT(3)

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.

enumerator IEEE802154_PHY_HRP_UWB_NOMINAL_128_M_HPRF = BIT(4)
enumerator IEEE802154_PHY_HRP_UWB_NOMINAL_256_M_HPRF = BIT(5)
IEEE802154_PHY_HRP_UWB_PRF4_TPSYM_SYMBOL_PERIOD_NS

Nominal PRF 4MHz symbol period.

IEEE802154_PHY_HRP_UWB_PRF16_TPSYM_SYMBOL_PERIOD_NS

Nominal PRF 16MHz symbol period.

IEEE802154_PHY_HRP_UWB_PRF64_TPSYM_SYMBOL_PERIOD_NS

Nominal PRF 64MHz symbol period.

IEEE802154_PHY_HRP_UWB_ERDEV_TPSYM_SYMBOL_PERIOD_NS

ERDEV symbol period.

IEEE802154_PHY_HRP_UWB_RDEV

RDEV device mask.

IEEE802154_PHY_HRP_UWB_ERDEV

ERDEV device mask.

IEEE 802.15.4 Driver API

enum ieee802154_hw_caps

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

Values:

enumerator IEEE802154_HW_ENERGY_SCAN = BIT(0)

Energy detection (ED) supported (optional)

enumerator IEEE802154_HW_FCS = BIT(1)

Frame checksum verification supported.

enumerator IEEE802154_HW_FILTER = BIT(2)

Filtering of PAN ID, extended and short address supported.

enumerator IEEE802154_HW_PROMISC = BIT(3)

Promiscuous mode supported.

enumerator IEEE802154_HW_CSMA = BIT(4)

CSMA-CA procedure supported on TX.

enumerator IEEE802154_HW_TX_RX_ACK = BIT(5)

Waits for ACK on TX if AR bit is set in TX pkt.

enumerator IEEE802154_HW_RETRANSMISSION = BIT(6)

Supports retransmission on TX ACK timeout.

enumerator IEEE802154_HW_RX_TX_ACK = BIT(7)

Sends ACK on RX if AR bit is set in RX pkt.

enumerator IEEE802154_HW_TXTIME = BIT(8)

TX at specified time supported.

enumerator IEEE802154_HW_SLEEP_TO_TX = BIT(9)

TX directly from sleep supported.

enumerator IEEE802154_HW_RXTIME = BIT(10)

Timed RX window scheduling supported.

enumerator IEEE802154_HW_TX_SEC = BIT(11)

TX security supported (key management, encryption and authentication)

enum ieee802154_filter_type

Filter type, see ieee802154_radio_api::filter.

Values:

enumerator IEEE802154_FILTER_TYPE_IEEE_ADDR
enumerator IEEE802154_FILTER_TYPE_SHORT_ADDR
enumerator IEEE802154_FILTER_TYPE_PAN_ID
enumerator IEEE802154_FILTER_TYPE_SRC_IEEE_ADDR
enumerator IEEE802154_FILTER_TYPE_SRC_SHORT_ADDR
enum ieee802154_event

Driver events, see IEEE802154_CONFIG_EVENT_HANDLER.

Values:

enumerator IEEE802154_EVENT_TX_STARTED

Data transmission started.

enumerator IEEE802154_EVENT_RX_FAILED

Data reception failed.

enumerator IEEE802154_EVENT_SLEEP

An RX slot ended, requires IEEE802154_HW_RXTIME.

Note

This event SHALL not be triggered by drivers when RX is synchronously switched of due to a call to stop() or an RX slot being configured.

enum ieee802154_rx_fail_reason

RX failed event reasons, see IEEE802154_EVENT_RX_FAILED.

Values:

enumerator IEEE802154_RX_FAIL_NOT_RECEIVED

Nothing received.

enumerator IEEE802154_RX_FAIL_INVALID_FCS

Frame had invalid checksum.

enumerator IEEE802154_RX_FAIL_ADDR_FILTERED

Address did not match.

enumerator IEEE802154_RX_FAIL_OTHER

General reason.

enum ieee802154_tx_mode

IEEE 802.15.4 Transmission mode.

Values:

enumerator IEEE802154_TX_MODE_DIRECT

Transmit packet immediately, no CCA.

enumerator IEEE802154_TX_MODE_CCA

Perform CCA before packet transmission.

enumerator IEEE802154_TX_MODE_CSMA_CA

Perform full CSMA/CA procedure before packet transmission.

Note

requires IEEE802154_HW_CSMA capability.

enumerator IEEE802154_TX_MODE_TXTIME

Transmit packet in the future, at the specified time, no CCA.

Note

requires IEEE802154_HW_TXTIME capability.

enumerator IEEE802154_TX_MODE_TXTIME_CCA

Transmit packet in the future, perform CCA before transmission.

Note

requires IEEE802154_HW_TXTIME capability.

enumerator IEEE802154_TX_MODE_COMMON_COUNT

Number of modes defined in ieee802154_tx_mode.

enumerator IEEE802154_TX_MODE_PRIV_START = IEEE802154_TX_MODE_COMMON_COUNT

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

enum ieee802154_fpb_mode

IEEE 802.15.4 Frame Pending Bit table address matching mode.

Values:

enumerator IEEE802154_FPB_ADDR_MATCH_THREAD

The pending bit shall be set only for addresses found in the list.

enumerator IEEE802154_FPB_ADDR_MATCH_ZIGBEE

The pending bit shall be cleared for short addresses found in the list.

enum ieee802154_config_type

IEEE 802.15.4 driver configuration types.

Values:

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.

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

enumerator IEEE802154_CONFIG_PAN_COORDINATOR

Indicates whether the device is a PAN coordinator.

This influences packet filtering.

Note

Available in any interface operational state.

enumerator IEEE802154_CONFIG_PROMISCUOUS

Enable/disable promiscuous mode.

Note

Available in any interface operational state.

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

enumerator IEEE802154_CONFIG_MAC_KEYS

Updates MAC keys, key index and the per-key frame counter for drivers supporting transmit security offloading, see section 9.5, tables 9-9 and 9-10.

The key configuration SHALL NOT be accepted if the frame counter (in case frame counter per key is true) is not strictly larger than the current frame counter associated with the same key, see sections 8.2.2, 9.2.4 g/h) and 9.4.3.

Note

Available in any interface operational state.

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

Note

Available in any interface operational state.

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.

enumerator IEEE802154_CONFIG_FRAME_COUNTER_IF_LARGER

Sets the current MAC frame counter value if the provided value is greater than the current one.

Note

Available in any interface operational state.

Warning

This configuration option does not conform to the requirements specified in #61227 as it is redundant with IEEE802154_CONFIG_FRAME_COUNTER, and will therefore be deprecated in the future.

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

enumerator IEEE802154_CONFIG_CSL_PERIOD

Configure CSL receiver (Endpoint) period.

In order to configure a CSL receiver the upper layer should combine several configuration options in the following way:

  1. Use IEEE802154_CONFIG_ENH_ACK_HEADER_IE once to inform the driver of the short and extended addresses of the peer to which it should inject CSL IEs.

  2. Use IEEE802154_CONFIG_CSL_RX_TIME periodically, before each use of IEEE802154_CONFIG_CSL_PERIOD setting parameters of the nearest CSL RX window, and before each use of IEEE_CONFIG_RX_SLOT setting parameters of the following (not the nearest one) CSL RX window, to allow the driver to calculate the proper CSL phase to the nearest CSL window to inject in the CSL IEs for both transmitted data and ACK frames.

  3. Use IEEE802154_CONFIG_CSL_PERIOD on each value change to update the current CSL period value which will be injected in the CSL IEs together with the CSL phase based on IEEE802154_CONFIG_CSL_RX_TIME.

  4. Use IEEE802154_CONFIG_RX_SLOT periodically to schedule the immediate receive window early enough before the expected window start time, taking into account possible clock drifts and scheduling uncertainties.

This diagram shows the usage of the four options over time: 

    Start CSL                                  Schedule CSL window

ENH_ACK_HEADER_IE                        CSL_RX_TIME (following window)
     |                                        |
     | CSL_RX_TIME (nearest window)           | RX_SLOT (nearest window)
     |    |                                   |   |
     |    | CSL_PERIOD                        |   |
     |    |    |                              |   |
     v    v    v                              v   v
----------------------------------------------------------[ CSL window ]-----+
                                        ^                                    |
                                        |                                    |
                                        +--------------------- loop ---------+

Note

Available in any interface operational state.

Warning

This configuration option does not conform to the requirements specified in #61227 as it is incompatible with standard primitives and may therefore be deprecated in the future.

enumerator IEEE802154_CONFIG_CSL_RX_TIME

Configure the next CSL receive window (i.e.

“channel sample”) center, in units of nanoseconds relative to the network subsystem’s local clock.

Note

Available in any interface operational state.

Warning

This configuration option does not conform to the requirements specified in #61227 as it is incompatible with standard primitives and may therefore be deprecated in the future.

enumerator IEEE802154_CONFIG_ENH_ACK_HEADER_IE

Indicates whether to inject IE into ENH ACK Frame for specific address or not.

Disabling the ENH ACK with no address provided (NULL pointer) should disable it for all enabled addresses.

Note

Available in any interface operational state.

Warning

This configuration option does not conform to the requirements specified in #61227 as it is incompatible with standard primitives and may therefore be modified in the future.

enumerator IEEE802154_CONFIG_COMMON_COUNT

Number of types defined in ieee802154_config_type.

enumerator IEEE802154_CONFIG_PRIV_START = IEEE802154_CONFIG_COMMON_COUNT

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

enum ieee802154_attr

IEEE 802.15.4 driver attributes.

See ieee802154_attr_value and ieee802154_radio_api for usage details.

Values:

enumerator IEEE802154_ATTR_PHY_SUPPORTED_CHANNEL_PAGES

Retrieves a bit field with supported channel pages.

This attribute SHALL be implemented by all drivers.

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

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

enumerator IEEE802154_ATTR_COMMON_COUNT

Number of attributes defined in ieee802154_attr.

enumerator IEEE802154_ATTR_PRIV_START = IEEE802154_ATTR_COMMON_COUNT

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

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

This only applies to drivers with a single channel page.

Parameters:

  • attr – The attribute to be retrieved.

  • phy_supported_channel_page – The driver’s unique channel page.

  • phy_supported_channels – Pointer to the structure that contains the driver’s channel range or ranges.

  • value – The pointer to the value struct provided by the user.

Return values:

  • 0 – if the attribute could be resolved

  • -ENOENT – if the attribute could not be resolved

IEEE802154_HW_CAPS_BITS_COMMON_COUNT

Number of bits used by ieee802154_hw_caps type.

IEEE802154_HW_CAPS_BITS_PRIV_START

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

IEEE802154_CONFIG_RX_SLOT_NONE

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

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.

IEEE 802.15.4 driver utils

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

Parameters:

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

Returns:

true if AR flag is set, false otherwise

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.

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.

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.

Parameters:

  • iface – A valid pointer on a network interface that received the packet

  • pkt – A valid pointer on a packet to check

Returns:

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

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.

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

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

Parameters:

  • iface – A valid pointer on a network interface

IEEE 802.15.4-2020, Section 6: MAC functional description

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.

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.

IEEE 802.15.4-2020, Section 8: MAC services

IEEE802154_MAC_A_BASE_SLOT_DURATION

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_NUM_SUPERFRAME_SLOTS

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

IEEE802154_MAC_A_BASE_SUPERFRAME_DURATION

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

IEEE802154_MAC_RESPONSE_WAIT_TIME_DEFAULT

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

IEEE802154_PHY_A_TURNAROUND_TIME_DEFAULT

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

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.

IEEE802154_PHY_A_CCA_TIME

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

IEEE802154_PHY_OQPSK_868MHZ_SYMBOL_PERIOD_NS

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

IEEE802154_PHY_OQPSK_780_TO_2450MHZ_SYMBOL_PERIOD_NS

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

IEEE 802.15.4-2020, Section 13: BPSK PHY

IEEE802154_PHY_BPSK_868MHZ_SYMBOL_PERIOD_NS

BPSK 868MHz band symbol period, see section 13.3.3.

IEEE802154_PHY_BPSK_915MHZ_SYMBOL_PERIOD_NS

BPSK 915MHz band symbol period, see section 13.3.3.

IEEE 802.15.4-2020, Section 19: SUN FSK PHY

IEEE802154_PHY_SUN_FSK_863MHZ_915MHZ_SYMBOL_PERIOD_NS

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

IEEE802154_PHY_SUN_FSK_PHR_LEN

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

struct ieee802154_phy_channel_range
#include <ieee802154_radio.h>

Represents a supported channel range, see ieee802154_phy_supported_channels.

struct ieee802154_phy_supported_channels
#include <ieee802154_radio.h>

Represents a list channels supported by a driver for a given interface, see IEEE802154_ATTR_PHY_SUPPORTED_CHANNEL_RANGES.

Public Members

const struct ieee802154_phy_channel_range *const ranges

Pointer to an array of channel range structures.

Warning

The pointer must be valid and constant throughout the life of the interface.

const uint8_t num_ranges

The number of currently available channel ranges.

struct ieee802154_filter
#include <ieee802154_radio.h>

Filter value, see ieee802154_radio_api::filter.

Public Members

uint8_t *ieee_addr

Extended address, in little endian.

uint16_t short_addr

Short address, in CPU byte order.

uint16_t pan_id

PAN ID, in CPU byte order.

struct ieee802154_key
#include <ieee802154_radio.h>

Key configuration for transmit security offloading, see IEEE802154_CONFIG_MAC_KEYS.

struct ieee802154_config
#include <ieee802154_radio.h>

IEEE 802.15.4 driver configuration data.

Public Members

struct ieee802154_config auto_ack_fpb

see IEEE802154_CONFIG_AUTO_ACK_FPB

struct ieee802154_config ack_fpb

see IEEE802154_CONFIG_ACK_FPB

bool pan_coordinator

see IEEE802154_CONFIG_PAN_COORDINATOR

bool promiscuous

see IEEE802154_CONFIG_PROMISCUOUS

ieee802154_event_cb_t event_handler

see IEEE802154_CONFIG_EVENT_HANDLER

struct ieee802154_key *mac_keys

see IEEE802154_CONFIG_MAC_KEYS

Pointer to an array containing a list of keys used for MAC encryption. Refer to secKeyIdLookupDescriptor and secKeyDescriptor in IEEE 802.15.4

The key_value field points to a buffer containing the 16 byte key. The buffer SHALL be copied by the driver before returning from the call.

The variable length array is terminated by key_value field set to NULL.

uint32_t frame_counter

see IEEE802154_CONFIG_FRAME_COUNTER

net_time_t start

Nanosecond resolution timestamp relative to the network subsystem’s local clock defining the start of the RX window during which the receiver is expected to be listening (i.e.

not including any driver startup times).

Configuring an rx_slot with the start attribute set to -1 will cancel and delete any previously active rx slot.

net_time_t duration

Nanosecond resolution duration of the RX window relative to the above RX window start time during which the receiver is expected to be listening (i.e.

not including any shutdown times). Only positive values larger than or equal zero are allowed.

Setting the duration to zero will disable the receiver, no matter what the start parameter.

struct ieee802154_config rx_slot

see IEEE802154_CONFIG_RX_SLOT

uint32_t csl_period

see IEEE802154_CONFIG_CSL_PERIOD

The CSL period in units of 10 symbol periods, see section 7.4.2.3.

in CPU byte order

net_time_t csl_rx_time

see IEEE802154_CONFIG_CSL_RX_TIME

Nanosecond resolution timestamp relative to the network subsystem’s local clock defining the center of the CSL RX window at which the receiver is expected to be fully started up (i.e. not including any startup times).

const uint8_t *data

Header IEs to be added to the Enh-Ack frame.

in little endian

uint16_t data_len

length of the header IEs

uint16_t short_addr

Filters the devices that will receive this IE by short address.

MAY be set to IEEE802154_BROADCAST_ADDRESS to disable the filter.

in CPU byte order

const uint8_t *ext_addr

Filters the devices that will receive this IE by extended address.

MAY be set to NULL to disable the filter.

in big endian

struct ieee802154_config ack_ie

see IEEE802154_CONFIG_ENH_ACK_HEADER_IE

union ieee802154_config

Configuration data.

struct ieee802154_attr_value
#include <ieee802154_radio.h>

IEEE 802.15.4 driver attribute values.

This structure is reserved to scalar and structured attributes that originate in the driver implementation and can neither be implemented as boolean ieee802154_hw_caps nor be derived directly or indirectly by the MAC (L2) layer. In particular this structure MUST NOT be used to return configuration data that originate from L2.

Note

To keep this union reasonably small, any attribute requiring a large memory area, SHALL be provided pointing to static memory allocated by the driver and valid throughout the lifetime of the driver instance.

Public Members

uint32_t phy_supported_channel_pages

A bit field that represents the supported channel pages, see ieee802154_phy_channel_page.

Note

To keep the API extensible as required by the standard, supported pages are modeled as a bitmap to support drivers that implement runtime switching between multiple channel pages.

Note

Currently none of the Zephyr drivers implements more than one channel page at runtime, therefore only one bit will be set and the current channel page (see the PHY PIB attribute phyCurrentPage, section 11.3, table 11-2) is considered to be read-only, fixed and “well known” via the supported channel pages attribute.

const struct ieee802154_phy_supported_channels *phy_supported_channels

Pointer to a structure representing channel ranges currently available on the selected channel page.

The selected channel page corresponds to the phyCurrentPage PHY PIB attribute, see the description of phy_supported_channel_pages above. Currently it can be retrieved via the IEEE802154_ATTR_PHY_SUPPORTED_CHANNEL_PAGES attribute.

Most drivers will expose a single channel page with a single, often zero-based, fixed channel range.

Some notable exceptions:

  • The legacy channel page (zero) exposes ranges in different bands and even PHYs that are usually not implemented by a single driver.

  • SUN and LECIM PHYs specify a large number of bands and operating modes on a single page with overlapping channel ranges each. Some of these ranges are not zero-based or contain “holes”. This explains why several ranges may be necessary to represent all available channels.

  • UWB PHYs often support partial channel ranges on the same channel page depending on the supported bands.

In these cases, drivers may expose custom configuration attributes (Kconfig, devicetree, runtime, …) that allow switching between sub-ranges within the same channel page (e.g. switching between SubG and 2.4G bands on channel page zero or switching between multiple operating modes in the SUN or LECIM PHYs.

Warning

The pointer must be valid and constant throughout the life of the interface.

uint32_t phy_hrp_uwb_supported_nominal_prfs

A bit field representing supported HRP UWB pulse repetition frequencies (PRF), see enum ieee802154_phy_hrp_uwb_nominal_prf.

Note

Currently none of the Zephyr HRP UWB drivers implements more than one nominal PRF at runtime, therefore only one bit will be set and the current PRF (UwbPrf, MCPS-DATA.request, section 8.3.2, table 8-88) is considered to be read-only, fixed and “well known” via the supported PRF attribute.

struct ieee802154_radio_api
#include <ieee802154_radio.h>

IEEE 802.15.4 driver interface API.

While L1-level driver features are exclusively implemented by drivers and MAY be mandatory to support certain application requirements, L2 features SHOULD be optional by default and only need to be implemented for performance optimization or precise timing as deemed necessary by driver maintainers. Fallback implementations (“Soft MAC”) SHOULD be provided in the driver-independent L2 layer for all L2/MAC features especially if these features are not implemented in vendor hardware/firmware by a majority of existing in-tree drivers. If, however, a driver offers offloading opportunities then L2 implementations SHALL delegate performance critical or resource intensive tasks to the driver.

All drivers SHALL support two externally observable interface operational states: “UP” and “DOWN”. Drivers MAY additionally support a “TESTING” interface state (see continuous_carrier()).

The following rules apply:

  • An interface is considered “UP” when it is able to transmit and receive packets, “DOWN” otherwise (see precise definitions of the corresponding ifOperStatus values in RFC 2863, section 3.1.14, net_if_oper_state and the continuous_carrier() exception below). A device that has its receiver temporarily disabled during “UP” state due to an active receive window configuration is still considered “UP”.

  • Upper layers will assume that the interface managed by the driver is “UP” after a call to start() returned zero or -EALREADY. Upper layers assume that the interface is “DOWN” after calling stop() returned zero or -EALREADY.

  • The driver SHALL block start()/stop() calls until the interface fully transitioned to the new state (e.g. the receiver is operational, ongoing transmissions were finished, etc.). Drivers SHOULD yield the calling thread (i.e. “sleep”) if waiting for the new state without CPU interaction is possible.

  • Drivers are responsible of guaranteeing atomicity of state changes. Appropriate means of synchronization SHALL be implemented (locking, atomic flags, …).

  • While the interface is “DOWN”, the driver SHALL be placed in the lowest possible power state. The driver MAY return from a call to stop() before it reaches the lowest possible power state, i.e. manage power asynchronously. While the interface is “UP”, the driver SHOULD autonomously and asynchronously transition to lower power states whenever possible. If the driver claims to support timed RX/TX capabilities and the upper layers configure an RX slot, then the driver SHALL immediately transition (asynchronously) to the lowest possible power state until the start of the RX slot or until a scheduled packet needs to be transmitted.

  • The driver SHALL NOT change the interface’s “UP”/”DOWN” state on its own. Initially, the interface SHALL be in the “DOWN” state.

  • Drivers that implement the optional continuous_carrier() operation will be considered to be in the RFC 2863 “testing” ifOperStatus state if that operation returns zero. This state is active until either start() or stop() is called. If continuous_carrier() returns a non-zero value then the previous state is assumed by upper layers.

  • If calls to start()/stop() return any other value than zero or -EALREADY, upper layers will consider the interface to be in a “lowerLayerDown” state as defined in RFC 2863.

  • The RFC 2863 “dormant”, “unknown” and “notPresent” ifOperStatus states are currently not supported. The “lowerLevelUp” state.

  • The ed_scan(), cca() and tx() operations SHALL only be supported in the “UP” state and return -ENETDOWN in any other state. See the function-level API documentation below for further details.

Note

This structure is called “radio” API for backwards compatibility. A better name would be “IEEE 802.15.4 driver API” as typical drivers will not only implement L1/radio (PHY) features but also L2 (MAC) features if the vendor-specific driver hardware or firmware offers offloading opportunities.

Note

In case of devices that support timed RX/TX, the “UP” state is not equal to “receiver enabled”. If a receive window (i.e. RX slot, see IEEE802154_CONFIG_RX_SLOT) is configured before calling start() then the receiver will not be enabled when transitioning to the “UP” state. Configuring a receive window while the interface is “UP” will cause the receiver to be disabled immediately until the configured reception time has arrived.

Public Members

struct net_if_api iface_api

network interface API

Note

Network devices must extend the network interface API. It is therefore mandatory to place it at the top of the driver API struct so that it can be cast to a network interface.

enum ieee802154_hw_caps (*get_capabilities)(const struct device *dev)

Get the device driver capabilities.

Note

Implementations SHALL be isr-ok and MUST NOT sleep. MAY be called in any interface state once the driver is fully initialized (“ready”).

Param dev:

pointer to IEEE 802.15.4 driver device

Return:

Bit field with all supported device driver capabilities.

int (*cca)(const struct device *dev)

Clear Channel Assessment - Check channel’s activity.

Note

Implementations SHALL be isr-ok and MAY sleep. SHALL return -ENETDOWN unless the interface is “UP”.

Param dev:

pointer to IEEE 802.15.4 driver device

Retval 0:

the channel is available

Retval -EBUSY:

The channel is busy.

Retval -EWOULDBLOCK:

The operation is called from ISR context but temporarily cannot be executed without blocking.

Retval -ENETDOWN:

The interface is not “UP”.

Retval -ENOTSUP:

CCA is not supported by this driver.

Retval -EIO:

The CCA procedure could not be executed.

int (*set_channel)(const struct device *dev, uint16_t channel)

Set current channel.

Note

Implementations SHALL be isr-ok and MAY sleep. SHALL return -EIO unless the interface is either “UP” or “DOWN”.

Param dev:

pointer to IEEE 802.15.4 driver device

Param channel:

the number of the channel to be set in CPU byte order

Retval 0:

channel was successfully set

Retval -EALREADY:

The previous channel is the same as the requested channel.

Retval -EINVAL:

The given channel is not within the range of valid channels of the driver’s current channel page, see the IEEE802154_ATTR_PHY_SUPPORTED_CHANNEL_RANGES driver attribute.

Retval -EWOULDBLOCK:

The operation is called from ISR context but temporarily cannot be executed without blocking.

Retval -ENOTSUP:

The given channel is within the range of valid channels of the driver’s current channel page but unsupported by the current driver.

Retval -EIO:

The channel could not be set.

int (*filter)(const struct device *dev, bool set, enum ieee802154_filter_type type, const struct ieee802154_filter *filter)

Set/Unset PAN ID, extended or short address filters.

Note

requires IEEE802154_HW_FILTER capability.

Note

Implementations SHALL be isr-ok and MAY sleep. SHALL return -EIO unless the interface is either “UP” or “DOWN”.

Param dev:

pointer to IEEE 802.15.4 driver device

Param set:

true to set the filter, false to remove it

Param type:

the type of entity to be added/removed from the filter list (a PAN ID or a source/destination address)

Param filter:

the entity to be added/removed from the filter list

Retval 0:

The filter was successfully added/removed.

Retval -EINVAL:

The given filter entity or filter entity type was not valid.

Retval -EWOULDBLOCK:

The operation is called from ISR context but temporarily cannot be executed without blocking.

Retval -ENOTSUP:

Setting/removing this filter or filter type is not supported by this driver.

Retval -EIO:

Error while setting/removing the filter.

int (*set_txpower)(const struct device *dev, int16_t dbm)

Set TX power level in dbm.

Note

Implementations SHALL be isr-ok and MAY sleep. SHALL return -EIO unless the interface is either “UP” or “DOWN”.

Param dev:

pointer to IEEE 802.15.4 driver device

Param dbm:

TX power in dbm

Retval 0:

The TX power was successfully set.

Retval -EINVAL:

The given dbm value is invalid or not supported by the driver.

Retval -EWOULDBLOCK:

The operation is called from ISR context but temporarily cannot be executed without blocking.

Retval -EIO:

The TX power could not be set.

int (*tx)(const struct device *dev, enum ieee802154_tx_mode mode, struct net_pkt *pkt, struct net_buf *frag)

Transmit a packet fragment as a single frame.

Depending on the level of offloading features supported by the driver, the frame MAY not be fully encrypted/authenticated or it MAY not contain an FCS. It is the responsibility of L2 implementations to prepare the frame according to the offloading capabilities announced by the driver and to decide whether CCA, CSMA/CA, ACK or retransmission procedures need to be executed outside (“soft MAC”) or inside (“hard MAC”) the driver .

All frames originating from L2 SHALL have all required IEs pre-allocated and pre-filled such that the driver does not have to parse and manipulate IEs at all. This includes ACK packets if the driver does not have the IEEE802154_HW_RX_TX_ACK capability. Also see IEEE802154_CONFIG_ENH_ACK_HEADER_IE for drivers that have the IEEE802154_HW_RX_TX_ACK capability.

IEs that cannot be prepared by L2 unless the TX time is known (e.g. CSL IE, Rendezvous Time IE, Time Correction IE, …) SHALL be sent in any of the timed TX modes with appropriate timing information pre-filled in the IE such that drivers do not have to parse and manipulate IEs at all unless the frame is generated by the driver itself.

In case any of the timed TX modes is supported and used (see ieee802154_hw_caps and ieee802154_tx_mode), the driver SHALL take responsibility of scheduling and sending the packet at the precise programmed time autonomously without further interaction by upper layers. The call to tx() will block until the package has either been sent successfully (possibly including channel acquisition and packet acknowledgment) or a terminal transmission error occurred. The driver SHALL sleep and keep power consumption to the lowest possible level until the scheduled transmission time arrives or during any other idle waiting time.

Note

Implementations MAY sleep and will usually NOT be isr-ok - especially when timed TX, CSMA/CA, retransmissions, auto-ACK or any other offloading feature is supported that implies considerable idle waiting time. SHALL return -ENETDOWN unless the interface is “UP”.

Warning

The driver SHALL NOT take ownership of the given network packet and frame (fragment) buffer. Any data required by the driver including the actual frame content must be read synchronously and copied internally if needed at a later time (e.g. the contents of IEs required for protocol configuration, states of frame counters, sequence numbers, etc). Both, the packet and the buffer MAY be re-used or released by upper layers immediately after the function returns.

Param dev:

pointer to IEEE 802.15.4 driver device

Param mode:

the transmission mode, some of which require specific offloading capabilities.

Param pkt:

pointer to the network packet to be transmitted.

Param frag:

pointer to a network buffer containing a single fragment with the frame data to be transmitted

Retval 0:

The frame was successfully sent or scheduled. If the driver supports ACK offloading and the frame requested acknowlegment (AR bit set), this means that the packet was successfully acknowledged by its peer.

Retval -EINVAL:

Invalid packet (e.g. an expected IE is missing or the encryption/authentication state is not as expected).

Retval -EBUSY:

The frame could not be sent because the medium was busy (CSMA/CA or CCA offloading feature only).

Retval -ENOMSG:

The frame was not confirmed by an ACK packet (TX ACK offloading feature only).

Retval -ENOBUFS:

The frame could not be scheduled due to missing internal resources (timed TX offloading feature only).

Retval -ENETDOWN:

The interface is not “UP”.

Retval -ENOTSUP:

The given TX mode is not supported.

Retval -EIO:

The frame could not be sent due to some unspecified driver error (e.g. the driver being busy).

int (*start)(const struct device *dev)

Start the device.

Upper layers will assume the interface is “UP” if this operation returns with zero or -EALREADY. The interface is placed in receive mode before returning from this operation unless an RX slot has been configured (even if it lies in the past, see IEEE802154_CONFIG_RX_SLOT).

Note

Implementations SHALL be isr-ok and MAY sleep. MAY be called in any interface state once the driver is fully initialized (“ready”).

Param dev:

pointer to IEEE 802.15.4 driver device

Retval 0:

The driver was successfully started.

Retval -EALREADY:

The driver was already “UP”.

Retval -EWOULDBLOCK:

The operation is called from ISR context but temporarily cannot be executed without blocking.

Retval -EIO:

The driver could not be started.

int (*stop)(const struct device *dev)

Stop the device.

Upper layers will assume the interface is “DOWN” if this operation returns with zero or -EALREADY. The driver switches off the receiver before returning if it was previously on. The driver enters the lowest possible power mode after this operation is called. This MAY happen asynchronously (i.e. after the operation already returned control).

Note

Implementations SHALL be isr-ok and MAY sleep. MAY be called in any interface state once the driver is fully initialized (“ready”).

Param dev:

pointer to IEEE 802.15.4 driver device

Retval 0:

The driver was successfully stopped.

Retval -EWOULDBLOCK:

The operation is called from ISR context but temporarily cannot be executed without blocking.

Retval -EALREADY:

The driver was already “DOWN”.

Retval -EIO:

The driver could not be stopped.

int (*continuous_carrier)(const struct device *dev)

Start continuous carrier wave transmission.

The method blocks until the interface has started to emit a continuous carrier. To leave this mode, start() or stop() should be called, which will put the driver back into the “UP” or “DOWN” states, respectively.

Note

Implementations MAY sleep and will usually NOT be isr-ok. MAY be called in any interface state once the driver is fully initialized (“ready”).

Param dev:

pointer to IEEE 802.15.4 driver device

Retval 0:

continuous carrier wave transmission started

Retval -EALREADY:

The driver was already in “TESTING” state and emitting a continuous carrier.

Retval -EIO:

not started

int (*configure)(const struct device *dev, enum ieee802154_config_type type, const struct ieee802154_config *config)

Set or update driver configuration.

The method blocks until the interface has been reconfigured atomically with respect to ongoing package reception, transmission or any other ongoing driver operation.

Note

Implementations SHALL be isr-ok and MAY sleep. MAY be called in any interface state once the driver is fully initialized (“ready”). Some configuration options may not be supported in all interface operational states, see the detailed specifications in ieee802154_config_type. In this case the operation returns -EACCES.

Param dev:

pointer to IEEE 802.15.4 driver device

Param type:

the configuration type to be set

Param config:

the configuration parameters to be set for the given configuration type

Retval 0:

configuration successful

Retval -EINVAL:

The configuration parameters are invalid for the given configuration type.

Retval -ENOTSUP:

The given configuration type is not supported by this driver.

Retval -EACCES:

The given configuration type is supported by this driver but cannot be configured in the current interface operational state.

Retval -ENOMEM:

The configuration cannot be saved due to missing memory resources.

Retval -ENOENT:

The resource referenced in the configuration parameters cannot be found in the configuration.

Retval -EWOULDBLOCK:

The operation is called from ISR context but temporarily cannot be executed without blocking.

Retval -EIO:

An internal error occurred while trying to configure the given configuration parameter.

int (*ed_scan)(const struct device *dev, uint16_t duration, energy_scan_done_cb_t done_cb)

Run an energy detection scan.

Note

requires IEEE802154_HW_ENERGY_SCAN capability

Note

The radio channel must be set prior to calling this function.

Note

Implementations SHALL be isr-ok and MAY sleep. SHALL return -ENETDOWN unless the interface is “UP”.

Param dev:

pointer to IEEE 802.15.4 driver device

Param duration:

duration of energy scan in ms

Param done_cb:

function called when the energy scan has finished

Retval 0:

the energy detection scan was successfully scheduled

Retval -EBUSY:

the energy detection scan could not be scheduled at this time

Retval -EALREADY:

a previous energy detection scan has not finished yet.

Retval -ENETDOWN:

The interface is not “UP”.

Retval -ENOTSUP:

This driver does not support energy scans.

Retval -EIO:

The energy detection procedure could not be executed.

net_time_t (*get_time)(const struct device *dev)

Get the current time in nanoseconds relative to the network subsystem’s local uptime clock as represented by this network interface.

See net_time_t for semantic details.

Note

requires IEEE802154_HW_TXTIME and/or IEEE802154_HW_RXTIME capabilities. Implementations SHALL be isr-ok and MUST NOT sleep. MAY be called in any interface state once the driver is fully initialized (“ready”).

Param dev:

pointer to IEEE 802.15.4 driver device

Return:

nanoseconds relative to the network subsystem’s local clock, -1 if an error occurred or the operation is not supported

uint8_t (*get_sch_acc)(const struct device *dev)

Get the current estimated worst case accuracy (maximum ± deviation from the nominal frequency) of the network subsystem’s local clock used to calculate tolerances and guard times when scheduling delayed receive or transmit radio operations.

The deviation is given in units of PPM (parts per million).

Note

requires IEEE802154_HW_TXTIME and/or IEEE802154_HW_RXTIME capabilities.

Note

Implementations may estimate this value based on current operating conditions (e.g. temperature). Implementations SHALL be isr-ok and MUST NOT sleep. MAY be called in any interface state once the driver is fully initialized (“ready”).

Param dev:

pointer to IEEE 802.15.4 driver device

Return:

current estimated clock accuracy in PPM

int (*attr_get)(const struct device *dev, enum ieee802154_attr attr, struct ieee802154_attr_value *value)

Get the value of a driver specific attribute.

Note

This function SHALL NOT return any values configurable by the MAC (L2) layer. It is reserved to non-boolean (i.e. scalar or structured) attributes that originate from the driver implementation and cannot be directly or indirectly derived by L2. Boolean attributes SHALL be implemented as ieee802154_hw_caps.

Note

Implementations SHALL be isr-ok and MUST NOT sleep. MAY be called in any interface state once the driver is fully initialized (“ready”).

Retval 0:

The requested attribute is supported by the driver and the value can be retrieved from the corresponding ieee802154_attr_value member.

Retval -ENOENT:

The driver does not provide the requested attribute. The value structure has not been updated with attribute data. The content of the value attribute is undefined.

IEEE 802.15.4 L2 / Native Stack API

This documents the IEEE 802.15.4 L2 native stack, which neither applications nor drivers will ever access directly. It is called internally by Zephyr’s upper network layers (L3+), its socket and network context abstractions. This API is therefore of interest to IEEE 802.15.4 subsystem contributors only.

group ieee802154_l2

IEEE 802.15.4 L2 APIs.

This API provides integration with Zephyr’s sockets and network contexts. Application and driver developers should never interface directly with this API. It is of interest to subsystem maintainers only.

The API implements and extends the following structures:

Note

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

Defines

IEEE802154_MAX_PHY_PACKET_SIZE

Represents the PHY constant aMaxPhyPacketSize, see section 11.3.

Note

Currently only 127 byte sized packets are supported although some PHYs (e.g. SUN, MSK, LECIM, …) support larger packet sizes. Needs to be changed once those PHYs should be fully supported.

IEEE802154_FCS_LENGTH

Represents the frame check sequence length, see section 7.2.1.1.

Note

Currently only a 2 byte FCS is supported although some PHYs (e.g. SUN, TVWS, …) optionally support a 4 byte FCS. Needs to be changed once those PHYs should be fully supported.

IEEE802154_MTU

IEEE 802.15.4 “hardware” MTU (not to be confused with L3/IP MTU), i.e.

the actual payload available to the next higher layer.

This is equivalent to the IEEE 802.15.4 MAC frame length minus checksum bytes which is again equivalent to the PHY payload aka PSDU length minus checksum bytes. This definition exists for compatibility with the same concept in Linux and Zephyr’s L3. It is not a concept from the IEEE 802.15.4 standard.

Note

Currently only the original frame size from the 2006 standard version and earlier is supported. The 2015+ standard introduced PHYs with larger PHY payload. These are not (yet) supported in Zephyr.

IEEE802154_SHORT_ADDR_LENGTH

IEEE 802.15.4 short address length.

IEEE802154_EXT_ADDR_LENGTH

IEEE 802.15.4 extended address length.

IEEE802154_MAX_ADDR_LENGTH

IEEE 802.15.4 maximum address length.

IEEE802154_NO_CHANNEL

A special channel value that symbolizes “all” channels or “any” channel - depending on context.

IEEE802154_BROADCAST_ADDRESS

Represents the IEEE 802.15.4 broadcast short address, see sections 6.1 and 8.4.3, table 8-94, macShortAddress.

IEEE802154_NO_SHORT_ADDRESS_ASSIGNED

Represents a special IEEE 802.15.4 short address that indicates that a device has been associated with a coordinator but did not receive a short address, see sections 6.4.1 and 8.4.3, table 8-94, macShortAddress.

IEEE802154_BROADCAST_PAN_ID

Represents the IEEE 802.15.4 broadcast PAN ID, see section 6.1.

IEEE802154_SHORT_ADDRESS_NOT_ASSOCIATED

Represents a special value of the macShortAddress MAC PIB attribute, while the device is not associated, see section 8.4.3, table 8-94.

IEEE802154_PAN_ID_NOT_ASSOCIATED

Represents a special value of the macPanId MAC PIB attribute, while the device is not associated, see section 8.4.3, table 8-94.

Enums

enum ieee802154_device_role

Values:

enumerator IEEE802154_DEVICE_ROLE_ENDDEVICE
enumerator IEEE802154_DEVICE_ROLE_COORDINATOR
enumerator IEEE802154_DEVICE_ROLE_PAN_COORDINATOR
struct ieee802154_security_ctx
#include <ieee802154.h>

Interface-level security attributes, see section 9.5.

Public Members

uint32_t frame_counter

Interface-level outgoing frame counter, section 9.5, table 9-8, secFrameCounter.

Only used when the driver does not implement key-specific frame counters.

uint8_t key[16]

Interface-level frame encryption security key material.

Currently native L2 only supports a single secKeySource, see section 9.5, table 9-9, in combination with secKeyMode zero (implicit key mode), see section 9.4.2.3, table 9-7.

Warning

This is no longer in accordance with the 2015+ versions of the standard and needs to be extended in the future for full security procedure compliance.

uint8_t key_len

Length in bytes of the interface-level security key material.

uint8_t level

Frame security level, possible values are defined in section 9.4.2.2, table 9-6.

Warning

Currently native L2 allows to configure one common security level for all frame types, commands and information elements. This is no longer in accordance with the 2015+ versions of the standard and needs to be extended in the future for full security procedure compliance.

uint8_t key_mode

Frame security key mode.

Currently only implicit key mode is partially supported, see section 9.4.2.3, table 9-7, secKeyMode.

Warning

This is no longer in accordance with the 2015+ versions of the standard and needs to be extended in the future for full security procedure compliance.

struct ieee802154_context
#include <ieee802154.h>

IEEE 802.15.4 L2 context.

Public Members

uint16_t pan_id

PAN ID.

The identifier of the PAN on which the device is operating. If this value is 0xffff, the device is not associated. See section 8.4.3.1, table 8-94, macPanId.

in CPU byte order

uint16_t channel

Channel Number.

The RF channel to use for all transmissions and receptions, see section 11.3, table 11-2, phyCurrentChannel. The allowable range of values is PHY dependent as defined in section 10.1.3.

in CPU byte order

uint16_t short_addr

Short Address (in CPU byte order)

Range:

  • 0x0000–0xfffd: associated, short address was assigned

  • 0xfffe: associated but no short address assigned

  • 0xffff: not associated (default),

See section 6.4.1, table 6-4 (Usage of the shart address) and section 8.4.3.1, table 8-94, macShortAddress.

uint8_t ext_addr[8]

Extended Address (in little endian)

The extended address is device specific, usually permanently stored on the device and immutable.

See section 8.4.3.1, table 8-94, macExtendedAddress.

struct net_linkaddr_storage linkaddr

Link layer address (in big endian)

struct ieee802154_security_ctx sec_ctx

Security context.

struct ieee802154_req_params *scan_ctx

Pointer to scanning parameters and results, guarded by scan_ctx_lock.

struct k_sem scan_ctx_lock

Used to maintain integrity of data for all fields in this struct unless otherwise documented on field level.

uint8_t coord_ext_addr[8]

Coordinator extended address.

see section 8.4.3.1, table 8-94, macCoordExtendedAddress, the address of the coordinator through which the device is associated.

A value of zero indicates that a coordinator extended address is unknown (default).

in little endian

uint16_t coord_short_addr

Coordinator short address.

see section 8.4.3.1, table 8-94, macCoordShortAddress, the short address assigned to the coordinator through which the device is associated.

A value of 0xfffe indicates that the coordinator is only using its extended address. A value of 0xffff indicates that this value is unknown.

in CPU byte order

int16_t tx_power

Transmission power in dBm.

enum net_l2_flags flags

L2 flags.

uint8_t sequence

Data sequence number.

The sequence number added to the transmitted Data frame or MAC command, see section 8.4.3.1, table 8-94, macDsn.

uint8_t device_role

Device Role.

See section 6.1: A device may be operating as end device (0), coordinator (1), or PAN coordinator (2). If no device role is explicitly configured then the device will be treated as an end device.

A value of 3 is undefined.

Can be read/set via ieee802154_device_role.

uint8_t ack_requested

ACK requested flag, guarded by ack_lock.

uint8_t ack_seq

ACK expected sequence number, guarded by ack_lock.

struct k_sem ack_lock

ACK lock, guards ack_* fields.

struct k_sem ctx_lock

Context lock.

This lock guards all mutable context attributes unless otherwise mentioned on attribute level.

OpenThread L2 Adaptation Layer API

Zephyr’s OpenThread L2 platform adaptation layer glues the external OpenThread stack together with Zephyr’s IEEE 802.15.4 protocol agnostic driver API. This API is of interest to OpenThread L2 subsystem contributors only.

The OpenThread API is part of the Thread protocol subsystem and documented there.