IEEE 802.15.4 header definitions and utility functions. More...

Detailed Description

IEEE 802.15.4 header definitions and utility functions.

Modules
	IEEE802.15.4 compile configurations

Files
file	ieee802154.h
	IEEE 802.15.4 header definitions.

Macros
#define	IEEE802154_SFD (0xa7)
	Default start frame delimiter.

#define	IEEE802154_FRAME_LEN_MAX (127U)
	maximum 802.15.4 frame length

#define	IEEE802154G_FRAME_LEN_MAX (2047U)
	maximum 802.15.4g-2012 frame length

#define	IEEE802154_ACK_FRAME_LEN (5U)
	ACK frame length.

#define	IEEE802154_LIFS_SYMS (40U)
	Number of symbols to wait during Long Inter Frame Spacing.

#define	IEEE802154_SIFS_SYMS (12U)
	Number of symbols to wait during Short Inter Frame Spacing.

#define	IEEE802154_SIFS_MAX_FRAME_SIZE (18U)
	Maximum frame size to consider a frame as short.

#define	IEEE802154_ACK_TIMEOUT_SYMS (54)
	ACK Timeout period in symbols.

#define	IEEE802154_RADIO_RSSI_OFFSET (-174)
	value of measured power when RSSI is zero. More...

#define	IEEE802154_PHY_MR_FSK_PHR_LEN (2)
	MR-FSK PHY header length.

#define	IEEE802154_PHY_MR_FSK_2FSK_SFD_LEN (2)
	MR-FSK SFD length on Filtered 2-FSK.

#define	IEEE802154G_ATURNAROUNDTIME_US (1 * US_PER_MS)
	For the SUN PHYs, the value is 1 ms expressed in symbol periods, rounded up to the next integer number of symbol periods using the ceiling() function. More...

#define	IEEE802154_ATURNAROUNDTIME_IN_SYMBOLS (12)
	IEEE Std 802.15.4-2020 Table 11-1—PHY constants: The value is 12 for all other PHYs.

#define	IEEE802154_CCA_DURATION_IN_SYMBOLS (8)
	IEEE Std 802.15.4-2020 Table 11-1—PHY constants: For all other PHYs¹, the duration of 8 symbol periods. More...

#define	CONFIG_IEEE802154_DEFAULT_CSMA_CA_MIN_BE (3U)
	IEEE802.15.4 default value for minimum backoff exponent.

#define	CONFIG_IEEE802154_DEFAULT_CSMA_CA_RETRIES (4U)
	IEEE802.15.4 default value for maximum number of CSMA-CA retries.

#define	CONFIG_IEEE802154_DEFAULT_CSMA_CA_MAX_BE (5U)
	IEEE802.15.4 default value for maximum backoff exponent.

#define	CONFIG_IEEE802154_CCA_THRESH_DEFAULT (-70)
	IEEE802.15.4 default value for CCA threshold (in dBm)

#define	CONFIG_IEEE802154_DEFAULT_MAX_FRAME_RETRANS (4U)
	IEEE802.15.4 default value for maximum frame retries.

#define	CONFIG_IEEE802154_AUTO_ACK_DISABLE 0
	Disable Auto ACK support.

#define	CONFIG_IEEE802154_DEFAULT_ACK_REQ 1
	Request ACKs by default.

Enumerations
enum	ieee802154_phy_mode_t { IEEE802154_PHY_DISABLED , IEEE802154_PHY_BPSK , IEEE802154_PHY_ASK , IEEE802154_PHY_OQPSK , IEEE802154_PHY_MR_OQPSK , IEEE802154_PHY_MR_OFDM , IEEE802154_PHY_MR_FSK }
	802.15.4 PHY modes More...

enum	{ IEEE802154_FEC_NONE , IEEE802154_FEC_NRNSC , IEEE802154_FEC_RSC }
	802.15.4 forward error correction schemes More...

Functions
size_t	ieee802154_set_frame_hdr (uint8_t buf, const uint8_t src, size_t src_len, const uint8_t *dst, size_t dst_len, le_uint16_t src_pan, le_uint16_t dst_pan, uint8_t flags, uint8_t seq)
	Initializes an IEEE 802.15.4 MAC frame header in `buf`. More...

