radio_sx1276.h

Go to the documentation of this file.

#pragma once
 
/// @file radio_sx1276.h
/// @brief SX1276 radio driver for IO-Homecontrol.
/// @ingroup hioc_radio
///
/// Implements the RadioDriver interface for the Semtech SX1276 transceiver.
/// Configures the chip in FSK mode with the IoHomeOn hardware feature that
/// handles CRC and packet framing specific to the IO-Homecontrol protocol.
 
#include "radio_interface.h"
#include "proto_timing.h"    // LONG_PREAMBLE
#include "radio_soft_phy.h"  // io868_tx_air_time_us(), soft_phy_air_time_us()
#include "esphome/core/hal.h"
 
namespace esphome {
namespace home_io_control {
 
/// `pa_pin` value that routes the output through the PA_BOOST pin; any other value selects the RFO
/// pin. Doubles as the PaSelect bit of REG_PA_CONFIG.
static constexpr uint8_t SX1276_PA_SELECT_PA_BOOST = 0x80;
 
/// Wait after retuning to the TX channel before the clear-channel RSSI reading. The fast-hop PLL
/// relocks in tens of µs, and with RssiSmoothing = 8 samples at the 50 kHz RX bandwidth one RSSI
/// update takes about 40 µs; 250 µs covers both with margin and costs nothing next to a preamble.
/// \todo Confirm on the bench (Heltec V2): time the retune and compare the reading against one
/// taken after a long dwell on the same channel.
static constexpr uint32_t SX1276_CCA_SETTLE_US = 250;
 
// ============================================================================
// SX1276 Register Addresses (subset needed for IO-Homecontrol)
// Full register map: see Semtech SX1276 datasheet or sx1276Regs-Fsk.h
// ============================================================================
 
static constexpr uint8_t REG_FIFO = 0x00;         ///< FIFO read/write access
static constexpr uint8_t REG_OP_MODE = 0x01;      ///< Operating mode (sleep/standby/tx/rx)
static constexpr uint8_t REG_BITRATE_MSB = 0x02;  ///< Bit rate MSB = FXOSC / bitrate
static constexpr uint8_t REG_BITRATE_LSB = 0x03;
static constexpr uint8_t REG_FDEV_MSB = 0x04;  ///< Frequency deviation MSB
static constexpr uint8_t REG_FDEV_LSB = 0x05;
static constexpr uint8_t REG_FRF_MSB = 0x06;  ///< Carrier frequency MSB (freq = FRF * FXOSC / 2^19)
static constexpr uint8_t REG_FRF_MID = 0x07;
static constexpr uint8_t REG_FRF_LSB = 0x08;
static constexpr uint8_t REG_PA_CONFIG = 0x09;        ///< Power amplifier config (pin select + power level)
static constexpr uint8_t REG_PA_RAMP = 0x0A;          ///< PA ramp time and modulation shaping
static constexpr uint8_t REG_LNA = 0x0C;              ///< Low noise amplifier gain and boost
static constexpr uint8_t REG_RX_CONFIG = 0x0D;        ///< Receiver configuration (AFC, AGC, trigger)
static constexpr uint8_t REG_RSSI_CONFIG = 0x0E;      ///< RSSI smoothing
static constexpr uint8_t REG_RX_BW = 0x12;            ///< Receiver bandwidth
static constexpr uint8_t REG_AFC_BW = 0x13;           ///< AFC bandwidth
static constexpr uint8_t REG_AFC_FEI = 0x1A;          ///< AFC auto clear
static constexpr uint8_t REG_PREAMBLE_DETECT = 0x1F;  ///< Preamble detector config
static constexpr uint8_t REG_OSC = 0x24;              ///< Oscillator / clock output
static constexpr uint8_t REG_RSSI_VALUE = 0x11;       ///< Instant RSSI value in FSK mode
static constexpr uint8_t REG_PREAMBLE_MSB = 0x25;     ///< TX preamble length MSB
static constexpr uint8_t REG_PREAMBLE_LSB = 0x26;
static constexpr uint8_t REG_SYNC_CONFIG = 0x27;     ///< Sync word config (size, polarity, enable)
static constexpr uint8_t REG_SYNC_VALUE1 = 0x28;     ///< Sync word byte 1 (registers 0x28-0x2F for bytes 1-8)
static constexpr uint8_t REG_PACKET_CONFIG1 = 0x30;  ///< Packet format, CRC, encoding
static constexpr uint8_t REG_PACKET_CONFIG2 = 0x31;  ///< Packet mode, IoHomeOn, PowerFrame
static constexpr uint8_t REG_PAYLOAD_LENGTH = 0x32;  ///< Max payload length
static constexpr uint8_t REG_FIFO_THRESH = 0x35;     ///< FIFO threshold for TX start condition
static constexpr uint8_t REG_IRQ_FLAGS1 = 0x3E;      ///< IRQ flags: mode ready, preamble detect, etc.
static constexpr uint8_t REG_IRQ_FLAGS2 = 0x3F;      ///< IRQ flags: FIFO full/empty, payload ready, CRC ok
static constexpr uint8_t REG_DIO_MAPPING1 = 0x40;    ///< DIO0-DIO3 pin mapping
static constexpr uint8_t REG_DIO_MAPPING2 = 0x41;    ///< DIO4-DIO5 pin mapping
static constexpr uint8_t REG_VERSION = 0x42;         ///< Chip version (should read 0x12 for SX1276)
static constexpr uint8_t REG_PLLHOP = 0x44;          ///< PLL hop: fast frequency change without standby
static constexpr uint8_t REG_IMAGE_CAL = 0x3B;       ///< Image calibration
 
// SX1276 operating modes (bits [2:0] of REG_OP_MODE)
static constexpr uint8_t MODE_SLEEP = 0x00;
static constexpr uint8_t MODE_STDBY = 0x01;
static constexpr uint8_t MODE_TX = 0x03;
static constexpr uint8_t MODE_RX = 0x05;
static constexpr uint8_t MODE_MASK = 0x07;
 
/// REG_RX_CONFIG as configured: RestartRxOnCollision | AfcAutoOn | AgcAutoOn | RxTrigger=PreambleDetect.
static constexpr uint8_t RX_CONFIG_VALUE = 0x9E;
/// REG_RX_CONFIG bit 5, RestartRxWithPllLock: restarts the receiver chain after a frequency change,
/// which also clears PreambleDetect and re-arms AGC/AFC for the new channel.
static constexpr uint8_t RX_CONFIG_RESTART_RX_WITH_PLL_LOCK = 0x20;
 
/// How long reception_in_progress() holds the idle hop on a channel once PreambleDetect is set:
/// the longest start preamble (LONG_PREAMBLE, 1024 bytes = 213 ms at 38400 bps) plus margin, so
/// the sync word at the end of a wake-up preamble arrives while the receiver is still there.
/// Also the bound on a preamble detection with no frame behind it (noise): after it the hop goes
/// on, and its receiver restart clears the flag.
static constexpr uint32_t SX1276_PREAMBLE_HOLD_US = 250000;
static_assert(SX1276_PREAMBLE_HOLD_US > soft_phy_air_time_us(LONG_PREAMBLE),
              "the preamble hold must outlast the longest start preamble");
 
/// SX1276 crystal oscillator frequency (32 MHz). Used to calculate register values
/// for bitrate, frequency deviation, and carrier frequency.
static constexpr uint32_t FXOSC = 32000000U;
 
// ============================================================================
// SX1276 Radio Driver
// ============================================================================
 
/// @brief SX1276 implementation of RadioDriver.
/// @ingroup hioc_radio
///
/// Manages the SX1276 via SPI using the SpiAccess interface. Configures the chip
/// in FSK mode with IoHomeOn for hardware CRC and IO‑Homecontrol packet framing.
class RadioSX1276 : public RadioDriver {
 public:
  RadioSX1276(SpiAccess *spi, InternalGPIOPin *rst_pin, InternalGPIOPin *dio0_pin, InternalGPIOPin *dio4_pin,
              uint8_t tx_power, uint8_t pa_pin)
      : RadioDriver(rst_pin),
        spi_(spi),
        dio0_pin_(dio0_pin),
        dio4_pin_(dio4_pin),
        tx_power_(tx_power),
        pa_pin_(pa_pin) {}
 
