radio_sx1262.h

Go to the documentation of this file.

#pragma once
 
/// @file radio_sx1262.h
/// @brief SX1262 radio driver for IO-Homecontrol.
/// @ingroup hioc_radio
///
/// Implements the RadioDriver interface for the Semtech SX1262 transceiver.
/// Unlike the SX1276, the SX1262 uses opcode-based SPI commands and requires a
/// BUSY pin check before every SPI transaction. The capture path preserves the
/// radio-reported RX metadata so offline analysis can work from trustworthy data.
/// The IRQ-driven RX/TX orchestration this driver shares with RadioLR1121 lives in
/// SoftPhyDriverBase (see radio_soft_phy_driver_base.h) — this file has the SX1262-specific
/// SPI transport and register/opcode encoding underneath it.
/// @todo Validate the Heltec V4.2 on real hardware, especially its assumed front-end module
///       enable pins and TCXO voltage selection. The V4.3 is validated and does not settle this:
///       its GC1109 is a different part from the V4.3's KCT8103L, and the two are wired the other
///       way round (see ADR 0035).
 
#include "radio_soft_phy_driver_base.h"
#include "esphome/core/hal.h"
 
#include <cstddef>
 
namespace esphome {
namespace home_io_control {
 
// ============================================================================
// SX1262 Opcode Constants
// ============================================================================
 
static constexpr uint8_t SX1262_SET_STANDBY = 0x80;
static constexpr uint8_t SX1262_SET_RX = 0x82;
static constexpr uint8_t SX1262_SET_TX = 0x83;
static constexpr uint8_t SX1262_SET_RF_FREQUENCY = 0x86;
static constexpr uint8_t SX1262_SET_RX_TX_FALLBACK_MODE = 0x93;
static constexpr uint8_t SX1262_WRITE_BUFFER = 0x0E;
static constexpr uint8_t SX1262_READ_BUFFER = 0x1E;
static constexpr uint8_t SX1262_SET_DIO_IRQ_PARAMS = 0x08;
static constexpr uint8_t SX1262_GET_IRQ_STATUS = 0x12;
static constexpr uint8_t SX1262_GET_PACKET_STATUS = 0x14;
static constexpr uint8_t SX1262_GET_DEVICE_ERRORS = 0x17;
static constexpr uint8_t SX1262_CLEAR_IRQ_STATUS = 0x02;
static constexpr uint8_t SX1262_CLEAR_DEVICE_ERRORS = 0x07;
static constexpr uint8_t SX1262_SET_PACKET_TYPE = 0x8A;
static constexpr uint8_t SX1262_SET_MODULATION_PARAMS = 0x8B;
static constexpr uint8_t SX1262_SET_PACKET_PARAMS = 0x8C;
static constexpr uint8_t SX1262_SET_BUFFER_BASE_ADDRESS = 0x8F;
static constexpr uint8_t SX1262_SET_PA_CONFIG = 0x95;
static constexpr uint8_t SX1262_SET_TX_PARAMS = 0x8E;
static constexpr uint8_t SX1262_SET_DIO2_AS_RF_SWITCH_CTRL = 0x9D;
static constexpr uint8_t SX1262_SET_DIO3_AS_TCXO_CTRL = 0x97;
static constexpr uint8_t SX1262_CALIBRATE = 0x89;
static constexpr uint8_t SX1262_CALIBRATE_IMAGE = 0x98;
static constexpr uint8_t SX1262_GET_RX_BUFFER_STATUS = 0x13;
static constexpr uint8_t SX1262_GET_RSSI_INST = 0x15;
static constexpr uint8_t SX1262_SET_REGULATOR_MODE = 0x96;
static constexpr uint8_t SX1262_GET_STATUS = 0xC0;
 
// SPI register access opcodes
static constexpr uint8_t SX1262_WRITE_REGISTER = 0x0D;
static constexpr uint8_t SX1262_READ_REGISTER = 0x1D;
 
// ============================================================================
// SX1262 IRQ Bit Masks
// ============================================================================
 
static constexpr uint16_t SX1262_IRQ_TX_DONE = 0x0001;
static constexpr uint16_t SX1262_IRQ_RX_DONE = 0x0002;
static constexpr uint16_t SX1262_IRQ_PREAMBLE_DETECTED = 0x0004;
static constexpr uint16_t SX1262_IRQ_SYNC_WORD_VALID = 0x0008;
static constexpr uint16_t SX1262_IRQ_CRC_ERR = 0x0040;
 
/// IRQ bits that represent a *terminal* radio event — a frame finished decoding, an outbound
/// frame completed, or the chip reported a bad CRC. Deliberately excludes PREAMBLE_DETECTED even
/// though `configure_radio_()` now includes it in `irqMask`: a preamble alone means a frame may
/// still be arriving, so SoftPhyDriverBase's poll_until_activity_()/check_for_packet() (gated by
/// @ref RadioSX1262::activity_irq_mask) must not treat it as terminal — doing so would tear down
/// RX mid-reception. Same trap, same fix shape as @ref LR1121_IRQ_ACTIVITY_MASK.
static constexpr uint16_t SX1262_IRQ_ACTIVITY_MASK =
    SX1262_IRQ_TX_DONE | SX1262_IRQ_RX_DONE | SX1262_IRQ_SYNC_WORD_VALID | SX1262_IRQ_CRC_ERR;
 
// ============================================================================
// SX1262 GetDeviceErrors bit masks
// ============================================================================
// The word returned by GetDeviceErrors (SX1262 datasheet §13.3.7, cross-checked against RadioLib's
// RADIOLIB_SX126X_*_ERR). XOSC_START_ERR and IMG_CALIB_ERR are expected at a cold start with a
// TCXO fitted and are simply cleared before calibration; the others are genuine faults.
static constexpr uint16_t SX1262_DEV_ERR_RC64K_CALIB = 0x0001;  ///< 64 kHz RC oscillator calibration failed.
static constexpr uint16_t SX1262_DEV_ERR_RC13M_CALIB = 0x0002;  ///< 13 MHz RC oscillator calibration failed.
static constexpr uint16_t SX1262_DEV_ERR_PLL_CALIB = 0x0004;    ///< PLL calibration failed.
static constexpr uint16_t SX1262_DEV_ERR_ADC_CALIB = 0x0008;    ///< ADC calibration failed.
static constexpr uint16_t SX1262_DEV_ERR_IMG_CALIB = 0x0010;    ///< Image calibration failed.
static constexpr uint16_t SX1262_DEV_ERR_XOSC_START = 0x0020;   ///< Crystal/TCXO failed to start.
static constexpr uint16_t SX1262_DEV_ERR_PLL_LOCK = 0x0040;     ///< PLL failed to lock.
static constexpr uint16_t SX1262_DEV_ERR_PA_RAMP = 0x0100;      ///< PA ramping failed (bit 0x0080 is unused).
 
/// Receive-side gain of a FEM profile's LNA, in the SX1262's RSSI scale.
struct FemRxGain {
  int8_t db;          ///< Gain (dB) the RSSI includes and the driver removes; 0 when unknown or absent.
  const char *basis;  ///< Where the figure comes from and how far to trust it, for the config dump.
};
 
/// @brief The receive gain to remove from RSSI for a FEM profile.
/// @param profile Any profile; `FemProfile::NONE` has no front end and yields 0.
FemRxGain sx1262_fem_rx_gain(FemProfile profile);
 
/// Antenna-port power estimate for a configured `tx_power` through a FEM profile's chain.
struct FemTxEstimate {
  uint8_t tx_power;  ///< The `tx_power` actually programmed: the configured value clamped to SetTxParams' range.
  int antenna_dbm;   ///< Estimated antenna-port power in dBm — a rough bound, not a calibrated figure.
};
 
/// @brief Estimate what a FEM profile radiates for a configured `tx_power`.
/// @param profile A real FEM profile (not `FemProfile::NONE`, which has no gain table).
/// @param tx_power Configured power setting; clamped like the value written to SetTxParams.
///
/// The gain tables behind it carry an uncertainty of about ±5–7 dB for the Heltec profiles; see
/// docs/adr/0035-fem-support-is-a-behaviour-profile-boards-always-supply-pins.md.
FemTxEstimate sx1262_fem_tx_estimate(FemProfile profile, uint8_t tx_power);
 
/// @brief Expand a GetDeviceErrors word into a human-readable `NAME|NAME|...` string.
/// @param errors Raw device-error bitmask from GetDeviceErrors.
/// @param buf Caller-owned output buffer; always NUL-terminated on return.
/// @param buf_size Size of @p buf. Use @ref DEVICE_ERROR_STR_SIZE.
///
/// Writes `"none"` when @p errors is zero, and appends `UNKNOWN_0x%04X` for any set bit with no
/// name in the table so an undocumented flag still shows up in the log.
void sx1262_format_device_errors(uint16_t errors, char *buf, size_t buf_size);
 
/// @brief Name of the chip mode in a GetStatus byte (bits 6:4).
/// @param chip_status The byte GetStatus returned.
/// @return `STDBY_RC`, `STDBY_XOSC`, `FS`, `RX`, `TX`, or `?` for a reserved or unused value.
const char *sx1262_chip_mode_name(uint8_t chip_status);
 
/// @brief Command status field of a GetStatus byte (bits 3:1).
/// @param chip_status The byte GetStatus returned.
/// @return The 3-bit field (2 = data available, 3 = command timeout, 4 = processing error,
///         5 = execution failure, 6 = TX done).
uint8_t sx1262_command_status(uint8_t chip_status);
 
// Sync word register base address
static constexpr uint16_t SX1262_REG_SYNC_WORD = 0x06C0;
static constexpr uint16_t SX1262_REG_RX_GAIN = 0x08AC;
static constexpr uint16_t SX1262_REG_TX_CLAMP_CONFIG = 0x08D8;
 
/// TX modulation-quality erratum register (SX1262 datasheet §15.1, "Modulation Quality with
/// 500 kHz LoRa Bandwidth" — the title names LoRa, but the workaround table covers every
/// modulation). Bit 2 must be cleared *only* for LoRa at BW 500 kHz and set to 1 for everything
/// else, explicitly including any (G)FSK configuration — which is all this driver ever uses.
/// Semtech's own driver and RadioLib apply it as `TxModulation` / `fixModulationQuality()`.
/// Leaving it at its reset value degrades transmitted modulation quality, which on this protocol
/// shows up as a peer that intermittently fails to decode an otherwise strong frame.
/// Counterpart to the already-applied TxClamp erratum (@ref SX1262_REG_TX_CLAMP_CONFIG).
static constexpr uint16_t SX1262_REG_TX_MODULATION = 0x0889;
// Code span, not \ref: doxygen 1.18 can't resolve \ref to this in a whole-project build
// (details in proto_sizes.h). Autolinking still links it.
/// Bit 2 of `SX1262_REG_TX_MODULATION` — the (G)FSK-correct value is 1.
static constexpr uint8_t SX1262_TX_MODULATION_GFSK_BIT = 0x04;
 
/// Data-buffer split programmed by configure_buffer_base(): TX packets build from 0x00, RX
/// packets land at 0x80. The RX base doubles as the read offset for a length-driven receive —
/// a single in-flight packet always starts exactly there.
static constexpr uint8_t SX1262_TX_BUFFER_BASE = 0x00;
static constexpr uint8_t SX1262_RX_BUFFER_BASE = 0x80;
 
static constexpr uint8_t SX1262_GFSK_PACKET_TYPE_KNOWN_LENGTH = 0x00;
static constexpr uint8_t SX1262_GFSK_CRC_OFF = 0x01;
/// Preamble detector length selector: 16 bits (0x04 = 8, 0x05 = 16, 0x06 = 24, 0x07 = 32 bits).
/// The 8-bit detector fired on noise 3-4 times per second of listening on a Heltec V3, and each
/// false detection held a rotating listen on an empty channel for 25-35 ms; at 16 bits those were
/// gone and every answer was still caught. A real preamble runs 14 ms or more (500+ bits), so 16
/// bits costs it nothing. 24 bits stopped all sync detection on the same bench (cause not known),
/// so do not raise this further without measuring. The LR1121 driver uses the same 16-bit value.
static constexpr uint8_t SX1262_PREAMBLE_DETECTOR_16_BIT = 0x05;
static constexpr uint8_t SX1262_FALLBACK_STDBY_XOSC = 0x30;
 
/// Ceiling on how long SoftPhyDriverBase::wait_busy_() waits for BUSY to drop before declaring the
/// chip failed. A healthy chip never waits for it, and the wait is judged on a fresh sample, so a
/// task preemption cannot trip it; this is headroom for the RC-oscillator-clocked commands (unlike
/// LR1121's post-reset boot ROM, see LR1121_BUSY_TIMEOUT_MS in radio_lr1121.h). It must stay below
/// the smallest TCXO bring-up rung budget (30 ms) so every rung still widens it.
static constexpr uint32_t SX1262_BUSY_TIMEOUT_MS = 25;
 
// ============================================================================
// SX1262 Radio Driver
// ============================================================================
 
/// @brief SX1262 implementation of RadioDriver.
/// @ingroup hioc_radio
///
/// Manages the SX1262 via opcode‑based SPI using the SpiAccess interface.
/// Configures the chip in FSK mode with software CRC‑CCITT to match the
/// IO‑Homecontrol protocol (the SX1262 lacks the SX1276's IoHomeOn mode).
/// The IRQ-driven RX/TX orchestration is inherited from SoftPhyDriverBase; this class supplies
/// the SPI transport and every SX1262-specific register/opcode encoding underneath it.
class RadioSX1262 : public SoftPhyDriverBase {
 public:
  RadioSX1262(SpiAccess *spi, InternalGPIOPin *rst_pin, InternalGPIOPin *dio1_pin, InternalGPIOPin *busy_pin,
              uint8_t tx_power, uint8_t tcxo_voltage, InternalGPIOPin *fem_en_pin = nullptr,
              InternalGPIOPin *vfem_pin = nullptr, InternalGPIOPin *fem_pa_pin = nullptr,
              FemProfile fem_profile = FemProfile::NONE)
      : SoftPhyDriverBase(rst_pin, busy_pin, SX1262_BUSY_TIMEOUT_MS, SX1262_RESPONSE_PREAMBLE,
                          SX1262_POST_TX_SETTLE_US),
        spi_(spi),
        dio1_pin_(dio1_pin),
        fem_en_pin_(fem_en_pin),
        vfem_pin_(vfem_pin),
        fem_pa_pin_(fem_pa_pin),
        fem_profile_(fem_profile),
        tx_power_(tx_power),
        tcxo_voltage_(tcxo_voltage) {}
 
