GNRC LoRaWAN internal header. More...

Detailed Description

GNRC LoRaWAN internal header.

Author: Jose Ignacio Alamos jose..nosp@m.alam.nosp@m.os@ha.nosp@m.w-ha.nosp@m.mburg.nosp@m..de

Definition in file gnrc_lorawan_internal.h.

#include <stdio.h>
#include <string.h>
#include "iolist.h"
#include "net/lora.h"
#include "net/lorawan/hdr.h"
#include "net/gnrc/pktbuf.h"
#include "xtimer.h"
#include "msg.h"
#include "net/netdev.h"
#include "net/netdev/layer.h"
#include "net/loramac.h"

Include dependency graph for gnrc_lorawan_internal.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	lorawan_buffer_t
	buffer helper for parsing and constructing LoRaWAN packets. More...

struct	mlme_lorawan_join_t
	MLME Join Request data. More...

struct	mlme_link_req_confirm_t
	MLME Link Check confirmation data. More...

struct	mcps_data_t
	MCPS data. More...

struct	gnrc_lorawan_mcps_t
	MCPS service access point descriptor. More...

struct	gnrc_lorawan_mlme_t
	MLME service access point descriptor. More...

struct	gnrc_lorawan_t
	GNRC LoRaWAN mac descriptor. More...

#define	MSG_TYPE_TIMEOUT (0x3457)
	Timeout message type.

#define	MSG_TYPE_MCPS_ACK_TIMEOUT (0x3458)
	ACK timeout message type.

#define	MSG_TYPE_MLME_BACKOFF_EXPIRE (0x3459)
	Backoff timer expiration message type.

#define	MTYPE_MASK 0xE0
	MHDR mtype mask.

#define	MTYPE_JOIN_REQUEST 0x0
	Join Request type.

#define	MTYPE_JOIN_ACCEPT 0x1
	Join Accept type.

#define	MTYPE_UNCNF_UPLINK 0x2
	Unconfirmed uplink type.

#define	MTYPE_UNCNF_DOWNLINK 0x3
	Unconfirmed downlink type.

#define	MTYPE_CNF_UPLINK 0x4
	Confirmed uplink type.

#define	MTYPE_CNF_DOWNLINK 0x5
	Confirmed downlink type.

#define	MTYPE_REJOIN_REQ 0x6
	Re-join request type.

#define	MTYPE_PROPIETARY 0x7
	Proprietary frame type.

#define	MAJOR_MASK 0x3
	Major mtype mask.

#define	MAJOR_LRWAN_R1 0x0
	LoRaWAN R1 version type.

#define	JOIN_REQUEST_SIZE (23U)
	Join Request size in bytes.

#define	MIC_SIZE (4U)
	MIC size in bytes.

#define	CFLIST_SIZE (16U)
	Channel Frequency list size in bytes.

#define	GNRC_LORAWAN_MAX_CHANNELS (16U)
	Maximum number of channels.

#define	LORAWAN_STATE_IDLE (0)
	MAC state machine in idle.

#define	LORAWAN_STATE_RX_1 (1)
	MAC state machine in RX1.

#define	LORAWAN_STATE_RX_2 (2)
	MAC state machine in RX2.

#define	LORAWAN_STATE_TX (3)
	MAC state machine in TX.

#define	GNRC_LORAWAN_DIR_UPLINK (0U)
	uplink frame direction

#define	GNRC_LORAWAN_DIR_DOWNLINK (1U)
	downlink frame direction

#define	GNRC_LORAWAN_BACKOFF_WINDOW_TICK (3600000000LL)
	backoff expire tick in usecs (set to 1 second)

#define	GNRC_LORAWAN_BACKOFF_BUDGET_1 (36000000LL)
	budget of time on air during the first hour

#define	GNRC_LORAWAN_BACKOFF_BUDGET_2 (36000000LL)
	budget of time on air between 1-10 hours after boot

#define	GNRC_LORAWAN_BACKOFF_BUDGET_3 (8700000LL)
	budget of time on air every 24 hours

