LoRa airtime and range#

use pamoja_lora::region::Region;

// EU863-870 numbers its data rates from the slowest. DR0 is SF12 at 125 kHz, the
// setting that reaches furthest and holds the channel longest.
let plan = Region::Eu868.plan();
let link = plan.link_settings(0).expect("DR0 is a LoRa data rate");
println!(
    "{} DR0 is SF{} at 125 kHz",
    plan.name,
    link.spreading_factor()
);

// The time on air for that setting, coding rate 4/5, an eight-symbol preamble, an
// explicit header and CRC on, carrying a ten-byte reading.
let airtime = link.airtime_us(10);
println!("airtime   {:.2} s for ten bytes", airtime as f64 / 1e6);

// 868.1 MHz falls in a sub-band capped at 1% of the time and 16 dBm, so every
// transmission buys ninety-nine times its own length in silence.
let channel = 868_100_000;
let permille = plan
    .duty_cycle_permille(channel)
    .expect("868.1 MHz is inside a limited sub-band");
let power = plan.max_eirp_dbm(channel);
println!("channel   {permille} per mille duty cycle, {power} dBm");

let off_time = link.min_off_time_us(10, permille);
println!(
    "silence   {:.1} s owed after each reading",
    off_time as f64 / 1e6
);

// The airtime plus that silence is what one reading really costs, which is the budget
// a deployment plans against.
let per_hour = link.messages_per_hour(10, permille);
println!("budget    {per_hour} readings an hour");

// A frequency in no sub-band the plan describes has no duty cycle to budget against.
// That is a limit published elsewhere, not permission to transmit.
let elsewhere = match plan.duty_cycle_permille(700_000_000) {
    Some(permille) => format!("limited to {permille} per mille"),
    None => "in no sub-band of this plan, so its limit is published elsewhere".to_string(),
};
println!("700 MHz   {elsewhere}");

use pamoja_lora::budget::{self, Decibels, Fcc15247, LinkBudget, GATEWAY_NOISE_FIGURE_DB};
use pamoja_lora::region::Region;

let eu868 = Region::Eu868.plan();
let dr0 = eu868.link_settings(0).expect("DR0 is a LoRa data rate");
let frequency = 868_100_000;

// A node with a 2.15 dBi whip on half a decibel of pigtail, heard by a gateway with a
// 6 dBi collinear antenna behind 1.5 dB of cable and a 3 dB noise figure.
let whip = LinkBudget {
    transmit_antenna_gain_dbi: Decibels::from_hundredths(215),
    transmit_cable_loss_db: Decibels::from_tenths(5),
    ..LinkBudget::default()
};

// The plan caps what leaves the antenna, so the antenna and cable decide how hard the
// radio may drive. A radio takes whole decibels, so the setting rounds down.
let ceiling = Decibels::from_db(eu868.max_eirp_dbm(frequency).into());
let most = whip.max_transmit_power_dbm(ceiling);
let node = LinkBudget {
    transmit_power_dbm: Decibels::from_db(most.floor_db()),
    receive_antenna_gain_dbi: Decibels::from_db(6),
    receive_cable_loss_db: Decibels::from_tenths(15),
    noise_figure_db: GATEWAY_NOISE_FIGURE_DB,
    ..whip
};
println!(
    "radio     {most} dBm allowed, set to {} dBm",
    node.transmit_power_dbm.round_db()
);
println!(
    "eirp      {} dBm under a {} dBm ceiling",
    node.eirp_dbm(),
    ceiling.round_db()
);

// The weakest signal the gateway still hears at SF12 and 125 kHz, and so the most path
// loss the link survives.
let sensitivity = node.sensitivity_dbm(dr0);
let survives = node.max_path_loss_db(dr0);
println!("gateway   hears down to {sensitivity} dBm, so {survives} dB of path loss");

// Free space at three distances, and what each path leaves to spare.
let mut margins = Vec::new();
for distance_m in [2_000, 5_000, 15_000] {
    let loss = budget::free_space_loss_db(distance_m, frequency);
    let margin = node.margin_db(dr0, loss);
    println!(
        "{:>2} km     {loss} dB lost, {margin} dB to spare",
        distance_m / 1_000
    );
    margins.push(margin);
}

// Free space assumes nothing is in the way. Terrain inside the first Fresnel zone adds
// diffraction loss, which starts once the clearance falls below 60% of its radius.
let radius = budget::fresnel_radius_mm(2_500, 2_500, frequency);
println!(
    "fresnel   {:.1} m at the middle of 5 km, keep {:.1} m clear",
    f64::from(radius) / 1000.0,
    f64::from(radius * 6 / 10) / 1000.0
);