  /// @copydoc RadioDriver::init
  bool init() override;
  /// @brief Apply SX1262 runtime tuning: RX bandwidth, response preamble, post-TX settle delay.
  void apply_tuning(const TuningConfig &tuning) override {
    this->set_rx_bandwidth_(tuning.sx1262_rx_bandwidth);
    this->set_response_preamble_(tuning.sx1262_response_preamble);
    this->set_post_tx_settle_us_(tuning.sx1262_post_tx_settle_us);
  }
  /// @brief Per-channel dwell for a rotating listen (SX1262).
  ///
  /// See `SX1262_DISCOVERY_HOP_SLICE_MS` for why a short dwell is correct here despite SX1262's
  /// slower per-channel retune than the SX1276's FastHop. Governs discovery and the broadcast
  /// roll-call alike (see @ref RadioDriver::hop_dwell_ms). The value comes from the user-facing
  /// `sx1262_discovery_hop_slice_ms` tuning field.
  [[nodiscard]] uint16_t hop_dwell_ms(const TuningConfig &tuning) const override {
    return tuning.sx1262_discovery_hop_slice_ms;
  }
  /// @brief TX→RX turnaround capability (SX1262): slow.
  ///
  /// The TX→standby→RX transition plus the post-TX settle delay is too slow to
  /// catch a device's immediate reply through the standard exchange wait; in
  /// pairing, the key-confirm (0x33) is missed that way. PairingEngine therefore
  /// uses its dedicated key-confirm wait with key-init re-trigger on this driver.
  [[nodiscard]] bool has_fast_tx_rx_turnaround() const override { return false; }
  /// @copydoc RadioDriver::set_mode_rx
  void set_mode_rx() override;
  /// @copydoc RadioDriver::set_mode_standby
  void set_mode_standby() override;
  [[nodiscard]] const char *chip_name() const override { return "sx1262"; }
  /// @brief Dump the FEM profile and its antenna-power estimate (nothing without a FEM).
  void dump_front_end() override;
  /// @brief Dump SX1262‑specific debug info.
  void dump_debug() override;
 
