LoRa radio types and driver classes. More...

Classes
struct	cad_info
	Result of a channel-activity-detection operation. More...

struct	lora_link
	Complete LoRa link configuration. More...

struct	lora_modulation
	LoRa modulation parameters. More...

struct	lora_packet_params
	LoRa packet framing parameters. More...

class	lora_transceiver
	Abstract base class for LoRa radio transceivers. More...

struct	packet_status
	Detailed status for the most recent packet. More...

struct	rx_duty_cycle
	Listen/sleep windows for duty-cycled receive. More...

struct	rx_info
	Information about a received packet. More...

class	sx126x
	Concrete LoRa radio driver for the Semtech SX126x family. More...

Enumerations
enum class	event_id : uint8_t { tx_done , rx_done , crc_error , cad_done , preamble_detected }
	Event IDs posted by a radio driver. More...

enum class	chip_mode : uint8_t { sleep , stdby , tx , rx , cad }
	Top-level radio operating mode. More...

enum class	spreading_factor : uint8_t { sf5 = 5 , sf6 = 6 , sf7 = 7 , sf8 = 8 , sf9 = 9 , sf10 = 10 , sf11 = 11 , sf12 = 12 }
	LoRa spreading factor. More...

enum class	bandwidth : uint8_t { bw_7_8 , bw_10_4 , bw_15_6 , bw_20_8 , bw_31_25 , bw_41_7 , bw_62_5 , bw_125 , bw_250 , bw_500 }
	LoRa channel bandwidth. More...

enum class	coding_rate : uint8_t { cr_4_5 = 5 , cr_4_6 = 6 , cr_4_7 = 7 , cr_4_8 = 8 }
	LoRa forward-error-correction coding rate. More...

enum class	lora_network : uint8_t { private_network , public_network }
	LoRa network selection. More...

enum class	header_type : uint8_t { variable , fixed }
	LoRa packet header mode. More...

enum class	ramp_time : uint8_t { us_10 , us_40 , us_200 , us_800 , us_3400 }
	Power-amplifier ramp-time bucket. More...

enum class	sx126x_irq_flag : uint16_t { tx_done = 1 << 0 , rx_done = 1 << 1 , preamble_detected = 1 << 2 , sync_word_valid = 1 << 3 , header_valid = 1 << 4 , header_err = 1 << 5 , crc_err = 1 << 6 , cad_done = 1 << 7 , cad_detected = 1 << 8 , timeout = 1 << 9 }
	SX126x IRQ-register bitfield. More...

Functions
constexpr std::chrono::microseconds	time_on_air (const lora_modulation &mod, const lora_packet_params &pkt, size_t payload_length) noexcept
	Computes the time-on-air of a LoRa packet.

constexpr std::optional< rx_duty_cycle >	rx_duty_cycle_for (const lora_modulation &mod, uint16_t sender_preamble, uint16_t min_symbols=8, std::chrono::microseconds min_sleep=default_min_rx_sleep) noexcept
	Computes duty-cycle receive windows that cannot miss a packet.

	IDFXX_EVENT_DEFINE_BASE (radio_events, event_id)
	Event base for all radio events.

Variables
constexpr std::chrono::microseconds	default_min_rx_sleep {1016}
	Default shortest sleep window worth duty-cycling for.

constexpr event< event_id >	tx_done {event_id::tx_done}
	Transmit-complete event.

constexpr event< event_id, rx_info >	rx_done {event_id::rx_done}
	Receive-complete event, carrying the packet's rx_info.

constexpr event< event_id >	crc_error {event_id::crc_error}
	CRC-error event.

constexpr event< event_id, cad_info >	cad_done {event_id::cad_done}
	Channel-scan-complete event, carrying cad_info.

constexpr event< event_id >	preamble_detected {event_id::preamble_detected}
	Preamble-detected event.

Detailed Description

LoRa radio types and driver classes.

Enumeration Type Documentation

◆ bandwidth

enum class idfxx::radio::bandwidth : uint8_t

strong

LoRa channel bandwidth.

Named by the bandwidth in kHz (with underscores for fractional values, so bw_7_8 is 7.8 kHz). Drivers translate these to chip-specific register values.

Enumerator
bw_7_8	7.8 kHz
bw_10_4	10.4 kHz
bw_15_6	15.6 kHz
bw_20_8	20.8 kHz
bw_31_25	31.25 kHz
bw_41_7	41.7 kHz
bw_62_5	62.5 kHz
bw_125	125 kHz
bw_250	250 kHz
bw_500	500 kHz

Definition at line 66 of file types.hpp.

◆ chip_mode

enum class idfxx::radio::chip_mode : uint8_t

strong

Top-level radio operating mode.

