radio_soft_phy_driver_base.h

Go to the documentation of this file.

#pragma once
 
/// @file radio_soft_phy_driver_base.h
/// @brief Shared driver flow for radios using the software PHY (SX1262, LR1121).
/// @ingroup hioc_radio
///
/// RadioSX1262 and RadioLR1121 both lack the SX1276's IoHomeOn hardware framing, so both
/// reproduce IO-Homecontrol framing in software on top of generic GFSK support
/// (`radio_soft_phy.h`'s UART bit-encode/probe). Beyond that shared bit-level codec, the two
/// drivers' IRQ-driven RX state machine and TX orchestration are identical in every detail that
/// isn't chip-specific transport or register encoding, so this class holds that shared flow once
/// instead of each driver maintaining its own copy.
///
/// This class holds everything the two drivers do identically: `wait_for_packet()`/
/// `check_for_packet()`'s IRQ polling and sync/RX-done race resolution, `read_rx_packet()`'s
/// buffer-read and UART-probe recovery, `send_packet()`'s TX orchestration, `read_rssi()`'s
/// formula, and the response-preamble/post-TX-settle tuning fields. What genuinely differs
/// between the two chips — SPI opcode encoding/transport, IRQ bit values and word width,
/// register-level packet/modulation parameter encoding, and the handful of one-off steps one
/// chip needs that the other doesn't (SX1262's buffer-base-address write, LR1121's high-ACP
/// pre-TX workaround and preamble-tolerant activity check) — stays behind virtual primitives and
/// hooks implemented by `RadioSX1262`/`RadioLR1121`.
 
#include "radio_interface.h"
#include "radio_soft_phy.h"
 
#include <cstddef>
#include <cstdint>
 