 protected:
  // --- Tuning helper unique to this chip (its RX-bandwidth enum is not shared, see
  // tuning_config.h's LR1121RxBandwidth comment for why the two chips' encodings diverged) ---
  /// Apply the RX bandwidth selector and rewrite the modulation parameters.
  /// @param bandwidth Bandwidth selector enum.
  void set_rx_bandwidth_(SX1262RxBandwidth bandwidth);
 
  // --- SPI communication (opcode‑based) ---
  /// Write an opcode with optional parameter bytes.
  /// @param opcode SX1262 opcode.
  /// @param params Pointer to parameter buffer (may be nullptr).
  /// @param len Parameter length.
  void write_opcode_(uint8_t opcode, const uint8_t *params, uint8_t len);
  /// Read response from an opcode.
  /// @param opcode Opcode that was previously written.
  /// @param data Output buffer.
  /// @param len Expected number of bytes to read.
  void read_opcode_(uint8_t opcode, uint8_t *data, uint8_t len);
  /// Write to a register (SX1262 uses opcodes for register access).
  /// @param addr 16‑bit register address.
  /// @param data Pointer to data bytes.
  /// @param len Number of bytes.
  void write_register_(uint16_t addr, const uint8_t *data, uint8_t len);
  /// Read from a register.
  /// @param addr 16‑bit register address.
  /// @param data Output buffer.
  /// @param len Number of bytes to read.
  void read_register_(uint16_t addr, uint8_t *data, uint8_t len);
  /// Write into the SX1262 TX/RX buffer at a given offset.
  /// @param offset Buffer offset.
  /// @param data Payload bytes.
  /// @param len Payload length.
  void write_buffer_(uint8_t offset, const uint8_t *data, uint8_t len);
  /// Read from the SX1262 RX buffer.
  /// @param offset Buffer offset.
  /// @param data Output buffer.
  /// @param len Number of bytes to read.
  void read_buffer_(uint8_t offset, uint8_t *data, uint8_t len);
 