// In the United States, 47 CFR 15.247 caps conducted power instead, and takes off every
// decibel an antenna has over 6 dBi.
let limit = Fcc15247::FrequencyHopping { channels: 64 }
    .max_conducted_dbm(Decibels::from_db(9))
    .expect("64 hopping channels have a limit");
println!("fcc       a 9 dBi Yagi on 64 hopping channels may carry {limit} dBm");

// Each step down in spreading factor halves the time on air and gives up 2.5 dB of
// reach: the trade between how often a node speaks and how far it is heard.
let duty_cycle = eu868
    .duty_cycle_permille(frequency)
    .expect("868.1 MHz is inside a limited sub-band");
let mut trade = Vec::new();
for data_rate in 0..=5 {
    let link = eu868.link_settings(data_rate).expect("DR0 to DR5 are LoRa");
    let sf = link.spreading_factor();
    let ms = link.airtime_us(10) as f64 / 1000.0;
    let readings = link.messages_per_hour(10, duty_cycle);
    let reach = node.max_path_loss_db(link);
    println!(
        "DR{data_rate} SF{sf:<2}  {ms:>5.1} ms, {readings:>3} an hour, {reach} dB of path loss"
    );
    trade.push((readings, reach));
}

import { LoraRegion, airtimeUs, messagesPerHour, minOffTimeUs, planFor } from '@pamoja/lora'

// EU863-870 numbers its data rates from the slowest. DR0 is SF12 at 125 kHz, the setting
// that reaches furthest and holds the channel longest.
const plan = planFor(LoraRegion.Eu868)
const link = plan.linkSettings(0)!
console.log(`${plan.name} DR0 is SF${link.spreadingFactor} at 125 kHz`)

// The time on air for that setting, coding rate 4/5, an eight-symbol preamble, an explicit
// header and CRC on, carrying a ten-byte reading.
const airtime = airtimeUs(link, 10)
console.log(`airtime   ${(airtime / 1e6).toFixed(2)} s for ten bytes`)

// 868.1 MHz falls in a sub-band capped at 1% of the time and 16 dBm, so every transmission
// buys ninety-nine times its own length in silence.
const channel = 868_100_000
const permille = plan.dutyCyclePermille(channel)!
console.log(`channel   ${permille} per mille duty cycle, ${plan.maxEirpDbm(channel)} dBm`)

const offTime = minOffTimeUs(link, 10, permille)!
console.log(`silence   ${(offTime / 1e6).toFixed(1)} s owed after each reading`)

// The airtime plus that silence is what one reading really costs, which is the budget a
// deployment plans against.
console.log(`budget    ${messagesPerHour(link, 10, permille)} readings an hour`)

// A frequency in no sub-band the plan describes has no duty cycle to budget against. That
// is a limit published elsewhere, not permission to transmit.
const outside = plan.dutyCyclePermille(700_000_000)
const elsewhere =
  outside === null
    ? 'in no sub-band of this plan, so its limit is published elsewhere'
    : `limited to ${outside} per mille`
console.log(`700 MHz   ${elsewhere}`)

import {
  GATEWAY_NOISE_FIGURE_DB,
  eirpDbm,
  fccMaxConductedDbm,
  freeSpaceLossDb,
  fresnelRadiusMm,
  linkBudget,
  marginDb,
  maxPathLossDb,
  maxTransmitPowerDbm,
  sensitivityDbm,
} from '@pamoja/lora'

const eu868 = planFor(LoraRegion.Eu868)
const dr0 = eu868.linkSettings(0)!
const frequency = 868_100_000

// A node with a 2.15 dBi whip on half a decibel of pigtail, heard by a gateway with a
// 6 dBi collinear antenna behind 1.5 dB of cable and a 3 dB noise figure.
const whip = { transmitAntennaGainDbi: 2.15, transmitCableLossDb: 0.5 }
const gateway = {
  receiveAntennaGainDbi: 6,
  receiveCableLossDb: 1.5,
  noiseFigureDb: GATEWAY_NOISE_FIGURE_DB,
}

// The plan caps what leaves the antenna, so the antenna and cable decide how hard the
// radio may drive. A radio takes whole decibels, so the setting rounds down.
const ceiling = eu868.maxEirpDbm(frequency)
const most = maxTransmitPowerDbm(linkBudget(whip), ceiling)
const node = linkBudget({ ...whip, ...gateway, transmitPowerDbm: Math.floor(most) })
console.log(`radio     ${most.toFixed(2)} dBm allowed, set to ${node.transmitPowerDbm} dBm`)
console.log(`eirp      ${eirpDbm(node).toFixed(2)} dBm under a ${ceiling} dBm ceiling`)