size_t	ieee802154_get_frame_hdr_len (const uint8_t *mhr)
	Get length of MAC header. More...

int	ieee802154_get_src (const uint8_t mhr, uint8_t src, le_uint16_t *src_pan)
	Gets source address from MAC header. More...

int	ieee802154_get_dst (const uint8_t mhr, uint8_t dst, le_uint16_t *dst_pan)
	Gets destination address from MAC header. More...

int	ieee802154_dst_filter (const uint8_t mhr, uint16_t pan, network_uint16_t short_addr, const eui64_t ext_addr)
	Check whether a frame pass the IEEE 802.15.4 frame filter. More...

static uint8_t	ieee802154_get_seq (const uint8_t *mhr)
	Gets sequence number from MAC header. More...

static eui64_t *	ieee802154_get_iid (eui64_t eui64, const uint8_t addr, size_t addr_len)
	Generates an IPv6 interface identifier from an IEEE 802.15.4 address. More...

static int16_t	ieee802154_rssi_to_dbm (uint8_t rssi)
	Convert from RSSI scale to dBm. More...

static uint8_t	ieee802154_dbm_to_rssi (int16_t dbm)
	Convert from dBm scale to RSSI. More...

const uint8_t	ieee802154_addr_bcast [IEEE802154_ADDR_BCAST_LEN]
	Broadcast address.

#define	IEEE802154_ADDR_BCAST { 0xff, 0xff }
	Special address definitions. More...

#define	IEEE802154_ADDR_BCAST_LEN (IEEE802154_SHORT_ADDRESS_LEN)
	Length in byte of IEEE802154_ADDR_BCAST.

#define	IEEE802154_SHORT_ADDRESS_LEN (2U)
	IEEE 802.15.4 address lengths. More...

#define	IEEE802154_LONG_ADDRESS_LEN (8U)
	long address (EUI-64)

#define	IEEE802154_MAX_HDR_LEN (23U)
	IEEE802.15.4 FCF field definitions.

#define	IEEE802154_MIN_FRAME_LEN (IEEE802154_FCF_LEN + sizeof(uint8_t))

#define	IEEE802154_FCF_LEN (2U)

#define	IEEE802154_FCS_LEN (2U)

#define	IEEE802154_FCF_TYPE_MASK (0x07)

#define	IEEE802154_FCF_TYPE_BEACON (0x00)

#define	IEEE802154_FCF_TYPE_DATA (0x01)

#define	IEEE802154_FCF_TYPE_ACK (0x02)

#define	IEEE802154_FCF_TYPE_MACCMD (0x03)

#define	IEEE802154_FCF_SECURITY_EN (0x08)
	enable security

#define	IEEE802154_FCF_FRAME_PEND (0x10)
	follow-up frame is pending

#define	IEEE802154_FCF_ACK_REQ (0x20)
	acknowledgement requested from receiver

#define	IEEE802154_FCF_PAN_COMP (0x40)
	compress source PAN ID

#define	IEEE802154_FCF_DST_ADDR_MASK (0x0c)

#define	IEEE802154_FCF_DST_ADDR_VOID (0x00)
	no destination address

#define	IEEE802154_FCF_DST_ADDR_RESV (0x04)
	reserved address mode

#define	IEEE802154_FCF_DST_ADDR_SHORT (0x08)
	destination address length is 2

#define	IEEE802154_FCF_DST_ADDR_LONG (0x0c)
	destination address length is 8

#define	IEEE802154_FCF_VERS_MASK (0x30)

#define	IEEE802154_FCF_VERS_V0 (0x00)

#define	IEEE802154_FCF_VERS_V1 (0x10)

#define	IEEE802154_FCF_SRC_ADDR_MASK (0xc0)

#define	IEEE802154_FCF_SRC_ADDR_VOID (0x00)
	no source address

#define	IEEE802154_FCF_SRC_ADDR_RESV (0x40)
	reserved address mode

#define	IEEE802154_FCF_SRC_ADDR_SHORT (0x80)
	source address length is 2

#define	IEEE802154_FCF_SRC_ADDR_LONG (0xc0)
	source address length is 8

