LoRa and LoRaWAN

Overview

LoRa (abbrev. for Long Range) is a proprietary low-power wireless communication protocol developed by the Semtech Corporation.

LoRa acts as the physical layer (PHY) based on the chirp spread spectrum (CSS) modulation technique.

LoRaWAN (for Long Range Wide Area Network) defines a networking layer on top of the LoRa PHY.

Zephyr provides APIs for LoRa to send raw data packets directly over the wireless interface as well as APIs for LoRaWAN to connect the end device to the internet through a gateway.

The Zephyr implementation is based on Semtech’s LoRaMac-node library, which is included as a Zephyr module.

The LoRaWAN specification is published by the LoRa Alliance.

Configuration Options

LoRa PHY

Related configuration options can be found under drivers/lora/Kconfig.

LoRaWAN

Related configuration options can be found under subsys/lorawan/Kconfig.

API Reference

LoRa PHY

group lora_api

Enums

enum lora_signal_bandwidth

LoRa signal bandwidth.

Values:

enumerator BW_125_KHZ = 0
enumerator BW_250_KHZ
enumerator BW_500_KHZ
enum lora_datarate

LoRa data-rate.

Values:

enumerator SF_6 = 6
enumerator SF_7
enumerator SF_8
enumerator SF_9
enumerator SF_10
enumerator SF_11
enumerator SF_12
enum lora_coding_rate

LoRa coding rate.

Values:

enumerator CR_4_5 = 1
enumerator CR_4_6 = 2
enumerator CR_4_7 = 3
enumerator CR_4_8 = 4

Functions

static inline int lora_config(const struct device *dev, struct lora_modem_config *config)

Configure the LoRa modem.

Parameters:

  • dev – LoRa device

  • config – Data structure containing the intended configuration for the modem

Returns:

0 on success, negative on error

static inline int lora_send(const struct device *dev, uint8_t *data, uint32_t data_len)

Send data over LoRa.

Note

This blocks until transmission is complete.

Parameters:

  • dev – LoRa device

  • data – Data to be sent

  • data_len – Length of the data to be sent

Returns:

0 on success, negative on error

static inline int lora_send_async(const struct device *dev, uint8_t *data, uint32_t data_len, struct k_poll_signal *async)

Asynchronously send data over LoRa.

Note

This returns immediately after starting transmission, and locks the LoRa modem until the transmission completes.

Parameters:

  • dev – LoRa device

  • data – Data to be sent

  • data_len – Length of the data to be sent

  • async – A pointer to a valid and ready to be signaled struct k_poll_signal. (Note: if NULL this function will not notify the end of the transmission).

Returns:

0 on success, negative on error

static inline int lora_recv(const struct device *dev, uint8_t *data, uint8_t size, k_timeout_t timeout, int16_t *rssi, int8_t *snr)

Receive data over LoRa.

Note

This is a blocking call.

Parameters:

  • dev – LoRa device

  • data – Buffer to hold received data

  • size – Size of the buffer to hold the received data. Max size allowed is 255.

  • timeout – Duration to wait for a packet.

  • rssi – RSSI of received data

  • snr – SNR of received data

Returns:

Length of the data received on success, negative on error

static inline int lora_recv_async(const struct device *dev, lora_recv_cb cb)

Receive data asynchronously over LoRa.

Receive packets continuously under the configuration previously setup by lora_config.

Reception is cancelled by calling this function again with cb = NULL. This can be done within the callback handler.

Parameters:

  • dev – Modem to receive data on.

  • cb – Callback to run on receiving data. If NULL, any pending asynchronous receptions will be cancelled.

Returns:

0 when reception successfully setup, negative on error

static inline int lora_test_cw(const struct device *dev, uint32_t frequency, int8_t tx_power, uint16_t duration)

Transmit an unmodulated continuous wave at a given frequency.

Note

Only use this functionality in a test setup where the transmission does not interfere with other devices.

Parameters:

  • dev – LoRa device

  • frequency – Output frequency (Hertz)

  • tx_power – TX power (dBm)

  • duration – Transmission duration in seconds.

Returns:

0 on success, negative on error

struct lora_modem_config
#include <lora.h>

Structure containing the configuration of a LoRa modem.

Public Members

uint32_t frequency

Frequency in Hz to use for transceiving.

enum lora_signal_bandwidth bandwidth

The bandwidth to use for transceiving.