#define	GNRC_LORAWAN_MLME_OPTS_LINK_CHECK_REQ (1 << 0)
	Internal Link Check request flag.

#define	GNRC_LORAWAN_CID_SIZE (1U)
	size of Command ID in FOps

#define	GNRC_LORAWAN_CID_LINK_CHECK_ANS (0x02)
	Link Check CID.

#define	GNRC_LORAWAN_FOPT_LINK_CHECK_ANS_SIZE (3U)
	size of Link check answer

#define	GNRC_LORAWAN_JOIN_DELAY_U32_MASK (0x1FFFFF)
	mask for detecting overflow in frame counter

#define	GNRC_LORAWAN_MAX_PAYLOAD_1 (59U)
	max MAC payload in DR0, DR1 and DR2

#define	GNRC_LORAWAN_MAX_PAYLOAD_2 (123U)
	max MAC payload in DR3

#define	GNRC_LORAWAN_MAX_PAYLOAD_3 (250U)
	max MAC payload above DR3

#define	GNRC_LORAWAN_CFLIST_ENTRY_SIZE (3U)
	size of Channel Frequency list

#define	GNRC_LORAWAN_JOIN_ACCEPT_MAX_SIZE (33U)
	max size of Join Accept frame

#define	GNRC_LORAWAN_BACKOFF_STATE_1 (0U)
	backoff state during the first hour after boot

#define	GNRC_LORAWAN_BACKOFF_STATE_2 (1U)
	backoff state between 1-10 hours after boot

#define	GNRC_LORAWAN_BACKOFF_STATE_3 (2U)
	backoff state past 11 hours after boot

#define	GNRC_LORAWAN_BACKOFF_TIME_1 (1U)
	duration of first backoff state (in hours)

#define	GNRC_LORAWAN_BACKOFF_TIME_2 (10U)
	duration of second backoff state (in hours)

#define	GNRC_LORAWAN_BACKOFF_TIME_3 (24U)
	duration of third backoff state (in hours)

#define	GNRC_LORAWAN_APP_NONCE_SIZE (3U)
	App Nonce size.

#define	GNRC_LORAWAN_NET_ID_SIZE (3U)
	Net ID size.

#define	GNRC_LORAWAN_DEV_NONCE_SIZE (2U)
	Dev Nonce size.

#define	GNRC_LORAWAN_FOPTS_MAX_SIZE (15U)
	Maximum size of Fopts field.

#define	GNRC_LORAWAN_FPORT_SIZE (1U)
	Size of the Fport field.

#define	MHDR_MIC_BUF_SIZE
	Size of the internal MHDR-MIC buffer. More...

void	gnrc_lorawan_encrypt_payload (iolist_t iolist, const le_uint32_t dev_addr, uint32_t fcnt, uint8_t dir, const uint8_t *appskey)
	Encrypts LoRaWAN payload. More...

void	gnrc_lorawan_decrypt_join_accept (const uint8_t key, uint8_t pkt, int has_clist, uint8_t *out)
	Decrypts join accept message. More...

void	gnrc_lorawan_generate_session_keys (const uint8_t app_nonce, const uint8_t dev_nonce, const uint8_t appkey, uint8_t nwkskey, uint8_t *appskey)
	Generate LoRaWAN session keys. More...

int	gnrc_lorawan_set_dr (gnrc_lorawan_t *mac, uint8_t datarate)
	Set datarate for the next transmission. More...

size_t	gnrc_lorawan_build_uplink (gnrc_lorawan_t mac, iolist_t payload, int confirmed_data, uint8_t port)
	build uplink frame More...

uint32_t	gnrc_lorawan_pick_channel (gnrc_lorawan_t *mac)
	pick a random available LoRaWAN channel More...

uint8_t	gnrc_lorawan_build_options (gnrc_lorawan_t mac, lorawan_buffer_t buf)
	Build fopts header. More...

