lora_transceiver.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Chris Leishman
 
#pragma once
 
#include <idfxx/error>
#include <idfxx/future>
#include <idfxx/radio/airtime.hpp>
#include <idfxx/radio/duty_cycle.hpp>
#include <idfxx/radio/types.hpp>
 
#include <chrono>
#include <cstdint>
#include <electro/decibel>
#include <frequency/frequency>
#include <optional>
#include <span>
 
namespace idfxx::radio {
 
class lora_transceiver {
public:
    virtual ~lora_transceiver() = default;
 
    lora_transceiver(const lora_transceiver&) = delete;
    lora_transceiver& operator=(const lora_transceiver&) = delete;
 
    // =========================================================================
    // Accessors
    // =========================================================================
 
    [[nodiscard]] chip_mode current_mode() const noexcept { return do_current_mode(); }
 
    [[nodiscard]] lora_modulation modulation() const noexcept { return _modulation; }
 
    [[nodiscard]] lora_packet_params packet_params() const noexcept { return _packet_params; }
 
    // =========================================================================
    // Link calculations
    // =========================================================================
 
    [[nodiscard]] std::chrono::microseconds time_on_air(size_t payload_length) const noexcept {
        return idfxx::radio::time_on_air(_modulation, _packet_params, payload_length);
    }
 
    [[nodiscard]] std::optional<rx_duty_cycle> rx_duty_cycle_for(uint16_t min_symbols = 8) const noexcept {
        return idfxx::radio::rx_duty_cycle_for(
            _modulation, _packet_params.preamble_length, min_symbols, do_rx_duty_cycle_min_sleep()
        );
    }
 
    // =========================================================================
    // Mode control
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void standby() { unwrap(try_standby()); }
 
    void sleep() { unwrap(try_sleep()); }
 
    void start_listening() { unwrap(try_start_listening()); }
 
    void start_listening(std::chrono::microseconds rx_period, std::chrono::microseconds sleep_period) {
        unwrap(try_start_listening(rx_period, sleep_period));
    }
 
    void start_listening(rx_duty_cycle cycle) { unwrap(try_start_listening(cycle)); }
 
    void start_listening(const std::optional<rx_duty_cycle>& cycle) { unwrap(try_start_listening(cycle)); }
 
    [[nodiscard]] idfxx::future<cad_info> start_channel_scan() { return unwrap(try_start_channel_scan()); }
 
    [[nodiscard]] cad_info scan_channel() { return unwrap(try_scan_channel()); }
 
    [[nodiscard]] bool channel_busy() { return unwrap(try_channel_busy()); }
#endif
 
    result<void> try_standby() { return do_standby(); }
 
    result<void> try_sleep() { return do_sleep(); }
 
    [[nodiscard]] result<void> try_start_listening() { return do_start_listening(); }
 
    [[nodiscard]] result<void>
    try_start_listening(std::chrono::microseconds rx_period, std::chrono::microseconds sleep_period) {
        if (rx_period <= std::chrono::microseconds::zero() || sleep_period <= std::chrono::microseconds::zero()) {
            return error(errc::invalid_arg);
        }
        return do_start_listening(rx_period, sleep_period);
    }
 
    [[nodiscard]] result<void> try_start_listening(rx_duty_cycle cycle) {
        return try_start_listening(cycle.rx_period, cycle.sleep_period);
    }
 
    [[nodiscard]] result<void> try_start_listening(const std::optional<rx_duty_cycle>& cycle) {
        return cycle ? try_start_listening(*cycle) : try_start_listening();
    }
 
    [[nodiscard]] result<idfxx::future<cad_info>> try_start_channel_scan() { return do_start_channel_scan(); }
 
    [[nodiscard]] result<cad_info> try_scan_channel() {
        auto f = try_start_channel_scan();
        if (!f) {
            return error(f.error());
        }
        return _await(*f, scan_guard_window);
    }
 
    [[nodiscard]] result<bool> try_channel_busy() {
        auto r = try_scan_channel();
        if (!r) {
            return error(r.error());
        }
        return r->detected;
    }
 
    // =========================================================================
    // Configuration
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void configure(const lora_link& link) { unwrap(try_configure(link)); }
 
    void set_frequency(freq::hertz hz) { unwrap(try_set_frequency(hz)); }
 
