radio_lr1121.h

Go to the documentation of this file.

#pragma once
 
/// @file radio_lr1121.h
/// @brief LR1121 radio driver for IO-Homecontrol.
/// @ingroup hioc_radio
///
/// Implements the RadioDriver interface for the Semtech LR1121 transceiver on the
/// LilyGo T3-S3 board. Like the SX1262, the LR1121 has no hardware equivalent of the
/// SX1276's IoHomeOn framing, so this driver reuses the shared software PHY
/// (`radio_soft_phy.h`) wholesale: software UART bit-encoding on TX, a UART-decode
/// probe with CRC-CCITT validation on RX, fixed-length GFSK packets, software CRC.
/// This is a re-plumbed RadioSX1262 with a different SPI command set, not a new
/// bring-up from first principles. The IRQ-driven RX/TX orchestration
/// this driver shares with RadioSX1262 lives in SoftPhyDriverBase (see
/// radio_soft_phy_driver_base.h).
///
/// The chip-level difference from the SX1262 that actually changes the driver's
/// shape is the SPI transport: the LR1121 uses 16-bit opcodes and a two-transaction
/// command/response protocol (write opcode+params, wait BUSY, then a second
/// transaction clocks out a status byte + response), instead of the SX1262's
/// single-transaction opcode+NOP-then-data pattern.
///
/// Hardware bring-up (2026-08) confirmed this driver end-to-end against a real Somfy Sunea IO
/// awning motor: authenticated open/close/stop exchanges complete reliably, with correct
/// position/state feedback decoded from the device's real responses. Every constant below is
/// therefore hardware-verified unless its own comment says otherwise.
 
#include "radio_soft_phy_driver_base.h"
#include "esphome/core/hal.h"
 
#include <cstddef>
 
