LWMAC

A Lightweight duty-cycling 802.15.4 MAC protocol. More...

Detailed Description

A Lightweight duty-cycling 802.15.4 MAC protocol.

Deprecated:

This module is deprecated and will be removed after the 2024.10 release. As an alternative MAC layer for IEEE 802.15.4, you can use openDSME - IEEE 802.15.4 DSME.

LWMAC implementation

Radio duty cycling

LWMAC adopts the radio duty-cycle scheme to conserve power. Namely, in each cycle period (MAC superframe), a node device wakes up for a short period of time (called listen period or wake-up period) for receiving possible incoming packets from other devices. Outside the listen period, the node device turns off its radio to conserve power.

Phase-lock scheme

LWMAC adopts the phase-lock scheme to further reduce power consumption. Each node device in LWMAC will try to record/track its Tx-neighbor's wake-up phase. This is called phase-lock. After phase-locking, the sender node will (likely) spend less preamble packets (also called WR packet, i.e., wake-up-request, in LWMAC) for initiating a hand-shaking procedure for transmitting a data packet, compared to the first time it talks to the receiver.

Burst transmission

LWMAC adopts pending-bit technique to enhance its throughput. Namely, in case of having multi packets for the receiver, a sender uses the pending-bit flag embedded in the MAC header to instruct this situation, and the buffered packets will be transmitted in a continuous sequence, back to back, to the receiver in one shot.

Auto wake-up extension

LWMAC adopts auto wake-up extension scheme based on timeout (like T-MAC). In short, when a packet is successfully received at the receiver side, the receiver will reset the wake-up timeout to extend its wake-up period for receiving more potential incoming packets. This is to be compatible with the pending-bit technique to allow the receiver to absorb more packets when needed, thus boosts the throughput.

Simple retransmission scheme

LWMAC adopts a simple retransmission scheme to enhance link reliability. The data packet will only be dropped in case the retransmission counter gets larger than CONFIG_GNRC_LWMAC_MAX_DATA_TX_RETRIES.

Automatic phase backoff scheme

LWMAC adopts an automatic phase backoff scheme to reduce WR (preamble) collision probability. In multi-hop scenarios, let's say, nodes A <—B <-—C (which is common in multi-hop data collection networks), in which B has packets for A, and C has packets for B. In case A and B's wake-up phases are too close (overlapping). Then, especially in high traffic conditions, B and C may initiate transmissions at the same time (B sends to A, and C sends to B), a link of either will be definitely interfered, leading to collisions and link throughput reduction. To this end, by using the automatic phase backoff scheme, if a sender finds its receiver's phase is too close to its own phase, it will run a backoff scheme to randomly reselect a new wake-up phase for itself.

Modules
	GNRC LWMAC compile configurations

Files
file	hdr.h
	Header definition LWMAC.
file	lwmac.h
	Interface definition for the LWMAC protocol.
file	timeout.h
	Timeout handling of LWMAC.
file	types.h
	Definition of internal types used by LWMAC.
file	lwmac_internal.h
	Interface definition for internal functions of LWMAC protocol.
file	rx_state_machine.h
	Implementation of RX state machine.
file	tx_state_machine.h
	Implementation of TX state machine.

Macros
#define	CONFIG_GNRC_LWMAC_RADIO_REINIT_THRESHOLD   (10U)
	Maximum preamble attempts before re-initialize radio in LWMAC.

Functions
int	gnrc_netif_lwmac_create (gnrc_netif_t *netif, char *stack, int stacksize, char priority, const char *name, netdev_t *dev)
	Creates an IEEE 802.15.4 LWMAC network interface.

Macro Definition Documentation

CONFIG_GNRC_LWMAC_RADIO_REINIT_THRESHOLD

#define CONFIG_GNRC_LWMAC_RADIO_REINIT_THRESHOLD   (10U)

Maximum preamble attempts before re-initialize radio in LWMAC.

After a long period of run time, a radio may be in wrong condition which needs to be re-calibrated. This is indicated by having a series of continuous preamble failure (no WA) in LWMAC. In case we have CONFIG_GNRC_LWMAC_RADIO_REINIT_THRESHOLD number of preamble failure, then we re-initialize the radio, trying to re-calibrate the radio for bringing it back to normal condition.

Definition at line 330 of file lwmac.h.

Function Documentation

gnrc_netif_lwmac_create()

int gnrc_netif_lwmac_create	(	gnrc_netif_t *	netif,
		char *	stack,
		int	stacksize,
		char	priority,
		const char *	name,
		netdev_t *	dev
	)

Creates an IEEE 802.15.4 LWMAC network interface.

Parameters

[out]	netif	The interface. May not be NULL.
[in]	stack	The stack for the LWMAC network interface's thread.
[in]	stacksize	Size of stack.
[in]	priority	Priority for the LWMAC network interface's thread.
[in]	name	Name for the LWMAC network interface. May be NULL.
[in]	dev	Device for the interface

See also

gnrc_netif_create()

Returns

0 on success

negative number on error