namespace esphome {
namespace home_io_control {
 
/// Fixed raw-RX probe length. Typical traffic is 23-25 byte protocol frames (34 raw bytes packed
/// with CRC); the binding case is the largest frame the probe must still recover intact — a 1W CMD
/// 0x30 add-controller with its out-of-length MAC trailer, which packs to 47 raw bytes and needs
/// up to 9 more bits of headroom for the probe's leading bit-offset sweep. 48 bytes covers that
/// (see the SOFT_PHY_MAX_WIRE_FRAME_RAW_BYTES static_assert below) without relying on either
/// chip's variable-length engine. This is a protocol-frame-size property, not a chip quirk, so
/// both drivers share one value — used here for the raw-probe threshold in @ref
/// SoftPhyDriverBase::read_rx_packet and by each driver's own `set_rx_packet_params()` for the
/// configured RX payload length.
static constexpr uint8_t SOFT_PHY_RX_PROBE_PACKET_LEN = 48;
 
/// Sentinel meaning "every IRQ bit counts as activity" — the default for @ref
/// SoftPhyDriverBase::activity_irq_mask. Neither concrete driver uses it any more: both SX1262
/// and LR1121 unmask PreambleDetected at the hardware level and override this to exclude it (see
/// SX1262_IRQ_ACTIVITY_MASK / LR1121_IRQ_ACTIVITY_MASK). Kept as the base-class default for a
/// hypothetical future driver that never unmasks PreambleDetected in the first place, where "any
/// bit" is genuinely safe again.
static constexpr uint32_t SOFT_PHY_ALL_IRQ_BITS = 0xFFFFFFFF;
 
/// Raw bytes read in the first stage of a length-driven receive — enough to hold CTRL0's UART
/// cell (10 bits) at any of the probe's bit alignments (up to 9 bits of slack).
static constexpr uint8_t SOFT_PHY_EARLY_HEADER_RAW_BYTES = 3;
 
/// Air-time margin added before every mid-reception buffer read, in raw bytes.
///
/// Covers the lag between a byte finishing on air and the chip having it in its data buffer, plus
/// the granularity of the polled sync-word observation. Two byte-times is generous at this line
/// rate and still leaves a length-driven receive far ahead of the fixed-length RX_DONE.
static constexpr uint8_t SOFT_PHY_EARLY_READ_MARGIN_BYTES = 2;
 
/// Poll interval while waiting out a frame's remaining air time, in microseconds.
static constexpr uint32_t SOFT_PHY_EARLY_POLL_US = 100;
 
/// Smallest receive window a length-driven receive will be attempted in, in milliseconds.
///
/// The longest possible frame (FRAME_MAX_SIZE + CRC, UART-packed) occupies ~9.4 ms of air time, so
/// a caller with less than this left cannot finish one either way. Declining up front keeps the
/// early path from spending a short window's whole budget on a receive it cannot complete.
static constexpr uint32_t SOFT_PHY_EARLY_MIN_WINDOW_MS = 12;
 
/// Blocking budget @ref SoftPhyDriverBase::check_for_packet gives a length-driven receive, in
/// milliseconds — the `timeout_ms` passed to `try_early_completion_()` from the non-blocking
/// idle-loop RX path (issue #81). The real bound on how long that call can block is the frame's
/// own air time (~9.4 ms worst case, see @ref SOFT_PHY_EARLY_MIN_WINDOW_MS), not this number; this
/// value only has to be large enough not to cut a genuine frame short. It is not itself a tight
/// bound on loop() latency — the actual air time is what stays well inside a loop() tick
/// (~16-30 ms) — and either way it is dwarfed by the 1-3 s a blocking exchange already costs
/// `loop()`.
static constexpr uint32_t SOFT_PHY_IDLE_RX_COMPLETION_BUDGET_MS = 20;
 
/// Wait after retuning to the TX channel before the clear-channel RSSI reading. A retune on these
/// chips is standby → SetRfFrequency → SetRx (the TCXO stays on in XOSC standby), after which the
/// PLL has to relock and the instantaneous RSSI has to average over the new channel; 1 ms covers
/// that with margin and costs nothing next to a preamble.
/// \todo Confirm on the bench (Heltec V3, T3-S3 LR1121): time the retune and compare the reading
/// against one taken after a long dwell on the same channel.
static constexpr uint32_t SOFT_PHY_CCA_SETTLE_US = 1000;
 
static_assert(SOFT_PHY_IDLE_RX_COMPLETION_BUDGET_MS >= SOFT_PHY_EARLY_MIN_WINDOW_MS,
              "a budget below the minimum window makes try_early_completion_() decline every "
              "idle-path call, silently turning issue #81's fix into a no-op");
 
// RX_HOP_HOLDOFF_US (radio_interface.h) exists to outlast the fixed-length RX_DONE on the
// software-PHY chips. Tied here, in the one header that can see both sides of the arithmetic,
// so a change to either constant that breaks the relationship fails the build instead of
// silently turning issue #81's gate back into the bug it fixes.
static_assert(RX_HOP_HOLDOFF_US >= soft_phy_air_time_us(SOFT_PHY_RX_PROBE_PACKET_LEN),
              "the hop holdoff must outlast the fixed-length RX_DONE it exists to wait for — a "
              "shorter bound lets the hop fire while the frame it is protecting is still on air, "
              "silently turning issue #81's gate back into the bug");
 
/// Largest real IO-Homecontrol frame the fixed-length RX probe has to recover intact: a 1W CMD
/// 0x30 "add controller". Its 9-byte header + 20-byte payload (wrapped key[16] + manufacturer[1] +
/// data[1] + sequence[2]) = 29 declared bytes, and it carries a 6-byte authenticator as an
/// out-of-length trailer *after* the declared length but still under the CRC — so the probe must
/// hold 29 + 6 = 35 wire bytes. This is larger than any frame CTRL0's length field alone
/// describes, which is why it, not FRAME_MAX_DECLARED_SIZE, is the binding case.
static constexpr uint16_t SOFT_PHY_MAX_WIRE_FRAME_BYTES =
    FRAME_MIN_SIZE + AES_KEY_SIZE + 1 /*manufacturer*/ + 1 /*data*/ + 2 /*sequence*/ + HMAC_SIZE;
 
/// Raw on-air bytes that frame occupies once its 2-byte CRC is appended and the whole thing is
/// UART-packed into 10-bit cells (start + 8 data + stop), rounded up to whole bytes — the same
/// arithmetic as soft_phy_raw_bytes_for_frame(), spelled out here because that helper is not
/// constexpr. Plus `UART_PROBE_MAX_BIT_OFFSET - 1` bits: the probe locates the frame start by
/// sweeping leading alignments, so a recovered frame can begin that many bits into the raw buffer.
/// 35 + 2 = 37 cells = 370 bits, + 9 slack bits = 379 → 48 raw bytes, exactly the probe length.
static constexpr uint16_t SOFT_PHY_MAX_WIRE_FRAME_RAW_BYTES =
    ((SOFT_PHY_MAX_WIRE_FRAME_BYTES + FRAME_CRC_SIZE) * UART_CELL_BITS + (UART_PROBE_MAX_BIT_OFFSET - 1) +
     BITS_PER_BYTE - 1) /
    BITS_PER_BYTE;
 
static_assert(SOFT_PHY_MAX_WIRE_FRAME_RAW_BYTES <= SOFT_PHY_RX_PROBE_PACKET_LEN,
              "the fixed-length RX probe must hold a UART-packed 1W 0x30 add-controller frame with "
              "its out-of-length MAC trailer and CRC, at any of the probe's leading bit alignments "
              "— a shorter probe clips the trailer (or CRC) off an enrollment frame mid-air and the "
              "frame is silently dropped");
 
static_assert(SOFT_PHY_RX_PROBE_PACKET_LEN <= RADIO_PACKET_BUFFER_SIZE,
              "the RX probe is read into RadioRxPacket::raw / ::data, which are "
              "RADIO_PACKET_BUFFER_SIZE bytes — if a growing frame format pushes the probe length "
              "past the buffer (via the assert above), those reads overflow");
 
// FRAME_MAX_WIRE_SIZE (proto_sizes.h) — a full 32-byte declared frame *plus* a trailer plus CRC —
// packs to 50 raw bytes (52 with the bit-offset slack applied above), past this 48-byte probe. It
// is unreachable only because no real frame combines a 32-byte declared length with an
// out-of-length trailer: the trailer rides exclusively on CMD 0x30, whose declared length is fixed
// at 29. If a second trailer-bearing command with a longer declared length is ever added,
// SOFT_PHY_MAX_WIRE_FRAME_BYTES above must grow to match and this probe length will need to grow
// with it.
 
// === Device-error decoding ===
// Both chips report a 16-bit "device errors" word (SX1262 GetDeviceErrors, LR1121 GetErrors) whose
// bit meanings differ; the decoding and the init-time capture below are shared, the tables are not.
 
/// One named bit of a chip's device-error word.
struct DeviceErrorBit {
  uint16_t mask;     ///< The bit (or bits) of the error word this row names.
  const char *name;  ///< Log name, e.g. `PLL_LOCK_ERR`.
};
 
/// Buffer size that always fits format_device_error_bits()'s longest output for either chip (every
/// named bit, `|`-joined, plus an UNKNOWN_0x%04X tail).
static constexpr size_t DEVICE_ERROR_STR_SIZE = 160;
 
/// @brief Expand a device-error word into a human-readable `NAME|NAME|...` string.
/// @param errors Raw device-error bitmask.
/// @param bits The chip's bit → name table, in output order.
/// @param bit_count Number of rows in @p bits.
/// @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 format_device_error_bits(uint16_t errors, const DeviceErrorBit *bits, size_t bit_count, char *buf,
                              size_t buf_size);
 
/// @copybrief format_device_error_bits
/// @tparam N Row count of the chip's table, deduced from the array so no caller counts it by hand.
template<size_t N>
void format_device_error_bits(uint16_t errors, const DeviceErrorBit (&bits)[N], char *buf, size_t buf_size) {
  format_device_error_bits(errors, bits, N, buf, buf_size);
}
 
/// A chip's own decoder, as passed to SoftPhyDriverBase::dump_init_device_errors_().
using DeviceErrorFormatter = void (*)(uint16_t errors, char *buf, size_t buf_size);
 
/// @brief Shared RX/TX driver flow for the software-PHY radios (SX1262, LR1121).
/// @ingroup hioc_radio
class SoftPhyDriverBase : public RadioDriver {
 public:
  /// @param rst_pin Active-low hardware reset pin, forwarded to RadioDriver.
  /// @param busy_pin BUSY line polled by @ref wait_busy_ before every SPI transaction — both
  ///   concrete drivers are opcode-based chips that require this, unlike the register-based
  ///   SX1276.
  /// @param busy_timeout_ms How long @ref wait_busy_ waits for BUSY to drop before declaring the
  ///   chip failed. Chip-specific (SX1262: 10 ms: RC-oscillator timing; LR1121: 3000 ms, matched
  ///   to RadioLib's post-reset boot-ROM wait) — this class has no opinion on the value, only on
  ///   where it's stored and how it's used.
  /// @param default_response_preamble Chip-specific default for @ref response_preamble (each
  ///   concrete driver passes its own validated constant — this class has no opinion on the
  ///   value, only on where it's stored).
  /// @param default_post_tx_settle_us Chip-specific default post-TX settling delay, same rationale.
  SoftPhyDriverBase(InternalGPIOPin *rst_pin, InternalGPIOPin *busy_pin, uint32_t busy_timeout_ms,
                    uint16_t default_response_preamble, uint16_t default_post_tx_settle_us)
      : RadioDriver(rst_pin),
        busy_pin_(busy_pin),
        response_preamble_(default_response_preamble),
        post_tx_settle_us_(default_post_tx_settle_us),
        busy_timeout_ms_(busy_timeout_ms) {}
 
