pamoja_lora/

link.rs

//! LoRa link settings and the time-on-air they imply.

// The symbol time above which low-data-rate optimization is required, in
// microseconds. Above 16 ms per symbol (SF11 and SF12 at 125 kHz) the LoRa modem
// turns it on, which the airtime formula accounts for.
const LOW_DATA_RATE_THRESHOLD_US: u64 = 16_000;

/// 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`](LinkSettings::airtime_us) of a payload, and
/// the [`off time`](LinkSettings::min_off_time_us) 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);
/// ```
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct LinkSettings {
    spreading_factor: u8,
    bandwidth_hz: u32,
    cr_denominator: u8,
    preamble_symbols: u16,
    explicit_header: bool,
    crc: bool,
}

impl LinkSettings {
    /// 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 as `125_000`; `0` counts as one
    ///   hertz, as it does across [`budget`](crate::budget).
    ///
    /// # Returns
    ///
    /// The link settings.
    pub fn new(spreading_factor: u8, bandwidth_hz: u32) -> Self {
        Self {
            spreading_factor: spreading_factor.clamp(5, 12),
            bandwidth_hz: bandwidth_hz.max(1),
            cr_denominator: 5,
            preamble_symbols: 8,
            explicit_header: true,
            crc: true,
        }
    }

    /// Sets the coding rate by its denominator, from 4/5 to 4/8.
    ///
    /// # Arguments
    ///
    /// * `denominator` - the coding-rate denominator, clamped to 5 to 8 for 4/5 to 4/8.
    ///
    /// # Returns
    ///
    /// The updated settings, for chaining.
    pub fn with_coding_rate(mut self, denominator: u8) -> Self {
        self.cr_denominator = denominator.clamp(5, 8);
        self
    }

    /// Sets the number of preamble symbols.
    ///
    /// # Arguments
    ///
    /// * `symbols` - the preamble length in symbols; the LoRa default is 8.
    ///
    /// # Returns
    ///
    /// The updated settings, for chaining.
    pub fn with_preamble(mut self, symbols: u16) -> Self {
        self.preamble_symbols = symbols;
        self
    }

    /// Uses an implicit header, which omits the header symbols from each frame.
    ///
    /// # Returns
    ///
    /// The updated settings, for chaining.
    pub fn implicit_header(mut self) -> Self {
        self.explicit_header = false;
        self
    }

    /// Turns the frame CRC off.
    ///
    /// # Returns
    ///
    /// The updated settings, for chaining.
    pub fn without_crc(mut self) -> Self {
        self.crc = false;
        self
    }

    /// Returns the spreading factor.
    ///
    /// # Returns
    ///
    /// The spreading factor, from 5 to 12.
    pub fn spreading_factor(&self) -> u8 {
        self.spreading_factor
    }

    /// Returns the channel bandwidth in hertz.
    ///
    /// # Returns
    ///
    /// The bandwidth in hertz.
    pub fn bandwidth_hz(&self) -> u32 {
        self.bandwidth_hz
    }

    /// Returns the coding-rate denominator.
    ///
    /// # Returns
    ///
    /// The denominator, from 5 to 8, for coding rates 4/5 to 4/8.
    pub fn coding_rate_denominator(&self) -> u8 {
        self.cr_denominator
    }

    /// Returns the preamble length.
    ///
    /// # Returns
    ///
    /// The number of preamble symbols.
    pub fn preamble_symbols(&self) -> u16 {
        self.preamble_symbols
    }

    /// Reports whether each frame carries an explicit header.
    ///
    /// # Returns
    ///
    /// `true` for an explicit header, `false` when the header is implicit.
    pub fn explicit_header(&self) -> bool {
        self.explicit_header
    }

    /// Reports whether each frame carries a CRC.
    ///
    /// # Returns
    ///
    /// `true` when the frame CRC is on.
    pub fn crc(&self) -> bool {
        self.crc
    }

    /// 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.
    pub fn low_data_rate_optimization(&self) -> bool {
        self.symbol_time_us() > LOW_DATA_RATE_THRESHOLD_US
    }

    /// Returns the duration of one symbol in microseconds.
    ///
    /// # Returns
    ///
    /// The symbol time, `2^spreading_factor / bandwidth`, in microseconds.
    pub fn symbol_time_us(&self) -> u64 {
        (1u64 << self.spreading_factor) * 1_000_000 / u64::from(self.bandwidth_hz)
    }

