semtech_loramac.h

Public API and definitions of the Semtech LoRaMAC.

MSG_TYPE_ISR

radio device ISR 

1
(0x3456)
MSG_TYPE_RX_TIMEOUT

radio driver RX timeout 

1
(0x3457)
MSG_TYPE_TX_TIMEOUT

radio driver TX timeout 

1
(0x3458)
MSG_TYPE_MAC_TIMEOUT

MAC timers timeout. 

1
(0x3459)
MSG_TYPE_LORAMAC_CMD

Command sent to the MAC. 

1
(0x3460)
MSG_TYPE_LORAMAC_JOIN

MAC join event. 

1
(0x3461)
MSG_TYPE_LORAMAC_TX_STATUS

MAC TX status. 

1
(0x3462)
MSG_TYPE_LORAMAC_RX

Some data received. 

1
(0x3463)
MSG_TYPE_LORAMAC_LINK_CHECK

Link check info received. 

1
(0x3464)
LORAWAN_APP_DATA_MAX_SIZE

Maximum payload size of a LoRaWAN application data. 

1
(242U)
enum @174
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_DATA_RECEIVED
Data received.
SEMTECH_LORAMAC_BUSY
Internal MAC is busy.
SEMTECH_LORAMAC_DUTYCYCLE_RESTRICTED
Restricted access to channels.
enum @175
SEMTECH_LORAMAC_STATE_IDLE = 0
SEMTECH_LORAMAC_STATE_BUSY
int semtech_loramac_init(semtech_loramac_t * mac)

Initializes the semtech loramac mac.

Parameters

mac:Pointer to loramac descriptor

Return values

  • 0 on success
  • -1 on failure
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

mac:Pointer to the mac
type:The type of join procedure (otaa or abp)

Return values

  • 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)
uint8_t semtech_loramac_send(semtech_loramac_t * mac, uint8_t * data, uint8_t len)

Sends data to the LoRaWAN network.

This function returns immediately and leave the mac in busy state until a message is received from the network (with RX1 and RX2 receive windows).

See also

semtech_loramac.h::semtech_loramac_recv()

Parameters

mac:Pointer to the mac
data:The TX data
len:The length of the TX data

Return values

  • 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_TX_SCHEDULED when the TX is scheduled in the mac
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.

See also

semtech_loramac.h::semtech_loramac_send()

Parameters

mac:Pointer to the mac

Return values

  • SEMTECH_LORAMAC_TX_DONE when TX has completed, no data received
  • SEMTECH_LORAMAC_DATA_RECEIVED when TX has completed and data is received
void semtech_loramac_request_link_check(semtech_loramac_t * mac)

Requests a LoRaWAN link check.

Parameters

mac:Pointer to the mac

void semtech_loramac_set_deveui(semtech_loramac_t * mac, const uint8_t * eui)

Sets the device EUI.

Parameters

mac:Pointer to the mac
eui:The device EUI

void semtech_loramac_get_deveui(const semtech_loramac_t * mac, uint8_t * eui)

Gets the device EUI.

Parameters

mac:Pointer to the mac
eui:The device EUI

void semtech_loramac_set_appeui(semtech_loramac_t * mac, const uint8_t * eui)

Sets the application EUI.

Parameters

mac:Pointer to the mac
eui:The application EUI

void semtech_loramac_get_appeui(const semtech_loramac_t * mac, uint8_t * eui)

Gets the application EUI.

Parameters

mac:Pointer to the mac
eui:The application EUI

void semtech_loramac_set_appkey(semtech_loramac_t * mac, const uint8_t * key)

Sets the application key.

Parameters

mac:Pointer to the mac
key:The application key

void semtech_loramac_get_appkey(const semtech_loramac_t * mac, uint8_t * key)

Gets the application key.

Parameters

mac:Pointer to the mac
key:The application key

void semtech_loramac_set_appskey(semtech_loramac_t * mac, const uint8_t * skey)

Sets the application session key.

Parameters

mac:Pointer to the mac
skey:The application session key

void semtech_loramac_get_appskey(const semtech_loramac_t * mac, uint8_t * skey)

Gets the application session key.

Parameters

mac:Pointer to the mac
skey:The application session key

void semtech_loramac_set_nwkskey(semtech_loramac_t * mac, const uint8_t * skey)

Sets the network session key.

Parameters

mac:Pointer to the mac
skey:The network session key

void semtech_loramac_get_nwkskey(const semtech_loramac_t * mac, uint8_t * skey)

Gets the network session key.

Parameters

mac:Pointer to the mac
skey:The network session key

void semtech_loramac_set_devaddr(semtech_loramac_t * mac, const uint8_t * addr)

Sets the device address.

Parameters

mac:Pointer to the mac
addr:The device address

void semtech_loramac_get_devaddr(const semtech_loramac_t * mac, uint8_t * addr)

Gets the device address.

Parameters

mac:Pointer to the mac
addr:The device address

void semtech_loramac_set_class(semtech_loramac_t * mac, loramac.h::loramac_class_t cls)

Sets the device class.

