This is the documentation for the latest (main) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

IEEE 802.15.4

Overview

IEEE 802.15.4 is a technical standard which defines the operation of low-rate wireless personal area networks (LR-WPANs). For more detailed overview of this standard, see this IEEE 802.15.4 Wikipedia article. Also, see IEEE GET Program for creating an IEEE account and downloading the specification.

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

API Reference

IEEE 802.15.4

group ieee802154

IEEE 802.15.4 library.

Defines

IEEE802154_MAX_ADDR_LENGTH
IEEE802154_NO_CHANNEL
IEEE802154_L2_CTX_TYPE
IEEE802154_AR_FLAG_SET

Typedefs

typedef void (*energy_scan_done_cb_t)(const struct device *dev, int16_t max_ed)
typedef void (*ieee802154_event_cb_t)(const struct device *dev, enum ieee802154_event evt, void *event_params)

Enums

enum ieee802154_channel

IEEE 802.15.4 Channel assignments.

Channel numbering for 868 MHz, 915 MHz, and 2450 MHz bands.

  • Channel 0 is for 868.3 MHz.

  • Channels 1-10 are for 906 to 924 MHz with 2 MHz channel spacing.

  • Channels 11-26 are for 2405 to 2530 MHz with 5 MHz channel spacing.

For more information, please refer to 802.15.4-2015 Section 10.1.2.2.

Values:

enumerator IEEE802154_SUB_GHZ_CHANNEL_MIN = 0
enumerator IEEE802154_SUB_GHZ_CHANNEL_MAX = 10
enumerator IEEE802154_2_4_GHZ_CHANNEL_MIN = 11
enumerator IEEE802154_2_4_GHZ_CHANNEL_MAX = 26
enum ieee802154_hw_caps

Values:

enumerator IEEE802154_HW_FCS = BIT(0)
enumerator IEEE802154_HW_PROMISC = BIT(1)
enumerator IEEE802154_HW_FILTER = BIT(2)
enumerator IEEE802154_HW_CSMA = BIT(3)
enumerator IEEE802154_HW_2_4_GHZ = BIT(4)
enumerator IEEE802154_HW_TX_RX_ACK = BIT(5)
enumerator IEEE802154_HW_SUB_GHZ = BIT(6)
enumerator IEEE802154_HW_ENERGY_SCAN = BIT(7)
enumerator IEEE802154_HW_TXTIME = BIT(8)
enumerator IEEE802154_HW_SLEEP_TO_TX = BIT(9)
enumerator IEEE802154_HW_TX_SEC = BIT(10)
enumerator IEEE802154_HW_RXTIME = BIT(11)
enum ieee802154_filter_type

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

Values:

enumerator IEEE802154_EVENT_TX_STARTED
enumerator IEEE802154_EVENT_RX_FAILED
enumerator IEEE802154_EVENT_SLEEP
enum ieee802154_rx_fail_reason

Values:

enumerator IEEE802154_RX_FAIL_NOT_RECEIVED
enumerator IEEE802154_RX_FAIL_INVALID_FCS
enumerator IEEE802154_RX_FAIL_ADDR_FILTERED
enumerator IEEE802154_RX_FAIL_OTHER
enum ieee802154_tx_mode

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

enumerator IEEE802154_TX_MODE_TXTIME

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

enumerator IEEE802154_TX_MODE_TXTIME_CCA

Transmit packet in the future, perform CCA before transmission.

enum ieee802154_fpb_mode

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

IEEE802.15.4 driver configuration types.

Values:

enumerator IEEE802154_CONFIG_AUTO_ACK_FPB

Indicates how radio driver should set Frame Pending bit in ACK responses for Data Requests. If enabled, radio 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 IEEE Std 802.15.4-2006, 7.2.2.3.1).

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.

enumerator IEEE802154_CONFIG_PAN_COORDINATOR

Indicates whether the device is a PAN coordinator.

enumerator IEEE802154_CONFIG_PROMISCUOUS

Enable/disable promiscuous mode.

enumerator IEEE802154_CONFIG_EVENT_HANDLER

Specifies new radio event handler. Specifying NULL as a handler will disable radio events notification.

