Interfaces for LoRa transceivers. More...

Files
file	lora.h
	Main header file for LoRa driver API.

Data Structures
struct	lora_modem_config
	Structure containing the configuration of a LoRa modem. More...

Enumerations
enum	lora_signal_bandwidth { BW_7_KHZ = 7 , BW_10_KHZ = 10 , BW_15_KHZ = 15 , BW_20_KHZ = 20 , BW_31_KHZ = 31 , BW_41_KHZ = 41 , BW_62_KHZ = 62 , BW_125_KHZ = 125 , BW_200_KHZ = 200 , BW_250_KHZ = 250 , BW_400_KHZ = 400 , BW_500_KHZ = 500 , BW_800_KHZ = 800 , BW_1000_KHZ = 1000 , BW_1600_KHZ = 1600 }
	LoRa signal bandwidth. More...
enum	lora_datarate { SF_5 = 5 , SF_6 = 6 , SF_7 = 7 , SF_8 = 8 , SF_9 = 9 , SF_10 = 10 , SF_11 = 11 , SF_12 = 12 }
	LoRa data-rate. More...
enum	lora_coding_rate { CR_4_5 = 1 , CR_4_6 = 2 , CR_4_7 = 3 , CR_4_8 = 4 }
	LoRa coding rate. More...
enum	lora_cad_symbol_num { LORA_CAD_SYMB_1 = 1 , LORA_CAD_SYMB_2 = 2 , LORA_CAD_SYMB_4 = 4 , LORA_CAD_SYMB_8 = 8 , LORA_CAD_SYMB_16 = 16 }
	Number of symbols used for Channel Activity Detection. More...
enum	lora_cad_mode { LORA_CAD_MODE_NONE = 0 , LORA_CAD_MODE_RX , LORA_CAD_MODE_LBT }
	Channel Activity Detection mode. More...

Functions
static int	lora_config (const struct device dev, struct lora_modem_config config)
	Configure the LoRa modem.
static uint32_t	lora_airtime (const struct device *dev, uint32_t data_len)
	Query the airtime of a packet with a given length.
static int	lora_send (const struct device dev, uint8_t data, uint32_t data_len)
	Send data over LoRa.
static 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.
static 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.
static int	lora_recv_async (const struct device dev, lora_recv_cb cb, void user_data)
	Receive data asynchronously over LoRa.
static int	lora_cad (const struct device *dev, k_timeout_t timeout)
	Perform Channel Activity Detection.
static int	lora_cad_async (const struct device dev, lora_cad_cb cb, void user_data)
	Perform Channel Activity Detection asynchronously.
static int	lora_recv_duty_cycle (const struct device dev, k_timeout_t rx_period, k_timeout_t sleep_period, lora_recv_cb cb, void user_data)
	Start receive duty cycling (wake-on-radio).
static 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.

Detailed Description

Interfaces for LoRa transceivers.

Since: 2.2

Version: 0.8.0

Enumeration Type Documentation

◆ lora_cad_mode

enum lora_cad_mode

#include <zephyr/drivers/lora.h>

Channel Activity Detection mode.

Controls whether send/recv operations perform CAD before the actual operation.

Enumerator

LORA_CAD_MODE_NONE

No CAD (default).

LORA_CAD_MODE_RX

CAD before receive: lora_recv() performs CAD first and returns 0 immediately if no activity is detected.

For continuous low-power listening, prefer lora_recv_duty_cycle instead.

LORA_CAD_MODE_LBT

Listen Before Talk: lora_send() performs CAD before transmitting and returns -EBUSY if the channel is busy.

◆ lora_cad_symbol_num

enum lora_cad_symbol_num

#include <zephyr/drivers/lora.h>

Number of symbols used for Channel Activity Detection.

More symbols improve detection reliability at the cost of increased latency and power consumption.

Enumerator
LORA_CAD_SYMB_1	1 symbol
LORA_CAD_SYMB_2	2 symbols
LORA_CAD_SYMB_4	4 symbols
LORA_CAD_SYMB_8	8 symbols
LORA_CAD_SYMB_16	16 symbols

◆ lora_coding_rate

enum lora_coding_rate

#include <zephyr/drivers/lora.h>

LoRa coding rate.

This enumeration defines the LoRa coding rate, used for forward error correction (FEC).

The coding rate is expressed as 4/x, where a lower denominator (e.g., 4/5) means less redundancy, resulting in a higher data rate but reduced robustness. Higher redundancy (e.g., 4/8) improves error tolerance at the cost of data rate.

Enumerator
CR_4_5	Coding rate 4/5 (4 information bits, 1 error correction bit).
CR_4_6	Coding rate 4/6 (4 information bits, 2 error correction bits).
CR_4_7	Coding rate 4/7 (4 information bits, 3 error correction bits).
CR_4_8	Coding rate 4/8 (4 information bits, 4 error correction bits).

◆ lora_datarate

enum lora_datarate

#include <zephyr/drivers/lora.h>

LoRa data-rate.

This enumeration represents the data rate of a LoRa signal, expressed as a Spreading Factor (SF).

The Spreading Factor determines how many chirps are used to encode each symbol (2^SF chips per symbol). Higher values result in lower data rates but increased range and robustness.

Enumerator
SF_5	Spreading factor 5 (fastest, shortest range).
SF_6	Spreading factor 6.
SF_7	Spreading factor 7.
SF_8	Spreading factor 8.
SF_9	Spreading factor 9.
SF_10	Spreading factor 10.
SF_11	Spreading factor 11.
SF_12	Spreading factor 12 (slowest, longest range).