  /// @copydoc RadioDriver::send_packet
  TxResult send_packet(const uint8_t *data, uint8_t len, const RadioTxConfig &tx_config) override;
  /// @copydoc RadioDriver::wait_for_packet
  bool wait_for_packet(RadioRxPacket &packet, uint32_t timeout_ms) override;
  /// @copydoc RadioDriver::check_for_packet
  bool check_for_packet(RadioRxPacket &packet) override;
  /// @copydoc RadioDriver::change_frequency
  void change_frequency(uint32_t freq_hz) override;
  /// @copydoc RadioDriver::read_rssi
  ///
  /// Same formula on both chips (`-(int16_t) raw / 2`, see @ref raw_rssi_to_dbm_); only the opcode
  /// used to read the single raw byte differs, via @ref read_rssi_raw_byte. Antenna-referred: the
  /// gain of an external receive front end is removed, see @ref front_end_rx_gain_db.
  int16_t read_rssi() override;
  /// @copydoc RadioDriver::is_sync_detected
  bool is_sync_detected() override;
  /// @copydoc RadioDriver::is_preamble_detected
  ///
  /// Consults the private `preamble_latched_at_timeout_` flag first; see that member's declaration
  /// for why.
  bool is_preamble_detected() override;
  /// @brief Preamble for response/continuation frames — shared storage, see the concrete
  /// drivers' constructors/tuning defaults for the chip-specific rationale and value.
  [[nodiscard]] uint16_t response_preamble() const override { return this->response_preamble_; }
 