#define	IEEE802154_CHANNEL_MIN_SUBGHZ (0U)
	Channel ranges. More...

#define	IEEE802154_CHANNEL_MAX_SUBGHZ (10U)
	Maximum channel for sub-GHz band.

#define	IEEE802154_CHANNEL_MIN (11U)
	Minimum channel for 2.4 GHz band.

#define	IEEE802154_CHANNEL_MAX (26U)
	Maximum channel for 2.4 GHz band.

#define	IEEE802154_PHY_MR_FSK_2FSK_CODED_SFD_0 (0x6F4E)
	For the MR-FSK PHY, the SFD value when PHR + PSDU are coded/uncoded and with phyMRFSKSFD = 0 or 1 respectively. More...

#define	IEEE802154_PHY_MR_FSK_2FSK_CODED_SFD_1 (0x632D)

#define	IEEE802154_PHY_MR_FSK_2FSK_UNCODED_SFD_0 (0x90E4)

#define	IEEE802154_PHY_MR_FSK_2FSK_UNCODED_SFD_1 (0x7A0E)

Macro Definition Documentation

◆ IEEE802154_ADDR_BCAST

#define IEEE802154_ADDR_BCAST { 0xff, 0xff }

Special address definitions.

Static initializer for broadcast address

Definition at line 198 of file ieee802154.h.

◆ IEEE802154_CCA_DURATION_IN_SYMBOLS

#define IEEE802154_CCA_DURATION_IN_SYMBOLS (8)

IEEE Std 802.15.4-2020 Table 11-1—PHY constants: For all other PHYs¹, the duration of 8 symbol periods.

[1] all but MR-O-QPSK

Definition at line 167 of file ieee802154.h.

◆ IEEE802154_CHANNEL_MIN_SUBGHZ

#define IEEE802154_CHANNEL_MIN_SUBGHZ (0U)

Channel ranges.

Minimum channel for sub-GHz band

Definition at line 92 of file ieee802154.h.

◆ IEEE802154_PHY_MR_FSK_2FSK_CODED_SFD_0

#define IEEE802154_PHY_MR_FSK_2FSK_CODED_SFD_0 (0x6F4E)

For the MR-FSK PHY, the SFD value when PHR + PSDU are coded/uncoded and with phyMRFSKSFD = 0 or 1 respectively.

802.15.4g, Table 131 (p. 51)

Definition at line 140 of file ieee802154.h.

◆ IEEE802154_RADIO_RSSI_OFFSET

#define IEEE802154_RADIO_RSSI_OFFSET (-174)

value of measured power when RSSI is zero.

This value is defined in the IEEE 802.15.4 standard

Definition at line 127 of file ieee802154.h.

◆ IEEE802154_SHORT_ADDRESS_LEN

#define IEEE802154_SHORT_ADDRESS_LEN (2U)

IEEE 802.15.4 address lengths.

short (16-bit) address

Definition at line 44 of file ieee802154.h.

◆ IEEE802154G_ATURNAROUNDTIME_US

#define IEEE802154G_ATURNAROUNDTIME_US (1 * US_PER_MS)

For the SUN PHYs, the value is 1 ms expressed in symbol periods, rounded up to the next integer number of symbol periods using the ceiling() function.

802.15.4g, Table 70 (p. 43)

Definition at line 152 of file ieee802154.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

802.15.4 forward error correction schemes

Enumerator
IEEE802154_FEC_NONE	no forward error correction
IEEE802154_FEC_NRNSC	non-recursive and non-systematic code
IEEE802154_FEC_RSC	recursive and systematic code

Definition at line 185 of file ieee802154.h.

◆ ieee802154_phy_mode_t

enum ieee802154_phy_mode_t

802.15.4 PHY modes

Enumerator
IEEE802154_PHY_DISABLED	PHY disabled, no mode selected.
IEEE802154_PHY_BPSK	Binary Phase Shift Keying.
IEEE802154_PHY_ASK	Amplitude-Shift Keying.
IEEE802154_PHY_OQPSK	Offset Quadrature Phase-Shift Keying.
IEEE802154_PHY_MR_OQPSK	Multi-Rate Offset Quadrature Phase-Shift Keying.
IEEE802154_PHY_MR_OFDM	Multi-Rate Orthogonal Frequency-Division Multiplexing.
IEEE802154_PHY_MR_FSK	Multi-Rate Frequency Shift Keying.