void	gnrc_lorawan_process_fopts (gnrc_lorawan_t mac, uint8_t fopts, size_t size)
	Process an fopts frame. More...

void	gnrc_lorawan_calculate_join_mic (const uint8_t buf, size_t len, const uint8_t key, le_uint32_t *out)
	calculate join Message Integrity Code More...

void	gnrc_lorawan_calculate_mic (const le_uint32_t dev_addr, uint32_t fcnt, uint8_t dir, iolist_t frame, const uint8_t nwkskey, le_uint32_t out)
	Calculate Message Integrity Code for a MCPS message. More...

size_t	gnrc_lorawan_build_hdr (uint8_t mtype, le_uint32_t dev_addr, uint32_t fcnt, uint8_t ack, uint8_t fopts_length, lorawan_buffer_t buf)
	Build a MCPS LoRaWAN header. More...

void	gnrc_lorawan_mcps_process_downlink (gnrc_lorawan_t mac, uint8_t psdu, size_t size)
	Process an MCPS downlink message (confirmable or non comfirmable) More...

void	gnrc_lorawan_channels_init (gnrc_lorawan_t *mac)
	Init regional channel settings. More...

void	gnrc_lorawan_reset (gnrc_lorawan_t *mac)
	Reset MAC parameters. More...

void	gnrc_lorawan_send_pkt (gnrc_lorawan_t mac, iolist_t psdu, uint8_t dr)
	Send a LoRaWAN packet. More...

void	gnrc_lorawan_mlme_process_join (gnrc_lorawan_t mac, uint8_t data, size_t size)
	Process join accept message. More...

void	gnrc_lorawan_mlme_no_rx (gnrc_lorawan_t *mac)
	Inform the MAC layer that no packet was received during reception. More...

void	gnrc_lorawan_event_no_rx (gnrc_lorawan_t *mac)
	Mac callback for no RX. More...

void	gnrc_lorawan_event_ack_timeout (gnrc_lorawan_t *mac)
	Mac callback for ACK timeout event. More...

uint8_t	gnrc_lorawan_region_mac_payload_max (uint8_t datarate)
	Get the maximum MAC payload (M value) for a given datarate. More...

void	gnrc_lorawan_mlme_backoff_expire (gnrc_lorawan_t *mac)
	MLME Backoff expiration tick. More...

void	gnrc_lorawan_process_pkt (gnrc_lorawan_t mac, iolist_t pkt)
	Process and dispatch a full LoRaWAN packet. More...

void	gnrc_lorawan_open_rx_window (gnrc_lorawan_t *mac)
	Open a reception window. More...

void	gnrc_lorawan_perform_save (gnrc_lorawan_t *mac)
	save internal MAC state in non-volatile storage and shutdown the MAC layer gracefully. More...

static int	gnrc_lorawan_mac_acquire (gnrc_lorawan_t *mac)
	Acquire the MAC layer. More...

static void	gnrc_lorawan_mac_release (gnrc_lorawan_t *mac)
	Release the MAC layer. More...

void	gnrc_lorawan_set_rx2_dr (gnrc_lorawan_t *mac, uint8_t rx2_dr)
	Set the datarate of the second reception window. More...

Macro Definition Documentation

◆ MHDR_MIC_BUF_SIZE

#define MHDR_MIC_BUF_SIZE

Value:

                           (sizeof(lorawan_hdr_t) + \
                           GNRC_LORAWAN_FOPTS_MAX_SIZE + \
                           GNRC_LORAWAN_FPORT_SIZE + \
                           MIC_SIZE)

Size of the internal MHDR-MIC buffer.

Definition at line 108 of file gnrc_lorawan_internal.h.

Function Documentation

◆ gnrc_lorawan_build_hdr()

size_t gnrc_lorawan_build_hdr	(	uint8_t	mtype,
		le_uint32_t *	dev_addr,
		uint32_t	fcnt,
		uint8_t	ack,
		uint8_t	fopts_length,
		lorawan_buffer_t *	buf
	)