enum lora_datarate datarate

The data-rate to use for transceiving.

enum lora_coding_rate coding_rate

The coding rate to use for transceiving.

uint16_t preamble_len

Length of the preamble.

int8_t tx_power

TX-power in dBm to use for transmission.

bool tx

Set to true for transmission, false for receiving.

bool iq_inverted

Invert the In-Phase and Quadrature (IQ) signals.

Normally this should be set to false. In advanced use-cases where a differentation is needed between “uplink” and “downlink” traffic, the IQ can be inverted to create two different channels on the same frequency

bool public_network

Sets the sync-byte to use:

  • false: for using the private network sync-byte

  • true: for using the public network sync-byte The public network sync-byte is only intended for advanced usage. Normally the private network sync-byte should be used for peer to peer communications and the LoRaWAN APIs should be used for interacting with a public network.

LoRaWAN

group lorawan_api

Defines

LW_RECV_PORT_ANY

Enums

enum lorawan_class

LoRaWAN class types.

Values:

enumerator LORAWAN_CLASS_A = 0x00
enumerator LORAWAN_CLASS_B = 0x01
enumerator LORAWAN_CLASS_C = 0x02
enum lorawan_act_type

LoRaWAN activation types.

Values:

enumerator LORAWAN_ACT_OTAA = 0
enumerator LORAWAN_ACT_ABP
enum lorawan_datarate

LoRaWAN datarate types.

Values:

enumerator LORAWAN_DR_0 = 0
enumerator LORAWAN_DR_1
enumerator LORAWAN_DR_2
enumerator LORAWAN_DR_3
enumerator LORAWAN_DR_4
enumerator LORAWAN_DR_5
enumerator LORAWAN_DR_6
enumerator LORAWAN_DR_7
enumerator LORAWAN_DR_8
enumerator LORAWAN_DR_9
enumerator LORAWAN_DR_10
enumerator LORAWAN_DR_11
enumerator LORAWAN_DR_12
enumerator LORAWAN_DR_13
enumerator LORAWAN_DR_14
enumerator LORAWAN_DR_15
enum lorawan_region

LoRaWAN region types.

Values:

enumerator LORAWAN_REGION_AS923
enumerator LORAWAN_REGION_AU915
enumerator LORAWAN_REGION_CN470
enumerator LORAWAN_REGION_CN779
enumerator LORAWAN_REGION_EU433
enumerator LORAWAN_REGION_EU868
enumerator LORAWAN_REGION_KR920
enumerator LORAWAN_REGION_IN865
enumerator LORAWAN_REGION_US915
enumerator LORAWAN_REGION_RU864
enum lorawan_message_type

LoRaWAN message types.

Values:

enumerator LORAWAN_MSG_UNCONFIRMED = 0
enumerator LORAWAN_MSG_CONFIRMED

Functions

int lorawan_set_battery_level_callback(uint8_t (*battery_lvl_cb)(void))

Add battery level callback function.

Provide the LoRaWAN stack with a function to be called whenever a battery level needs to be read. As per LoRaWAN specification the callback needs to return “0: node is connected to an external power source,

1..254: battery level, where 1 is the minimum and 254 is the maximum

value,

255: the node was not able to measure the battery level”

Should no callback be provided the lorawan backend will report 255.

Parameters:

  • battery_lvl_cb – Pointer to the battery level function

Returns:

0 if successful, negative errno code if failure

Register a callback to be run on downlink packets.

Parameters:

  • cb – Pointer to structure containing callback parameters

void lorawan_register_dr_changed_callback(void (*dr_cb)(enum lorawan_datarate))

Register a callback to be called when the datarate changes.

The callback is called once upon successfully joining a network and again each time the datarate changes due to ADR.

The callback function takes one parameter:

  • dr - updated datarate

Parameters:

  • dr_cb – Pointer to datarate update callback

int lorawan_join(const struct lorawan_join_config *config)

Join the LoRaWAN network.

Join the LoRaWAN network using OTAA or AWB.

Parameters:

  • config – Configuration to be used

Returns:

0 if successful, negative errno code if failure

int lorawan_start(void)

Start the LoRaWAN stack.

This function need to be called before joining the network.

Returns:

0 if successful, negative errno code if failure

int lorawan_send(uint8_t port, uint8_t *data, uint8_t len, enum lorawan_message_type type)

