semtech_loramac.h File Reference

Public API and definitions of the Semtech LoRaMAC. More...

Detailed Description

Public API and definitions of the Semtech LoRaMAC.

Author
Alexandre Abadie alexa.nosp@m.ndre.nosp@m..abad.nosp@m.ie@i.nosp@m.nria..nosp@m.fr

Definition in file semtech_loramac.h.

#include <inttypes.h>
#include "mutex.h"
#include "net/netdev.h"
#include "net/loramac.h"
#include "sx127x.h"
+ Include dependency graph for semtech_loramac.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  semtech_loramac_channel_params_t
 LoRaMAC channel radio parameters. More...
 
struct  semtech_loramac_rx_data_t
 Structure containing LoRaWAN RX data. More...
 
struct  semtech_loramac_link_check_info_t
 LoRaMAC link check information. More...
 
struct  semtech_loramac_t
 Semtech LoRaMAC descriptor. More...
 

Macros

#define LORAWAN_APP_DATA_MAX_SIZE   (242U)
 Maximum payload size of a LoRaWAN application data.
 

Enumerations

enum  {
  SEMTECH_LORAMAC_JOIN_SUCCEEDED, SEMTECH_LORAMAC_JOIN_FAILED, SEMTECH_LORAMAC_NOT_JOINED, SEMTECH_LORAMAC_ALREADY_JOINED,
  SEMTECH_LORAMAC_TX_OK, SEMTECH_LORAMAC_TX_SCHEDULE, SEMTECH_LORAMAC_TX_DONE, SEMTECH_LORAMAC_TX_CNF_FAILED,
  SEMTECH_LORAMAC_TX_ERROR, SEMTECH_LORAMAC_RX_DATA, SEMTECH_LORAMAC_RX_LINK_CHECK, SEMTECH_LORAMAC_RX_CONFIRMED,
  SEMTECH_LORAMAC_BUSY, SEMTECH_LORAMAC_DUTYCYCLE_RESTRICTED
}
 LoRaMAC return status. More...
 
enum  { SEMTECH_LORAMAC_STATE_IDLE = 0, SEMTECH_LORAMAC_STATE_BUSY }
 LoRaMAC internal state.
 

Functions

int semtech_loramac_init (semtech_loramac_t *mac)
 Initializes the semtech loramac mac. More...
 
uint8_t semtech_loramac_join (semtech_loramac_t *mac, uint8_t type)
 Starts a LoRaWAN network join procedure. More...
 
uint8_t semtech_loramac_send (semtech_loramac_t *mac, uint8_t *data, uint8_t len)
 Sends data to the LoRaWAN network. More...
 
uint8_t semtech_loramac_recv (semtech_loramac_t *mac)
 Wait for a message sent by the LoRaWAN network. More...
 
bool semtech_loramac_is_mac_joined (semtech_loramac_t *mac)
 Check if network is already joined. More...
 
void semtech_loramac_request_link_check (semtech_loramac_t *mac)
 Requests a LoRaWAN link check. More...
 
void semtech_loramac_set_deveui (semtech_loramac_t *mac, const uint8_t *eui)
 Sets the device EUI. More...
 
void semtech_loramac_get_deveui (const semtech_loramac_t *mac, uint8_t *eui)
 Gets the device EUI. More...
 
void semtech_loramac_set_appeui (semtech_loramac_t *mac, const uint8_t *eui)
 Sets the application EUI. More...
 
void semtech_loramac_get_appeui (const semtech_loramac_t *mac, uint8_t *eui)
 Gets the application EUI. More...
 
void semtech_loramac_set_appkey (semtech_loramac_t *mac, const uint8_t *key)
 Sets the application key. More...
 
void semtech_loramac_get_appkey (const semtech_loramac_t *mac, uint8_t *key)
 Gets the application key. More...
 
void semtech_loramac_set_appskey (semtech_loramac_t *mac, const uint8_t *skey)
 Sets the application session key. More...
 
void semtech_loramac_get_appskey (semtech_loramac_t *mac, uint8_t *skey)
 Gets the application session key. More...
 
void semtech_loramac_set_nwkskey (semtech_loramac_t *mac, const uint8_t *skey)
 Sets the network session key. More...
 
void semtech_loramac_get_nwkskey (semtech_loramac_t *mac, uint8_t *skey)
 Gets the network session key. More...
 
void semtech_loramac_set_devaddr (semtech_loramac_t *mac, const uint8_t *addr)
 Sets the device address. More...
 