Build a MCPS LoRaWAN header.

Parameters

[in]	mtype	the MType of the header
[in]	dev_addr	the Device Address
[in]	fcnt	frame counter
[in]	ack	true if ACK bit is set
[in]	fopts_length	the length of the FOpts field
[out]	buf	destination buffer of the hdr

Returns: the size of the header

◆ gnrc_lorawan_build_options()

uint8_t gnrc_lorawan_build_options	(	gnrc_lorawan_t *	mac,
		lorawan_buffer_t *	buf
	)

Build fopts header.

Parameters

[in]	mac	pointer to MAC descriptor
[out]	buf	destination buffer of fopts. If NULL, this function just returns the size of the expected fopts frame.

Returns: size of the fopts frame

◆ gnrc_lorawan_build_uplink()

size_t gnrc_lorawan_build_uplink	(	gnrc_lorawan_t *	mac,
		iolist_t *	payload,
		int	confirmed_data,
		uint8_t	port
	)

build uplink frame

Parameters

[in]	mac	pointer to MAC descriptor
[in]	payload	packet containing payload
[in]	confirmed_data	true if confirmed frame
[in]	port	MAC port

Returns: full LoRaWAN frame including payload; NULL if packet buffer is full. payload is released

◆ gnrc_lorawan_calculate_join_mic()

void gnrc_lorawan_calculate_join_mic	(	const uint8_t *	buf,
		size_t	len,
		const uint8_t *	key,
		le_uint32_t *	out
	)

calculate join Message Integrity Code

Parameters

[in]	buf	pointer to the frame
[in]	len	length of the frame
[in]	key	key used to calculate the MIC
[out]	out	calculated MIC

◆ gnrc_lorawan_calculate_mic()

void gnrc_lorawan_calculate_mic	(	const le_uint32_t *	dev_addr,
		uint32_t	fcnt,
		uint8_t	dir,
		iolist_t *	frame,
		const uint8_t *	nwkskey,
		le_uint32_t *	out
	)

Calculate Message Integrity Code for a MCPS message.

Parameters

[in]	dev_addr	the Device Address
[in]	fcnt	frame counter
[in]	dir	direction of the packet (0 is uplink, 1 is downlink)
[in]	frame	pointer to the PSDU frame (without MIC)
[in]	nwkskey	pointer to the Network Session Key
[out]	out	calculated MIC

◆ gnrc_lorawan_channels_init()

void gnrc_lorawan_channels_init ( gnrc_lorawan_t * mac )

Init regional channel settings.

   Intended to be called upon initialization

Parameters

[in] mac pointer to the MAC descriptor

◆ gnrc_lorawan_decrypt_join_accept()

void gnrc_lorawan_decrypt_join_accept	(	const uint8_t *	key,
		uint8_t *	pkt,
		int	has_clist,
		uint8_t *	out
	)

Decrypts join accept message.

Parameters

[in]	key	key to be used in the decryption
[in]	pkt	pointer to Join Accept MAC component (next byte after the MHDR)
[in]	has_clist	true if the Join Accept frame has CFList
[out]	out	buffer where the decryption is stored

◆ gnrc_lorawan_encrypt_payload()

void gnrc_lorawan_encrypt_payload	(	iolist_t *	iolist,
		const le_uint32_t *	dev_addr,
		uint32_t	fcnt,
		uint8_t	dir,
		const uint8_t *	appskey
	)

Encrypts LoRaWAN payload.

Note: This function is also used for decrypting a LoRaWAN packet. The LoRaWAN server encrypts the packet using decryption, so the end device only needs to implement encryption

Parameters

[in]	iolist	pointer to the MSDU frame
[in]	dev_addr	device address
[in]	fcnt	frame counter
[in]	dir	direction of the packet (0 if uplink, 1 if downlink)
[in]	appskey	pointer to the Application Session Key

◆ gnrc_lorawan_event_ack_timeout()

void gnrc_lorawan_event_ack_timeout ( gnrc_lorawan_t * mac )