Definition at line 172 of file ieee802154.h.

Function Documentation

◆ ieee802154_dbm_to_rssi()

static uint8_t ieee802154_dbm_to_rssi ( int16_t dbm )

inlinestatic

Convert from dBm scale to RSSI.

The RSSI calculation is based on the IEEE 802.15.4 2020 specification and it's represented as one octet of integer.

RSSI equal to zero maps to -174 dBm and has the same scale as dBm (1 RSSI step == 1 dBm). Therefore an RSSI value of 254 maps to +80 dBm.

Parameters

[in] dbm RF power in dBm scale.

Returns: RF power in RSSI scale.

Definition at line 544 of file ieee802154.h.

◆ ieee802154_dst_filter()

int ieee802154_dst_filter	(	const uint8_t *	mhr,
		uint16_t	pan,
		network_uint16_t	short_addr,
		const eui64_t *	ext_addr
	)

Check whether a frame pass the IEEE 802.15.4 frame filter.

A frame passes the frame filter only if:

The PAN ID matches the PAN ID of the frame filter or the broadcast PAN ID
Either the Short or Extended Address matches the frame filter OR the Short Address is the broadcast address.

Parameters

[in]	mhr	MAC header (PSDU)
[in]	pan	PAN ID of the frame filter.
[in]	short_addr	Short Address of the frame filter.
[in]	ext_addr	Extended Address of the frame filter.

Returns: 0 if frame passes the frame filter.; 1 if frame doesn't pass the frame filter.

◆ ieee802154_get_dst()

int ieee802154_get_dst	(	const uint8_t *	mhr,
		uint8_t *	dst,
		le_uint16_t *	dst_pan
	)

Gets destination address from MAC header.

Precondition: (dst != NULL) && (dst_pan != NULL)

Parameters

[in]	mhr	MAC header.
[out]	dst	Destination address in network byte order in MAC header.
[out]	dst_pan	Destination PAN in little-endian byte order in MAC header.

Returns: Length of destination address.; -EINVAL, if mhr contains unexpected flags.

◆ ieee802154_get_frame_hdr_len()

size_t ieee802154_get_frame_hdr_len ( const uint8_t * mhr )

Get length of MAC header.

Todo:: include security header implications

Parameters

[in] mhr MAC header.

Returns: Length of MAC header on success.; 0, on error (source mode or destination mode set to reserved).

◆ ieee802154_get_iid()

static eui64_t* ieee802154_get_iid	(	eui64_t *	eui64,
		const uint8_t *	addr,
		size_t	addr_len
	)

inlinestatic

Generates an IPv6 interface identifier from an IEEE 802.15.4 address.

Precondition: (eui64 != NULL) && (addr != NULL)

See also: RFC 4944, section 6; RFC 6282, section 3.2.2

Parameters

[out]	eui64	The resulting EUI-64.
[in]	addr	An IEEE 802.15.4 address.
[in]	addr_len	The length of `addr`. Must be 2 (short address), 4 (PAN ID + short address), or 8 (long address).

Returns: Copy of eui64 on success.; NULL, if addr_len was of illegal length.

Definition at line 470 of file ieee802154.h.

◆ ieee802154_get_seq()

static uint8_t ieee802154_get_seq ( const uint8_t * mhr )

inlinestatic

Gets sequence number from MAC header.

Precondition: length of allocated space at mhr > 3

Parameters

[in] mhr MAC header.

Returns: The sequence number in mhr.

Definition at line 446 of file ieee802154.h.

◆ ieee802154_get_src()

int ieee802154_get_src	(	const uint8_t *	mhr,
		uint8_t *	src,
		le_uint16_t *	src_pan
	)

Gets source address from MAC header.

Precondition: (src != NULL) && (src_pan != NULL)

Parameters

[in]	mhr	MAC header.
[out]	src	Source address in network byte order in MAC header.
[out]	src_pan	Source PAN little-endian byte order in MAC header.

Returns: Length of source address.; -EINVAL, if mhr contains unexpected flags.