void semtech_loramac_get_devaddr (semtech_loramac_t *mac, uint8_t *addr)
 Gets the device address. More...
 
void semtech_loramac_set_class (semtech_loramac_t *mac, loramac_class_t cls)
 Sets the device class. More...
 
loramac_class_t semtech_loramac_get_class (semtech_loramac_t *mac)
 Gets the device class. More...
 
void semtech_loramac_set_dr (semtech_loramac_t *mac, uint8_t dr)
 Sets the channels datarate. More...
 
uint8_t semtech_loramac_get_dr (semtech_loramac_t *mac)
 Gets the channels datarate. More...
 
void semtech_loramac_set_adr (semtech_loramac_t *mac, bool adr)
 Enables/disable adaptive datarate. More...
 
bool semtech_loramac_get_adr (semtech_loramac_t *mac)
 Checks if adaptive datarate is set. More...
 
void semtech_loramac_set_public_network (semtech_loramac_t *mac, bool public)
 Enable/disable the public network mode. More...
 
bool semtech_loramac_get_public_network (semtech_loramac_t *mac)
 Checks if public network is set. More...
 
void semtech_loramac_set_netid (semtech_loramac_t *mac, uint32_t netid)
 Sets the NetID (only useful with ABP join procedure) More...
 
uint32_t semtech_loramac_get_netid (semtech_loramac_t *mac)
 Gets the NetID. More...
 
void semtech_loramac_set_tx_power (semtech_loramac_t *mac, uint8_t power)
 Sets the channels TX power index. More...
 
uint8_t semtech_loramac_get_tx_power (semtech_loramac_t *mac)
 Gets the channels TX power index. More...
 
void semtech_loramac_set_tx_port (semtech_loramac_t *mac, uint8_t port)
 Sets the TX application port. More...
 
void semtech_loramac_set_system_max_rx_error (semtech_loramac_t *mac, uint32_t error)
 Sets the maximum system overall timing error for RX (in ms) More...
 
void semtech_loramac_set_min_rx_symbols (semtech_loramac_t *mac, uint8_t min_rx)
 Sets the minimum required number of symbols to detect a frame. More...
 
uint8_t semtech_loramac_get_tx_port (semtech_loramac_t *mac)
 Gets the TX application port. More...
 
void semtech_loramac_set_tx_mode (semtech_loramac_t *mac, uint8_t mode)
 Sets the TX confirmable mode. More...
 
uint8_t semtech_loramac_get_tx_mode (semtech_loramac_t *mac)
 Gets the TX confirmable mode. More...
 
void semtech_loramac_set_rx2_freq (semtech_loramac_t *mac, uint32_t freq)
 Sets the RX2 frequency. More...
 
uint32_t semtech_loramac_get_rx2_freq (semtech_loramac_t *mac)
 Gets the RX2 frequency. More...
 
void semtech_loramac_set_rx2_dr (semtech_loramac_t *mac, uint8_t dr)
 Sets the RX2 datarate. More...
 
uint8_t semtech_loramac_get_rx2_dr (semtech_loramac_t *mac)
 Gets the RX2 datarate. More...
 

Definitions for messages exchanged between the MAC and call threads

#define MSG_TYPE_ISR   (0x3456)
 radio device ISR
 
#define MSG_TYPE_RX_TIMEOUT   (0x3457)
 radio driver RX timeout
 
#define MSG_TYPE_TX_TIMEOUT   (0x3458)
 radio driver TX timeout
 
#define MSG_TYPE_MAC_TIMEOUT   (0x3459)
 MAC timers timeout.
 
#define MSG_TYPE_LORAMAC_CMD   (0x3460)
 Command sent to the MAC.
 
#define MSG_TYPE_LORAMAC_JOIN_STATUS   (0x3461)
 Join status.
 
#define MSG_TYPE_LORAMAC_TX_STATUS   (0x3462)
 Uplink status.
 
#define MSG_TYPE_LORAMAC_MLME_CONFIRM   (0x3463)
 MAC MLME confirm event.
 
#define MSG_TYPE_LORAMAC_MLME_INDICATION   (0x3464)
 MAC MLME indication event.
 
#define MSG_TYPE_LORAMAC_MCPS_CONFIRM   (0x3465)
 MAC MCPS confirm event.
 
#define MSG_TYPE_LORAMAC_MCPS_INDICATION   (0x3466)
 MAC MCPS indication event.
 

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

