IEEE 802.15.4

Overview
API Reference
- IEEE 802.15.4
- IEEE 802.15.4 Management

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_PHY_PACKET_SIZE

IEEE802154_FCS_LENGTH

IEEE802154_MTU

IEEE802154_SHORT_ADDR_LENGTH

IEEE802154_EXT_ADDR_LENGTH

IEEE802154_MAX_ADDR_LENGTH

IEEE802154_NO_CHANNEL

IEEE802154_BROADCAST_ADDRESS

IEEE802154_NO_SHORT_ADDRESS_ASSIGNED

IEEE802154_SHORT_ADDRESS_NOT_ASSOCIATED

IEEE802154_BROADCAST_PAN_ID

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:

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

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 most significant octet and ending with the least significant octet. A device with an extended address 01:23:45:67:89:ab:cd:ef as written in the usual big-endian hex notation should provide a pointer to an array containing values in the exact same 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, channel is in CPU byte order.

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 net management 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

IEEE 802.15.4

Overview

API Reference

IEEE 802.15.4

IEEE 802.15.4 Management

Overview 

API Reference 

IEEE 802.15.4 

IEEE 802.15.4 Management 