◆ ieee802154_rssi_to_dbm()

static int16_t ieee802154_rssi_to_dbm ( uint8_t rssi )

inlinestatic

Convert from RSSI scale to dBm.

The RSSI calculation is based on the IEEE 802.15.4 2020 specification and it's represented as one octet of integer.

RSSI equal to zero maps to -174 dBm and has the same scale as dBm (1 RSSI step == 1 dBm). Therefore an RSSI value of 254 maps to +80 dBm.

Note: RSSI == 255 is defined as reserved by the standard and ignored by this function.

Parameters

[in] rssi RF power in RSSI scale

Returns: RF power in dBm scale

Definition at line 526 of file ieee802154.h.

◆ ieee802154_set_frame_hdr()

size_t ieee802154_set_frame_hdr	(	uint8_t *	buf,
		const uint8_t *	src,
		size_t	src_len,
		const uint8_t *	dst,
		size_t	dst_len,
		le_uint16_t	src_pan,
		le_uint16_t	dst_pan,
		uint8_t	flags,
		uint8_t	seq
	)

Initializes an IEEE 802.15.4 MAC frame header in buf.

Precondition: Resulting header must fit in memory allocated at buf.

See also: IEEE Std 802.15.4-2011, 5.2.1 General MAC frame format.

If dst is NULL the IEEE802154_FCF_ACK_REQ will be unset to prevent flooding the network.

Parameters

[out]	buf	Target memory for frame header.
[in]	src	Source address for frame in network byteorder. May be NULL if IEEE802154_FCF_SRC_ADDR_VOID is set in `flags`.
[in]	src_len	Length of `src`. Legal values are: 0 (will set IEEE802154_FCF_SRC_ADDR_VOID in MHR) 2 (will set IEEE802154_FCF_SRC_ADDR_SHORT in MHR) 8 (will set IEEE802154_FCF_SRC_ADDR_LONG in MHR)
[in]	dst	Destination address for frame in network byteorder. May be NULL if IEEE802154_FCF_SRC_ADDR_VOID is set in `flags`.
[in]	dst_len	Length of `dst`. Legal values are: 0 (will set IEEE802154_FCF_DST_ADDR_VOID in MHR) 2 (will set IEEE802154_FCF_DST_ADDR_SHORT in MHR) 8 (will set IEEE802154_FCF_DST_ADDR_LONG in MHR)
[in]	src_pan	Source PAN ID in little-endian. May be 0 if IEEE802154_FCF_PAN_COMP is set in `flags`. Otherwise, it will be ignored, when IEEE802154_FCF_PAN_COMP is set.
[in]	dst_pan	Destination PAN ID in little-endian.
[in]	flags	Flags for the frame. These are interchangeable with the first byte of the IEEE 802.15.4 FCF. This means that it encompasses the type values, IEEE802154_FCF_SECURITY_EN, IEEE802154_FCF_FRAME_PEND, and IEEE802154_FCF_ACK_REQ.
[in]	seq	Sequence number for frame.

The version field in the FCF will be set implicitly to version 1.

Returns: Size of frame header on success.; 0, on error (flags set to unexpected state).

Detailed Description

Modules

Files

Macros

Enumerations

Functions

Macro Definition Documentation

◆ IEEE802154_ADDR_BCAST

◆ IEEE802154_CCA_DURATION_IN_SYMBOLS

◆ IEEE802154_CHANNEL_MIN_SUBGHZ

◆ IEEE802154_PHY_MR_FSK_2FSK_CODED_SFD_0

◆ IEEE802154_RADIO_RSSI_OFFSET

◆ IEEE802154_SHORT_ADDRESS_LEN

◆ IEEE802154G_ATURNAROUNDTIME_US

Enumeration Type Documentation

◆ anonymous enum

◆ ieee802154_phy_mode_t

Function Documentation

◆ ieee802154_dbm_to_rssi()

◆ ieee802154_dst_filter()

◆ ieee802154_get_dst()

◆ ieee802154_get_frame_hdr_len()

◆ ieee802154_get_iid()

◆ ieee802154_get_seq()

◆ ieee802154_get_src()

◆ ieee802154_rssi_to_dbm()

◆ ieee802154_set_frame_hdr()