LoRaMAC return status.

Enumerator
SEMTECH_LORAMAC_JOIN_SUCCEEDED 

Join procedure succeeded.

SEMTECH_LORAMAC_JOIN_FAILED 

Join procedure failed.

SEMTECH_LORAMAC_NOT_JOINED 

MAC is not joined.

SEMTECH_LORAMAC_ALREADY_JOINED 

MAC is already joined.

SEMTECH_LORAMAC_TX_OK 

Transmission is in progress.

SEMTECH_LORAMAC_TX_SCHEDULE 

TX needs reschedule.

SEMTECH_LORAMAC_TX_DONE 

Transmission completed.

SEMTECH_LORAMAC_TX_CNF_FAILED 

Confirmable transmission failed.

SEMTECH_LORAMAC_TX_ERROR 

Error in TX (invalid param, unknown service)

SEMTECH_LORAMAC_RX_DATA 

Data received.

SEMTECH_LORAMAC_RX_LINK_CHECK 

Link check info received.

SEMTECH_LORAMAC_RX_CONFIRMED 

Confirmed ACK received.

SEMTECH_LORAMAC_BUSY 

Internal MAC is busy.

SEMTECH_LORAMAC_DUTYCYCLE_RESTRICTED 

Restricted access to channels.

Definition at line 60 of file semtech_loramac.h.

Function Documentation

◆ semtech_loramac_get_adr()

bool semtech_loramac_get_adr ( semtech_loramac_t mac)

Checks if adaptive datarate is set.

Parameters
[in]macPointer to the mac
Returns
true if adr is on, false otherwise

◆ semtech_loramac_get_appeui()

void semtech_loramac_get_appeui ( const semtech_loramac_t mac,
uint8_t *  eui 
)

Gets the application EUI.

Parameters
[in]macPointer to the mac
[out]euiThe application EUI

◆ semtech_loramac_get_appkey()

void semtech_loramac_get_appkey ( const semtech_loramac_t mac,
uint8_t *  key 
)

Gets the application key.

Parameters
[in]macPointer to the mac
[in]keyThe application key

◆ semtech_loramac_get_appskey()

void semtech_loramac_get_appskey ( semtech_loramac_t mac,
uint8_t *  skey 
)

Gets the application session key.

Parameters
[in]macPointer to the mac
[in]skeyThe application session key

◆ semtech_loramac_get_class()

loramac_class_t semtech_loramac_get_class ( semtech_loramac_t mac)

Gets the device class.

Parameters
[in]macPointer to the mac
Returns
The device class

◆ semtech_loramac_get_devaddr()

void semtech_loramac_get_devaddr ( semtech_loramac_t mac,
uint8_t *  addr 
)

Gets the device address.

Parameters
[in]macPointer to the mac
[in]addrThe device address

◆ semtech_loramac_get_deveui()

void semtech_loramac_get_deveui ( const semtech_loramac_t mac,
uint8_t *  eui 
)

Gets the device EUI.

Parameters
[in]macPointer to the mac
[out]euiThe device EUI

◆ semtech_loramac_get_dr()

uint8_t semtech_loramac_get_dr ( semtech_loramac_t mac)

Gets the channels datarate.

Parameters
[in]macPointer to the mac
Returns
The datarate (from 1 to 16)

◆ semtech_loramac_get_netid()

uint32_t semtech_loramac_get_netid ( semtech_loramac_t mac)

Gets the NetID.

Parameters
[in]macPointer to the mac
Returns
The NetID

◆ semtech_loramac_get_nwkskey()

void semtech_loramac_get_nwkskey ( semtech_loramac_t mac,
uint8_t *  skey 
)

Gets the network session key.

Parameters
[in]macPointer to the mac
[in]skeyThe network session key

◆ semtech_loramac_get_public_network()

bool semtech_loramac_get_public_network ( semtech_loramac_t mac)

Checks if public network is set.

Parameters
[in]macPointer to the mac
Returns
true if public network is on, false otherwise

◆ semtech_loramac_get_rx2_dr()

uint8_t semtech_loramac_get_rx2_dr ( semtech_loramac_t mac)

Gets the RX2 datarate.

Parameters
[in]macPointer to the mac
Returns
The RX2 datarate

◆ semtech_loramac_get_rx2_freq()

uint32_t semtech_loramac_get_rx2_freq ( semtech_loramac_t mac)

Gets the RX2 frequency.