Parameters

mac:Pointer to the mac
cls:The device class

loramac.h::loramac_class_t semtech_loramac_get_class(semtech_loramac_t * mac)

Gets the device class.

Parameters

mac:Pointer to the mac

Return values

  • The device class
void semtech_loramac_set_dr(semtech_loramac_t * mac, uint8_t dr)

Sets the channels datarate.

Parameters

mac:Pointer to the mac
dr:The datarate (from 1 to 16)

uint8_t semtech_loramac_get_dr(semtech_loramac_t * mac)

Gets the channels datarate.

Parameters

mac:Pointer to the mac

Return values

  • The datarate (from 1 to 16)
void semtech_loramac_set_adr(semtech_loramac_t * mac, bool adr)

Enables/disable adaptive datarate.

Parameters

mac:Pointer to the mac
adr:Adaptive datarate mode

bool semtech_loramac_get_adr(semtech_loramac_t * mac)

Checks if adaptive datarate is set.

Parameters

mac:Pointer to the mac

Return values

  • true if adr is on, false otherwise
void semtech_loramac_set_public_network(semtech_loramac_t * mac, bool public)

Enable/disable the public network mode.

Parameters

mac:Pointer to the mac
public:The public network mode

bool semtech_loramac_get_public_network(semtech_loramac_t * mac)

Checks if public network is set.

Parameters

mac:Pointer to the mac

Return values

  • true if public network is on, false otherwise
void semtech_loramac_set_netid(semtech_loramac_t * mac, uint32_t netid)

Sets the NetID (only useful with ABP join procedure)

Parameters

mac:Pointer to the mac
netid:The NetID

uint32_t semtech_loramac_get_netid(semtech_loramac_t * mac)

Gets the NetID.

Parameters

mac:Pointer to the mac

Return values

  • The NetID
void semtech_loramac_set_tx_power(semtech_loramac_t * mac, uint8_t power)

Sets the channels TX power index.

Parameters

mac:Pointer to the mac
power:The TX power index (from 1 to 16)

uint8_t semtech_loramac_get_tx_power(semtech_loramac_t * mac)

Gets the channels TX power index.

Parameters

mac:Pointer to the mac

Return values

  • The TX power index (from 1 to 16)
void semtech_loramac_set_tx_port(semtech_loramac_t * mac, uint8_t port)

Sets the TX application port.

Parameters

mac:Pointer to the mac
port:The TX application port

uint8_t semtech_loramac_get_tx_port(semtech_loramac_t * mac)

Gets the TX application port.

Parameters

mac:Pointer to the mac

Return values

  • The TX application port
void semtech_loramac_set_tx_mode(semtech_loramac_t * mac, uint8_t mode)

Sets the TX confirmable mode.

Parameters

mac:Pointer to the mac
mode:The TX mode (confirmable or not confirmable)

uint8_t semtech_loramac_get_tx_mode(semtech_loramac_t * mac)

Gets the TX confirmable mode.

Parameters

mac:Pointer to the mac

Return values

  • The TX mode (confirmable or not confirmable)
void semtech_loramac_set_rx2_freq(semtech_loramac_t * mac, uint32_t freq)

Sets the RX2 frequency.

Parameters

mac:Pointer to the mac
freq:The RX2 frequency

uint32_t semtech_loramac_get_rx2_freq(semtech_loramac_t * mac)

Gets the RX2 frequency.

Parameters

mac:Pointer to the mac

Return values

  • The RX2 frequency
void semtech_loramac_set_rx2_dr(semtech_loramac_t * mac, uint8_t dr)

Sets the RX2 datarate.

Parameters

mac:Pointer to the mac
dr:The RX2 datarate

uint8_t semtech_loramac_get_rx2_dr(semtech_loramac_t * mac)

Gets the RX2 datarate.

Parameters

mac:Pointer to the mac

Return values

  • The RX2 datarate
struct semtech_loramac_channel_params_t

LoRaMAC channel radio parameters.

uint32_t frequency

channel center frequency

uint8_t datarate

channel datarate

struct semtech_loramac_rx_data_t

Structure containing LoRaWAN RX data.

uint8_t payload()

RX payload buffer.

uint8_t payload_len

Length of the RX payload.

uint8_t port

RX port.

struct semtech_loramac_link_check_info_t

LoRaMAC link check information.

uint8_t demod_margin

Demodulation margin.

uint8_t nb_gateways

number of LoRa gateways found

bool available

new link check information avalable

struct semtech_loramac_t

Semtech LoRaMAC descriptor.

mutex_t lock

loramac access lock

uint8_t caller_pid

pid of caller thread

uint8_t port

application TX port

uint8_t cnf

enable/disable confirmable messages

uint8_t deveui()

device EUI

uint8_t appeui()

application EUI

uint8_t appkey()

application key

uint8_t appskey()

application session key

uint8_t nwkskey()

network session key

uint8_t devaddr()

device address

semtech_loramac_rx_data_t rx_data

struct handling the RX data

semtech_loramac_link_check_info_t link_chk

link check information