  // --- Radio configuration ---
  /// Full radio initialization (called from init()).
  void configure_radio_();
  /// @brief Bring up the DIO3-controlled TCXO and calibrate, with a bounded XOSC-start retry.
  ///
  /// Runs up to three attempts on a strictly increasing startup-delay ladder (5/10/50 ms). Each
  /// attempt issues SetDIO3AsTCXOCtrl, clears the device-error latch (XOSC_START_ERR /
  /// IMG_CALIB_ERR are expected at a cold TCXO start), calibrates, then re-reads the errors and
  /// stops as soon as XOSC_START_ERR is clear. Records the attempt count and last delay in
  /// `tcxo_startup_attempts_` / `tcxo_startup_delay_us_`.
  ///
  /// wait_busy_()'s budget is widened to each rung's startup window (plus a calibration margin)
  /// for the duration, and — if the ladder had to escalate — a ceiling wide enough for the
  /// successful rung is kept for the rest of the session, because `configure_radio_()` step 4
  /// re-enters STDBY_XOSC and re-pays that same startup window. Skipped entirely when
  /// `tcxo_voltage: none` selects a bare crystal.
  void configure_tcxo_();
  /// @copydoc SoftPhyDriverBase::set_frequency_register
  void set_frequency_register(uint32_t freq_hz) override;
  /// Configure packet parameters (preamble, payload length, CRC).
  /// @param preamble_len Preamble length in symbols.
  /// @param payload_len Expected payload length.
  /// @param packet_type Fixed for GFSK.
  /// @param crc_type CRC configuration (off or on).
  void set_packet_params_(uint16_t preamble_len, uint8_t payload_len, uint8_t packet_type, uint8_t crc_type);
  /// Apply the runtime bandwidth setting to the SX1262 modulation parameters.
  void write_modulation_params_();
  /// Apply the Semtech TX modulation-quality erratum workaround (datasheet §15.1). The datasheet
  /// requires it "before any packet transmission", so it hangs off @ref before_tx_arm rather than
  /// running once at init — same placement rationale as RadioLR1121's high-ACP workaround.
  void apply_tx_modulation_workaround_();
  /// @copydoc SoftPhyDriverBase::set_rx_packet_params
  void set_rx_packet_params() override;
  /// @copydoc SoftPhyDriverBase::set_tx_packet_params
  void set_tx_packet_params(uint16_t preamble_len, uint8_t payload_len) override {
    this->set_packet_params_(preamble_len, payload_len, SX1262_GFSK_PACKET_TYPE_KNOWN_LENGTH, SX1262_GFSK_CRC_OFF);
  }
  /// @copydoc SoftPhyDriverBase::clear_irq_status
  void clear_irq_status(uint32_t irq_mask) override;
  /// @brief Read device error flags (and clear them).
  /// @return Error bitmask.
  uint16_t get_device_errors_();
  /// @brief Read the GetStatus byte (chip mode and last command status).
  uint8_t read_chip_status_();
  /// @brief Log GetStatus, whether the IRQ word holds TX-done, the device errors and the DIO1/BUSY
  /// pin levels after a TX that never reported TX-done.
  void log_tx_timeout_state(uint32_t irq_status) override;
  /// @brief Clear device error flags.
  void clear_device_errors_();
  /// @copydoc SoftPhyDriverBase::front_end_rx_gain_db
  ///
  /// The LNA gain of the configured FEM profile; see sx1262_fem_rx_gain().
  [[nodiscard]] int8_t front_end_rx_gain_db() const override { return sx1262_fem_rx_gain(this->fem_profile_).db; }
  /// @copydoc SoftPhyDriverBase::configure_buffer_base
  ///
  /// SX1262's buffer base addresses (TX=0x00, RX=0x80) are re-asserted on every RX reset — LR1121
  /// has no equivalent register.
  void configure_buffer_base() override;
  /// @copydoc SoftPhyDriverBase::early_rx_read_offset
  ///
  /// The SX1262 writes demodulated bytes into its data buffer as they arrive, and a single
  /// in-flight packet always starts at the RX base address programmed by configure_buffer_base(),
  /// so the shared flow can read the frame out on its own air time rather than waiting the fixed
  /// ~10 ms for the 48-byte RX_DONE.
  [[nodiscard]] int16_t early_rx_read_offset() const override { return SX1262_RX_BUFFER_BASE; }
  /// @copydoc SoftPhyDriverBase::fill_capture_info
  ///
  /// Note: `crc_error` is set from the CrcErr IRQ bit — unlike the SX1276, this
  /// driver sees and reports frames with a bad CRC.
  void fill_capture_info(bool blocking_wait, uint32_t irq_status, uint8_t rx_offset, uint8_t reported_len,
                         const uint8_t *raw, uint8_t raw_len, const uint8_t *frame, uint8_t frame_len) override;
 