namespace esphome {
namespace home_io_control {
 
// ============================================================================
// LR1121 Opcode Constants (16-bit)
// ============================================================================
//
// The opcodes below marked "cross-checked" were verified against Semtech's SWDR001 driver and
// RadioLib's LR11x0_commands.h before first use, rather than inferred from observed traffic.
 
static constexpr uint16_t LR1121_CMD_GET_STATUS = 0x0100;   ///< cross-checked
static constexpr uint16_t LR1121_CMD_GET_VERSION = 0x0101;  ///< cross-checked
static constexpr uint16_t LR1121_CMD_GET_ERRORS = 0x010D;   ///< cross-checked (2-byte response)
static constexpr uint16_t LR1121_CMD_CLEAR_ERRORS =
    0x010E;  ///< hardware-verified (called on every init/RX cycle, never rejected — see log_command_status_())
static constexpr uint16_t LR1121_CMD_WRITE_BUFFER = 0x0109;  ///< cross-checked
static constexpr uint16_t LR1121_CMD_READ_BUFFER = 0x010A;   ///< cross-checked
static constexpr uint16_t LR1121_CMD_WRITE_REG_MEM_MASK32 =
    0x010C;  ///< cross-checked (Semtech SWDR001 lr11xx_radio.c / RadioLib LR11x0_commands.h)
static constexpr uint16_t LR1121_CMD_CALIBRATE = 0x010F;        ///< cross-checked
static constexpr uint16_t LR1121_CMD_CALIBRATE_IMAGE = 0x0111;  ///< cross-checked (RadioLib calibrateImageRejection)
static constexpr uint16_t LR1121_CMD_SET_DIO_AS_RF_SWITCH = 0x0112;  ///< cross-checked
static constexpr uint16_t LR1121_CMD_SET_DIO_IRQ_PARAMS = 0x0113;    ///< cross-checked
static constexpr uint16_t LR1121_CMD_CLEAR_IRQ = 0x0114;             ///< cross-checked
static constexpr uint16_t LR1121_CMD_SET_TCXO_MODE = 0x0117;         ///< cross-checked
static constexpr uint16_t LR1121_CMD_SET_STANDBY = 0x011C;           ///< cross-checked
static constexpr uint16_t LR1121_CMD_GET_RX_BUFFER_STATUS = 0x0203;  ///< cross-checked
static constexpr uint16_t LR1121_CMD_GET_PKT_STATUS =
    0x0204;  ///< cross-checked (Semtech SWDR001 lr11xx_radio.c :: lr11xx_radio_get_gfsk_pkt_status —
             ///< 0 request params, 4-byte GFSK response: [rssi_sync, rssi_avg, rx_len, status_flags],
             ///< rssi_sync/avg both decode via -(raw>>1) dBm, same formula as LR1121_CMD_GET_RSSI_INST)
static constexpr uint16_t LR1121_CMD_GET_RSSI_INST = 0x0205;            ///< cross-checked
static constexpr uint16_t LR1121_CMD_SET_GFSK_SYNC_WORD = 0x0206;       ///< cross-checked
static constexpr uint16_t LR1121_CMD_SET_RX = 0x0209;                   ///< cross-checked
static constexpr uint16_t LR1121_CMD_SET_TX = 0x020A;                   ///< cross-checked
static constexpr uint16_t LR1121_CMD_SET_RF_FREQUENCY = 0x020B;         ///< cross-checked
static constexpr uint16_t LR1121_CMD_SET_PACKET_TYPE = 0x020E;          ///< cross-checked
static constexpr uint16_t LR1121_CMD_SET_MODULATION_PARAMS = 0x020F;    ///< cross-checked
static constexpr uint16_t LR1121_CMD_SET_PACKET_PARAMS = 0x0210;        ///< cross-checked
static constexpr uint16_t LR1121_CMD_SET_TX_PARAMS = 0x0211;            ///< cross-checked
static constexpr uint16_t LR1121_CMD_SET_RX_TX_FALLBACK_MODE = 0x0213;  ///< cross-checked
static constexpr uint16_t LR1121_CMD_SET_PA_CONFIG = 0x0215;            ///< cross-checked
 
// ============================================================================
// LR1121 IRQ Bit Masks (32-bit word)
// ============================================================================
// Bit positions are cross-checked against RadioLib and the LR1121 datasheet.
 
static constexpr uint32_t LR1121_IRQ_TX_DONE = 1UL << 2;
static constexpr uint32_t LR1121_IRQ_RX_DONE = 1UL << 3;
static constexpr uint32_t LR1121_IRQ_PREAMBLE_DETECTED = 1UL << 4;
static constexpr uint32_t LR1121_IRQ_SYNC_WORD_VALID = 1UL << 5;
static constexpr uint32_t LR1121_IRQ_CRC_ERR = 1UL << 7;
static constexpr uint32_t LR1121_IRQ_TIMEOUT = 1UL << 10;
 
/// IRQ bits that represent a *terminal* radio event — a frame finished decoding, an outbound
/// frame completed, or the chip gave up on its own. Deliberately excludes PREAMBLE_DETECTED,
/// even though it's part of LR1121_IRQ_DIO_ENABLE_MASK: a preamble alone means a frame may
/// still be arriving, so SoftPhyDriverBase's poll_until_activity_()/check_for_packet() (gated by
/// @ref RadioLR1121::activity_irq_mask) must not treat it as terminal — doing so would tear down
/// RX mid-reception.
static constexpr uint32_t LR1121_IRQ_ACTIVITY_MASK =
    LR1121_IRQ_TX_DONE | LR1121_IRQ_RX_DONE | LR1121_IRQ_SYNC_WORD_VALID | LR1121_IRQ_CRC_ERR | LR1121_IRQ_TIMEOUT;
 
/// DIO-routed IRQ enable mask: TxDone|RxDone|PreambleDetected|SyncWordValid|Timeout.
/// Deliberately excludes CrcErr from the DIO-routed set, unlike SX1262; CrcErr is still visible
/// in the raw status word for capture diagnostics.
static constexpr uint32_t LR1121_IRQ_DIO_ENABLE_MASK = LR1121_IRQ_TX_DONE | LR1121_IRQ_RX_DONE |
                                                       LR1121_IRQ_PREAMBLE_DETECTED | LR1121_IRQ_SYNC_WORD_VALID |
                                                       LR1121_IRQ_TIMEOUT;
 
// ============================================================================
// LR1121 chip identity / GFSK / packet constants
// ============================================================================
 
static constexpr uint8_t LR1121_DEVICE_TYPE = 0x03;  ///< cross-checked against RadioLib and the datasheet
 
// GetErrors bit masks — Semtech's SWTL001 `lr11xx_system_errors_e`. Bits 8+ are undocumented there.
static constexpr uint16_t LR1121_ERR_LF_RC_CALIB = 0x0001;    ///< Low-frequency RC oscillator calibration failed.
static constexpr uint16_t LR1121_ERR_HF_RC_CALIB = 0x0002;    ///< High-frequency RC oscillator calibration failed.
static constexpr uint16_t LR1121_ERR_ADC_CALIB = 0x0004;      ///< ADC calibration failed.
static constexpr uint16_t LR1121_ERR_PLL_CALIB = 0x0008;      ///< PLL calibration failed.
static constexpr uint16_t LR1121_ERR_IMG_CALIB = 0x0010;      ///< Image calibration failed.
static constexpr uint16_t LR1121_ERR_HF_XOSC_START = 0x0020;  ///< High-frequency crystal/TCXO failed to start.
static constexpr uint16_t LR1121_ERR_LF_XOSC_START = 0x0040;  ///< Low-frequency crystal failed to start.
static constexpr uint16_t LR1121_ERR_PLL_LOCK = 0x0080;       ///< PLL failed to lock.
 
/// @brief Expand a GetErrors word into a human-readable `NAME|NAME|...` string.
/// @param errors Raw GetErrors bitmask.
/// @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 lr1121_format_device_errors(uint16_t errors, char *buf, size_t buf_size);
 
/// Newest LR1121 transceiver firmware known at the time this file was last updated, per the
/// version-numbered filenames and CHANGELOG.md at
/// https://github.com/Lora-net/radio_firmware_images/tree/master/lr1121/transceiver — the same
/// two bytes GetVersion reports as fw_major/fw_minor (e.g. `lr1121_transceiver_0104.bin` is
/// major=0x01, minor=0x04). Deliberately NOT queried live (baked in, per design decision) — this
/// is a point-in-time snapshot that will go stale as Semtech ships new firmware, and needs a
/// manual refresh here when it does.
///
/// Last checked 2026-08-05: latest is 0x0104 (2026-04-01), which per that changelog fixes
/// CVE-2025-14857/-14858/-14859 (see https://www.semtech.com/company/security/security-bulletins)
/// on top of earlier feature/bugfix releases — not just a cosmetic version bump.
///
/// Reachability caveat: this project's `lr1121_firmware_update:` feature (docs/lr1121-firmware.md)
/// can flash any published image, but 0x0104 requires bootloader 0x2101. Reaching it from the
/// common 0x2100 bootloader needs the separate, opt-in bootloader rewrite (ADR 0021) — an
/// irreversible operation gated behind its own arming switch — so without that opted in, 0x0103
/// is the practical ceiling. The "update available" line below can therefore point at a version
/// that is not reachable on a given chip as currently configured; the flash feature's own
/// boot-time bootloader-version report is what tells a user which case they are in.
static constexpr uint8_t LR1121_KNOWN_LATEST_FW_MAJOR = 0x01;
static constexpr uint8_t LR1121_KNOWN_LATEST_FW_MINOR = 0x04;
 
/// Pure comparison against the known-latest constants above — no I/O, host-testable. Only ever
/// flags a version as outdated when it is strictly older than what this file knows about;
/// versions equal to or newer than LR1121_KNOWN_LATEST_FW_* (including any real future firmware
/// this snapshot predates) are never flagged, so a stale baked-in constant fails silent rather
/// than crying wolf.
[[nodiscard]] constexpr bool lr1121_firmware_is_outdated(uint8_t fw_major, uint8_t fw_minor) {
  return (fw_major < LR1121_KNOWN_LATEST_FW_MAJOR) ||
         (fw_major == LR1121_KNOWN_LATEST_FW_MAJOR && fw_minor < LR1121_KNOWN_LATEST_FW_MINOR);
}
 
static constexpr uint8_t LR1121_PACKET_TYPE_GFSK = 0x01;          ///< cross-checked against RadioLib
static constexpr uint8_t LR1121_GFSK_CRC_OFF = 0x01;              ///< cross-checked (same encoding as SX126x)
static constexpr uint8_t LR1121_GFSK_PACKET_FIXED_LENGTH = 0x00;  ///< cross-checked (same encoding as SX126x)
/// Preamble detector length selector: 16 bits. Shares the SX126x GFSK preamble-detector enum
/// (0x00 off, 0x04=8bit, 0x05=16bit, 0x06=24bit, 0x07=32bit) — the LR11xx sub-GHz GFSK modem
/// descends from the same core.
static constexpr uint8_t LR1121_PREAMBLE_DETECTOR_16_BIT = 0x05;
/// Sync word length: 24 bits, encoded as a literal bit count — cross-checked, identical encoding
/// to SX1262's SX1262_SYNC_WORD_PARAM_24_BITS.
static constexpr uint8_t LR1121_SYNC_WORD_PARAM_24_BITS = 0x18;
 
/// Calibrate "all blocks" bitmask. LR11xx calibration blocks are LF-RC(0)/HF-RC(1)/PLL(2)/
/// ADC(3)/IMG(4)/PLL-TX(5), so "all" = 0x3F — NOT the SX126x value (0x7F), which uses a
/// different bit layout for a different chip.
static constexpr uint8_t LR1121_CALIBRATE_ALL_BLOCKS = 0x3F;
 
/// SetRxTxFallbackMode value for STDBY_XOSC. LR11xx fallback-mode is a small sequential enum
/// (FS=0x00, STDBY_RC=0x01, STDBY_XOSC=0x02), unlike SX126x's raw standby-mode byte (0x30)
/// reused directly in that field.
static constexpr uint8_t LR1121_FALLBACK_STDBY_XOSC = 0x02;
 
/// Offset a reception is written to in the LR1121's data buffer.
///
/// Unlike the SX1262 there is no SetBufferBaseAddress on this chip — the whole 256-byte buffer is
/// one area whose pointers the chip manages, and a fresh reception after SetRx starts at the
/// bottom of it (the same buffer model @ref RadioLR1121::write_buffer_'s own doc comment records
/// for the TX direction). Used as the read offset for the length-driven receive; see
/// @ref RadioLR1121::early_rx_read_offset.
static constexpr uint8_t LR1121_RX_BUFFER_BASE = 0x00;
 
// ============================================================================
// Vendor errata / calibration workaround registers — Semtech's own driver (lr11xx_radio.c) and
// RadioLib both apply these unconditionally. Register addresses/masks/values are byte-for-byte
// matches to `lr11xx_radio_apply_high_acp_workaround` and `lr11xx_workaround_gfsk_reset`.
// ============================================================================
 
/// High-ACP (adjacent channel power) TX-quality erratum: clear bit 30 of this register before
/// every SetRx/SetTx. Without it the chip's TX spectrum has excess spectral regrowth — plausibly
/// why our own (tolerant) monitors decode our frames byte-exact while the awning's spec-compliant
/// receiver mostly can't.
static constexpr uint32_t LR1121_REG_HIGH_ACP_WORKAROUND_ADDR = 0x00F30054;
static constexpr uint32_t LR1121_REG_HIGH_ACP_WORKAROUND_MASK = 1UL << 30;
static constexpr uint32_t LR1121_REG_HIGH_ACP_WORKAROUND_VALUE = 0x00000000;
 
/// GFSK modulation workaround register trio, standard (non-0.6/1.2kbps) values for our 38.4kbps
/// config — applied after every modulation-params write, mirroring RadioLib's workaroundGFSK()
/// ("always the first step, even when resetting" per its own comment on the first write).
static constexpr uint32_t LR1121_REG_GFSK_WORKAROUND_1_ADDR = 0x00F20344;
static constexpr uint32_t LR1121_REG_GFSK_WORKAROUND_1_MASK = 0x00000030;
static constexpr uint32_t LR1121_REG_GFSK_WORKAROUND_1_VALUE = 0x00000010;
static constexpr uint32_t LR1121_REG_GFSK_WORKAROUND_2_ADDR = 0x00F20348;
static constexpr uint32_t LR1121_REG_GFSK_WORKAROUND_2_MASK = 0x00000005;
static constexpr uint32_t LR1121_REG_GFSK_WORKAROUND_2_VALUE = 0x00000001;
static constexpr uint32_t LR1121_REG_GFSK_WORKAROUND_3_ADDR = 0x00F20244;
static constexpr uint32_t LR1121_REG_GFSK_WORKAROUND_3_MASK = 0x0001FF03;
static constexpr uint32_t LR1121_REG_GFSK_WORKAROUND_3_VALUE = 0x00000A01;
 
/// Banded image calibration for 868.25-869.85MHz +/-4MHz (~860-876MHz), matching RadioLib's
/// setFrequency() margin. CalibImage params are {floor((fmin-1)/4), ceil((fmax+1)/4)}.
static constexpr uint8_t LR1121_IMAGE_CAL_FREQ1 = 0xD7;
static constexpr uint8_t LR1121_IMAGE_CAL_FREQ2 = 0xDB;
 
// ============================================================================
// T3-S3 RF-switch table — sourced from the Meshtastic `tlora_t3s3_v1` variant's rfswitch.h,
// cross-checked against LilyGo's own T3-S3 LR1121 example and confirmed on real hardware.
// ============================================================================
//
// SetDioAsRfSwitch parameter layout: [enable_mask, standby, rx, tx, tx_hp, tx_hf, gnss, wifi]
// (8 bytes total), matching RadioLib's Lr11x0::setDioAsRfSwitch() signature. Each mode byte is
// a bitmask of which switch-controlled DIOs (bit0=DIO5, bit1=DIO6, ...) should be driven high
// in that mode.
static constexpr uint8_t LR1121_RFSWITCH_ENABLE_DIO5_DIO6 = 0x03;  ///< DIO5 + DIO6 are switch pins.
static constexpr uint8_t LR1121_RFSWITCH_STANDBY = 0x00;           ///< Both low.
static constexpr uint8_t LR1121_RFSWITCH_RX = 0x01;                ///< DIO5 high.
static constexpr uint8_t LR1121_RFSWITCH_TX = 0x02;                ///< DIO6 high (both LP and HP PA).
static constexpr uint8_t LR1121_RFSWITCH_TX_HP = 0x02;             ///< Same as TX (LP PA only used today).
static constexpr uint8_t LR1121_RFSWITCH_TX_HF = 0x00;             ///< 2.4GHz path unused; both low.
static constexpr uint8_t LR1121_RFSWITCH_GNSS = 0x00;              ///< Unused; both low.
static constexpr uint8_t LR1121_RFSWITCH_WIFI = 0x00;              ///< Unused; both low.
 
/// How long SoftPhyDriverBase::wait_busy_() waits for BUSY to drop before declaring the chip
/// failed. The LR11xx runs an internal boot ROM after reset before BUSY is meaningful —
/// cross-checked against RadioLib's LRxxxx::reset(), which waits ~300ms ("typical transition
/// duration should be 273 ms") and then polls BUSY with a 3s timeout; matched here exactly rather
/// than picking an arbitrary shorter value, since the only cost of a longer timeout is on the
/// already-failing path (a genuinely dead chip takes a few seconds longer to report failure).
/// Much longer than SX1262's (see SX1262_BUSY_TIMEOUT_MS in radio_sx1262.h) — different chips,
/// different boot behavior, not a value that should be unified.
static constexpr uint32_t LR1121_BUSY_TIMEOUT_MS = 3000;
 
/// LR1121 TCXO voltage on the T3-S3 board — 3.0V, confirmed on real hardware.
static constexpr uint8_t LR1121_TCXO_STARTUP_DELAY_TICKS_MSB = 0x00;
static constexpr uint8_t LR1121_TCXO_STARTUP_DELAY_TICKS_MID = 0x01;
/// 0x140 ticks at 30.52us/tick (32.768kHz RTC) is ~9.8ms (the SX1262's tick base differs, so the
/// same tick count means a different time there) — harmless either way, since a longer startup is safe.
static constexpr uint8_t LR1121_TCXO_STARTUP_DELAY_TICKS_LSB = 0x40;
 
// ============================================================================
// LR1121 Radio Driver
// ============================================================================
 
/// @brief LR1121 implementation of RadioDriver.
/// @ingroup hioc_radio
///
/// Manages the LR1121 via 16-bit-opcode, two-transaction SPI using the SpiAccess
/// interface. Configures the chip in GFSK mode with software CRC-CCITT to match the
/// IO-Homecontrol protocol (the LR1121, like 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 LR1121-specific register/opcode encoding
/// underneath it. See the file header for the driver's relationship to RadioSX1262.
class RadioLR1121 : public SoftPhyDriverBase {
 public:
  RadioLR1121(SpiAccess *spi, InternalGPIOPin *rst_pin, InternalGPIOPin *irq_pin, InternalGPIOPin *busy_pin,
              uint8_t tx_power, uint8_t tcxo_voltage_code)
      : SoftPhyDriverBase(rst_pin, busy_pin, LR1121_BUSY_TIMEOUT_MS, LR1121_RESPONSE_PREAMBLE,
                          LR1121_POST_TX_SETTLE_US),
        spi_(spi),
        irq_pin_(irq_pin),
        tx_power_(tx_power),
        tcxo_voltage_code_(tcxo_voltage_code) {}
 
