This module defines a common layer for handling the lower part of the IEEE 802.15.4 MAC layer. More...

Detailed Description

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

Warning: This feature is experimental!
This API is experimental and in an early state - expect changes!

This layer is responsible for:

Handling CSMA-CA and retransmissions.
Maintaining part of the MAC Information Base, e.g IEEE 802.15.4 addresses, channel settings, CSMA-CA params, etc.

Author: José I. Alamos jose..nosp@m.alam.nosp@m.os@ha.nosp@m.w-ha.nosp@m.mburg.nosp@m..de

Data Structures
struct	ieee802154_submac_cb_t
	IEEE 802.15.4 SubMAC callbacks. More...

struct	ieee802154_submac
	IEEE 802.15.4 SubMAC descriptor. More...

Macros
#define	IEEE802154_SUBMAC_MAX_RETRANSMISSIONS (4U)
	maximum number of frame retransmissions

Typedefs
typedef struct ieee802154_submac	ieee802154_submac_t
	IEEE 802.15.4 SubMAC forward declaration.

Enumerations
enum	ieee802154_submac_state_t { IEEE802154_STATE_OFF, IEEE802154_STATE_IDLE, IEEE802154_STATE_LISTEN }
	SubMAC states. More...

Functions
static ieee802154_submac_state_t	ieee802154_get_state (ieee802154_submac_t *submac)
	Get the internal state of the SubMAC. More...

int	ieee802154_set_state (ieee802154_submac_t *submac, ieee802154_submac_state_t state)
	Set the internal state of the SubMAC. More...

int	ieee802154_send (ieee802154_submac_t submac, const iolist_t iolist)
	Transmit an IEEE 802.15.4 PSDU. More...

static int	ieee802154_set_short_addr (ieee802154_submac_t submac, const network_uint16_t short_addr)
	Set the IEEE 802.15.4 short address. More...

static int	ieee802154_set_ext_addr (ieee802154_submac_t submac, const eui64_t ext_addr)
	Set the IEEE 802.15.4 extended address. More...

static int	ieee802154_set_panid (ieee802154_submac_t submac, const uint16_t panid)
	Set the IEEE 802.15.4 PAN ID. More...

int	ieee802154_set_phy_conf (ieee802154_submac_t *submac, uint16_t channel_num, uint8_t channel_page, int8_t tx_pow)
	Set IEEE 802.15.4 PHY configuration (channel, TX power) More...

static int	ieee802154_set_channel_number (ieee802154_submac_t *submac, uint16_t channel_num)
	Set IEEE 802.15.4 channel number. More...

static int	ieee802154_set_channel_page (ieee802154_submac_t *submac, uint16_t channel_page)
	Set IEEE 802.15.4 channel page. More...

static int	ieee802154_set_tx_power (ieee802154_submac_t *submac, int8_t tx_pow)
	Set IEEE 802.15.4 transmission power. More...

static int	ieee802154_get_frame_length (ieee802154_submac_t *submac)
	Get the received frame length. More...

static int	ieee802154_read_frame (ieee802154_submac_t submac, void buf, size_t len, ieee802154_rx_info_t *info)
	Read the received frame. More...

int	ieee802154_submac_init (ieee802154_submac_t submac, const network_uint16_t short_addr, const eui64_t *ext_addr)
	Init the IEEE 802.15.4 SubMAC. More...

void	ieee802154_submac_ack_timer_set (ieee802154_submac_t *submac, uint16_t us)
	Set the ACK timeout timer. More...

void	ieee802154_submac_ack_timer_cancel (ieee802154_submac_t *submac)
	Cancel the ACK timeout timer. More...

void	ieee802154_submac_ack_timeout_fired (ieee802154_submac_t *submac)
	Indicate the SubMAC that the ACK timeout fired. More...

void	ieee802154_submac_rx_done_cb (ieee802154_submac_t *submac)
	Indicate the SubMAC that the device received a frame. More...

void	ieee802154_submac_tx_done_cb (ieee802154_submac_t *submac)
	Indicate the SubMAC that the device finished the transmission procedure. More...

Enumeration Type Documentation

◆ ieee802154_submac_state_t

enum ieee802154_submac_state_t

SubMAC states.

Enumerator

IEEE802154_STATE_OFF

SubMAC and network devices are off.

The corresponding network device is put in a state with the lowest energy consumption.

IEEE802154_STATE_IDLE