    // The number of symbols in the payload portion of the frame.
    fn payload_symbols(&self, payload_len: usize) -> u128 {
        let sf = i128::from(self.spreading_factor);
        let low_data_rate = self.low_data_rate_optimization();
        let de = i128::from(low_data_rate);
        let ih = i128::from(!self.explicit_header);
        let crc = i128::from(self.crc);

        let numerator = 8 * payload_len as i128 - 4 * sf + 28 + 16 * crc - 20 * ih;
        let denominator = 4 * (sf - 2 * de); // always positive: sf >= 5, de <= 1
        let term = if numerator > 0 {
            let groups = (numerator as u128).div_ceil(denominator as u128);
            groups * u128::from(self.cr_denominator)
        } else {
            0
        };
        8 + term
    }

    /// 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.
    pub fn airtime_us(&self, payload_len: usize) -> u64 {
        let payload_symbols = self.payload_symbols(payload_len);
        // Work in quarter-symbols so the preamble's 4.25-symbol tail stays exact.
        let quarter_symbols = (4 * u128::from(self.preamble_symbols) + 17) + 4 * payload_symbols;
        let symbol_units = quarter_symbols << self.spreading_factor;
        let micros = symbol_units * 1_000_000 / (4 * u128::from(self.bandwidth_hz));
        u64::try_from(micros).unwrap_or(u64::MAX)
    }

    /// 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, so `10`
    ///   is 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.
    pub fn min_off_time_us(&self, payload_len: usize, duty_cycle_permille: u32) -> u64 {
        if duty_cycle_permille == 0 {
            return u64::MAX;
        }
        if duty_cycle_permille >= 1000 {
            return 0;
        }
        let airtime = u128::from(self.airtime_us(payload_len));
        let permille = u128::from(duty_cycle_permille);
        u64::try_from(airtime * (1000 - permille) / permille).unwrap_or(u64::MAX)
    }