Drivers expose the high-level mode their chip is in. Chip-specific sub-modes (e.g. SX126x's stdby_rc vs stdby_xosc) are internal to each driver.

Enumerator
sleep	Sleep / low-power state.
stdby	Standby (radio off, registers active).
tx	Transmitting.
rx	Receiving.
cad	Channel-activity detection.

Definition at line 32 of file types.hpp.

◆ coding_rate

enum class idfxx::radio::coding_rate : uint8_t

strong

LoRa forward-error-correction coding rate.

The underlying value is the denominator of the 4/N rate (e.g. cr_4_8 = 8 = "4/8 coding rate").

Enumerator
cr_4_5	4/5
cr_4_6	4/6
cr_4_7	4/7
cr_4_8	4/8

Definition at line 86 of file types.hpp.

◆ event_id

enum class idfxx::radio::event_id : uint8_t

strong

Event IDs posted by a radio driver.

Enumerator
tx_done	Transmit complete.
rx_done	Receive complete (carries rx_info).
crc_error	Received packet had a CRC error.
cad_done	Channel scan finished (carries cad_info).
preamble_detected	Preamble detected during continuous RX.

Definition at line 24 of file events.hpp.

◆ header_type

enum class idfxx::radio::header_type : uint8_t

strong

LoRa packet header mode.

Enumerator
variable	Explicit (variable-length) header.
fixed	Implicit (fixed-length) header.

Definition at line 109 of file types.hpp.

◆ lora_network

enum class idfxx::radio::lora_network : uint8_t

strong

LoRa network selection.

Selects the sync word senders and receivers must share to hear each other. Drivers map each value to their chip's native sync-word encoding.

Enumerator
private_network	Private / ad-hoc point-to-point links.
public_network	Public LoRaWAN networks.

Definition at line 100 of file types.hpp.

◆ ramp_time

enum class idfxx::radio::ramp_time : uint8_t

strong

Power-amplifier ramp-time bucket.

Drivers map each value to the closest supported chip option.

Enumerator
us_10	~10 µs ramp-up.
us_40	~40 µs ramp-up.
us_200	~200 µs ramp-up.
us_800	~800 µs ramp-up.
us_3400	~3.4 ms ramp-up.

Definition at line 120 of file types.hpp.

◆ spreading_factor

enum class idfxx::radio::spreading_factor : uint8_t

strong

LoRa spreading factor.

Values are the LoRa spec spreading-factor numbers. Each driver maps these to its chip's register encoding.

Enumerator
sf5
sf6
sf7
sf8
sf9
sf10
sf11
sf12

Definition at line 47 of file types.hpp.

◆ sx126x_irq_flag

enum class idfxx::radio::sx126x_irq_flag : uint16_t

strong

SX126x IRQ-register bitfield.

The chip's IRQ register is 16 bits wide; each bit reflects an underlying chip event (Semtech DS_SX1261-2_V2.2 §13.3, table 13-29 "IRQ Registers"). The driver normally translates these into chip-agnostic events from <idfxx/radio/events> — only reach for this surface when you need direct register-level access. Accessible as sx126x::irq_flag after the class definition.

Enumerator
tx_done
rx_done
preamble_detected
sync_word_valid
header_valid
header_err
crc_err
cad_done
cad_detected
timeout

Definition at line 46 of file sx126x.hpp.

Function Documentation

◆ IDFXX_EVENT_DEFINE_BASE()

idfxx::radio::IDFXX_EVENT_DEFINE_BASE	(	radio_events	,
		event_id
	)

Event base for all radio events.

Subscribe to this base on a concrete driver's event loop:

loop.listener_add(idfxx::radio::rx_done,
    [](const idfxx::radio::rx_info& info) {
        // ...
    });

◆ rx_duty_cycle_for()

constexpr std::optional< rx_duty_cycle > idfxx::radio::rx_duty_cycle_for	(	const lora_modulation &	mod,
		uint16_t	sender_preamble,
		uint16_t	min_symbols = `8`,
		std::chrono::microseconds	min_sleep = `default_min_rx_sleep`
	)

constexprnoexcept

Computes duty-cycle receive windows that cannot miss a packet.

Chooses listen/sleep windows such that, no matter how a sender's transmission aligns with the cycle, the radio is awake for at least min_symbols of the preamble and can detect the packet:

sleep = Tsym · (sender_preamble − 2·min_symbols)
rx    = max( (Tsym·(sender_preamble + 1) − (sleep − 1 ms)) / 2,
             Tsym·(min_symbols + 1) )

where Tsym = 2^SF / BW is the symbol duration. This is the algorithm RadioLib's startReceiveDutyCycleAuto uses. The sleep window is rounded down and the listen window up, so rounding only ever increases the time spent listening.

Returns std::nullopt when duty-cycling cannot work for the given parameters — when the preamble is too short to sleep inside (2·min_symbols ≥ sender_preamble) or the resulting sleep window is shorter than min_sleep. The caller should then use continuous receive; passing the result straight to lora_transceiver::start_listening does exactly that.

Parameters

mod	Modulation parameters (spreading factor and bandwidth are used).
sender_preamble	Preamble length, in symbols, that senders on this link use (`lora_packet_params::preamble_length`).
min_symbols	Minimum preamble symbols the radio must observe to detect a packet; must be at least 1. Increase for margin at the cost of longer listen windows.
min_sleep	Shortest sleep window worth duty-cycling for. Below this the radio spends the window transitioning in and out of sleep instead of saving power; add the oscillator start-up time (e.g. the TCXO delay on SX126x) when the chip uses one.

Returns: The listen/sleep windows, or std::nullopt if duty-cycling cannot reliably catch packets and continuous receive should be used.

using namespace std::chrono_literals;
constexpr idfxx::radio::lora_modulation mod{.sf = idfxx::radio::spreading_factor::sf9};
constexpr idfxx::radio::lora_packet_params pkt{.preamble_length = 100};
 
// Falls back to continuous receive automatically when nullopt.
radio.start_listening(idfxx::radio::rx_duty_cycle_for(mod, pkt.preamble_length));

Definition at line 80 of file duty_cycle.hpp.

Referenced by idfxx::radio::lora_transceiver::rx_duty_cycle_for().

◆ time_on_air()

constexpr std::chrono::microseconds idfxx::radio::time_on_air	(	const lora_modulation &	mod,
		const lora_packet_params &	pkt,
		size_t	payload_length
	)

constexprnoexcept

Computes the time-on-air of a LoRa packet.

Returns how long the radio occupies the channel transmitting (or receiving) a packet of payload_length bytes under the given modulation and framing, using the classic Semtech air-time equation:

Ts        = 2^SF / BW
nPayload  = 8 + max(ceil((8·PL − 4·SF + 28 + 16·CRC − 20·IH)
                         / (4·(SF − 2·DE))) · (CR + 4), 0)
T         = (preamble_length + 4.25)·Ts + nPayload·Ts

where DE is mod.low_data_rate_optimize, IH is set for a fixed (implicit) header, CRC follows pkt.crc_on, and CR is the coding-rate index. The result is rounded to the nearest microsecond. The computation is exact integer arithmetic, so it is usable in static_assert.

Parameters

mod	Modulation parameters (spreading factor, bandwidth, coding rate, low-data-rate optimization).
pkt	Packet framing (preamble length, header type, CRC). `pkt.payload_length` is ignored — `payload_length` is the byte count used.
payload_length	Number of payload bytes the packet carries.

Returns: The packet's time-on-air.

Note: The equation is exact for spreading factors SF7–SF12. SF5 and SF6 reuse the SF7–SF12 coefficients and so are approximate. TODO: add the SF5/SF6 special-case coefficients for exact short-range air-time.

using namespace std::chrono_literals;
idfxx::radio::lora_modulation mod{.sf = idfxx::radio::spreading_factor::sf9};
idfxx::radio::lora_packet_params pkt{};
auto airtime = idfxx::radio::time_on_air(mod, pkt, payload.size());
radio.transmit(payload, airtime + 200ms);

Definition at line 135 of file airtime.hpp.

Referenced by idfxx::radio::lora_transceiver::time_on_air().

Variable Documentation

◆ cad_done

constexpr event<event_id, cad_info> idfxx::radio::cad_done {event_id::cad_done}

inlineconstexpr

Channel-scan-complete event, carrying cad_info.

Definition at line 64 of file events.hpp.

◆ crc_error

constexpr event<event_id> idfxx::radio::crc_error {event_id::crc_error}

inlineconstexpr

CRC-error event.

Definition at line 61 of file events.hpp.

◆ default_min_rx_sleep

constexpr std::chrono::microseconds idfxx::radio::default_min_rx_sleep {1016}

inlineconstexpr

Default shortest sleep window worth duty-cycling for.

Below this the radio spends the window transitioning in and out of sleep instead of saving power; chips that restart an oscillator on each wake add that start-up time (e.g. the TCXO delay on SX126x).

Definition at line 32 of file duty_cycle.hpp.

Referenced by idfxx::radio::lora_transceiver::do_rx_duty_cycle_min_sleep().

◆ preamble_detected

constexpr event<event_id> idfxx::radio::preamble_detected {event_id::preamble_detected}

inlineconstexpr

Preamble-detected event.

Definition at line 67 of file events.hpp.

◆ rx_done

constexpr event<event_id, rx_info> idfxx::radio::rx_done {event_id::rx_done}

inlineconstexpr

Receive-complete event, carrying the packet's rx_info.

The payload describes the packet that raised the event, which suits metadata-only listeners (e.g. signal monitoring). To read the packet's bytes, call lora_transceiver::read_received and pair the bytes with the rx_info it returns — the receive cache holds only the most recent packet, which may already be newer than the one that raised this event.

Definition at line 58 of file events.hpp.

◆ tx_done

constexpr event<event_id> idfxx::radio::tx_done {event_id::tx_done}

inlineconstexpr

Transmit-complete event.

Definition at line 47 of file events.hpp.

Classes

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ bandwidth

◆ chip_mode

◆ coding_rate

◆ event_id

◆ header_type

◆ lora_network

◆ ramp_time

◆ spreading_factor

◆ sx126x_irq_flag

Function Documentation

◆ IDFXX_EVENT_DEFINE_BASE()

◆ rx_duty_cycle_for()

◆ time_on_air()

Variable Documentation

◆ cad_done

◆ crc_error

◆ default_min_rx_sleep

◆ preamble_detected

◆ rx_done

◆ tx_done