enumerator IEEE802154_CONFIG_MAC_KEYS

Updates MAC keys and key index for radios supporting transmit security.

enumerator IEEE802154_CONFIG_FRAME_COUNTER

Sets the current MAC frame counter value for radios supporting transmit security.

enumerator IEEE802154_CONFIG_RX_SLOT

Configure a radio reception slot. This can be used for any scheduler reception, e.g.: Zigbee GP device, CSL, TSCH, etc.

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 radio 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 radio 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 earlier 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 ———+

enumerator IEEE802154_CONFIG_CSL_PERIOD

Configure CSL receiver (Endpoint) period

enumerator IEEE802154_CONFIG_CSL_RX_TIME

Configure the next CSL receive window center, in units of microseconds, based on the radio time.

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.

Functions

static inline bool ieee802154_is_ar_flag_set(struct net_buf *frag)

Check if AR flag is set on the frame inside given net_pkt.

Parameters
  • frag – A valid pointer on a net_buf structure, must not be NULL, and its length should be at least made of 1 byte (ACK frames are the smallest frames on 15.4 and made of 3 bytes, not not counting the FCS part).

Returns

True if AR flag is set, False otherwise

enum net_verdict ieee802154_radio_handle_ack(struct net_if *iface, struct net_pkt *pkt)

Radio driver ACK handling function that hw drivers should use.

ACK handling requires fast handling and thus such function helps to hook directly the hw drivers to the radio driver.

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 it was handled, NET_CONTINUE otherwise

void ieee802154_init(struct net_if *iface)

Initialize L2 stack for a given interface.

Parameters
  • iface – A valid pointer on a network interface

struct ieee802154_security_ctx
#include <ieee802154.h>
struct ieee802154_context
#include <ieee802154.h>
struct ieee802154_filter
#include <ieee802154_radio.h>
struct ieee802154_key
#include <ieee802154_radio.h>
struct ieee802154_config
#include <ieee802154_radio.h>

IEEE802.15.4 driver configuration data.

Public Members

struct ieee802154_config.[anonymous].[anonymous] auto_ack_fpb

IEEE802154_CONFIG_AUTO_ACK_FPB

struct ieee802154_config.[anonymous].[anonymous] ack_fpb

IEEE802154_CONFIG_ACK_FPB

bool pan_coordinator

IEEE802154_CONFIG_PAN_COORDINATOR

bool promiscuous

IEEE802154_CONFIG_PROMISCUOUS

ieee802154_event_cb_t event_handler

IEEE802154_CONFIG_EVENT_HANDLER

struct ieee802154_key *mac_keys

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

key_value field points to a buffer containing the 16 byte key. The buffer is copied by the callee.

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

uint32_t frame_counter

IEEE802154_CONFIG_FRAME_COUNTER

struct ieee802154_config.[anonymous].[anonymous] rx_slot

IEEE802154_CONFIG_RX_SLOT

uint32_t csl_period

IEEE802154_CONFIG_CSL_PERIOD

uint32_t csl_rx_time

IEEE802154_CONFIG_CSL_RX_TIME

const uint8_t *ext_addr

The extended address is expected to be passed starting with the leftmost octet and ending with the rightmost octet. A device with an extended address 01:23:45:67:89:ab:cd:ef should provide a pointer to array containing values in the same exact order.

struct ieee802154_config.[anonymous].[anonymous] ack_ie

IEEE802154_CONFIG_ENH_ACK_HEADER_IE

union ieee802154_config.[anonymous] [anonymous]

Configuration data.

struct ieee802154_radio_api
#include <ieee802154_radio.h>

IEEE 802.15.4 radio interface API.

Public Members

struct net_if_api iface_api

Mandatory to get in first position. A network device should indeed provide a pointer on such net_if_api structure. So we make current structure pointer that can be casted to a net_if_api structure pointer.

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

Get the device capabilities

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

Clear Channel Assessment - Check channel’s activity

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

Set current channel

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

Set/Unset filters (for IEEE802154_HW_FILTER )

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

Set TX power level in dbm

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

Transmit a packet fragment

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

