IEEE802.15.4 header definitions and utility functions. More...

Detailed Description

IEEE802.15.4 header definitions and utility functions.

Modules
	IEEE802.15.4 SubMAC layer
	This module defines a common layer for handling the lower part of the IEEE 802.15.4 MAC layer.

	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_RADIO_RSSI_OFFSET (-174)
	value of measured power when RSSI is zero. More...

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

Enumerations
enum	{ 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...

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

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

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.

Macro Definition Documentation

◆ IEEE802154_ADDR_BCAST

#define IEEE802154_ADDR_BCAST { 0xff, 0xff }

Special address definitions.

Static initializer for broadcast address

Definition at line 175 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 144 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 91 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 121 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 43 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 129 of file ieee802154.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

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 149 of file ieee802154.h.

◆ 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 162 of file ieee802154.h.

Function Documentation

◆ 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 385 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 361 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_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_RADIO_RSSI_OFFSET

◆ IEEE802154_SHORT_ADDRESS_LEN

◆ IEEE802154G_ATURNAROUNDTIME_US

Enumeration Type Documentation

◆ anonymous enum

◆ anonymous enum

Function Documentation

◆ ieee802154_get_dst()

◆ ieee802154_get_frame_hdr_len()

◆ ieee802154_get_iid()

◆ ieee802154_get_seq()

◆ ieee802154_get_src()

◆ ieee802154_set_frame_hdr()