  /// @copydoc RadioDriver::init
  bool init() override;
  /// @brief Apply LR1121 runtime tuning: RX bandwidth, response preamble, post-TX settle delay.
  void apply_tuning(const TuningConfig &tuning) override {
    this->set_rx_bandwidth_(tuning.lr1121_rx_bandwidth);
    this->set_response_preamble_(tuning.lr1121_response_preamble);
    this->set_post_tx_settle_us_(tuning.lr1121_post_tx_settle_us);
  }
  // The chip constants below are code spans, not \ref: doxygen 1.18 can't resolve \ref to them
  // in a whole-project build (details in proto_sizes.h). Autolinking still links them.
  /// @brief Per-channel dwell for a rotating listen (LR1121).
  ///
  /// See `LR1121_DISCOVERY_HOP_SLICE_MS` for why this is measured independently rather than
  /// inherited from SX1262, and `SX1262_DISCOVERY_HOP_SLICE_MS` for the shared short-dwell
  /// reasoning. Governs discovery and the broadcast roll-call alike (see
  /// @ref RadioDriver::hop_dwell_ms). The value comes from the user-facing
  /// `lr1121_discovery_hop_slice_ms` tuning field.
  [[nodiscard]] uint16_t hop_dwell_ms(const TuningConfig &tuning) const override {
    return tuning.lr1121_discovery_hop_slice_ms;
  }
  /// @brief TX→RX turnaround capability (LR1121): slow, same as SX1262.
  ///
  /// See @ref RadioSX1262::has_fast_tx_rx_turnaround for the rationale — the LR1121 needs
  /// the same standby/settle cycle between TX and RX.
  [[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 "lr1121"; }
  /// @brief Dump LR1121-specific debug info.
  void dump_debug() override;
 
 protected:
  // --- Tuning helper unique to this chip (its RX-bandwidth enum is not shared with SX1262 —
  // see tuning_config.h's LR1121RxBandwidth comment: two of the five borrowed SX1262 byte values
  // turned out wrong for this chip during 2026-07-17 bring-up) ---
  /// Apply the RX bandwidth selector and rewrite the modulation parameters.
  void set_rx_bandwidth_(LR1121RxBandwidth bandwidth);
 
  // --- SPI communication (16-bit opcode, two-transaction) ---
  /// Write-only command: opcode + params, single NSS cycle.
  /// @param opcode LR1121 16-bit opcode.
  /// @param params Pointer to parameter buffer (may be nullptr).
  /// @param len Parameter length.
  void write_command_(uint16_t opcode, const uint8_t *params, uint8_t len);
  /// Read-type command: write transaction, wait BUSY, then a second NSS cycle clocks out
  /// a Stat1 status byte followed by `out_len` response bytes.
  /// @param opcode LR1121 16-bit opcode.
  /// @param params Pointer to request parameter buffer (may be nullptr).
  /// @param params_len Request parameter length.
  /// @param out Output buffer for the response bytes (excludes Stat1).
  /// @param out_len Number of response bytes to read.
  void read_command_(uint16_t opcode, const uint8_t *params, uint8_t params_len, uint8_t *out, uint8_t out_len);
  /// Write into the LR1121 TX buffer (always from the chip's internal write pointer, which
  /// resets to the buffer base for a fresh WriteBuffer sequence — unlike SX1262 there is no
  /// separate offset parameter here).
  void write_buffer_(const uint8_t *data, uint8_t len);
  /// Read from the LR1121 RX buffer at a given offset (as reported by GetRxBufferStatus).
  void read_buffer_(uint8_t offset, uint8_t len, uint8_t *data);
  /// Log a warning if the most recently observed Stat1 command-status byte indicates the
  /// chip rejected the previous command (a FAIL or PERR command-status code in Stat1).
  void log_command_status_(uint16_t opcode) const;
  /// WriteRegMemMask32: read-modify-write a 32-bit register through `mask`/`value`. Used by the
  /// vendor errata workarounds below; opcode 0x010C.
  void write_reg_mem_mask32_(uint32_t addr, uint32_t mask, uint32_t value);
  /// Apply the Semtech high-ACP TX-quality erratum workaround. Must run before
  /// every SetRx/SetTx — called from set_mode_rx() and @ref before_tx_arm rather than once at
  /// init, mirroring Semtech's own call sites.
  void apply_high_acp_workaround_();
  /// Apply the GFSK modulation workaround register trio. Called at the end of
  /// write_modulation_params_() so it re-applies on every bandwidth retune too.
  void apply_gfsk_workaround_();
  /// Issue a banded image calibration for the 868MHz operating range.
  void calibrate_image_();
 
  // --- Radio configuration ---
  /// Full radio initialization (called from init()).
  void configure_radio_();
  /// @copydoc SoftPhyDriverBase::set_frequency_register
  ///
  /// Plain Hz, 32-bit — no PLL-step conversion needed on this chip.
  void set_frequency_register(uint32_t freq_hz) override;
  /// Configure GFSK packet parameters (preamble, payload length, CRC).
  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 LR1121 modulation parameters.
  void write_modulation_params_();
  /// @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, LR1121_GFSK_PACKET_FIXED_LENGTH, LR1121_GFSK_CRC_OFF);
  }
  /// @copydoc SoftPhyDriverBase::clear_irq_status
  void clear_irq_status(uint32_t irq_mask) override;
  /// @brief Read device error flags (for diagnostics only — see dump_debug()).
  /// @return Error bitmask (2-byte response, cross-checked against RadioLib).
  uint16_t get_errors_();
  /// @brief Clear device error flags. Called both during init (after TCXO configuration, before
  ///        calibration) and at the end of configure_radio_(), which records them first.
  void clear_errors_();
  /// @copydoc SoftPhyDriverBase::fill_capture_info
  ///
  /// Note: RadioCaptureInfo::irq_status is uint16_t; the 32-bit IRQ word is mapped down by
  /// taking bits [2..10] and shifting right by 2.
  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;
 