Mac callback for ACK timeout event.

Parameters

[in] mac pointer to the MAC descriptor

◆ gnrc_lorawan_event_no_rx()

void gnrc_lorawan_event_no_rx ( gnrc_lorawan_t * mac )

Mac callback for no RX.

Parameters

[in] mac pointer to the MAC descriptor

◆ gnrc_lorawan_generate_session_keys()

void gnrc_lorawan_generate_session_keys	(	const uint8_t *	app_nonce,
		const uint8_t *	dev_nonce,
		const uint8_t *	appkey,
		uint8_t *	nwkskey,
		uint8_t *	appskey
	)

Generate LoRaWAN session keys.

Intended to be called after a successful Join Request in order to generate NwkSKey and AppSKey

Parameters

[in]	app_nonce	pointer to the app_nonce of the Join Accept message
[in]	dev_nonce	pointer to the dev_nonce buffer
[in]	appkey	pointer to eh AppKey
[out]	nwkskey	pointer to the NwkSKey
[out]	appskey	pointer to the AppSKey

◆ gnrc_lorawan_mac_acquire()

static int gnrc_lorawan_mac_acquire ( gnrc_lorawan_t * mac )

inlinestatic

Acquire the MAC layer.

Parameters

[in] mac pointer to the MAC descriptor

Returns: true on success; false if MAC is already acquired

Definition at line 463 of file gnrc_lorawan_internal.h.

◆ gnrc_lorawan_mac_release()

static void gnrc_lorawan_mac_release ( gnrc_lorawan_t * mac )

inlinestatic

Release the MAC layer.

Parameters

[in] mac pointer to the MAC descriptor

Definition at line 476 of file gnrc_lorawan_internal.h.

◆ gnrc_lorawan_mcps_process_downlink()

void gnrc_lorawan_mcps_process_downlink	(	gnrc_lorawan_t *	mac,
		uint8_t *	psdu,
		size_t	size
	)

Process an MCPS downlink message (confirmable or non comfirmable)

Parameters

[in]	mac	pointer to the MAC descriptor
[in]	psdu	pointer to the downlink PSDU
[in]	size	size of the PSDU

◆ gnrc_lorawan_mlme_backoff_expire()

void gnrc_lorawan_mlme_backoff_expire ( gnrc_lorawan_t * mac )

MLME Backoff expiration tick.

   Should be called every hour in order to maintain the Time On Air budget.

Parameters

[in] mac pointer to the MAC descriptor

◆ gnrc_lorawan_mlme_no_rx()

void gnrc_lorawan_mlme_no_rx ( gnrc_lorawan_t * mac )

Inform the MAC layer that no packet was received during reception.

   To be called when the radio reports "NO RX" after the second reception
   window

Parameters

[in] mac pointer to the MAC descriptor

◆ gnrc_lorawan_mlme_process_join()

void gnrc_lorawan_mlme_process_join	(	gnrc_lorawan_t *	mac,
		uint8_t *	data,
		size_t	size
	)

Process join accept message.

Parameters

[in]	mac	pointer to the MAC descriptor
[in]	data	the Join Accept packet
[in]	size	size of the Join Accept packet

◆ gnrc_lorawan_open_rx_window()

void gnrc_lorawan_open_rx_window ( gnrc_lorawan_t * mac )

Open a reception window.

   This is called by the MAC layer on timeout event.

Parameters

[in] mac pointer to the MAC descriptor

◆ gnrc_lorawan_perform_save()

void gnrc_lorawan_perform_save ( gnrc_lorawan_t * mac )

save internal MAC state in non-volatile storage and shutdown the MAC layer gracefully.

Parameters

mac

◆ gnrc_lorawan_pick_channel()

uint32_t gnrc_lorawan_pick_channel ( gnrc_lorawan_t * mac )

pick a random available LoRaWAN channel

Parameters

[in] mac pointer to the MAC descriptor

Returns: a free channel