  /// @copydoc RadioDriver::default_start_preamble
  ///
  /// This PHY puts less usable preamble on air than its programmed length suggests, so it asks for
  /// more than the protocol's documented value (`SOFT_PHY_START_PREAMBLE`, which carries the
  /// measurement). The override belongs here rather than on each concrete driver because the
  /// shared PHY is the level the effect follows: SX1262 and LR1121 measured the same as each other
  /// and both differed from the register PHY, so a per-driver value would invent a difference the
  /// evidence does not show. See ADR 0042.
  [[nodiscard]] uint16_t default_start_preamble() const override { return SOFT_PHY_START_PREAMBLE; }
 
  /// @brief Transmit time: the preamble, sync word and UART-coded frame at the protocol line rate.
  [[nodiscard]] uint32_t tx_air_time_us(uint8_t len, const RadioTxConfig &cfg) const override {
    return io868_tx_air_time_us(cfg.preamble_len, len);
  }
 
 protected:
  // --- Tuning helpers shared by both drivers (values/defaults stay chip-specific) ---
  /// Set the preamble length used for response/continuation frames within an exchange.
  void set_response_preamble_(uint16_t preamble) { this->response_preamble_ = preamble; }
  /// Set the delay between TX completion and re-entering RX.
  void set_post_tx_settle_us_(uint16_t delay_us) { this->post_tx_settle_us_ = delay_us; }
  /// @brief Current @ref wait_busy_ timeout, in milliseconds.
  [[nodiscard]] uint32_t get_busy_timeout_ms_() const { return this->busy_timeout_ms_; }
  /// @brief Set the @ref wait_busy_ timeout, in milliseconds.
  ///
  /// Exposed so a concrete driver can widen it around a bring-up step that legitimately holds BUSY
  /// far longer than the steady-state value (SX1262 TCXO startup runs up to 50 ms against a 10 ms
  /// default) and then restore it. Pair every widen with a restore.
  void set_busy_timeout_ms_(uint32_t timeout_ms) { this->busy_timeout_ms_ = timeout_ms; }
  /// @brief Wait until @ref busy_pin_ reads low, feeding the watchdog while polling.
  ///
  /// Shared verbatim between SX1262 and LR1121 — the two chips differ only in how long they're
  /// willing to wait (`busy_timeout_ms_`). A call short-circuits once the driver has latched
  /// `failed_`: without that guard, every remaining `configure_radio_()` step after the first
  /// failure would re-run the full timeout, turning one bad boot into tens of seconds of hang at
  /// the LR1121's 3000 ms timeout (harmless but still pointless at the SX1262's 10 ms one).
  void wait_busy_();
  /// @brief Keep the device-error word read at the end of `configure_radio_()` and warn if it is
  ///        non-zero.
  /// @param tag Log tag of the calling driver.
  /// @param chip_label Chip name for the warning, e.g. "SX1262".
  /// @param errors The word read from the chip, before the caller clears its register.
  /// @param format The calling chip's decoder for its device-error word.
  void record_init_device_errors_(const char *tag, const char *chip_label, uint16_t errors,
                                  DeviceErrorFormatter format);
  /// @brief Gain (dB) of the board's external receive front end that the chip's RSSI includes.
  ///
  /// A low-noise amplifier ahead of the radio raises every RSSI reading by its gain, which makes an
  /// idle channel look busy against a threshold defined at the antenna (listen-before-talk) and
  /// makes signal levels incomparable between boards. Drivers whose board has such a front end
  /// override this; @ref raw_rssi_to_dbm_ then reports antenna-referred values. Boards without one
  /// keep the default of 0.
  [[nodiscard]] virtual int8_t front_end_rx_gain_db() const { return 0; }
  /// @brief Convert a chip's raw RSSI byte to an antenna-referred dBm reading.
  /// @param raw Raw byte from the chip (`dBm = -raw / 2` at the radio's input, on both chips).
  /// @return The reading with @ref front_end_rx_gain_db removed. Used for every RSSI this driver
  ///         reports — live (@ref read_rssi) and per received packet — so they share one scale.
  [[nodiscard]] int16_t raw_rssi_to_dbm_(uint8_t raw) const {
    return static_cast<int16_t>((-static_cast<int16_t>(raw) / 2) - this->front_end_rx_gain_db());
  }
  /// @brief Log the init-time device errors under @p tag, or nothing when there were none.
  /// @param tag Log tag of the calling driver, so the line stays inside its own dump section.
  /// @param format The calling chip's decoder for its device-error word.
  void dump_init_device_errors_(const char *tag, DeviceErrorFormatter format) const;
  /// Device-error word a driver reads at the end of `configure_radio_()`, before it clears the
  /// chip's register. The chip still initializes and transmits with some of these set (PLL lock,
  /// calibration, TCXO start), so the config dump reports the captured value: a later read of the
  /// register would only ever see the cleared state.
  uint16_t init_device_errors_{0};
  /// BUSY line, read directly by both concrete drivers' own `dump_debug()` in addition to
  /// @ref wait_busy_, so this stays protected rather than folding entirely into the private
  /// wait-loop state below.
  InternalGPIOPin *busy_pin_;
 
