sx126x.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Chris Leishman
 
#pragma once
 
#include <idfxx/cpu>
#include <idfxx/error>
#include <idfxx/event>
#include <idfxx/flags>
#include <idfxx/future>
#include <idfxx/gpio>
#include <idfxx/radio/events.hpp>
#include <idfxx/radio/lora_transceiver.hpp>
#include <idfxx/radio/types.hpp>
#include <idfxx/spi/master>
 
#include <chrono>
#include <cstdint>
#include <electro/decibel>
#include <electro/electro>
#include <frequency/frequency>
#include <memory>
#include <optional>
#include <span>
 
namespace idfxx::radio {
 
enum class sx126x_irq_flag : uint16_t {
    tx_done = 1 << 0,
    rx_done = 1 << 1,
    preamble_detected = 1 << 2,
    sync_word_valid = 1 << 3,
    header_valid = 1 << 4,
    header_err = 1 << 5,
    crc_err = 1 << 6,
    cad_done = 1 << 7,
    cad_detected = 1 << 8,
    timeout = 1 << 9,
};
 
} // namespace idfxx::radio
 
template<>
inline constexpr bool idfxx::enable_flags_operators<idfxx::radio::sx126x_irq_flag> = true;
 
namespace idfxx::radio {
 
class sx126x final : public lora_transceiver {
public:
    using irq_flag = sx126x_irq_flag;
 
    enum class chip_variant : uint8_t {
        sx1261, 
        sx1262, 
        sx1268, 
    };
 
    enum class regulator : uint8_t {
        ldo = 0x00,   
        dc_dc = 0x01, 
    };
 
    enum class standby_clock : uint8_t {
        rc,   
        xosc, 
    };
 
    enum class sleep_mode : uint8_t {
        warm, 
        cold, 
    };
 
    struct tcxo_config {
        electro::millivolts voltage{1700};        
        std::chrono::microseconds startup{5'000}; 
 
        [[nodiscard]] constexpr bool operator==(const tcxo_config&) const noexcept = default;
    };
 
    enum class cad_symbols : uint8_t {
        sym_1 = 0x00,  
        sym_2 = 0x01,  
        sym_4 = 0x02,  
        sym_8 = 0x03,  
        sym_16 = 0x04, 
    };
 
    struct cad_params {
        cad_symbols symbols = cad_symbols::sym_2; 
        uint8_t det_peak = 22;                    
        uint8_t det_min = 10;                     
 
        [[nodiscard]] constexpr bool operator==(const cad_params&) const noexcept = default;
    };
 
    struct config {
        chip_variant variant = chip_variant::sx1262;    
        idfxx::gpio cs = gpio::nc();                    
        idfxx::gpio busy = gpio::nc();                  
        idfxx::gpio dio1 = gpio::nc();                  
        idfxx::gpio nreset = gpio::nc();                
        freq::hertz clock_speed{10'000'000};            
        bool dio2_as_rf_switch = true;                  
        idfxx::gpio rxen = gpio::nc();                  
        idfxx::gpio txen = gpio::nc();                  
        std::optional<tcxo_config> tcxo = std::nullopt; 
        enum regulator regulator = regulator::ldo;      
        bool rx_boost = false;                          
        std::chrono::milliseconds busy_timeout{100};    
        std::optional<flags<sx126x_irq_flag>> dio1_mask = std::nullopt;
        bool warm_start = false;
        event_loop* loop = nullptr;        
        task_priority worker_priority{18}; 
        size_t worker_stack_size = 4096;   
        std::optional<core_id> worker_core = std::nullopt; 
    };
 
    // =========================================================================
    // Construction / lifetime
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] explicit sx126x(spi::master_bus& bus, config config);
#endif
 
    [[nodiscard]] static result<sx126x> make(spi::master_bus& bus, config config);
 
    ~sx126x() override;
 
    sx126x(const sx126x&) = delete;
    sx126x& operator=(const sx126x&) = delete;
    sx126x(sx126x&& other) noexcept;
    sx126x& operator=(sx126x&& other) noexcept;
 
    // =========================================================================
    // Accessors
    // =========================================================================
 
    [[nodiscard]] chip_variant variant() const noexcept;
 
    [[nodiscard]] spi::master_device& spi() noexcept;
 
    // =========================================================================
    // SX126x-specific mode control
    //
    // The chip-agnostic mode-control methods (standby, sleep, start_listening,
    // start_channel_scan, ...) are inherited from radio::lora_transceiver. The overloads
    // here expose SX126x-specific refinements of the same operations.
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    using lora_transceiver::sleep;
    using lora_transceiver::standby;
#endif
    using lora_transceiver::try_sleep;
    using lora_transceiver::try_standby;
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void standby(standby_clock clock) { unwrap(try_standby(clock)); }
 
