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 (*
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:
-
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
¶
-
enumerator
-
enum
ieee802154_event
¶ Values:
-
enumerator
IEEE802154_EVENT_TX_STARTED
¶
-
enumerator
IEEE802154_EVENT_RX_FAILED
¶
-
enumerator
IEEE802154_EVENT_SLEEP
¶
-
enumerator
-
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
¶
-
enumerator
-
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.
-
enumerator
-
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.
-
enumerator
-
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 to1
(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
-
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.
-
enumerator
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
-
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.4key_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
-
struct ieee802154_config.[anonymous].[anonymous]
ack_ie
¶ IEEE802154_CONFIG_ENH_ACK_HEADER_IE
-
union ieee802154_config.[anonymous] [anonymous]¶
Configuration data.
-
struct ieee802154_config.[anonymous].[anonymous]
-
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 (*
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 (*
tx
)(const struct device *dev, enum ieee802154_tx_mode mode, struct net_pkt *pkt, struct net_buf *frag)¶ Transmit a packet fragment
-
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.
-
struct net_if_api
-
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
¶
-
enumerator
-
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
-
uint32_t
-
struct
ieee802154_security_params
¶ - #include <ieee802154_mgmt.h>
Security parameters.
Used to setup the link-layer security settings
-