  /// DIO1 ISR — sets dio_fired flag. Runs in interrupt context.
  static void gpio_intr(RadioSX1262 *arg);
 
  /// @copydoc SoftPhyDriverBase::read_irq_status_raw
  uint32_t read_irq_status_raw() override;
  /// @copydoc SoftPhyDriverBase::sync_word_valid_bit
  [[nodiscard]] uint32_t sync_word_valid_bit() const override { return SX1262_IRQ_SYNC_WORD_VALID; }
  /// @copydoc SoftPhyDriverBase::rx_done_bit
  [[nodiscard]] uint32_t rx_done_bit() const override { return SX1262_IRQ_RX_DONE; }
  /// @copydoc SoftPhyDriverBase::tx_done_bit
  [[nodiscard]] uint32_t tx_done_bit() const override { return SX1262_IRQ_TX_DONE; }
  /// @copydoc SoftPhyDriverBase::preamble_detected_bit
  [[nodiscard]] uint32_t preamble_detected_bit() const override { return SX1262_IRQ_PREAMBLE_DETECTED; }
  /// @copydoc SoftPhyDriverBase::activity_irq_mask
  ///
  /// The base class default ("any bit") stopped being safe the moment `configure_radio_()`
  /// unmasked PreambleDetected — see @ref SX1262_IRQ_ACTIVITY_MASK's doc comment.
  [[nodiscard]] uint32_t activity_irq_mask() const override { return SX1262_IRQ_ACTIVITY_MASK; }
  /// @copydoc SoftPhyDriverBase::read_rssi_raw_byte
  uint8_t read_rssi_raw_byte() override;
  /// @copydoc SoftPhyDriverBase::write_tx_buffer
  void write_tx_buffer(const uint8_t *data, uint8_t len) override {
    this->write_buffer_(SX1262_TX_BUFFER_BASE, data, len);
  }
  /// @copydoc SoftPhyDriverBase::get_rx_buffer_status
  void get_rx_buffer_status(uint8_t &reported_len, uint8_t &rx_offset) override;
  /// @copydoc SoftPhyDriverBase::read_rx_buffer
  void read_rx_buffer(uint8_t offset, uint8_t *data, uint8_t len) override { this->read_buffer_(offset, data, len); }
  /// @copydoc SoftPhyDriverBase::start_tx
  void start_tx() override;
  /// @copydoc SoftPhyDriverBase::before_tx_arm
  ///
  /// TX modulation-quality erratum (`SX1262_REG_TX_MODULATION`): the datasheet requires bit 2
  /// be set for every (G)FSK transmission, so it is re-asserted before each SetTx rather than
  /// assumed to survive from init. Also drives the FEM mode pin to its TX-active level — see
  /// @ref fem_set_tx_mode_.
  void before_tx_arm() override {
    this->apply_tx_modulation_workaround_();
    this->fem_set_tx_mode_();
  }
 
