gnrc_lorawan_internal.h File Reference

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.
 
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...
 
gnrc_pktsnip_tgnrc_lorawan_build_uplink (gnrc_lorawan_t *mac, gnrc_pktsnip_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 iolist_t *io, 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 *pkt, 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, gnrc_pktsnip_t *pkt)
 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, gnrc_pktsnip_t *pkt, uint8_t dr)
 Send a LoRaWAN packet. More...
 
void gnrc_lorawan_mlme_process_join (gnrc_lorawan_t *mac, gnrc_pktsnip_t *pkt)
 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_mcps_event (gnrc_lorawan_t *mac, int event, int data)
 Trigger a MCPS 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, gnrc_pktsnip_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...
 

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]mtypethe MType of the header
[in]dev_addrthe Device Address
[in]fcntframe counter
[in]acktrue if ACK bit is set
[in]fopts_lengththe length of the FOpts field
[out]bufdestination 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]macpointer to MAC descriptor
[out]bufdestination 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()

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

build uplink frame

Parameters
[in]macpointer to MAC descriptor
[in]payloadpacket containing payload
[in]confirmed_datatrue if confirmed frame
[in]portMAC 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 iolist_t io,
const uint8_t *  key,
le_uint32_t out 
)

calculate join Message Integrity Code

Parameters
[in]ioiolist representation of the packet
[in]keykey used to calculate the MIC
[out]outcalculated MIC

◆ gnrc_lorawan_calculate_mic()

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

Calculate Message Integrity Code for a MCPS message.

Parameters
[in]dev_addrthe Device Address
[in]fcntframe counter
[in]dirdirection of the packet (0 is uplink, 1 is downlink)
[in]pktthe pkt
[in]nwkskeypointer to the Network Session Key
[out]outcalculated 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]macpointer 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]keykey to be used in the decryption
[in]pktpointer to Join Accept MAC component (next byte after the MHDR)
[in]has_clisttrue if the Join Accept frame has CFList
[out]outbuffer 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]iolistpacket iolist representation
[in]dev_addrdevice address
[in]fcntframe counter
[in]dirdirection of the packet (0 if uplink, 1 if downlink)
[in]appskeypointer to the Application Session Key

◆ 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_noncepointer to the app_nonce of the Join Accept message
[in]dev_noncepointer to the dev_nonce buffer
[in]appkeypointer to eh AppKey
[out]nwkskeypointer to the NwkSKey
[out]appskeypointer to the AppSKey

◆ gnrc_lorawan_mac_acquire()

static int gnrc_lorawan_mac_acquire ( gnrc_lorawan_t mac)
inlinestatic

Acquire the MAC layer.

Parameters
[in]macpointer to the MAC descriptor
Returns
true on success
false if MAC is already acquired

Definition at line 430 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]macpointer to the MAC descriptor

Definition at line 443 of file gnrc_lorawan_internal.h.

◆ gnrc_lorawan_mcps_event()

void gnrc_lorawan_mcps_event ( gnrc_lorawan_t mac,
int  event,
int  data 
)

Trigger a MCPS event.

Parameters
[in]macpointer to the MAC descriptor
[in]eventthe event to be processed.
[in]dataset to true if the packet contains payload

◆ gnrc_lorawan_mcps_process_downlink()

void gnrc_lorawan_mcps_process_downlink ( gnrc_lorawan_t mac,
gnrc_pktsnip_t pkt 
)

Process an MCPS downlink message (confirmable or non comfirmable)

Parameters
[in]macpointer to the MAC descriptor
[in]pktpointer to the downlink message

◆ 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]macpointer 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]macpointer to the MAC descriptor

◆ gnrc_lorawan_mlme_process_join()

void gnrc_lorawan_mlme_process_join ( gnrc_lorawan_t mac,
gnrc_pktsnip_t pkt 
)

Process join accept message.

Parameters
[in]macpointer to the MAC descriptor
[in]pktthe 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]macpointer 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]macpointer 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]macpointer to MAC descriptor
[in]foptspointer to fopts frame
[in]sizesize of fopts frame

◆ gnrc_lorawan_process_pkt()

void gnrc_lorawan_process_pkt ( gnrc_lorawan_t mac,
gnrc_pktsnip_t pkt 
)

Process and dispatch a full LoRaWAN packet.

Intended to be called right after reception from the radio

Parameters
[in]macpointer to the MAC descriptor
[in]pktthe 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]dataratedatarate
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]macpointer to the MAC layer

◆ gnrc_lorawan_send_pkt()

void gnrc_lorawan_send_pkt ( gnrc_lorawan_t mac,
gnrc_pktsnip_t pkt,
uint8_t  dr 
)

Send a LoRaWAN packet.

Parameters
[in]macpointer to the MAC descriptor
[in]pktthe packet to be sent
[in]drthe 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]macpointer to the MAC descriptor
[in]dataratedesired 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]macpointer to the MAC descriptor
[in]rx2_drdatarate of RX2