Parameters
[in]macPointer to the mac
Returns
The RX2 frequency

◆ semtech_loramac_get_tx_mode()

uint8_t semtech_loramac_get_tx_mode ( semtech_loramac_t mac)

Gets the TX confirmable mode.

Parameters
[in]macPointer to the mac
Returns
The TX mode (confirmable or not confirmable)

◆ semtech_loramac_get_tx_port()

uint8_t semtech_loramac_get_tx_port ( semtech_loramac_t mac)

Gets the TX application port.

Parameters
[in]macPointer to the mac
Returns
The TX application port

◆ semtech_loramac_get_tx_power()

uint8_t semtech_loramac_get_tx_power ( semtech_loramac_t mac)

Gets the channels TX power index.

Parameters
[in]macPointer to the mac
Returns
The TX power index (from 1 to 16)

◆ semtech_loramac_init()

int semtech_loramac_init ( semtech_loramac_t mac)

Initializes the semtech loramac mac.

Parameters
[in]macPointer to loramac descriptor
Returns
0 on success
-1 on failure

◆ semtech_loramac_is_mac_joined()

bool semtech_loramac_is_mac_joined ( semtech_loramac_t mac)

Check if network is already joined.

Parameters
[in]macPointer to the mac
Returns
true when network is joined, false otherwise

◆ semtech_loramac_join()

uint8_t semtech_loramac_join ( semtech_loramac_t mac,
uint8_t  type 
)

Starts a LoRaWAN network join procedure.

This function blocks until the join procedure succeeds or fails.

Parameters
[in]macPointer to the mac
[in]typeThe type of join procedure (otaa or abp)
Returns
SEMTECH_LORAMAC_JOIN_SUCCEEDED on success
SEMTECH_LORAMAC_JOIN_FAILED on failure
SEMTECH_LORAMAC_BUSY when the mac is already active (join or tx in progress)

◆ semtech_loramac_recv()

uint8_t semtech_loramac_recv ( semtech_loramac_t mac)

Wait for a message sent by the LoRaWAN network.

This function blocks until a single message is received by the mac (RX1 and RX2 windows). With a class A device, a message can only be received after a send. With a class C device, a message can be received at any time. In this case, this function can be used in a dedicated listener thread.

Be sure to call this function before the end of the RX windows otherwise it may block the calling thread.

By default this feature is not available to the user application, enable it by adding USEMODULE += semtech_loramac_rx to the application Makefile.

See also
semtech_loramac_send
Parameters
[in]macPointer to the mac
Returns
SEMTECH_LORAMAC_RX_DATA when data is received
SEMTECH_LORAMAC_RX_LINK_CHECK when link check information is received
SEMTECH_LORAMAC_RX_CONFIRMED when an ACK is received from the network

◆ semtech_loramac_request_link_check()

void semtech_loramac_request_link_check ( semtech_loramac_t mac)

Requests a LoRaWAN link check.

By default this feature is not available to the user application, enable it by adding USEMODULE += semtech_loramac_rx to the application Makefile.

Parameters
[in]macPointer to the mac

◆ semtech_loramac_send()

uint8_t semtech_loramac_send ( semtech_loramac_t mac,
uint8_t *  data,
uint8_t  len 
)

Sends data to the LoRaWAN network.

This function returns after TX status is replied from the MAC. To receive potential messages sent from the network an explicit call to semtech_loramac_recv must be done after this function if it returned SEMTECH_LORAMAC_TX_OK and within the RX windows delays.

See also
semtech_loramac_recv
Parameters
[in]macPointer to the mac
[in]dataThe TX data
[in]lenThe length of the TX data
Returns
SEMTECH_LORAMAC_TX_OK when the message can be transmitted
SEMTECH_LORAMAC_NOT_JOINED when the network is not joined
SEMTECH_LORAMAC_BUSY when the mac is already active (join or tx in progress)
SEMTECH_LORAMAC_DUTYCYCLE_RESTRICTED when the send is rejected because of dutycycle restriction
SEMTECH_LORAMAC_TX_ERROR when an invalid parameter is given

◆ semtech_loramac_set_adr()

void semtech_loramac_set_adr ( semtech_loramac_t mac,
bool  adr 
)

Enables/disable adaptive datarate.

Parameters
[in]macPointer to the mac
[in]adrAdaptive datarate mode

◆ semtech_loramac_set_appeui()