// The weakest signal the gateway still hears at SF12 and 125 kHz, and so the most path
// loss the link survives.
const sensitivity = sensitivityDbm(node, dr0)
const survives = maxPathLossDb(node, dr0)
console.log(
  `gateway   hears down to ${sensitivity.toFixed(2)} dBm, so ${survives.toFixed(2)} dB of path loss`,
)

// Free space at three distances, and what each path leaves to spare.
const margins = [2_000, 5_000, 15_000].map((distanceM) => {
  const loss = freeSpaceLossDb(distanceM, frequency)
  const margin = marginDb(node, dr0, loss)
  const km = String(distanceM / 1_000).padStart(2)
  console.log(`${km} km     ${loss.toFixed(2)} dB lost, ${margin.toFixed(2)} dB to spare`)
  return margin
})

// Free space assumes nothing is in the way. Terrain inside the first Fresnel zone adds
// diffraction loss, which starts once the clearance falls below 60% of its radius.
const radius = fresnelRadiusMm(2_500, 2_500, frequency)
const clear = Math.floor((radius * 6) / 10)
console.log(
  `fresnel   ${(radius / 1000).toFixed(1)} m at the middle of 5 km, keep ${(clear / 1000).toFixed(1)} m clear`,
)

// In the United States, 47 CFR 15.247 caps conducted power instead, and takes off every
// decibel an antenna has over 6 dBi.
const limit = fccMaxConductedDbm(9, 64)!
console.log(`fcc       a 9 dBi Yagi on 64 hopping channels may carry ${limit.toFixed(2)} dBm`)

// Each step down in spreading factor halves the time on air and gives up 2.5 dB of reach:
// the trade between how often a node speaks and how far it is heard.
const dutyCycle = eu868.dutyCyclePermille(frequency)!
const trade = [0, 1, 2, 3, 4, 5].map((dataRate) => {
  const rate = eu868.linkSettings(dataRate)!
  const sf = String(rate.spreadingFactor).padEnd(2)
  const ms = (airtimeUs(rate, 10) / 1000).toFixed(1).padStart(5)
  const readings = messagesPerHour(rate, 10, dutyCycle)
  const reach = maxPathLossDb(node, rate)
  const hour = String(readings).padStart(3)
  console.log(`DR${dataRate} SF${sf}  ${ms} ms, ${hour} an hour, ${reach.toFixed(2)} dB of path loss`)
  return { readings, reach }
})

from pamoja.lora import messages_per_hour, plan_for

# EU863-870 numbers its data rates from the slowest. DR0 is SF12 at 125 kHz, the setting
# that reaches furthest and holds the channel longest.
plan = plan_for("EU868")
link = plan.link_settings(0)
print(f"{plan.name} DR0 is SF{link.spreading_factor} at 125 kHz")

# The time on air for that setting, coding rate 4/5, an eight-symbol preamble, an explicit
# header and CRC on, carrying a ten-byte reading.
airtime = link.airtime_us(10)
print(f"airtime   {airtime / 1e6:.2f} s for ten bytes")

# 868.1 MHz falls in a sub-band capped at 1% of the time and 16 dBm, so every transmission
# buys ninety-nine times its own length in silence.
channel = 868_100_000
permille = plan.duty_cycle_permille(channel)
print(f"channel   {permille} per mille duty cycle, {plan.max_eirp_dbm(channel)} dBm")

off_time = link.min_off_time_us(10, permille)
print(f"silence   {off_time / 1e6:.1f} s owed after each reading")

# The airtime plus that silence is what one reading really costs, which is the budget a
# deployment plans against.
print(f"budget    {messages_per_hour(link, 10, permille)} readings an hour")

# A frequency in no sub-band the plan describes has no duty cycle to budget against. That
# is a limit published elsewhere, not permission to transmit.
outside = plan.duty_cycle_permille(700_000_000)
elsewhere = (
    "in no sub-band of this plan, so its limit is published elsewhere"
    if outside is None
    else f"limited to {outside} per mille"
)
print(f"700 MHz   {elsewhere}")

import math

from pamoja.lora import (
    GATEWAY_NOISE_FIGURE_DB,
    LinkBudget,
    fcc_max_conducted_dbm,
    free_space_loss_db,
    fresnel_radius_mm,
    plan_for,
)

