pub struct LinkSettings { /* private fields */ }Expand description
The radio settings of a LoRa link, enough to compute its time-on-air.
A LoRa transmission’s duration is fixed by the spreading factor, the bandwidth,
the coding rate, and the frame options, not by the data itself beyond its length.
This struct gathers those settings and computes the two numbers a long-range
deployment lives by: the airtime of a payload, and
the off time a duty-cycle limit then forces
before the next transmission.
A higher spreading factor reaches much further but spends far longer on air, so the same payload that takes tens of milliseconds at SF7 can take most of a second at SF12, with a correspondingly longer mandatory silence. The arithmetic is exact and integer-only, so it runs on the smallest node.
§Examples
use pamoja_lora::LinkSettings;
// The default European long-range setup: SF12, 125 kHz, coding rate 4/5.
let link = LinkSettings::new(12, 125_000);
// A 10-byte payload takes just under a second on air at SF12.
assert_eq!(link.airtime_us(10), 991_232);Implementations§
Source§impl LinkSettings
impl LinkSettings
Sourcepub fn new(spreading_factor: u8, bandwidth_hz: u32) -> Self
pub fn new(spreading_factor: u8, bandwidth_hz: u32) -> Self
Creates link settings from a spreading factor and bandwidth, with LoRa defaults.
The defaults are coding rate 4/5, an 8-symbol preamble, an explicit header, and CRC on, matching a typical uplink.
§Arguments
spreading_factor- the spreading factor; clamped to the LoRa range 5 to 12. SF5 and SF6 carry the data rates RP002-1.0.5 added to several regions.bandwidth_hz- the channel bandwidth in hertz, such as125_000;0counts as one hertz, as it does acrossbudget.
§Returns
The link settings.
Sourcepub fn with_coding_rate(self, denominator: u8) -> Self
pub fn with_coding_rate(self, denominator: u8) -> Self
Sourcepub fn with_preamble(self, symbols: u16) -> Self
pub fn with_preamble(self, symbols: u16) -> Self
Sourcepub fn implicit_header(self) -> Self
pub fn implicit_header(self) -> Self
Uses an implicit header, which omits the header symbols from each frame.
§Returns
The updated settings, for chaining.
Sourcepub fn without_crc(self) -> Self
pub fn without_crc(self) -> Self
Sourcepub fn spreading_factor(&self) -> u8
pub fn spreading_factor(&self) -> u8
Sourcepub fn bandwidth_hz(&self) -> u32
pub fn bandwidth_hz(&self) -> u32
Sourcepub fn coding_rate_denominator(&self) -> u8
pub fn coding_rate_denominator(&self) -> u8
Returns the coding-rate denominator.
§Returns
The denominator, from 5 to 8, for coding rates 4/5 to 4/8.
Sourcepub fn preamble_symbols(&self) -> u16
pub fn preamble_symbols(&self) -> u16
Sourcepub fn explicit_header(&self) -> bool
pub fn explicit_header(&self) -> bool
Reports whether each frame carries an explicit header.
§Returns
true for an explicit header, false when the header is implicit.
Sourcepub fn low_data_rate_optimization(&self) -> bool
pub fn low_data_rate_optimization(&self) -> bool
Reports whether the link uses low data rate optimization.
It is on when a symbol lasts longer than 16 ms, which is SF11 and SF12 at 125 kHz and SF12 at 250 kHz. The airtime assumes it, so a radio configured from these settings must enable it too.
§Returns
true when the symbol time exceeds 16 ms.
Sourcepub fn symbol_time_us(&self) -> u64
pub fn symbol_time_us(&self) -> u64
Returns the duration of one symbol in microseconds.
§Returns
The symbol time, 2^spreading_factor / bandwidth, in microseconds.
Sourcepub fn airtime_us(&self, payload_len: usize) -> u64
pub fn airtime_us(&self, payload_len: usize) -> u64
Returns the time on air of a payload in microseconds.
This is the channel occupancy the transmission costs: how long the radio holds the air, which sets both the duty-cycle budget and a large part of the energy the transmission spends.
§Arguments
payload_len- the payload length in bytes. One LoRa frame carries at most 255; the count runs on past that for a caller who asks.
§Returns
The time on air in microseconds, held at u64::MAX rather than overflowing.
Sourcepub fn min_off_time_us(
&self,
payload_len: usize,
duty_cycle_permille: u32,
) -> u64
pub fn min_off_time_us( &self, payload_len: usize, duty_cycle_permille: u32, ) -> u64
Returns the minimum silence after a transmission to honor a duty-cycle limit.
A duty-cycle limit caps the fraction of time a node may transmit, so after a transmission of a given airtime the node must stay quiet for long enough that the airtime is no more than that fraction of the whole cycle.
§Arguments
payload_len- the payload length in bytes.duty_cycle_permille- the duty-cycle limit in parts per thousand, so10is 1%.
§Returns
The required off time in microseconds: u64::MAX if the limit is zero, and 0
for a limit of 1000 or more, the whole of the time.
Sourcepub fn messages_per_hour(
&self,
payload_len: usize,
duty_cycle_permille: u32,
) -> u64
pub fn messages_per_hour( &self, payload_len: usize, duty_cycle_permille: u32, ) -> u64
Returns how many transmissions of a payload fit in an hour under a duty-cycle limit.
A transmission really costs its airtime plus the silence the limit forces after it, so this is the message budget a deployment plans against.
§Arguments
payload_len- the payload length in bytes.duty_cycle_permille- the duty-cycle limit in parts per thousand, so10is 1%.
§Returns
The number of whole transmissions an hour, or 0 when the limit is zero and so
forbids transmitting.
§Examples
use pamoja_lora::LinkSettings;
// Ten bytes at SF12 hold the air for just under a second, and 1% of the time
// leaves room for thirty-six of them an hour.
let link = LinkSettings::new(12, 125_000);
assert_eq!(link.messages_per_hour(10, 10), 36);
assert_eq!(link.messages_per_hour(10, 0), 0);Trait Implementations§
Source§impl Clone for LinkSettings
impl Clone for LinkSettings
Source§fn clone(&self) -> LinkSettings
fn clone(&self) -> LinkSettings
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read more