void semtech_loramac_set_appeui ( semtech_loramac_t mac,
const uint8_t *  eui 
)

Sets the application EUI.

Parameters
[in]macPointer to the mac
[in]euiThe application EUI

◆ semtech_loramac_set_appkey()

void semtech_loramac_set_appkey ( semtech_loramac_t mac,
const uint8_t *  key 
)

Sets the application key.

Parameters
[in]macPointer to the mac
[in]keyThe application key

◆ semtech_loramac_set_appskey()

void semtech_loramac_set_appskey ( semtech_loramac_t mac,
const uint8_t *  skey 
)

Sets the application session key.

Parameters
[in]macPointer to the mac
[in]skeyThe application session key

◆ semtech_loramac_set_class()

void semtech_loramac_set_class ( semtech_loramac_t mac,
loramac_class_t  cls 
)

Sets the device class.

Parameters
[in]macPointer to the mac
[in]clsThe device class

◆ semtech_loramac_set_devaddr()

void semtech_loramac_set_devaddr ( semtech_loramac_t mac,
const uint8_t *  addr 
)

Sets the device address.

Parameters
[in]macPointer to the mac
[in]addrThe device address

◆ semtech_loramac_set_deveui()

void semtech_loramac_set_deveui ( semtech_loramac_t mac,
const uint8_t *  eui 
)

Sets the device EUI.

Parameters
[in]macPointer to the mac
[in]euiThe device EUI

◆ semtech_loramac_set_dr()

void semtech_loramac_set_dr ( semtech_loramac_t mac,
uint8_t  dr 
)

Sets the channels datarate.

Parameters
[in]macPointer to the mac
[in]drThe datarate (from 1 to 16)

◆ semtech_loramac_set_min_rx_symbols()

void semtech_loramac_set_min_rx_symbols ( semtech_loramac_t mac,
uint8_t  min_rx 
)

Sets the minimum required number of symbols to detect a frame.

Parameters
[in]macPointer to the mac
[in]min_rxThe minimum rx symbols

◆ semtech_loramac_set_netid()

void semtech_loramac_set_netid ( semtech_loramac_t mac,
uint32_t  netid 
)

Sets the NetID (only useful with ABP join procedure)

Parameters
[in]macPointer to the mac
[in]netidThe NetID

◆ semtech_loramac_set_nwkskey()

void semtech_loramac_set_nwkskey ( semtech_loramac_t mac,
const uint8_t *  skey 
)

Sets the network session key.

Parameters
[in]macPointer to the mac
[in]skeyThe network session key

◆ semtech_loramac_set_public_network()

void semtech_loramac_set_public_network ( semtech_loramac_t mac,
bool  public 
)

Enable/disable the public network mode.

Parameters
[in]macPointer to the mac
[in]publicThe public network mode

◆ semtech_loramac_set_rx2_dr()

void semtech_loramac_set_rx2_dr ( semtech_loramac_t mac,
uint8_t  dr 
)

Sets the RX2 datarate.

Parameters
[in]macPointer to the mac
[in]drThe RX2 datarate

◆ semtech_loramac_set_rx2_freq()

void semtech_loramac_set_rx2_freq ( semtech_loramac_t mac,
uint32_t  freq 
)

Sets the RX2 frequency.

Parameters
[in]macPointer to the mac
[in]freqThe RX2 frequency

◆ semtech_loramac_set_system_max_rx_error()

void semtech_loramac_set_system_max_rx_error ( semtech_loramac_t mac,
uint32_t  error 
)

Sets the maximum system overall timing error for RX (in ms)

Parameters
[in]macPointer to the mac
[in]errorThe maximum rx timing error

◆ semtech_loramac_set_tx_mode()

void semtech_loramac_set_tx_mode ( semtech_loramac_t mac,
uint8_t  mode 
)

Sets the TX confirmable mode.

Parameters
[in]macPointer to the mac
[in]modeThe TX mode (confirmable or not confirmable)

◆ semtech_loramac_set_tx_port()

void semtech_loramac_set_tx_port ( semtech_loramac_t mac,
uint8_t  port 
)

Sets the TX application port.

Parameters
[in]macPointer to the mac
[in]portThe TX application port

◆ semtech_loramac_set_tx_power()

void semtech_loramac_set_tx_power ( semtech_loramac_t mac,
uint8_t  power 
)

Sets the channels TX power index.

Parameters
[in]macPointer to the mac
[in]powerThe TX power index (from 1 to 16)