SubMAC is ready to be used.

IEEE802154_STATE_LISTEN

SubMAC is ready to be used and listening to incoming frames.

Definition at line 49 of file submac.h.

Function Documentation

◆ ieee802154_get_frame_length()

static int ieee802154_get_frame_length ( ieee802154_submac_t * submac )

inlinestatic

Get the received frame length.

Parameters

[in] submac pointer to the SubMAC

Returns: length of the PSDU (excluding FCS length)

Definition at line 307 of file submac.h.

◆ ieee802154_get_state()

static ieee802154_submac_state_t ieee802154_get_state ( ieee802154_submac_t * submac )

inlinestatic

Get the internal state of the SubMAC.

Parameters

[in] submac pointer to the SubMAC descriptor

Returns: the SubMAC state

Definition at line 132 of file submac.h.

◆ ieee802154_read_frame()

static int ieee802154_read_frame	(	ieee802154_submac_t *	submac,
		void *	buf,
		size_t	len,
		ieee802154_rx_info_t *	info
	)

inlinestatic

Read the received frame.

This functions reads the received PSDU from the device (excluding FCS)

Parameters

[in]	submac	pointer to the SubMAC descriptor
[out]	buf	buffer to write into. If NULL, the packet is discarded
[in]	len	length of the buffer
[out]	info	RX information of the packet. If NULL, the information is not fetched.

Returns: the number of bytes written to buf; negative errno on error

Definition at line 325 of file submac.h.

◆ ieee802154_send()

int ieee802154_send	(	ieee802154_submac_t *	submac,
		const iolist_t *	iolist
	)

Transmit an IEEE 802.15.4 PSDU.

This function performs an IEEE 802.15.4 transmission, including CSMA-CA and retransmissions (if ACK Request bit is set). When the transmission finishes an ieee802154_submac_cb_t::tx_done event is issued.

Parameters

[in]	submac	pointer to the SubMAC descriptor
[in]	iolist	pointer to the PSDU frame (without FCS)

Returns: 0 on success; negative errno on error

◆ ieee802154_set_channel_number()

static int ieee802154_set_channel_number	(	ieee802154_submac_t *	submac,
		uint16_t	channel_num
	)

inlinestatic

Set IEEE 802.15.4 channel number.

This is a shortcut to ieee802154_set_phy_conf

Parameters

[in]	submac	pointer the SubMAC descriptor
[in]	channel_num	channel number

Returns: 0 on success; -ENOTSUP if the channel number is not supported; negative errno on error

Definition at line 255 of file submac.h.

◆ ieee802154_set_channel_page()

static int ieee802154_set_channel_page	(	ieee802154_submac_t *	submac,
		uint16_t	channel_page
	)

inlinestatic

Set IEEE 802.15.4 channel page.

This is a shortcut to ieee802154_set_phy_conf

Parameters

[in]	submac	pointer the SubMAC descriptor
[in]	channel_page	channel page

Returns: 0 on success; -ENOTSUP if the channel page is not supported; negative errno on error

Definition at line 274 of file submac.h.

◆ ieee802154_set_ext_addr()

static int ieee802154_set_ext_addr	(	ieee802154_submac_t *	submac,
		const eui64_t *	ext_addr
	)

inlinestatic

Set the IEEE 802.15.4 extended address.

Parameters

[in]	submac	pointer to the SubMAC descriptor
[in]	ext_addr	IEEE 802.15.4 extended address

Returns: 0 on success; negative errno on error

Definition at line 194 of file submac.h.

◆ ieee802154_set_panid()

static int ieee802154_set_panid	(	ieee802154_submac_t *	submac,
		const uint16_t *	panid
	)

inlinestatic

Set the IEEE 802.15.4 PAN ID.

Parameters

[in]	submac	pointer to the SubMAC descriptor
[in]	panid	IEEE 802.15.4 PAN ID

Returns: 0 on success; negative errno on error

Definition at line 215 of file submac.h.

◆ ieee802154_set_phy_conf()

int ieee802154_set_phy_conf	(	ieee802154_submac_t *	submac,
		uint16_t	channel_num,
		uint8_t	channel_page,
		int8_t	tx_pow
	)

Set IEEE 802.15.4 PHY configuration (channel, TX power)

Parameters

[in]	submac	pointer to the SubMAC descriptor
[in]	channel_num	channel number
[in]	channel_page	channel page
[in]	tx_pow	transmission power (in dBm)

