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

Related code samples

LoRa receive

Receive packets in both synchronous and asynchronous mode using the LoRa radio.

LoRa send

Transmit a preconfigured payload every second using the LoRa radio.

group lora_api

Since

2.2

Version

0.1.0

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

Related code samples

LoRaWAN FUOTA

Perform a LoRaWAN firmware-upgrade over the air (FUOTA) operation.

LoRaWAN class A device

Join a LoRaWAN network and send a message periodically.

group lorawan_api

Since

2.5

Version

0.1.0

Defines

LW_RECV_PORT_ANY

Flag to indicate receiving on any port.

Typedefs

typedef uint8_t (*lorawan_battery_level_cb_t)(void)

Defines the battery level callback handler function signature.

Retval 0:

if the node is connected to an external power source

Retval 1..254:

battery level, where 1 is the minimum and 254 is the maximum value

Retval 255:

if the node was not able to measure the battery level

typedef void (*lorawan_dr_changed_cb_t)(enum lorawan_datarate dr)

Defines the datarate changed callback handler function signature.

Param dr:

Updated datarate.

Enums

enum lorawan_class

LoRaWAN class types.

Values:

enumerator LORAWAN_CLASS_A = 0x00

Class A device.

enumerator LORAWAN_CLASS_B = 0x01

Class B device.

enumerator LORAWAN_CLASS_C = 0x02

Class C device.

enum lorawan_act_type

LoRaWAN activation types.

Values:

enumerator LORAWAN_ACT_OTAA = 0

Over-the-Air Activation (OTAA)

enumerator LORAWAN_ACT_ABP

Activation by Personalization (ABP)

enum lorawan_channels_mask_size

LoRaWAN channels mask sizes.

Values:

enumerator LORAWAN_CHANNELS_MASK_SIZE_AS923 = 1

Region AS923 mask size.

enumerator LORAWAN_CHANNELS_MASK_SIZE_AU915 = 6

Region AU915 mask size.

enumerator LORAWAN_CHANNELS_MASK_SIZE_CN470 = 6

Region CN470 mask size.

enumerator LORAWAN_CHANNELS_MASK_SIZE_CN779 = 1

Region CN779 mask size.

enumerator LORAWAN_CHANNELS_MASK_SIZE_EU433 = 1

Region EU433 mask size.

enumerator LORAWAN_CHANNELS_MASK_SIZE_EU868 = 1

Region EU868 mask size.

enumerator LORAWAN_CHANNELS_MASK_SIZE_KR920 = 1

Region KR920 mask size.

enumerator LORAWAN_CHANNELS_MASK_SIZE_IN865 = 1

Region IN865 mask size.

enumerator LORAWAN_CHANNELS_MASK_SIZE_US915 = 6

Region US915 mask size.

enumerator LORAWAN_CHANNELS_MASK_SIZE_RU864 = 1

Region RU864 mask size.

enum lorawan_datarate

LoRaWAN datarate types.

Values:

enumerator LORAWAN_DR_0 = 0

DR0 data rate.

enumerator LORAWAN_DR_1

DR1 data rate.

enumerator LORAWAN_DR_2

DR2 data rate.

enumerator LORAWAN_DR_3

DR3 data rate.

enumerator LORAWAN_DR_4

DR4 data rate.

enumerator LORAWAN_DR_5

DR5 data rate.

enumerator LORAWAN_DR_6

DR6 data rate.

enumerator LORAWAN_DR_7

DR7 data rate.

enumerator LORAWAN_DR_8

DR8 data rate.

enumerator LORAWAN_DR_9

DR9 data rate.

enumerator LORAWAN_DR_10

DR10 data rate.

enumerator LORAWAN_DR_11

DR11 data rate.

enumerator LORAWAN_DR_12

DR12 data rate.

enumerator LORAWAN_DR_13

DR13 data rate.

enumerator LORAWAN_DR_14

DR14 data rate.

enumerator LORAWAN_DR_15

DR15 data rate.

enum lorawan_region

LoRaWAN region types.

Values:

enumerator LORAWAN_REGION_AS923

Asia 923 MHz frequency band.

enumerator LORAWAN_REGION_AU915

Australia 915 MHz frequency band.

enumerator LORAWAN_REGION_CN470

China 470 MHz frequency band.

enumerator LORAWAN_REGION_CN779

China 779 MHz frequency band.

enumerator LORAWAN_REGION_EU433

Europe 433 MHz frequency band.

enumerator LORAWAN_REGION_EU868

Europe 868 MHz frequency band.

enumerator LORAWAN_REGION_KR920

South Korea 920 MHz frequency band.

enumerator LORAWAN_REGION_IN865

India 865 MHz frequency band.

enumerator LORAWAN_REGION_US915

United States 915 MHz frequency band.

enumerator LORAWAN_REGION_RU864

Russia 864 MHz frequency band.

enum lorawan_message_type

LoRaWAN message types.

Values:

enumerator LORAWAN_MSG_UNCONFIRMED = 0

Unconfirmed message.

enumerator LORAWAN_MSG_CONFIRMED

Confirmed message.

Functions

void lorawan_register_battery_level_callback(lorawan_battery_level_cb_t cb)

Register a battery level callback function.

Provide the LoRaWAN stack with a function to be called whenever a battery level needs to be read.

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

Parameters:

  • cb – Pointer to the battery level function

Register a callback to be run on downlink packets.

Parameters:

  • cb – Pointer to structure containing callback parameters

void lorawan_register_dr_changed_callback(lorawan_dr_changed_cb_t cb)

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.

Parameters:

  • 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_channels_mask(uint16_t *channels_mask, size_t channels_mask_size)

Set the channels mask.

Change the default channels mask. When mask is not changed, all the channels can be used for data transmission. Some Network Servers don’t use all the channels, in this case, the channels mask must be provided.

Parameters:

  • channels_mask – Buffer with channels mask to be used.

  • channels_mask_size – Size of channels mask buffer.

Return values:

  • 0 – successful

  • -EINVAL – channels mask or channels mask size is wrong

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.

uint16_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

struct lorawan_join_otaa otaa

OTAA join parameters.

struct lorawan_join_abp abp

ABP join parameters.

union lorawan_join_config.[anonymous] [anonymous]

Join parameters.

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.