  // --- Shared RX/TX orchestration (moved verbatim from RadioSX1262/RadioLR1121) ---
  /// Read a received packet from the buffer and return the raw bytes reported by the chip.
  /// Virtual to allow test doubles (both concrete drivers' tests override this).
  virtual bool read_rx_packet(RadioRxPacket &packet, bool blocking_wait, uint32_t irq_status);
  /// Reset RX state machine and buffer. Optionally force standby first.
  void reset_rx_state_(bool force_standby = true);
  /// Minimal path back into RX immediately after a transmission — see the definition for why this
  /// is deliberately not @ref reset_rx_state_.
  void rearm_rx_after_tx_();
 
  /// @brief The GFSK SetPacketParams fields both software-PHY chips program identically.
  ///
  /// Both drivers build the same nine-byte SetPacketParams payload in the same order; only the
  /// preamble-detector length and the sync-word selector are chip constants, and only the opcode
  /// and transport differ. Everything else — the field order and the byte/bit preamble conversion
  /// that the `63e2502` fix had to patch in two places — lives in @ref build_gfsk_packet_params.
  struct SoftPhyPacketParams {
    uint16_t preamble_bytes;    ///< Byte-denominated, like every other preamble value in this codebase.
    uint8_t preamble_detector;  ///< Chip-specific detector-length selector.
    uint8_t sync_word_param;    ///< Chip-specific 24-bit sync-word selector.
    uint8_t packet_type;        ///< Known-length / fixed-length selector.
    uint8_t payload_len;        ///< Configured payload length.
    uint8_t crc_type;           ///< Chip-specific CRC-mode selector.
  };
  /// Byte count of the GFSK SetPacketParams payload — identical on both software-PHY chips.
  static constexpr uint8_t GFSK_PACKET_PARAMS_LEN = 9;
  /// @brief Fill the nine-byte GFSK SetPacketParams payload shared by both chips.
  ///
  /// Owns the field order and the ×8 preamble conversion: the SetPacketParams preamble field is
  /// bit-denominated on both chips (Semtech names it `preamble_len_in_bits` /
  /// `pbl_len_in_bit`), but every caller in this codebase passes a byte count. Address comparison
  /// and whitening are always off.
  /// @param p   The chip-independent field values (byte-denominated preamble, chip constants).
  /// @param out Buffer for exactly @ref GFSK_PACKET_PARAMS_LEN bytes.
  ///
  /// Named without the trailing `_` the file's other protected helpers carry: it uses no instance
  /// state, so clang-tidy's `readability-convert-member-functions-to-static` wants it `static`, and
  /// `.clang-tidy`'s `ClassMethodCase = lower_case` then rejects a trailing `_` on a `static`
  /// method. Leaving it `static` and dropping the underscore keeps clang-tidy quiet without a
  /// suppression.
  static void build_gfsk_packet_params(const SoftPhyPacketParams &p, uint8_t out[GFSK_PACKET_PARAMS_LEN]);
 