  /// IRQ pin (DIO9) ISR — sets dio_fired flag. Runs in interrupt context.
  static void gpio_intr(RadioLR1121 *arg);
 
  /// @copydoc SoftPhyDriverBase::read_irq_status_raw
  ///
  /// Reads the raw 32-bit IRQ status word from the radio (via GetStatus).
  uint32_t read_irq_status_raw() override;
  /// @copydoc SoftPhyDriverBase::sync_word_valid_bit
  [[nodiscard]] uint32_t sync_word_valid_bit() const override { return LR1121_IRQ_SYNC_WORD_VALID; }
  /// @copydoc SoftPhyDriverBase::rx_done_bit
  [[nodiscard]] uint32_t rx_done_bit() const override { return LR1121_IRQ_RX_DONE; }
  /// @copydoc SoftPhyDriverBase::tx_done_bit
  [[nodiscard]] uint32_t tx_done_bit() const override { return LR1121_IRQ_TX_DONE; }
  /// @copydoc SoftPhyDriverBase::preamble_detected_bit
  [[nodiscard]] uint32_t preamble_detected_bit() const override { return LR1121_IRQ_PREAMBLE_DETECTED; }
  /// @copydoc SoftPhyDriverBase::activity_irq_mask
  ///
  /// Excludes PREAMBLE_DETECTED, unlike the base's "any bit" default — see
  /// LR1121_IRQ_ACTIVITY_MASK's doc comment for why this chip needs the distinction.
  [[nodiscard]] uint32_t activity_irq_mask() const override { return LR1121_IRQ_ACTIVITY_MASK; }
  /// @copydoc SoftPhyDriverBase::early_rx_read_offset
  ///
  /// Opted in (issue #81). The LR1121's ReadBuffer8 is the same non-destructive, offset-addressed
  /// read the SX1262's is, so the length-driven receive ports unchanged; only the offset differs,
  /// and this chip's has to be reasoned about rather than programmed (see @ref
  /// LR1121_RX_BUFFER_BASE).
  ///
  /// Not yet confirmed against a real LR1121, and deliberately shipped that way: a wrong offset
  /// here is safe, but *not* merely because try_early_completion_() gates on CRC-CCITT. On this
  /// chip's single shared TX/RX buffer, the bytes sitting at a wrong offset right after a
  /// transmission would otherwise be the hub's own last-sent frame — genuinely CRC-valid, not
  /// noise, so the CRC gate alone would not catch it. What actually makes a wrong guess harmless
  /// is @ref invalidate_stale_rx_content_after_tx overwriting that content after every TX, so a
  /// wrong offset degrades to reading real garbage instead — which the CRC gate (or the stage-1
  /// length peek) then correctly rejects, falling through to the RX_DONE path exactly as it does
  /// today. Either way it cannot cost a frame, only the latency saving. `RadioCaptureInfo::rx_offset`
  /// (logged in @ref SoftPhyDriverBase::read_rx_packet under `IOHOME_FRAME_LOG`) carries the
  /// chip's own post-RX_DONE answer if the assumption ever needs checking on hardware.
  [[nodiscard]] int16_t early_rx_read_offset() const override { return LR1121_RX_BUFFER_BASE; }
  /// @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_(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, len, data); }
  /// @copydoc SoftPhyDriverBase::start_tx
  void start_tx() override;
  /// @copydoc SoftPhyDriverBase::before_tx_arm
  ///
  /// High-ACP workaround — Semtech applies this unconditionally before every
  /// SetTx, same as before every SetRx (see set_mode_rx()).
  void before_tx_arm() override { this->apply_high_acp_workaround_(); }
  /// @copydoc SoftPhyDriverBase::invalidate_stale_rx_content_after_tx
  ///
  /// Overwrites the header-peek window at @ref LR1121_RX_BUFFER_BASE with non-frame-shaped bytes
  /// (all-zero: a run of zero bits can never satisfy `decode_uart_probe`'s stop-bit check, so
  /// `soft_phy_peek_frame_length()` fails deterministically on it, not merely with high
  /// probability). `write_buffer_()` always starts from the chip's own buffer base — the same
  /// address `early_rx_read_offset()` reads from — so this needs no separate offset parameter.
  /// Sized to exactly the bytes `try_early_completion_()`'s stage 1 reads, so it stays a single
  /// short SPI write rather than clearing the whole probe window.
  void invalidate_stale_rx_content_after_tx() override {
    uint8_t const zeros[SOFT_PHY_EARLY_HEADER_RAW_BYTES] = {0};
    this->write_buffer_(zeros, sizeof(zeros));
  }
 
 private:
  SpiAccess *spi_;
  InternalGPIOPin *irq_pin_;
  uint8_t tx_power_;
  uint8_t tcxo_voltage_code_;  ///< TCXO_VOLTAGE_OPTIONS code from YAML (1_6V=0x00 .. 3_3V=0x07); the chip's
                               ///< SetTcxoMode voltage code directly. TCXO_VOLTAGE_NONE means no TCXO (bare crystal).
  uint8_t last_stat1_{0};      ///< Most recent Stat1 byte (diagnostics).
  LR1121RxBandwidth rx_bandwidth_{LR1121RxBandwidth::BW_117_3_KHZ};  ///< Runtime-tunable RX bandwidth.
};
 
}  // namespace home_io_control
}  // namespace esphome