  /// @brief Initialize the SX1276 radio (reset, calibrate, configure registers).
  /// @return true on success; false on failure (e.g., version check).
  bool init() override;
  /// @brief Transmit a frame with specified frequency and preamble.
  /// @param data Pointer to payload bytes.
  /// @param len Payload length.
  /// @param tx_config Transmission config (frequency, preamble).
  /// @return true if transmit succeeded.
  TxResult send_packet(const uint8_t *data, uint8_t len, const RadioTxConfig &tx_config) override;
  /// @brief Blocking wait for a packet with timeout.
  /// @param packet Output: received packet (freq, len, data).
  /// @param timeout_ms Maximum time to wait.
  /// @return true if a packet was received; false on timeout.
  bool wait_for_packet(RadioRxPacket &packet, uint32_t timeout_ms) override;
  /// @brief Non‑blocking check for a received packet (called from loop).
  /// @param packet Output: received packet if any.
  /// @return true if a packet was read; false if no interrupt fired.
  bool check_for_packet(RadioRxPacket &packet) override;
  /// @brief Change RF frequency using fast hop (no standby needed).
  /// @param freq_hz New frequency in Hz.
  void change_frequency(uint32_t freq_hz) override;
  /// @brief Read instantaneous RSSI (dBm) while in RX mode (used for LBT).
  /// @return RSSI in dBm (negative).
  int16_t read_rssi() override;
  /// @copydoc RadioDriver::is_sync_detected
  bool is_sync_detected() override;
  /// @copydoc RadioDriver::is_preamble_detected
  bool is_preamble_detected() override;
  /// @copydoc RadioDriver::reception_in_progress
  ///
  /// Read live from REG_IRQ_FLAGS1 rather than recorded from check_for_packet(): DIO0 carries
  /// PayloadReady only, so this driver's check_for_packet() returns before reading any register
  /// while a frame is still arriving and has nothing to record (issue #81).
  ///
  /// Holds on SyncAddressMatch (the frame itself, bounded by RX_HOP_HOLDOFF_US) and on
  /// PreambleDetect (a start preamble whose sync word is still to come, bounded by
  /// SX1276_PREAMBLE_HOLD_US). The preamble hold is meaningful only because change_frequency()
  /// restarts the receiver, which clears the flag; without that it latches on the first preamble
  /// (or noise) and stays set across hops.
  [[nodiscard]] bool reception_in_progress() override;
  /// @brief Per-channel dwell for a rotating listen (SX1276).
  ///
  /// The SX1276 supports FastHop (PllHop), so frequency changes need no standby transition and a
  /// short slice is enough. Governs discovery and the broadcast roll-call alike (see @ref
  /// RadioDriver::hop_dwell_ms). The value comes from the user-facing
  /// `sx1276_discovery_hop_slice_ms` tuning field.
  [[nodiscard]] uint16_t hop_dwell_ms(const TuningConfig &tuning) const override {
    return tuning.sx1276_discovery_hop_slice_ms;
  }
  /// @brief TX→RX turnaround capability (SX1276): fast.
  ///
  /// The IoHomeOn TX path returns to RX quickly enough that immediate replies
  /// (including the pairing key-confirm 0x33) are caught through the standard
  /// exchange wait — validated by real-hardware pairing on this driver.
  [[nodiscard]] bool has_fast_tx_rx_turnaround() const override { return true; }
  /// @brief Transmit time (SX1276): the preamble, sync word and the IoHomeOn-coded frame at the
  /// protocol line rate — the same waveform the software PHY produces.
  [[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);
  }
  // `SX1276_RESPONSE_PREAMBLE` 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 Preamble for response/continuation frames (SX1276).
  ///
  /// Runtime-tunable; the default and its hardware rationale are documented at
  /// `SX1276_RESPONSE_PREAMBLE`.
  [[nodiscard]] uint16_t response_preamble() const override { return this->response_preamble_; }
  /// @brief Apply SX1276 runtime tuning: RX bandwidth and response preamble.
  void apply_tuning(const TuningConfig &tuning) override {
    this->set_rx_bandwidth_(tuning.sx1276_rx_bandwidth);
    this->set_response_preamble_(tuning.sx1276_response_preamble);
  }
  /// @brief Switch radio into continuous receive mode.
  void set_mode_rx() override;
  /// @brief Switch radio into standby mode.
  void set_mode_standby() override;
  /// @copydoc RadioDriver::chip_name
  [[nodiscard]] const char *chip_name() const override { return "sx1276"; }
  /// @brief Dump radio‑specific debug info to log.
  void dump_debug() override;
 