eu868 = plan_for("EU868")
dr0 = eu868.link_settings(0)
frequency = 868_100_000

# A node with a 2.15 dBi whip on half a decibel of pigtail, heard by a gateway with a
# 6 dBi collinear antenna behind 1.5 dB of cable and a 3 dB noise figure.
whip = {"transmit_antenna_gain_dbi": 2.15, "transmit_cable_loss_db": 0.5}
gateway = {
    "receive_antenna_gain_dbi": 6,
    "receive_cable_loss_db": 1.5,
    "noise_figure_db": GATEWAY_NOISE_FIGURE_DB,
}

# The plan caps what leaves the antenna, so the antenna and cable decide how hard the
# radio may drive. A radio takes whole decibels, so the setting rounds down.
ceiling = eu868.max_eirp_dbm(frequency)
most = LinkBudget(**whip).max_transmit_power_dbm(ceiling)
node = LinkBudget(transmit_power_dbm=math.floor(most), **whip, **gateway)
print(f"radio     {most:.2f} dBm allowed, set to {node.transmit_power_dbm:.0f} dBm")
print(f"eirp      {node.eirp_dbm():.2f} dBm under a {ceiling} dBm ceiling")

# The weakest signal the gateway still hears at SF12 and 125 kHz, and so the most path
# loss the link survives.
sensitivity = node.sensitivity_dbm(dr0)
survives = node.max_path_loss_db(dr0)
print(f"gateway   hears down to {sensitivity:.2f} dBm, so {survives:.2f} dB of path loss")

# Free space at three distances, and what each path leaves to spare.
margins = []
for distance_m in (2_000, 5_000, 15_000):
    loss = free_space_loss_db(distance_m, frequency)
    margin = node.margin_db(dr0, loss)
    print(f"{distance_m // 1_000:>2} km     {loss:.2f} dB lost, {margin:.2f} dB to spare")
    margins.append(margin)

# Free space assumes nothing is in the way. Terrain inside the first Fresnel zone adds
# diffraction loss, which starts once the clearance falls below 60% of its radius.
radius = fresnel_radius_mm(2_500, 2_500, frequency)
clear = radius * 6 // 10
print(f"fresnel   {radius / 1000:.1f} m at the middle of 5 km, keep {clear / 1000:.1f} m clear")

# In the United States, 47 CFR 15.247 caps conducted power instead, and takes off every
# decibel an antenna has over 6 dBi.
limit = fcc_max_conducted_dbm(9, hopping_channels=64)
print(f"fcc       a 9 dBi Yagi on 64 hopping channels may carry {limit:.2f} dBm")

# Each step down in spreading factor halves the time on air and gives up 2.5 dB of reach:
# the trade between how often a node speaks and how far it is heard.
duty_cycle = eu868.duty_cycle_permille(frequency)
trade = []
for data_rate in range(6):
    rate = eu868.link_settings(data_rate)
    ms = rate.airtime_us(10) / 1000
    readings = rate.messages_per_hour(10, duty_cycle)
    reach = node.max_path_loss_db(rate)
    print(
        f"DR{data_rate} SF{rate.spreading_factor:<2}  {ms:>5.1f} ms, {readings:>3} an hour, "
        f"{reach:.2f} dB of path loss"
    )
    trade.append((readings, reach))

// EU863-870 numbers its data rates from the slowest. DR0 is SF12 at 125 kHz, the
// setting that reaches furthest and holds the channel longest.
using LoraChannelPlan plan = LoraChannelPlan.ForRegion(LoraRegion.Eu868);
LoraLink link = plan.LinkSettings(0)!;
Console.WriteLine($"{plan.Name} DR0 is SF{link.SpreadingFactor} at 125 kHz");

// The time on air for that setting, coding rate 4/5, an eight-symbol preamble, an
// explicit header and CRC on, carrying a ten-byte reading.
ulong airtime = link.AirtimeMicros(10);
Console.WriteLine(Invariant($"airtime   {airtime / 1e6:F2} s for ten bytes"));

// 868.1 MHz falls in a sub-band capped at 1% of the time and 16 dBm, so every
// transmission buys ninety-nine times its own length in silence.
const uint Channel = 868_100_000;
uint permille = plan.DutyCyclePermille(Channel)!.Value;
Console.WriteLine(
    $"channel   {permille} per mille duty cycle, {plan.MaxEirpDbm(Channel)} dBm");

ulong offTime = link.MinOffTimeMicros(10, permille)!.Value;
Console.WriteLine(Invariant($"silence   {offTime / 1e6:F1} s owed after each reading"));