    void set_output_power(electro::dbm power, ramp_time ramp = ramp_time::us_200) {
        unwrap(try_set_output_power(power, ramp));
    }
 
    void set_modulation(lora_modulation mod) { unwrap(try_set_modulation(mod)); }
 
    void set_packet_params(lora_packet_params params) { unwrap(try_set_packet_params(params)); }
 
    void set_sync_word(lora_network network) { unwrap(try_set_sync_word(network)); }
#endif
 
    [[nodiscard]] result<void> try_configure(const lora_link& link) {
        if (link.frequency.count() == 0) {
            return error(errc::invalid_arg);
        }
        if (auto r = try_set_frequency(link.frequency); !r) {
            return r;
        }
        if (auto r = try_set_output_power(link.output_power, link.ramp); !r) {
            return r;
        }
        if (auto r = try_set_modulation(link.modulation); !r) {
            return r;
        }
        if (auto r = try_set_packet_params(link.packet_params); !r) {
            return r;
        }
        return try_set_sync_word(link.network);
    }
 
    [[nodiscard]] result<void> try_set_frequency(freq::hertz hz) { return do_set_frequency(hz); }
 
    [[nodiscard]] result<void> try_set_output_power(electro::dbm power, ramp_time ramp = ramp_time::us_200) {
        return do_set_output_power(power, ramp);
    }
 
    [[nodiscard]] result<void> try_set_modulation(lora_modulation mod) {
        if (auto r = do_set_modulation(mod); !r) {
            return r;
        }
        _modulation = mod;
        return {};
    }
 
    [[nodiscard]] result<void> try_set_packet_params(lora_packet_params params) {
        if (auto r = do_set_packet_params(params); !r) {
            return r;
        }
        _packet_params = params;
        return {};
    }
 
    [[nodiscard]] result<void> try_set_sync_word(lora_network network) { return do_set_sync_word(network); }
 
    // =========================================================================
    // Data path: blocking
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void transmit(std::span<const uint8_t> data) { unwrap(try_transmit(data)); }
 
    template<typename Rep, typename Period>
    void transmit(std::span<const uint8_t> data, const std::chrono::duration<Rep, Period>& timeout) {
        unwrap(try_transmit(data, timeout));
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] rx_info receive(std::span<uint8_t> buffer, const std::chrono::duration<Rep, Period>& timeout) {
        return unwrap(try_receive(buffer, timeout));
    }
#endif
 
    [[nodiscard]] result<void> try_transmit(std::span<const uint8_t> data) {
        return try_transmit(data, time_on_air(data.size()) + transmit_timeout_margin);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void>
    try_transmit(std::span<const uint8_t> data, const std::chrono::duration<Rep, Period>& timeout) {
        auto f = try_start_transmit(data);
        if (!f) {
            return error(f.error());
        }
        return _await(*f, std::chrono::ceil<std::chrono::milliseconds>(timeout));
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<rx_info>
    try_receive(std::span<uint8_t> buffer, const std::chrono::duration<Rep, Period>& timeout) {
        auto f = try_start_receive(buffer);
        if (!f) {
            return error(f.error());
        }
        return _await(*f, std::chrono::ceil<std::chrono::milliseconds>(timeout));
    }
 
    // =========================================================================
    // Data path: async
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] idfxx::future<void> start_transmit(std::span<const uint8_t> data) {
        return unwrap(try_start_transmit(data));
    }
 
    [[nodiscard]] idfxx::future<rx_info> start_receive(std::span<uint8_t> buffer) {
        return unwrap(try_start_receive(buffer));
    }
 
    [[nodiscard]] rx_info read_received(std::span<uint8_t> buffer) { return unwrap(try_read_received(buffer)); }
#endif
 
    [[nodiscard]] result<idfxx::future<void>> try_start_transmit(std::span<const uint8_t> data) {
        if (data.empty() || data.size() > max_payload_length) {
            return error(errc::invalid_arg);
        }
        return do_start_transmit(data);
    }
 
    [[nodiscard]] result<idfxx::future<rx_info>> try_start_receive(std::span<uint8_t> buffer) {
        return do_start_receive(buffer);
    }
 
    [[nodiscard]] result<rx_info> try_read_received(std::span<uint8_t> buffer) { return do_read_received(buffer); }
 
    // =========================================================================
    // Status
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] packet_status last_packet_status() { return unwrap(try_last_packet_status()); }
 