  /// @brief Read the raw IRQ status word from the radio.
  /// Virtual to allow test doubles (both concrete drivers' tests override this).
  virtual uint32_t read_irq_status_raw() = 0;
  /// Clear IRQ status bits.
  /// @param irq_mask Bitmask of IRQs to clear (each driver narrows to its own IRQ word width).
  virtual void clear_irq_status(uint32_t irq_mask) = 0;
 
  /// @name Chip-specific IRQ bit values
  /// Each driver's own IRQ bit constants, exposed as accessors so the shared RX/TX orchestration
  /// never needs to name a chip-specific constant directly.
  ///@{
  [[nodiscard]] virtual uint32_t sync_word_valid_bit() const = 0;
  [[nodiscard]] virtual uint32_t rx_done_bit() const = 0;
  [[nodiscard]] virtual uint32_t tx_done_bit() const = 0;
  [[nodiscard]] virtual uint32_t preamble_detected_bit() const = 0;
  ///@}
 
  /// @brief IRQ bits that count as "activity" for the internal `poll_until_activity_()` helper
  /// and @ref check_for_packet.
  ///
  /// Default is "any bit" — safe only for a driver whose `SetDioIrqParams`-equivalent mask never
  /// includes `PreambleDetected` in the first place, so a preamble-only reading can never reach
  /// this check. Neither current driver qualifies: both SX1262 and LR1121 unmask
  /// `PreambleDetected` (each for its own reason) and override this to exclude it — a
  /// preamble-only reading means a frame may still be arriving, and treating it as terminal
  /// activity would tear down RX mid-reception.
  [[nodiscard]] virtual uint32_t activity_irq_mask() const { return SOFT_PHY_ALL_IRQ_BITS; }
 
  // `SOFT_PHY_RX_PROBE_PACKET_LEN` below is a code span, not \ref: doxygen 1.18 can't resolve
  // \ref to it in a whole-project build (details in proto_sizes.h). Autolinking still links it.
  /// @brief Data-buffer offset an in-flight reception is being written to, or a negative value
  /// when this chip must not be read before RX_DONE.
  ///
  /// Neither chip's RX_DONE marks the end of the *frame*: with no hardware framing, RX runs in
  /// fixed-length mode at `SOFT_PHY_RX_PROBE_PACKET_LEN`, so RX_DONE arrives a fixed ~10 ms
  /// after the sync word no matter how short the frame actually was. That delay lands squarely on
  /// the protocol's tightest turnaround — the hub's reply to a device's challenge — so a driver
  /// that can read its buffer while reception is still running opts in here and the shared flow
  /// finishes on the frame's own air time instead (see `try_early_completion_`).
  ///
  /// Default is -1: wait for RX_DONE exactly as before. SX1262 overrides it with the RX base
  /// address it programs in configure_buffer_base(), which is where a single in-flight packet
  /// always starts. LR1121 also opts in, at the base of its one shared TX/RX buffer — see
  /// RadioLR1121::early_rx_read_offset for why a wrong guess there is safe only in combination
  /// with @ref invalidate_stale_rx_content_after_tx.
  [[nodiscard]] virtual int16_t early_rx_read_offset() const { return -1; }
 