Send data to the LoRaWAN network.

Send data to the connected LoRaWAN network.

Parameters:

  • port – Port to be used for sending data. Must be set if the payload is not empty.

  • data – Data buffer to be sent

  • len – Length of the buffer to be sent. Maximum length of this buffer is 255 bytes but the actual payload size varies with region and datarate.

  • type – Specifies if the message shall be confirmed or unconfirmed. Must be one of lorawan_message_type.

Returns:

0 if successful, negative errno code if failure

int lorawan_set_class(enum lorawan_class dev_class)

Set the current device class.

Change the current device class. This function may be called before or after a network connection has been established.

Parameters:

  • dev_class – New device class

Returns:

0 if successful, negative errno code if failure

int lorawan_set_conf_msg_tries(uint8_t tries)

Set the number of tries used for transmissions.

Parameters:

  • tries – Number of tries to be used

Returns:

0 if successful, negative errno code if failure

void lorawan_enable_adr(bool enable)

Enable Adaptive Data Rate (ADR)

Control whether adaptive data rate (ADR) is enabled. When ADR is enabled, the data rate is treated as a default data rate that will be used if the ADR algorithm has not established a data rate. ADR should normally only be enabled for devices with stable RF conditions (i.e., devices in a mostly static location).

Parameters:

  • enable – Enable or Disable adaptive data rate.

int lorawan_set_datarate(enum lorawan_datarate dr)

Set the default data rate.

Change the default data rate.

Parameters:

  • dr – Data rate used for transmissions

Returns:

0 if successful, negative errno code if failure

enum lorawan_datarate lorawan_get_min_datarate(void)

Get the minimum possible datarate.

The minimum possible datarate may change in response to a TxParamSetupReq command from the network server.

Returns:

Minimum possible data rate

void lorawan_get_payload_sizes(uint8_t *max_next_payload_size, uint8_t *max_payload_size)

Get the current payload sizes.

Query the current payload sizes. The maximum payload size varies with datarate, while the current payload size can be less due to MAC layer commands which are inserted into uplink packets.

Parameters:

  • max_next_payload_size – Maximum payload size for the next transmission

  • max_payload_size – Maximum payload size for this datarate

int lorawan_set_region(enum lorawan_region region)

Set the region and frequency to be used.

Control the LoRa region and frequency settings. This should be called before lorawan_start(). If you only have support for a single region selected via Kconfig, this function does not need to be called at all.

Parameters:

  • region – The region to be selected

Returns:

0 if successful, negative errno otherwise

struct lorawan_join_otaa
#include <lorawan.h>

LoRaWAN join parameters for over-the-Air activation (OTAA)

Note that all of the fields use LoRaWAN 1.1 terminology.

All parameters are optional if a secure element is present in which case the values stored in the secure element will be used instead.

Public Members

uint8_t *join_eui

Join EUI.

uint8_t *nwk_key

Network Key.

uint8_t *app_key

Application Key.

uint32_t dev_nonce

Device Nonce.

Starting with LoRaWAN 1.0.4 the DevNonce must be monotonically increasing for each OTAA join with the same EUI. The DevNonce should be stored in non-volatile memory by the application.

struct lorawan_join_abp
#include <lorawan.h>

LoRaWAN join parameters for activation by personalization (ABP)

Public Members

uint32_t dev_addr

Device address on the network.

uint8_t *app_skey

Application session key.

uint8_t *nwk_skey

Network session key.

uint8_t *app_eui

Application EUI.

struct lorawan_join_config
#include <lorawan.h>

LoRaWAN join parameters.

Public Members

uint8_t *dev_eui

Device EUI.

Optional if a secure element is present.

enum lorawan_act_type mode

Activation mode.

#include <lorawan.h>

LoRaWAN downlink callback parameters.

Public Members

Port to handle messages for.

  • Port 0: TX packet acknowledgements

  • Ports 1-255: Standard downlink port

  • LW_RECV_PORT_ANY: All downlinks

Callback function to run on downlink data.

Note

Callbacks are run on the system workqueue, and should therefore be as short as possible.

Param port:

Port message was sent on

Param data_pending:

Network server has more downlink packets pending

Param rssi:

Received signal strength in dBm

Param snr:

Signal to Noise ratio in dBm

Param len:

Length of data received, will be 0 for ACKs

Param data:

Data received, will be NULL for ACKs

Node for callback list.