    [[nodiscard]] electro::centi_dbm current_rssi() { return unwrap(try_current_rssi()); }
#endif
 
    [[nodiscard]] result<packet_status> try_last_packet_status() { return do_last_packet_status(); }
 
    [[nodiscard]] result<electro::centi_dbm> try_current_rssi() { return do_current_rssi(); }
 
    static constexpr size_t max_payload_length = 255;
 
    static constexpr std::chrono::milliseconds transmit_timeout_margin{250};
 
    static constexpr std::chrono::milliseconds scan_guard_window{1000};
 
protected:
    lora_transceiver() = default;
    lora_transceiver(lora_transceiver&&) noexcept = default;
    lora_transceiver& operator=(lora_transceiver&&) noexcept = default;
 
    // =========================================================================
    // Customization hooks
    //
    // Concrete drivers override these (typically privately). Each hook
    // implements the correspondingly named public method; argument validation
    // common to all chips (payload length, positive durations) has already
    // been performed by the public wrappers.
    // =========================================================================
 
    [[nodiscard]] virtual chip_mode do_current_mode() const noexcept = 0;
 
    [[nodiscard]] virtual result<void> do_standby() = 0;
    [[nodiscard]] virtual result<void> do_sleep() = 0;
    [[nodiscard]] virtual result<void> do_start_listening() = 0;
    [[nodiscard]] virtual result<void>
    do_start_listening(std::chrono::microseconds rx_period, std::chrono::microseconds sleep_period) {
        (void)rx_period;
        (void)sleep_period;
        return error(errc::not_supported);
    }
    [[nodiscard]] virtual result<idfxx::future<cad_info>> do_start_channel_scan() = 0;
 
    [[nodiscard]] virtual result<void> do_set_frequency(freq::hertz hz) = 0;
    [[nodiscard]] virtual result<void> do_set_output_power(electro::dbm power, ramp_time ramp) = 0;
    [[nodiscard]] virtual result<void> do_set_modulation(lora_modulation mod) = 0;
    [[nodiscard]] virtual result<void> do_set_packet_params(lora_packet_params params) = 0;
    [[nodiscard]] virtual result<void> do_set_sync_word(lora_network network) = 0;
 
    [[nodiscard]] virtual result<idfxx::future<void>> do_start_transmit(std::span<const uint8_t> data) = 0;
    [[nodiscard]] virtual result<idfxx::future<rx_info>> do_start_receive(std::span<uint8_t> buffer) = 0;
    [[nodiscard]] virtual result<rx_info> do_read_received(std::span<uint8_t> buffer) = 0;
 
    [[nodiscard]] virtual result<packet_status> do_last_packet_status() = 0;
    [[nodiscard]] virtual result<electro::centi_dbm> do_current_rssi() = 0;
 
    [[nodiscard]] virtual std::chrono::microseconds do_rx_duty_cycle_min_sleep() const noexcept {
        return default_min_rx_sleep;
    }
 
private:
    // Link parameters applied by the last successful try_set_modulation /
    // try_set_packet_params; served back by modulation()/packet_params()
    // and consumed by the time_on_air/rx_duty_cycle_for members.
    lora_modulation _modulation{};
    lora_packet_params _packet_params{};
 
    // Shared tail of the blocking compositions (try_transmit / try_receive /
    // try_scan_channel): waits for the operation's future, cancelling the
    // operation via try_standby if it does not complete in time and masking
    // the resulting cancellation error back to `errc::timeout`.
    template<typename T>
    [[nodiscard]] result<T> _await(const idfxx::future<T>& f, std::chrono::milliseconds timeout) {
        auto r = f.try_wait_for(timeout);
        if (r || r.error() != errc::timeout) {
            return r;
        }
        // The completion IRQ may land between the wait timing out and the
        // cancel below; only cancel an operation that is still pending.
        if (f.done()) {
            return f.try_wait();
        }
        (void)try_standby();
        auto late = f.try_wait_for(std::chrono::milliseconds{0});
        if (late || late.error() != errc::not_finished) {
            return late;
        }
        return error(errc::timeout); // our own cancellation, reported as a timeout
    }
};
 
} // namespace idfxx::radio