Returns: 0 on success; -ENOTSUP if the PHY settings are not supported; negative errno on error

◆ ieee802154_set_short_addr()

static int ieee802154_set_short_addr	(	ieee802154_submac_t *	submac,
		const network_uint16_t *	short_addr
	)

inlinestatic

Set the IEEE 802.15.4 short address.

Parameters

[in]	submac	pointer to the SubMAC descriptor
[in]	short_addr	IEEE 802.15.4 short address

Returns: 0 on success; negative errno on error

Definition at line 172 of file submac.h.

◆ ieee802154_set_state()

int ieee802154_set_state	(	ieee802154_submac_t *	submac,
		ieee802154_submac_state_t	state
	)

Set the internal state of the SubMAC.

Parameters

[in]	submac	pointer to the SubMAC descriptor
[in]	state	the desired state

Returns: 0 on success; negative errno on error.

◆ ieee802154_set_tx_power()

static int ieee802154_set_tx_power	(	ieee802154_submac_t *	submac,
		int8_t	tx_pow
	)

inlinestatic

Set IEEE 802.15.4 transmission power.

This is a shortcut to ieee802154_set_phy_conf

Parameters

[in]	submac	pointer the SubMAC descriptor
[in]	tx_pow	transmission power (in dBm)

Returns: 0 on success; -ENOTSUP if the transmission power is not supported; negative errno on error

Definition at line 293 of file submac.h.

◆ ieee802154_submac_ack_timeout_fired()

void ieee802154_submac_ack_timeout_fired ( ieee802154_submac_t * submac )

Indicate the SubMAC that the ACK timeout fired.

This function must be called when the ACK timeout timer fires.

Note: this function should not be called inside ISR context.

Parameters

[in] submac pointer to the SubMAC descriptor

◆ ieee802154_submac_ack_timer_cancel()

void ieee802154_submac_ack_timer_cancel ( ieee802154_submac_t * submac )

Cancel the ACK timeout timer.

Note: This function should be implemented by the user of the SubMAC.

Parameters

[in] submac pointer to the SubMAC descriptor

◆ ieee802154_submac_ack_timer_set()

void ieee802154_submac_ack_timer_set	(	ieee802154_submac_t *	submac,
		uint16_t	us
	)

Set the ACK timeout timer.

Note: This function should be implemented by the user of the SubMAC.

Parameters

[in]	submac	pointer to the SubMAC descriptor
[in]	us	microseconds until the ACK timeout timer is fired

◆ ieee802154_submac_init()

int ieee802154_submac_init	(	ieee802154_submac_t *	submac,
		const network_uint16_t *	short_addr,
		const eui64_t *	ext_addr
	)

Init the IEEE 802.15.4 SubMAC.

Parameters

[in]	submac	pointer to the SubMAC descriptor
[in]	short_addr	pointer to the IEEE 802.15.4 short address
[in]	ext_addr	pointer to the IEEE 802.15.4 extended address

Returns: 0 on success; negative errno on error

◆ ieee802154_submac_rx_done_cb()

void ieee802154_submac_rx_done_cb ( ieee802154_submac_t * submac )

Indicate the SubMAC that the device received a frame.

Parameters

[in] submac pointer to the SubMAC descriptor

◆ ieee802154_submac_tx_done_cb()

void ieee802154_submac_tx_done_cb ( ieee802154_submac_t * submac )

Indicate the SubMAC that the device finished the transmission procedure.

Parameters

[in] submac pointer to the SubMAC descriptor

Detailed Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Enumeration Type Documentation

◆ ieee802154_submac_state_t

Function Documentation

◆ ieee802154_get_frame_length()

◆ ieee802154_get_state()

◆ ieee802154_read_frame()

◆ ieee802154_send()

◆ ieee802154_set_channel_number()

◆ ieee802154_set_channel_page()

◆ ieee802154_set_ext_addr()

◆ ieee802154_set_panid()

◆ ieee802154_set_phy_conf()

◆ ieee802154_set_short_addr()

◆ ieee802154_set_state()

◆ ieee802154_set_tx_power()

◆ ieee802154_submac_ack_timeout_fired()

◆ ieee802154_submac_ack_timer_cancel()

◆ ieee802154_submac_ack_timer_set()

◆ ieee802154_submac_init()

◆ ieee802154_submac_rx_done_cb()

◆ ieee802154_submac_tx_done_cb()