airtime.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Chris Leishman
 
#pragma once
 
#include <idfxx/radio/types.hpp>
 
#include <chrono>
#include <cstddef>
#include <cstdint>
#include <utility>
 
namespace idfxx::radio {
 
namespace airtime_detail {
 
[[nodiscard]] constexpr uint32_t bandwidth_hz(bandwidth bw) noexcept {
    switch (bw) {
    case bandwidth::bw_7_8:
        return 7'800;
    case bandwidth::bw_10_4:
        return 10'400;
    case bandwidth::bw_15_6:
        return 15'625;
    case bandwidth::bw_20_8:
        return 20'800;
    case bandwidth::bw_31_25:
        return 31'250;
    case bandwidth::bw_41_7:
        return 41'700;
    case bandwidth::bw_62_5:
        return 62'500;
    case bandwidth::bw_125:
        return 125'000;
    case bandwidth::bw_250:
        return 250'000;
    case bandwidth::bw_500:
        return 500'000;
    }
    return 125'000; // safe default = 125 kHz
}
 
[[nodiscard]] constexpr uint32_t payload_symbols(
    spreading_factor sf,
    coding_rate cr,
    header_type header,
    bool crc_on,
    bool low_data_rate_optimize,
    size_t payload_length
) noexcept {
    const int32_t sf_n = static_cast<int32_t>(std::to_underlying(sf));
    const int32_t cr_n = static_cast<int32_t>(std::to_underlying(cr)) - 4; // 1..4
    const int32_t crc = crc_on ? 1 : 0;
    const int32_t ih = (header == header_type::fixed) ? 1 : 0; // implicit header
    const int32_t de = low_data_rate_optimize ? 1 : 0;
    const int32_t pl = static_cast<int32_t>(payload_length);
 
    // numerator = 8·PL − 4·SF + 28 + 16·CRC − 20·IH. Clamping it to zero here is
    // equivalent to the classic `max(ceil(...)·(CR+4), 0)`: a non-positive
    // numerator contributes no extra symbols beyond the fixed eight.
    int32_t numerator = 8 * pl - 4 * sf_n + 28 + 16 * crc - 20 * ih;
    if (numerator < 0) {
        numerator = 0;
    }
    const int32_t denominator = 4 * (sf_n - 2 * de);
    const int32_t ceil_term = (numerator + denominator - 1) / denominator; // ceil of a non-negative ratio
    return 8u + static_cast<uint32_t>(ceil_term) * static_cast<uint32_t>(cr_n + 4);
}
 
} // namespace airtime_detail
 
[[nodiscard]] constexpr std::chrono::microseconds
time_on_air(const lora_modulation& mod, const lora_packet_params& pkt, size_t payload_length) noexcept {
    const uint64_t bw = airtime_detail::bandwidth_hz(mod.bw);
    const uint64_t sf = std::to_underlying(mod.sf);
    const uint32_t n_payload = airtime_detail::payload_symbols(
        mod.sf, mod.cr, pkt.header, pkt.crc_on, mod.low_data_rate_optimize, payload_length
    );
 
    // Total symbol count scaled ×4 so the 4.25-symbol preamble offset (×4 = 17)
    // stays integral.
    const uint64_t n_symbol_x4 = (static_cast<uint64_t>(pkt.preamble_length) + n_payload) * 4 + 17;
 
    // T = n_symbol · (2^SF / BW). Fold the ×4 of n_symbol_x4 into the divisor and
    // scale by 1e6 µs/s, then round to the nearest microsecond — all in integer
    // arithmetic so the result is deterministic and constexpr-evaluable.
    const uint64_t numerator = n_symbol_x4 * (uint64_t{1} << sf) * 1'000'000ull;
    const uint64_t denominator = 4ull * bw;
    const uint64_t us = (numerator + denominator / 2) / denominator;
    return std::chrono::microseconds{static_cast<int64_t>(us)};
}
 
} // namespace idfxx::radio