  /// @brief The level `fem_pa_pin_` is driven to for the duration of a transmission, for the
  /// current `fem_profile_`. `true` (HIGH) for GC1109/KCT8103L, whose shared truth table treats the
  /// mode pin as CPS/CTX -- active HIGH selects the TX/full-PA path. `false` (LOW) for XY16P35,
  /// whose "LNA Ctrl" pin is the receive-side enable: HIGH turns the LNA *on* (receive), LOW turns
  /// it off (transmit or idle) -- the inverse sense, per LilyGO's own datasheet note (ADR 0035).
  /// Never called for FemProfile::NONE (both callers guard on that first).
  [[nodiscard]] bool fem_tx_active_level_() const;
  /// @brief Drive the FEM mode pin to its transmit state (full PA), a no-op when no FEM profile
  /// is configured.
  ///
  /// "Mode pin" is fem_pa_pin_ -- CPS on GC1109 (V4.2), CTX on KCT8103L (V4.3), the LNA-control pin
  /// on XY16P35 (T-Beam 1W) -- see the shared truth table in
  /// docs/adr/0035-fem-support-is-a-behaviour-profile-boards-always-supply-pins.md. Called from
  /// @ref before_tx_arm, right before SetTx.
  void fem_set_tx_mode_();
  /// @brief Drive the FEM mode pin to its receive state (LNA), a no-op when no FEM profile is
  /// configured.
  ///
  /// Called from both @ref set_mode_rx and @ref set_mode_standby (not just the former) because a
  /// TX timeout in SoftPhyDriverBase::send_packet() calls set_mode_standby() directly and never
  /// reaches set_mode_rx() — without this hook there too, a timed-out TX would leave the mode pin
  /// stranded in its TX-active state indefinitely (nothing else would ever drop it back).
  void fem_set_rx_mode_();
 
 private:
  SpiAccess *spi_;
  InternalGPIOPin *dio1_pin_;
  InternalGPIOPin *fem_en_pin_;
  InternalGPIOPin *vfem_pin_;
  InternalGPIOPin *fem_pa_pin_;
  FemProfile fem_profile_;
  uint8_t tx_power_;
  uint8_t tcxo_voltage_;               ///< 0-based chip voltage code, or @ref TCXO_VOLTAGE_NONE for a bare crystal.
  uint8_t tcxo_startup_attempts_{0};   ///< SetDIO3AsTCXOCtrl attempts the last bring-up took (0 = skipped/none).
  uint32_t tcxo_startup_delay_us_{0};  ///< Startup delay of the last rung tried, in µs — the rung that started the
                                       ///< TCXO on success, or the one reached before giving up.
  SX1262RxBandwidth rx_bandwidth_{SX1262RxBandwidth::BW_58_6_KHZ};  ///< Runtime-tunable RX bandwidth.
};
 
}  // namespace home_io_control
}  // namespace esphome