◆ lora_signal_bandwidth

enum lora_signal_bandwidth

#include <zephyr/drivers/lora.h>

LoRa signal bandwidth.

This enumeration defines the bandwidth of a LoRa signal.

The bandwidth determines how much spectrum is used to transmit data. Wider bandwidths enable higher data rates but typically reduce sensitivity and range.

Enumerator
BW_7_KHZ	7.81 kHz
BW_10_KHZ	10.42 kHz
BW_15_KHZ	15.63 kHz
BW_20_KHZ	20.83 kHz
BW_31_KHZ	31.25 kHz
BW_41_KHZ	41.67 kHz
BW_62_KHZ	62.5 kHz
BW_125_KHZ	125 kHz
BW_200_KHZ	203 kHz
BW_250_KHZ	250 kHz
BW_400_KHZ	406 kHz
BW_500_KHZ	500 kHz
BW_800_KHZ	812 kHz
BW_1000_KHZ	1000 kHz
BW_1600_KHZ	1625 kHz

Function Documentation

◆ lora_airtime()

uint32_t lora_airtime	(	const struct device *	dev,
		uint32_t	data_len )

inlinestatic

#include <zephyr/drivers/lora.h>

Query the airtime of a packet with a given length.

Note: Uses the current radio configuration from lora_config

Parameters

dev	LoRa device
data_len	Length of the data

Returns: Airtime of packet in milliseconds

◆ lora_cad()

int lora_cad	(	const struct device *	dev,
		k_timeout_t	timeout )

inlinestatic

#include <zephyr/drivers/lora.h>

Perform Channel Activity Detection.

Checks whether a LoRa signal is present on the channel using the modem configuration previously set by lora_config (including CAD parameters).

Note: This is a blocking call.

Parameters

dev	LoRa device
timeout	Maximum time to wait for CAD to complete

Returns: 0 if no activity detected (channel free); 1 if activity detected (channel busy); -EBUSY if the modem is in use; -ETIMEDOUT if the operation timed out; negative on other errors

◆ lora_cad_async()

int lora_cad_async	(	const struct device *	dev,
		lora_cad_cb	cb,
		void *	user_data )

inlinestatic

#include <zephyr/drivers/lora.h>

Perform Channel Activity Detection asynchronously.

Starts a single CAD operation using the CAD parameters from lora_config. When complete, invokes cb with the result.

Cancel a pending operation by calling this function again with cb = NULL.

Parameters

dev	LoRa device
cb	Callback invoked on completion. NULL to cancel.
user_data	User data passed to callback

Returns: 0 on success, negative on error

◆ lora_config()

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

inlinestatic

#include <zephyr/drivers/lora.h>

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

◆ lora_recv()

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

inlinestatic

#include <zephyr/drivers/lora.h>

Receive data over LoRa.

Note: This is a blocking call.; When cad.mode is LORA_CAD_MODE_RX, performs CAD before receiving. Returns 0 immediately if no activity is detected.

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

◆ lora_recv_async()

int lora_recv_async	(	const struct device *	dev,
		lora_recv_cb	cb,
		void *	user_data )

inlinestatic

#include <zephyr/drivers/lora.h>

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.
user_data	User data passed to callback

Returns: 0 when reception successfully setup, negative on error

◆ lora_recv_duty_cycle()

int lora_recv_duty_cycle	(	const struct device *	dev,
		k_timeout_t	rx_period,
		k_timeout_t	sleep_period,
		lora_recv_cb	cb,
		void *	user_data )

inlinestatic

#include <zephyr/drivers/lora.h>

Start receive duty cycling (wake-on-radio).

The radio autonomously alternates between sleep and listening for a LoRa preamble. When a valid packet is received, cb is invoked. The duty cycle continues until cancelled by calling this function with cb = NULL.

The transmitter must use a preamble longer than (sleep_period + rx_period) to guarantee detection.

Parameters

dev	LoRa device
rx_period	Listen window duration
sleep_period	Sleep duration between listen windows
cb	Callback on packet reception. NULL to cancel.
user_data	User data passed to callback

Returns: 0 on success, negative on error

◆ lora_send()

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

inlinestatic

#include <zephyr/drivers/lora.h>

Send data over LoRa.

Note: This blocks until transmission is complete.; When cad.mode is LORA_CAD_MODE_LBT, performs CAD before transmitting. Returns -EBUSY if the channel is busy.

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

◆ lora_send_async()

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

inlinestatic

#include <zephyr/drivers/lora.h>

Asynchronously send data over LoRa.

Note: This returns immediately after starting transmission, and locks the LoRa modem until the transmission completes.; When cad.mode is LORA_CAD_MODE_LBT, performs CAD before transmitting. The signal result carries -EBUSY if the channel is busy.

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

◆ lora_test_cw()

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

inlinestatic

#include <zephyr/drivers/lora.h>

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

Files

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ lora_cad_mode

◆ lora_cad_symbol_num

◆ lora_coding_rate

◆ lora_datarate

◆ lora_signal_bandwidth

Function Documentation

◆ lora_airtime()

◆ lora_cad()

◆ lora_cad_async()

◆ lora_config()

◆ lora_recv()

◆ lora_recv_async()

◆ lora_recv_duty_cycle()

◆ lora_send()

◆ lora_send_async()

◆ lora_test_cw()