    void sleep(sleep_mode mode) { unwrap(try_sleep(mode)); }
#endif
 
    result<void> try_standby(standby_clock clock);
 
    result<void> try_sleep(sleep_mode mode);
 
    // =========================================================================
    // SX126x-specific surface
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    using lora_transceiver::set_sync_word;
#endif
    using lora_transceiver::try_set_sync_word;
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void set_sync_word(uint16_t sync_word) { unwrap(try_set_sync_word(sync_word)); }
 
    void set_cad_params(cad_params params) { unwrap(try_set_cad_params(params)); }
 
    [[nodiscard]] std::optional<rx_info> adopt_pending() { return unwrap(try_adopt_pending()); }
 
    [[nodiscard]] flags<irq_flag> irq_status() { return unwrap(try_irq_status()); }
 
    void clear_irq_status(flags<irq_flag> mask) { unwrap(try_clear_irq_status(mask)); }
#endif
 
    [[nodiscard]] result<std::optional<rx_info>> try_adopt_pending();
 
    [[nodiscard]] result<void> try_set_sync_word(uint16_t sync_word);
 
    [[nodiscard]] result<void> try_set_cad_params(cad_params params);
 
    [[nodiscard]] result<flags<irq_flag>> try_irq_status();
 
    [[nodiscard]] result<void> try_clear_irq_status(flags<irq_flag> mask);
 
    // =========================================================================
    // Low-level opcode escape hatch
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void write_command(uint8_t opcode, std::span<const uint8_t> params) { unwrap(try_write_command(opcode, params)); }
 
    void read_command(uint8_t opcode, std::span<uint8_t> response) { unwrap(try_read_command(opcode, response)); }
 
    void write_register(uint16_t addr, std::span<const uint8_t> data) { unwrap(try_write_register(addr, data)); }
 
    void read_register(uint16_t addr, std::span<uint8_t> data) { unwrap(try_read_register(addr, data)); }
 
    void write_buffer(uint8_t offset, std::span<const uint8_t> data) { unwrap(try_write_buffer(offset, data)); }
 
    void read_buffer(uint8_t offset, std::span<uint8_t> data) { unwrap(try_read_buffer(offset, data)); }
#endif
 
    [[nodiscard]] result<void> try_write_command(uint8_t opcode, std::span<const uint8_t> params);
    [[nodiscard]] result<void> try_read_command(uint8_t opcode, std::span<uint8_t> response);
    [[nodiscard]] result<void> try_write_register(uint16_t addr, std::span<const uint8_t> data);
    [[nodiscard]] result<void> try_read_register(uint16_t addr, std::span<uint8_t> data);
    [[nodiscard]] result<void> try_write_buffer(uint8_t offset, std::span<const uint8_t> data);
    [[nodiscard]] result<void> try_read_buffer(uint8_t offset, std::span<uint8_t> data);
 
    struct state;
 
private:
    explicit sx126x(std::unique_ptr<state> s) noexcept;
 
    // radio::lora_transceiver customization hooks.
    [[nodiscard]] chip_mode do_current_mode() const noexcept override;
    [[nodiscard]] result<void> do_standby() override;
    [[nodiscard]] result<void> do_sleep() override;
    [[nodiscard]] result<void> do_start_listening() override;
    [[nodiscard]] result<void>
    do_start_listening(std::chrono::microseconds rx_period, std::chrono::microseconds sleep_period) override;
    [[nodiscard]] result<idfxx::future<rx_info>> do_start_receive(std::span<uint8_t> buffer) override;
    [[nodiscard]] result<idfxx::future<cad_info>> do_start_channel_scan() override;
    [[nodiscard]] result<void> do_set_frequency(freq::hertz hz) override;
    [[nodiscard]] result<void> do_set_output_power(electro::dbm power, ramp_time ramp) override;
    [[nodiscard]] result<void> do_set_modulation(lora_modulation mod) override;
    [[nodiscard]] result<void> do_set_packet_params(lora_packet_params params) override;
    [[nodiscard]] result<void> do_set_sync_word(lora_network network) override;
    [[nodiscard]] result<idfxx::future<void>> do_start_transmit(std::span<const uint8_t> data) override;
    [[nodiscard]] result<rx_info> do_read_received(std::span<uint8_t> buffer) override;
    [[nodiscard]] result<packet_status> do_last_packet_status() override;
    [[nodiscard]] result<electro::centi_dbm> do_current_rssi() override;
    [[nodiscard]] std::chrono::microseconds do_rx_duty_cycle_min_sleep() const noexcept override;
 
    std::unique_ptr<state> _state;
};
 
} // namespace idfxx::radio