// The airtime plus that silence is what one reading really costs, which is the
// budget a deployment plans against.
Console.WriteLine($"budget    {link.MessagesPerHour(10, permille)} readings an hour");

// A frequency in no sub-band the plan describes has no duty cycle to budget
// against. That is a limit published elsewhere, not permission to transmit.
uint? outside = plan.DutyCyclePermille(700_000_000);
string elsewhere = outside is null
    ? "in no sub-band of this plan, so its limit is published elsewhere"
    : $"limited to {outside} per mille";
Console.WriteLine($"700 MHz   {elsewhere}");

using LoraChannelPlan eu868 = LoraChannelPlan.ForRegion(LoraRegion.Eu868);
LoraLink dr0 = eu868.LinkSettings(0)!;
const uint Frequency = 868_100_000;

// A node with a 2.15 dBi whip on half a decibel of pigtail, heard by a gateway with
// a 6 dBi collinear antenna behind 1.5 dB of cable and a 3 dB noise figure.
var whip = new LoraLinkBudget { TransmitAntennaGainDbi = 2.15, TransmitCableLossDb = 0.5 };

// The plan caps what leaves the antenna, so the antenna and cable decide how hard
// the radio may drive. A radio takes whole decibels, so the setting rounds down.
sbyte ceiling = eu868.MaxEirpDbm(Frequency);
double most = whip.MaxTransmitPowerDbm(ceiling);
LoraLinkBudget node = whip with
{
    TransmitPowerDbm = Math.Floor(most),
    ReceiveAntennaGainDbi = 6,
    ReceiveCableLossDb = 1.5,
    NoiseFigureDb = LoraLinkBudget.GatewayNoiseFigureDb,
};
Console.WriteLine(Invariant($"radio     {most:F2} dBm allowed, set to {node.TransmitPowerDbm} dBm"));
Console.WriteLine(Invariant($"eirp      {node.EirpDbm:F2} dBm under a {ceiling} dBm ceiling"));

// The weakest signal the gateway still hears at SF12 and 125 kHz, and so the most
// path loss the link survives.
double sensitivity = node.SensitivityDbm(dr0);
double survives = node.MaxPathLossDb(dr0);
Console.WriteLine(Invariant(
    $"gateway   hears down to {sensitivity:F2} dBm, so {survives:F2} dB of path loss"));

// Free space at three distances, and what each path leaves to spare.
var margins = new List<double>();
foreach (uint distanceMeters in new uint[] { 2_000, 5_000, 15_000 })
{
    double loss = LoraLinkBudget.FreeSpaceLossDb(distanceMeters, Frequency);
    double margin = node.MarginDb(dr0, loss);
    Console.WriteLine(Invariant(
        $"{distanceMeters / 1_000,2} km     {loss:F2} dB lost, {margin:F2} dB to spare"));
    margins.Add(margin);
}

// Free space assumes nothing is in the way. Terrain inside the first Fresnel zone
// adds diffraction loss, which starts once the clearance falls below 60% of its
// radius.
uint radius = LoraLinkBudget.FresnelRadiusMillimeters(2_500, 2_500, Frequency);
uint clear = radius * 6 / 10;
Console.WriteLine(Invariant(
    $"fresnel   {radius / 1000.0:F1} m at the middle of 5 km, keep {clear / 1000.0:F1} m clear"));

// In the United States, 47 CFR 15.247 caps conducted power instead, and takes off
// every decibel an antenna has over 6 dBi.
double limit = LoraLinkBudget.FccMaxConductedDbm(9, hoppingChannels: 64)!.Value;
Console.WriteLine(Invariant($"fcc       a 9 dBi Yagi on 64 hopping channels may carry {limit:F2} dBm"));

// Each step down in spreading factor halves the time on air and gives up 2.5 dB of
// reach: the trade between how often a node speaks and how far it is heard.
uint dutyCycle = eu868.DutyCyclePermille(Frequency)!.Value;
var trade = new List<(ulong Readings, double Reach)>();
for (byte dataRate = 0; dataRate <= 5; dataRate++)
{
    LoraLink rate = eu868.LinkSettings(dataRate)!;
    double ms = rate.AirtimeMicros(10) / 1000.0;
    ulong readings = rate.MessagesPerHour(10, dutyCycle);
    double reach = node.MaxPathLossDb(rate);
    Console.WriteLine(Invariant(
        $"DR{dataRate} SF{rate.SpreadingFactor,-2}  {ms,5:F1} ms, {readings,3} an hour, {reach:F2} dB of path loss"));
    trade.Add((readings, reach));
}