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...

void	semtech_loramac_set_uplink_counter (semtech_loramac_t *mac, uint32_t counter)
	Sets the Uplink Frame Counter. More...

uint32_t	semtech_loramac_get_uplink_counter (semtech_loramac_t *mac)
	Gets the Uplink Frame Counter. 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] mac Pointer 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]	mac	Pointer to the mac
[out]	eui	The 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]	mac	Pointer to the mac
[in]	key	The 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]	mac	Pointer to the mac
[in]	skey	The application session key

◆ semtech_loramac_get_class()

loramac_class_t semtech_loramac_get_class ( semtech_loramac_t * mac )

Gets the device class.

Parameters

[in] mac Pointer 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]	mac	Pointer to the mac
[in]	addr	The 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]	mac	Pointer to the mac
[out]	eui	The device EUI

◆ semtech_loramac_get_dr()

uint8_t semtech_loramac_get_dr ( semtech_loramac_t * mac )

Gets the channels datarate.

Parameters

[in] mac Pointer 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] mac Pointer 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]	mac	Pointer to the mac
[in]	skey	The 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] mac Pointer 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] mac Pointer 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] mac Pointer 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] mac Pointer 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] mac Pointer 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] mac Pointer to the mac

Returns: The TX power index (from 1 to 16)

◆ semtech_loramac_get_uplink_counter()

uint32_t semtech_loramac_get_uplink_counter ( semtech_loramac_t * mac )

Gets the Uplink Frame Counter.

Parameters

[in] mac Pointer to the mac

Returns: Uplink frame counter

◆ semtech_loramac_init()

int semtech_loramac_init ( semtech_loramac_t * mac )

Initializes the semtech loramac mac.

Parameters

[in] mac Pointer 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] mac Pointer 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]	mac	Pointer to the mac
[in]	type	The 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_ALREADY_JOINED if network was already joined

◆ 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] mac Pointer 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] mac Pointer 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_DONE and within the RX windows delays.

See also: semtech_loramac_recv

Parameters

[in]	mac	Pointer to the mac
[in]	data	The TX data
[in]	len	The length of the TX data

Returns: SEMTECH_LORAMAC_TX_DONE when the message was 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_TX_CNF_FAILED when message was transmitted but no ACK was received

◆ semtech_loramac_set_adr()

void semtech_loramac_set_adr	(	semtech_loramac_t *	mac,
		bool	adr
	)

Enables/disable adaptive datarate.

Parameters

[in]	mac	Pointer to the mac
[in]	adr	Adaptive 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]	mac	Pointer to the mac
[in]	eui	The 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]	mac	Pointer to the mac
[in]	key	The 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]	mac	Pointer to the mac
[in]	skey	The 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]	mac	Pointer to the mac
[in]	cls	The 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]	mac	Pointer to the mac
[in]	addr	The 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]	mac	Pointer to the mac
[in]	eui	The device EUI

◆ semtech_loramac_set_dr()

void semtech_loramac_set_dr	(	semtech_loramac_t *	mac,
		uint8_t	dr
	)

Sets the channels datarate.

Parameters

[in]	mac	Pointer to the mac
[in]	dr	The 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]	mac	Pointer to the mac
[in]	min_rx	The 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]	mac	Pointer to the mac
[in]	netid	The 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]	mac	Pointer to the mac
[in]	skey	The 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]	mac	Pointer to the mac
[in]	public	The 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]	mac	Pointer to the mac
[in]	dr	The 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]	mac	Pointer to the mac
[in]	freq	The 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]	mac	Pointer to the mac
[in]	error	The 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]	mac	Pointer to the mac
[in]	mode	The 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]	mac	Pointer to the mac
[in]	port	The 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]	mac	Pointer to the mac
[in]	power	The TX power index (from 1 to 16)

◆ semtech_loramac_set_uplink_counter()

void semtech_loramac_set_uplink_counter	(	semtech_loramac_t *	mac,
		uint32_t	counter
	)

Sets the Uplink Frame Counter.

Parameters

[in]	mac	Pointer to the mac
[in]	counter	Frame counter to set

Detailed Description

Data Structures

Macros

Enumerations

Functions

Definitions for messages exchanged between the MAC and call threads

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ semtech_loramac_get_adr()

◆ semtech_loramac_get_appeui()

◆ semtech_loramac_get_appkey()

◆ semtech_loramac_get_appskey()

◆ semtech_loramac_get_class()

◆ semtech_loramac_get_devaddr()

◆ semtech_loramac_get_deveui()

◆ semtech_loramac_get_dr()

◆ semtech_loramac_get_netid()

◆ semtech_loramac_get_nwkskey()

◆ semtech_loramac_get_public_network()

◆ semtech_loramac_get_rx2_dr()

◆ semtech_loramac_get_rx2_freq()

◆ semtech_loramac_get_tx_mode()

◆ semtech_loramac_get_tx_port()

◆ semtech_loramac_get_tx_power()

◆ semtech_loramac_get_uplink_counter()

◆ semtech_loramac_init()

◆ semtech_loramac_is_mac_joined()

◆ semtech_loramac_join()

◆ semtech_loramac_recv()

◆ semtech_loramac_request_link_check()

◆ semtech_loramac_send()

◆ semtech_loramac_set_adr()

◆ semtech_loramac_set_appeui()

◆ semtech_loramac_set_appkey()

◆ semtech_loramac_set_appskey()

◆ semtech_loramac_set_class()

◆ semtech_loramac_set_devaddr()

◆ semtech_loramac_set_deveui()

◆ semtech_loramac_set_dr()

◆ semtech_loramac_set_min_rx_symbols()

◆ semtech_loramac_set_netid()

◆ semtech_loramac_set_nwkskey()

◆ semtech_loramac_set_public_network()

◆ semtech_loramac_set_rx2_dr()

◆ semtech_loramac_set_rx2_freq()

◆ semtech_loramac_set_system_max_rx_error()

◆ semtech_loramac_set_tx_mode()

◆ semtech_loramac_set_tx_port()

◆ semtech_loramac_set_tx_power()

◆ semtech_loramac_set_uplink_counter()