 protected:
  // --- Tuning helpers (applied via apply_tuning) ---
  /// Apply the RX bandwidth selector to REG_RX_BW and REG_AFC_BW.
  /// @param bandwidth Bandwidth selector enum (register byte written verbatim).
  void set_rx_bandwidth_(SX1276RxBandwidth bandwidth);
  /// Set the preamble length used for response/continuation frames within an exchange.
  /// @param preamble Preamble length in bytes.
  void set_response_preamble_(uint16_t preamble) { this->response_preamble_ = preamble; }
 
  /// The PreambleDetect half of reception_in_progress(): true while a fresh preamble detection is
  /// younger than SX1276_PREAMBLE_HOLD_US.
  bool preamble_hold_();
 
  // --- SPI register access ---
  /// Read an SX1276 register over SPI.
  /// @param reg Register address (7 bits, MSB clear for read).
  /// @return Register value.
  uint8_t read_register_(uint8_t reg);
  /// Write an SX1276 register over SPI.
  /// @param reg Register address (7 bits, MSB set for write).
  /// @param value Byte to write.
  void write_register_(uint8_t reg, uint8_t value);
 
  // --- Radio hardware control ---
  /// Set the operating mode (sleep/standby/tx/rx) and wait for mode completion.
  /// @param mode One of MODE_SLEEP, MODE_STDBY, MODE_TX, or MODE_RX.
  void set_mode_(uint8_t mode);
  /// Perform full radio configuration (called during init).
  void configure_radio_();
  /// Run image calibration routine (required after reset).
  void run_image_cal_();
  /// Wait until FIFO payload is ready (polling for TX/RX readiness).
  /// @param timeout_ms How long to wait.
  /// @param saw_dio0 Output: true if DIO0 fired.
  /// @param irq1 Output: IRQ flags 1.
  /// @param irq2 Output: IRQ flags 2.
  /// @return true if payload ready before timeout; false otherwise.
  bool poll_until_payload_ready_(uint32_t timeout_ms, bool &saw_dio0, uint8_t &irq1, uint8_t &irq2);
  /// Read a packet from the RX FIFO into a buffer.
  /// @param buf Output buffer.
  /// @param buf_size Size of buf.
  /// @return Number of bytes read.
  uint8_t read_fifo_packet_(uint8_t *buf, uint8_t buf_size);
  /// Populate last_capture_ from raw telemetry.
  /// Note: `crc_error` is never set on this driver — in IoHomeOn mode the hardware
  /// silently drops frames with a bad CRC before they reach the FIFO.
  /// @param blocking_wait if this was a blocking receive.
  /// @param irq1 IRQ flags 1.
  /// @param irq2 IRQ flags 2.
  /// @param rssi RSSI value.
  /// @param raw Pointer to raw bytes (may be nullptr).
  /// @param raw_len Length of raw buffer.
  /// @param frame Pointer to parsed frame bytes (may be nullptr).
  /// @param frame_len Length of parsed frame.
  void fill_capture_info_(bool blocking_wait, uint8_t irq1, uint8_t irq2, uint8_t rssi, const uint8_t *raw,
                          uint8_t raw_len, const uint8_t *frame, uint8_t frame_len);
 
  /// DIO0 ISR — sets dio_fired flag. Runs in interrupt context.
  static void gpio_intr(RadioSX1276 *arg);
 
  /// True when TX goes out through PA_BOOST rather than RFO; the PA config and the dump both key on it.
  [[nodiscard]] bool uses_pa_boost_() const { return this->pa_pin_ == SX1276_PA_SELECT_PA_BOOST; }
 
  SpiAccess *spi_;
  InternalGPIOPin *dio0_pin_;
  InternalGPIOPin *dio4_pin_;
  uint8_t tx_power_;
  uint8_t pa_pin_;
  SX1276RxBandwidth rx_bandwidth_{SX1276RxBandwidth::BW_41_7_KHZ};  ///< Runtime-tunable RX bandwidth.
  uint16_t response_preamble_{SX1276_RESPONSE_PREAMBLE};            ///< Runtime-tunable response preamble.
  uint32_t sync_hold_since_us_{0};      ///< First-sighting timestamp for reception_in_progress()'s un-stick bound.
  uint32_t preamble_hold_since_us_{0};  ///< First-sighting timestamp for reception_in_progress()'s preamble hold.
};
 
}  // namespace home_io_control
}  // namespace esphome