Start the device

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

Stop the device

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

Set specific radio driver configuration.

uint16_t (*get_subg_channel_count)(const struct device *dev)

Get the available amount of Sub-GHz channels

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

Run an energy detection scan. Note: channel must be set prior to request this function. duration parameter is in ms.

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

Get the current radio time in microseconds

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

Get the current accuracy, in units of ± ppm, of the clock used for scheduling delayed receive or transmit radio operations. Note: Implementations may optimize this value based on operational conditions (i.e.: temperature).

IEEE 802.15.4 Management

group ieee802154_mgmt

IEEE 802.15.4 library.

Defines

NET_REQUEST_IEEE802154_SET_ACK
NET_REQUEST_IEEE802154_UNSET_ACK
NET_REQUEST_IEEE802154_PASSIVE_SCAN
NET_REQUEST_IEEE802154_ACTIVE_SCAN
NET_REQUEST_IEEE802154_CANCEL_SCAN
NET_REQUEST_IEEE802154_ASSOCIATE
NET_REQUEST_IEEE802154_DISASSOCIATE
NET_REQUEST_IEEE802154_SET_CHANNEL
NET_REQUEST_IEEE802154_GET_CHANNEL
NET_REQUEST_IEEE802154_SET_PAN_ID
NET_REQUEST_IEEE802154_GET_PAN_ID
NET_REQUEST_IEEE802154_SET_EXT_ADDR
NET_REQUEST_IEEE802154_GET_EXT_ADDR
NET_REQUEST_IEEE802154_SET_SHORT_ADDR
NET_REQUEST_IEEE802154_GET_SHORT_ADDR
NET_REQUEST_IEEE802154_GET_TX_POWER
NET_REQUEST_IEEE802154_SET_TX_POWER
NET_EVENT_IEEE802154_SCAN_RESULT
IEEE802154_IS_CHAN_SCANNED(_channel_set, _chan)
IEEE802154_IS_CHAN_UNSCANNED(_channel_set, _chan)
IEEE802154_ALL_CHANNELS

Enums

enum net_request_ieee802154_cmd

Values:

enumerator NET_REQUEST_IEEE802154_CMD_SET_ACK = 1
enumerator NET_REQUEST_IEEE802154_CMD_UNSET_ACK
enumerator NET_REQUEST_IEEE802154_CMD_PASSIVE_SCAN
enumerator NET_REQUEST_IEEE802154_CMD_ACTIVE_SCAN
enumerator NET_REQUEST_IEEE802154_CMD_CANCEL_SCAN
enumerator NET_REQUEST_IEEE802154_CMD_ASSOCIATE
enumerator NET_REQUEST_IEEE802154_CMD_DISASSOCIATE
enumerator NET_REQUEST_IEEE802154_CMD_SET_CHANNEL
enumerator NET_REQUEST_IEEE802154_CMD_GET_CHANNEL
enumerator NET_REQUEST_IEEE802154_CMD_SET_PAN_ID
enumerator NET_REQUEST_IEEE802154_CMD_GET_PAN_ID
enumerator NET_REQUEST_IEEE802154_CMD_SET_EXT_ADDR
enumerator NET_REQUEST_IEEE802154_CMD_GET_EXT_ADDR
enumerator NET_REQUEST_IEEE802154_CMD_SET_SHORT_ADDR
enumerator NET_REQUEST_IEEE802154_CMD_GET_SHORT_ADDR
enumerator NET_REQUEST_IEEE802154_CMD_GET_TX_POWER
enumerator NET_REQUEST_IEEE802154_CMD_SET_TX_POWER
enumerator NET_REQUEST_IEEE802154_CMD_SET_SECURITY_SETTINGS
enumerator NET_REQUEST_IEEE802154_CMD_GET_SECURITY_SETTINGS
enum net_event_ieee802154_cmd

Values:

enumerator NET_EVENT_IEEE802154_CMD_SCAN_RESULT = 1
struct ieee802154_req_params
#include <ieee802154_mgmt.h>

Scanning parameters.

Used to request a scan and get results as well

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.[anonymous] [anonymous]

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