    /// 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, so `10` is
    ///   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);
    /// ```
    pub fn messages_per_hour(&self, payload_len: usize, duty_cycle_permille: u32) -> u64 {
        if duty_cycle_permille == 0 {
            return 0;
        }
        let airtime = u128::from(self.airtime_us(payload_len));
        let silence = u128::from(self.min_off_time_us(payload_len, duty_cycle_permille));
        let each = (airtime + silence).max(1);
        u64::try_from(3_600_000_000 / each).unwrap_or(u64::MAX)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn the_settings_report_what_a_radio_is_configured_with() {
        let link = LinkSettings::new(9, 250_000)
            .with_coding_rate(8)
            .with_preamble(12)
            .implicit_header()
            .without_crc();
        assert_eq!(link.coding_rate_denominator(), 8);
        assert_eq!(link.preamble_symbols(), 12);
        assert!(!link.explicit_header());
        assert!(!link.crc());
        assert!(!link.low_data_rate_optimization());
        assert!(LinkSettings::new(11, 125_000).low_data_rate_optimization());
        assert!(LinkSettings::new(12, 250_000).low_data_rate_optimization());
        assert!(!LinkSettings::new(10, 125_000).low_data_rate_optimization());
    }

    #[test]
    fn airtime_matches_the_reference_sf12() {
        // The widely published reference value for SF12, BW125, CR4/5, 8-symbol
        // preamble, explicit header, CRC on, 10-byte payload.
        let link = LinkSettings::new(12, 125_000);
        assert_eq!(link.airtime_us(10), 991_232);
    }

    #[test]
    fn airtime_matches_the_reference_sf7() {
        let link = LinkSettings::new(7, 125_000);
        assert_eq!(link.airtime_us(10), 41_216);
    }

    #[test]
    fn a_higher_spreading_factor_is_slower() {
        let slow = LinkSettings::new(12, 125_000);
        let fast = LinkSettings::new(7, 125_000);
        assert!(slow.airtime_us(20) > fast.airtime_us(20) * 10);
    }

    #[test]
    fn symbol_time_follows_spreading_factor_and_bandwidth() {
        assert_eq!(LinkSettings::new(12, 125_000).symbol_time_us(), 32_768);
        assert_eq!(LinkSettings::new(7, 125_000).symbol_time_us(), 1_024);
        assert_eq!(LinkSettings::new(7, 250_000).symbol_time_us(), 512);
    }

    #[test]
    fn the_spreading_factor_is_clamped_to_the_lora_range() {
        assert_eq!(LinkSettings::new(3, 125_000).spreading_factor(), 5);
        assert_eq!(LinkSettings::new(20, 125_000).spreading_factor(), 12);
    }

    #[test]
    fn the_fastest_spreading_factors_survive_unclamped() {
        // RP002-1.0.5 added SF6 and SF5 data rates to several regions, so
        // clamping them up to SF7 would report the wrong airtime for them.
        assert_eq!(LinkSettings::new(6, 125_000).spreading_factor(), 6);
        assert_eq!(LinkSettings::new(5, 125_000).spreading_factor(), 5);
        assert!(
            LinkSettings::new(5, 125_000).airtime_us(10)
                < LinkSettings::new(7, 125_000).airtime_us(10),
            "a lower spreading factor is faster"
        );
    }

    #[test]
    fn a_one_percent_duty_cycle_forces_ninety_nine_times_the_airtime() {
        let link = LinkSettings::new(7, 125_000);
        let airtime = link.airtime_us(10);
        assert_eq!(link.min_off_time_us(10, 10), airtime * 99);
    }

    #[test]
    fn a_zero_duty_cycle_never_allows_another_send() {
        let link = LinkSettings::new(7, 125_000);
        assert_eq!(link.min_off_time_us(10, 0), u64::MAX);
    }

    #[test]
    fn implicit_header_and_no_crc_shorten_the_frame() {
        let full = LinkSettings::new(9, 125_000);
        let lean = LinkSettings::new(9, 125_000)
            .implicit_header()
            .without_crc();
        assert!(lean.airtime_us(20) < full.airtime_us(20));
    }

    #[test]
    fn a_zero_byte_payload_still_costs_the_preamble_and_header() {
        // Even with no payload, the preamble and header occupy the air.
        let link = LinkSettings::new(7, 125_000);
        assert!(link.airtime_us(0) > 0);
        assert!(link.airtime_us(0) < link.airtime_us(10));
    }

    #[test]
    fn airtime_grows_with_the_payload() {
        let link = LinkSettings::new(10, 125_000);
        assert!(link.airtime_us(1) <= link.airtime_us(10));
        assert!(link.airtime_us(10) < link.airtime_us(64));
    }

    #[test]
    fn a_wider_bandwidth_is_faster() {
        // Doubling the bandwidth roughly halves the time on air.
        let narrow = LinkSettings::new(9, 125_000).airtime_us(20);
        let wide = LinkSettings::new(9, 250_000).airtime_us(20);
        assert!(wide < narrow);
    }

    #[test]
    fn a_zero_bandwidth_counts_as_one_hertz() {
        let link = LinkSettings::new(12, 0);
        assert_eq!(link.bandwidth_hz(), 1);
        assert_eq!(link.symbol_time_us(), 4_096_000_000);
        assert_eq!(
            link.airtime_us(10),
            LinkSettings::new(12, 125_000).airtime_us(10) * 125_000
        );
    }

    #[test]
    fn a_payload_past_one_frame_keeps_counting_up() {
        let link = LinkSettings::new(12, 125_000);
        let most = link.airtime_us(255);
        assert!(link.airtime_us(1 << 29) > most);
        assert!(link.airtime_us(u32::MAX as usize) > link.airtime_us(1 << 29));
        assert_eq!(link.airtime_us(usize::MAX), u64::MAX);
    }

    #[test]
    fn a_limit_of_the_whole_time_owes_no_silence() {
        let link = LinkSettings::new(12, 125_000);
        assert_eq!(link.min_off_time_us(10, 1000), 0);
        assert_eq!(link.min_off_time_us(10, 1001), 0);
        assert_eq!(link.min_off_time_us(10, u32::MAX), 0);
        assert_eq!(link.min_off_time_us(10, 0), u64::MAX);
    }

    #[test]
    fn the_hourly_budget_is_the_hour_over_what_each_transmission_costs() {
        let link = LinkSettings::new(12, 125_000);
        let each = link.airtime_us(10) + link.min_off_time_us(10, 10);
        assert_eq!(link.messages_per_hour(10, 10), 3_600_000_000 / each);
        assert_eq!(
            link.messages_per_hour(10, 1000),
            3_600_000_000 / link.airtime_us(10),
            "the whole of the time owes no silence"
        );
        assert_eq!(
            link.messages_per_hour(10, 0),
            0,
            "a zero limit forbids sending"
        );
        assert_eq!(link.messages_per_hour(usize::MAX, 10), 0);
        let instant = LinkSettings::new(5, u32::MAX);
        assert_eq!(instant.airtime_us(0), 0);
        assert_eq!(instant.messages_per_hour(0, 1000), 3_600_000_000);
    }
}