◆ gnrc_lorawan_process_fopts()

void gnrc_lorawan_process_fopts	(	gnrc_lorawan_t *	mac,
		uint8_t *	fopts,
		size_t	size
	)

Process an fopts frame.

Parameters

[in]	mac	pointer to MAC descriptor
[in]	fopts	pointer to fopts frame
[in]	size	size of fopts frame

◆ gnrc_lorawan_process_pkt()

void gnrc_lorawan_process_pkt	(	gnrc_lorawan_t *	mac,
		iolist_t *	pkt
	)

Process and dispatch a full LoRaWAN packet.

   Intended to be called right after reception from the radio

Parameters

[in]	mac	pointer to the MAC descriptor
[in]	pkt	the received packet

◆ gnrc_lorawan_region_mac_payload_max()

uint8_t gnrc_lorawan_region_mac_payload_max ( uint8_t datarate )

Get the maximum MAC payload (M value) for a given datarate.

Note: This function is region specific

Parameters

[in] datarate datarate

Returns: the maximum allowed size of the packet

◆ gnrc_lorawan_reset()

void gnrc_lorawan_reset ( gnrc_lorawan_t * mac )

Reset MAC parameters.

Note: This doesn't affect backoff timers variables.

Parameters

[in] mac pointer to the MAC layer

◆ gnrc_lorawan_send_pkt()

void gnrc_lorawan_send_pkt	(	gnrc_lorawan_t *	mac,
		iolist_t *	psdu,
		uint8_t	dr
	)

Send a LoRaWAN packet.

Parameters

[in]	mac	pointer to the MAC descriptor
[in]	psdu	the psdu frame to be sent
[in]	dr	the datarate used for the transmission

◆ gnrc_lorawan_set_dr()

int gnrc_lorawan_set_dr	(	gnrc_lorawan_t *	mac,
		uint8_t	datarate
	)

Set datarate for the next transmission.

Parameters

[in]	mac	pointer to the MAC descriptor
[in]	datarate	desired datarate

Returns: 0 on success; -EINVAL if datarate is not available in the current region

◆ gnrc_lorawan_set_rx2_dr()

void gnrc_lorawan_set_rx2_dr	(	gnrc_lorawan_t *	mac,
		uint8_t	rx2_dr
	)

Set the datarate of the second reception window.

Parameters

[in]	mac	pointer to the MAC descriptor
[in]	rx2_dr	datarate of RX2

Detailed Description

Data Structures

Macro Definition Documentation

◆ MHDR_MIC_BUF_SIZE

Function Documentation

◆ gnrc_lorawan_build_hdr()

◆ gnrc_lorawan_build_options()

◆ gnrc_lorawan_build_uplink()

◆ gnrc_lorawan_calculate_join_mic()

◆ gnrc_lorawan_calculate_mic()

◆ gnrc_lorawan_channels_init()

◆ gnrc_lorawan_decrypt_join_accept()

◆ gnrc_lorawan_encrypt_payload()

◆ gnrc_lorawan_event_ack_timeout()

◆ gnrc_lorawan_event_no_rx()

◆ gnrc_lorawan_generate_session_keys()

◆ gnrc_lorawan_mac_acquire()

◆ gnrc_lorawan_mac_release()

◆ gnrc_lorawan_mcps_process_downlink()

◆ gnrc_lorawan_mlme_backoff_expire()

◆ gnrc_lorawan_mlme_no_rx()

◆ gnrc_lorawan_mlme_process_join()

◆ gnrc_lorawan_open_rx_window()

◆ gnrc_lorawan_perform_save()

◆ gnrc_lorawan_pick_channel()

◆ gnrc_lorawan_process_fopts()

◆ gnrc_lorawan_process_pkt()

◆ gnrc_lorawan_region_mac_payload_max()

◆ gnrc_lorawan_reset()

◆ gnrc_lorawan_send_pkt()

◆ gnrc_lorawan_set_dr()

◆ gnrc_lorawan_set_rx2_dr()