  /// @brief Blocking budget for the idle-path length-driven receive, in milliseconds (issue #81).
  ///
  /// Virtual only so tests can widen it. The host clock stubs advance `millis()`/`micros()` by one
  /// unit per call (`tests/include/esphome/core/hal.h`), so a frame's few thousand microseconds of
  /// air time also burns a few thousand fake milliseconds — any production-sized budget expires
  /// inside `wait_for_air_time()`'s first stage and the whole path becomes untestable. The existing
  /// blocking-path early-completion tests dodge this by passing `wait_for_packet()` a 20000 ms
  /// timeout; this path has no caller-supplied timeout to widen, so the seam has to live here.
  [[nodiscard]] virtual uint32_t idle_rx_completion_budget_ms() const { return SOFT_PHY_IDLE_RX_COMPLETION_BUDGET_MS; }
 
  /// Set RF frequency via the chip's own frequency register/opcode encoding, and update
  /// `current_freq_`. Called from both @ref change_frequency and the shared `send_packet()`.
  virtual void set_frequency_register(uint32_t freq_hz) = 0;
  /// Configure RX-specific packet parameters (preamble detector length, fixed probe length).
  virtual void set_rx_packet_params() = 0;
  /// Configure TX packet parameters for one outgoing UART-encoded frame.
  /// @param preamble_len Preamble length in symbols, from the caller's RadioTxConfig.
  /// @param payload_len UART-encoded payload length in bytes.
  virtual void set_tx_packet_params(uint16_t preamble_len, uint8_t payload_len) = 0;
  /// Read the single raw RSSI byte (chip-specific opcode); formula is shared, see @ref read_rssi.
  virtual uint8_t read_rssi_raw_byte() = 0;
  /// Write the UART-encoded TX payload into the chip's TX buffer.
  virtual void write_tx_buffer(const uint8_t *data, uint8_t len) = 0;
  /// Read the chip-reported RX length and buffer offset (raw, before any clamping).
  virtual void get_rx_buffer_status(uint8_t &reported_len, uint8_t &rx_offset) = 0;
  /// Read `len` bytes from the RX buffer starting at `offset`.
  virtual void read_rx_buffer(uint8_t offset, uint8_t *data, uint8_t len) = 0;
  /// Issue the SetTx opcode with the fixed TX timeout — identical 3-byte payload on both chips,
  /// differing only in opcode/transport, so this stays a thin chip-specific wrapper.
  virtual void start_tx() = 0;
  /// Populate the RadioCaptureInfo from chip-specific telemetry (RSSI opcode, packet-status byte,
  /// and IRQ-word-width narrowing all differ per chip).
  virtual 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) = 0;
 
  /// @brief Hook run immediately before every `SetTx`. No-op by default; LR1121 overrides this to
  /// apply its high-ACP TX-quality workaround, which Semtech's own reference applies unconditionally
  /// before every SetRx/SetTx.
  virtual void before_tx_arm() {}
  /// @brief Hook run as part of @ref reset_rx_state_, before re-entering RX. No-op by default;
  /// SX1262 overrides this to (re-)write its buffer base address, which LR1121 doesn't need.
  virtual void configure_buffer_base() {}
  /// @brief Hook run from @ref rearm_rx_after_tx_, after a transmission and before re-entering RX.
  /// No-op by default.
  ///
  /// SX1262 has a real address split written once at init (@ref configure_buffer_base): TX always
  /// builds at its own base, RX always lands at a different one, so nothing a transmission wrote
  /// can ever appear where a length-driven receive (@ref early_rx_read_offset) later reads from.
  /// LR1121 has no such split — one shared 256-byte buffer for both directions, and `WriteBuffer`
  /// always starts from the buffer base (see `write_buffer_`'s doc comment) — so after every LR1121
  /// transmission, the offset a length-driven receive will read from holds a real, CRC-valid,
  /// UART-encoded copy of the hub's own last-sent frame. That is not noise: if
  /// `early_rx_read_offset()`'s offset guess ever turns out to be wrong, reading that residue back
  /// would pass every stage of `try_early_completion_()` and hand back the hub's own transmission as
  /// a phantom received packet — worse than doing nothing, since `check_for_packet()` would then
  /// tear down and re-arm RX (issue #81's `force_standby` path) over whatever real reception was
  /// actually in progress. RadioLR1121 overrides this to overwrite that offset with a few
  /// non-frame-shaped bytes after every TX, so a wrong offset guess degrades back to reading genuine
  /// garbage — which correctly fails the length-driven receive's stage 1 or stage 3 — instead of a
  /// valid-looking phantom frame.
  virtual void invalidate_stale_rx_content_after_tx() {}
 
 private:
  // === wait_for_packet/check_for_packet state-machine helpers (private) ===
  /// Poll for first *terminal* radio activity (IRQ pin or an IRQ status bit within
  /// @ref activity_irq_mask) within timeout.
  bool poll_until_activity_(uint32_t start, uint32_t timeout_ms, uint32_t &irq);
  /// Resolve the SYNC_WORD_VALID → RX_DONE race condition common to both chips, and — on a chip
  /// that opts into @ref early_rx_read_offset — give the length-driven receive its chance first.
  /// @param early_completed Set when a whole CRC-valid frame was recovered without waiting for
  ///   RX_DONE; `packet` is then already populated and the caller is done.
  bool resolve_sync_race_(uint32_t start, uint32_t timeout_ms, uint32_t &irq, RadioRxPacket &packet,
                          bool &early_completed);
  /// Finish a reception on the frame's own air time rather than on the chip's fixed-length
  /// RX_DONE. Returns true only when a CRC-valid frame was recovered.
  bool try_early_completion_(RadioRxPacket &packet, uint32_t sync_us, uint32_t irq_status, uint32_t start_ms,
                             uint32_t timeout_ms);
  /// Finalize receive: read the packet if RX_DONE is set, otherwise record failure.
  bool finalize_receive_(RadioRxPacket &packet, uint32_t irq);
 
  uint16_t response_preamble_;
  uint16_t post_tx_settle_us_;
  uint32_t busy_timeout_ms_;
 
  /// @brief Whether `PreambleDetected` was latched at the exact moment a dwell's
  /// `poll_until_activity_()` gave up waiting, captured before `reset_rx_state_()` wipes the IRQ
  /// word out from under it.
  ///
  /// `PreambleDetected` is deliberately excluded from @ref activity_irq_mask (a bare preamble must
  /// not look like terminal activity), and that exclusion is exactly why a dwell *can* time out
  /// while the bit is still latched — the timeout branch has no way to notice, since
  /// activity_irq_mask() never told it to look. What happens next is a separate problem:
  /// `reset_rx_state_()` runs immediately afterward and clears the whole IRQ word, so a live
  /// re-read a few tens of microseconds later (in `listen()`'s `preamble_or_sync_incoming()` guard)
  /// would need the chip to re-observe a fresh preamble from scratch — which takes a little longer
  /// on a chip with a longer preamble-detector length — and it almost never has done so by the time
  /// the guard asks. This flag is the only way that information survives the reset long enough for
  /// the guard to read it.
  ///
  /// `is_sync_detected()` needs no equivalent snapshot — not because no path clears sync before a
  /// timeout (`resolve_sync_race_()` does exactly that: it clears `SYNC_WORD_VALID` up front once a
  /// reception is underway, and can still time out later waiting for RX_DONE), but because that
  /// path never calls `reset_rx_state_()` on its way out. Whatever `PreambleDetected` state existed
  /// going into it survives untouched, which is all the guard actually depends on there.
  ///
  /// Lifetime is bounded to a single `poll_until_activity_()` call so a stale detection can never
  /// suppress a later, unrelated hop: every exit from that function's loop sets this flag from
  /// scratch (true only on the timeout branch, and only when the bit was actually set on that exact
  /// read), and @ref is_preamble_detected consumes (clears) it the moment it is read as true.
  bool preamble_latched_at_timeout_{false};
};
 
}  // namespace home_io_control
}  // namespace esphome