SX1276 implementation of RadioDriver. More...

#include <radio_sx1276.h>

Inheritance diagram for esphome::home_io_control::RadioSX1276:

Collaboration diagram for esphome::home_io_control::RadioSX1276:

Public Member Functions
	RadioSX1276 (SpiAccess spi, InternalGPIOPin rst_pin, InternalGPIOPin dio0_pin, InternalGPIOPin dio4_pin, uint8_t tx_power, uint8_t pa_pin)
bool	init () override
	Initialize the SX1276 radio (reset, calibrate, configure registers).
bool	send_packet (const uint8_t *data, uint8_t len, const RadioTxConfig &tx_config) override
	Transmit a frame with specified frequency and preamble.
bool	wait_for_packet (RadioRxPacket &packet, uint32_t timeout_ms) override
	Blocking wait for a packet with timeout.
bool	check_for_packet (RadioRxPacket &packet) override
	Non‑blocking check for a received packet (called from loop).
void	change_frequency (uint32_t freq_hz) override
	Change RF frequency using fast hop (no standby needed).
int16_t	read_rssi () override
	Read instantaneous RSSI (dBm) while in RX mode (used for LBT).
bool	is_sync_detected () override
	Check if sync word has been detected (while in RX).
bool	is_preamble_detected () override
	Check if preamble has been detected (while in RX).
bool	reception_in_progress () override
	True while a frame is arriving on the current channel and retuning would destroy it.
uint16_t	hop_dwell_ms (const TuningConfig &tuning) const override
	Per-channel dwell for a rotating listen (SX1276).
bool	has_fast_tx_rx_turnaround () const override
	TX→RX turnaround capability (SX1276): fast.
uint16_t	response_preamble () const override
	Preamble for response/continuation frames (SX1276).
void	apply_tuning (const TuningConfig &tuning) override
	Apply SX1276 runtime tuning: RX bandwidth and response preamble.
void	set_mode_rx () override
	Switch radio into continuous receive mode.
void	set_mode_standby () override
	Switch radio into standby mode.
bool	is_failed () const override
	Returns true if the radio failed to initialize or encountered a fatal error.
const char *	chip_name () const override
	Get a human‑readable chip name.
void	dump_debug () override
	Dump radio‑specific debug info to log.
Public Member Functions inherited from esphome::home_io_control::RadioDriver
	RadioDriver (InternalGPIOPin *rst_pin=nullptr)
virtual	~RadioDriver ()=default
uint32_t	get_current_freq () const
	Get the current RF frequency.
const RadioCaptureInfo &	get_last_capture () const
	Get the most recent radio capture info.
void	clear_last_capture ()
	Reset the diagnostic capture buffer.
bool	is_dio_fired () const
	Set by the ISR when DIO fires.
void	clear_dio_fired ()
void	mark_dio_fired_from_isr ()

Protected Member Functions
void	set_rx_bandwidth_ (SX1276RxBandwidth bandwidth)
	Apply the RX bandwidth selector to REG_RX_BW and REG_AFC_BW.
void	set_response_preamble_ (uint16_t preamble)
	Set the preamble length used for response/continuation frames within an exchange.
uint8_t	read_register_ (uint8_t reg)
	Read an SX1276 register over SPI.
void	write_register_ (uint8_t reg, uint8_t value)
	Write an SX1276 register over SPI.
void	set_mode_ (uint8_t mode)
	Set the operating mode (sleep/standby/tx/rx) and wait for mode completion.
void	configure_radio_ ()
	Perform full radio configuration (called during init).
void	run_image_cal_ ()
	Run image calibration routine (required after reset).
bool	poll_until_payload_ready_ (uint32_t timeout_ms, bool &saw_dio0, uint8_t &irq1, uint8_t &irq2)
	Wait until FIFO payload is ready (polling for TX/RX readiness).
uint8_t	read_fifo_packet_ (uint8_t *buf, uint8_t buf_size)
	Read a packet from the RX FIFO into a buffer.
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)
	Populate last_capture_ from raw telemetry.
Protected Member Functions inherited from esphome::home_io_control::RadioDriver
void	prepare_blocking_receive_ (RadioRxPacket &packet)
	Common preamble for blocking receive: clear diagnostics and output packet.
void	prepare_nonblocking_receive_ (RadioRxPacket &packet)
	Common preamble for non‑blocking receive: clear diagnostics, output packet, and DIO latch.
void	note_reception_in_progress_ ()
	Record that a frame is arriving right now.
void	clear_reception_in_progress_ ()
	Drop the holdoff: the reception ended, was delivered, or was torn down deliberately.
void	reset_hardware_ ()
	Shared hardware reset sequence for chips with an active-low RST pin.
void	populate_capture_base_ (bool blocking_wait, uint32_t freq_hz, int16_t rssi_dbm, const uint8_t raw, uint8_t raw_len, const uint8_t frame, uint8_t frame_len)
	Populate the common fields of RadioCaptureInfo from raw telemetry.

Static Protected Member Functions
static void	gpio_intr (RadioSX1276 *arg)
	DIO0 ISR — sets dio_fired flag. Runs in interrupt context.

Protected Attributes
SpiAccess *	spi_
InternalGPIOPin *	dio0_pin_
InternalGPIOPin *	dio4_pin_
uint8_t	tx_power_
uint8_t	pa_pin_
bool	failed_ {false}
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.
Protected Attributes inherited from esphome::home_io_control::RadioDriver
uint32_t	current_freq_ {FREQ_CH2}
RadioCaptureInfo	last_capture_ {}
InternalGPIOPin *	rst_pin_ {nullptr}
bool	rx_hold_armed_ {false}
	Idle-hop holdoff latch — see reception_in_progress().
uint32_t	rx_hold_since_us_ {0}
	micros() timestamp the holdoff was last (re-)armed at.
volatile bool	dio_fired_ {false}

Detailed Description

SX1276 implementation of RadioDriver.

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.

Definition at line 78 of file radio_sx1276.h.

Constructor & Destructor Documentation

◆ RadioSX1276()

esphome::home_io_control::RadioSX1276::RadioSX1276	(	SpiAccess *	spi,
		InternalGPIOPin *	rst_pin,
		InternalGPIOPin *	dio0_pin,
		InternalGPIOPin *	dio4_pin,
		uint8_t	tx_power,
		uint8_t	pa_pin )

inline

Definition at line 80 of file radio_sx1276.h.

Here is the call graph for this function:

Member Function Documentation

◆ apply_tuning()

void esphome::home_io_control::RadioSX1276::apply_tuning ( const TuningConfig & tuning )

inlineoverridevirtual

Apply SX1276 runtime tuning: RX bandwidth and response preamble.

Reimplemented from esphome::home_io_control::RadioDriver.

Definition at line 144 of file radio_sx1276.h.

Here is the call graph for this function:

◆ change_frequency()

void esphome::home_io_control::RadioSX1276::change_frequency ( uint32_t freq_hz )

overridevirtual

Change RF frequency using fast hop (no standby needed).

Parameters

freq_hz New frequency in Hz.

Implements esphome::home_io_control::RadioDriver.

Definition at line 90 of file radio_sx1276.cpp.

Here is the call graph for this function:

◆ check_for_packet()

bool esphome::home_io_control::RadioSX1276::check_for_packet ( RadioRxPacket & packet )

overridevirtual

Non‑blocking check for a received packet (called from loop).

Parameters

packet Output: received packet if any.

Returns: true if a packet was read; false if no interrupt fired.

Implements esphome::home_io_control::RadioDriver.

Definition at line 353 of file radio_sx1276.cpp.

Here is the call graph for this function:

◆ chip_name()

const char * esphome::home_io_control::RadioSX1276::chip_name ( ) const

inlinenodiscardoverridevirtual

Get a human‑readable chip name.

Returns: Short lowercase identifier (e.g. "sx1276").

Implements esphome::home_io_control::RadioDriver.

Definition at line 155 of file radio_sx1276.h.

◆ configure_radio_()

void esphome::home_io_control::RadioSX1276::configure_radio_ ( )

protected

Perform full radio configuration (called during init).

Definition at line 159 of file radio_sx1276.cpp.

Here is the call graph for this function:

◆ dump_debug()

void esphome::home_io_control::RadioSX1276::dump_debug ( )

overridevirtual

Dump radio‑specific debug info to log.

Reimplemented from esphome::home_io_control::RadioDriver.

Definition at line 378 of file radio_sx1276.cpp.

Here is the call graph for this function:

◆ fill_capture_info_()

void esphome::home_io_control::RadioSX1276::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 )

protected

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.

Parameters

blocking_wait	if this was a blocking receive.
irq1	IRQ flags 1.
irq2	IRQ flags 2.
rssi	RSSI value.
raw	Pointer to raw bytes (may be nullptr).
raw_len	Length of raw buffer.
frame	Pointer to parsed frame bytes (may be nullptr).
frame_len	Length of parsed frame.

Definition at line 77 of file radio_sx1276.cpp.

Here is the call graph for this function:

◆ gpio_intr()

void IRAM_ATTR esphome::home_io_control::RadioSX1276::gpio_intr ( RadioSX1276 * arg )

staticprotected

DIO0 ISR — sets dio_fired flag. Runs in interrupt context.

Definition at line 75 of file radio_sx1276.cpp.

Here is the call graph for this function:

◆ has_fast_tx_rx_turnaround()

bool esphome::home_io_control::RadioSX1276::has_fast_tx_rx_turnaround ( ) const

inlinenodiscardoverridevirtual

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.

Implements esphome::home_io_control::RadioDriver.

Definition at line 137 of file radio_sx1276.h.

◆ hop_dwell_ms()

uint16_t esphome::home_io_control::RadioSX1276::hop_dwell_ms ( const TuningConfig & tuning ) const

inlinenodiscardoverridevirtual

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 RadioDriver::hop_dwell_ms). The value comes from the user-facing sx1276_discovery_hop_slice_ms tuning field.

Implements esphome::home_io_control::RadioDriver.

Definition at line 129 of file radio_sx1276.h.

◆ init()

bool esphome::home_io_control::RadioSX1276::init ( )

overridevirtual

Initialize the SX1276 radio (reset, calibrate, configure registers).

Returns: true on success; false on failure (e.g., version check).

Implements esphome::home_io_control::RadioDriver.

Definition at line 133 of file radio_sx1276.cpp.

Here is the call graph for this function:

◆ is_failed()

bool esphome::home_io_control::RadioSX1276::is_failed ( ) const

inlinenodiscardoverridevirtual

Returns true if the radio failed to initialize or encountered a fatal error.

Returns: true on failure.

Implements esphome::home_io_control::RadioDriver.

Definition at line 153 of file radio_sx1276.h.

◆ is_preamble_detected()

bool esphome::home_io_control::RadioSX1276::is_preamble_detected ( )

overridevirtual

Check if preamble has been detected (while in RX).

Used together with sync detection to gate frequency hopping.

Implements esphome::home_io_control::RadioDriver.

Definition at line 104 of file radio_sx1276.cpp.

Here is the call graph for this function:

◆ is_sync_detected()

bool esphome::home_io_control::RadioSX1276::is_sync_detected ( )

overridevirtual

Check if sync word has been detected (while in RX).

Used to gate frequency hopping — prevents hopping away mid-frame.

Implements esphome::home_io_control::RadioDriver.

Definition at line 100 of file radio_sx1276.cpp.

Here is the call graph for this function:

◆ poll_until_payload_ready_()

bool esphome::home_io_control::RadioSX1276::poll_until_payload_ready_	(	uint32_t	timeout_ms,
		bool &	saw_dio0,
		uint8_t &	irq1,
		uint8_t &	irq2 )

protected

Wait until FIFO payload is ready (polling for TX/RX readiness).

Parameters

timeout_ms	How long to wait.
saw_dio0	Output: true if DIO0 fired.
irq1	Output: IRQ flags 1.
irq2	Output: IRQ flags 2.

Returns: true if payload ready before timeout; false otherwise.

Definition at line 296 of file radio_sx1276.cpp.

Here is the call graph for this function:

◆ read_fifo_packet_()

uint8_t esphome::home_io_control::RadioSX1276::read_fifo_packet_	(	uint8_t *	buf,
		uint8_t	buf_size )

protected

Read a packet from the RX FIFO into a buffer.

Parameters

buf	Output buffer.
buf_size	Size of buf.

Returns: Number of bytes read.

Definition at line 320 of file radio_sx1276.cpp.

Here is the call graph for this function:

◆ read_register_()

uint8_t esphome::home_io_control::RadioSX1276::read_register_ ( uint8_t reg )

protected

Read an SX1276 register over SPI.

Parameters

reg	Register address (7 bits, MSB clear for read).

Returns: Register value.

Definition at line 24 of file radio_sx1276.cpp.

◆ read_rssi()

int16_t esphome::home_io_control::RadioSX1276::read_rssi ( )

overridevirtual

Read instantaneous RSSI (dBm) while in RX mode (used for LBT).

Returns: RSSI in dBm (negative).

Implements esphome::home_io_control::RadioDriver.

Definition at line 98 of file radio_sx1276.cpp.

Here is the call graph for this function:

◆ reception_in_progress()

bool esphome::home_io_control::RadioSX1276::reception_in_progress ( )

nodiscardoverridevirtual

True while a frame is arriving on the current channel and retuning would destroy it.

Consulted by ExchangeEngine::maybe_hop() — the idle-path hop — which is purely time-gated and otherwise fires on essentially every loop() pass (issue #81). Not consulted by hop_frequency() itself: the blocking listen() loop does its own, differently-shaped gating through preamble_or_sync_incoming(), and a caller that asked for a hop explicitly must get one.

The default implementation is the recorded-state one: a driver reports a reception by calling note_reception_in_progress_() from wherever it can actually observe one, and the holdoff expires by itself after RX_HOP_HOLDOFF_US. That default is correct for any driver whose RX path passes through check_for_packet() while the frame is still arriving, and it is what both software-PHY drivers use. A driver that cannot observe a reception from check_for_packet() overrides this and reads the chip at hop time instead — see RadioSX1276.

Non-const because it expires its own latch, and because an override may do SPI.

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).

Reimplemented from esphome::home_io_control::RadioDriver.

Definition at line 108 of file radio_sx1276.cpp.

Here is the call graph for this function:

◆ response_preamble()

uint16_t esphome::home_io_control::RadioSX1276::response_preamble ( ) const

inlinenodiscardoverridevirtual

Preamble for response/continuation frames (SX1276).

Runtime-tunable; the default and its hardware rationale are documented at SX1276_RESPONSE_PREAMBLE.

Reimplemented from esphome::home_io_control::RadioDriver.

Definition at line 142 of file radio_sx1276.h.

◆ run_image_cal_()

void esphome::home_io_control::RadioSX1276::run_image_cal_ ( )

protected

Run image calibration routine (required after reset).

Definition at line 61 of file radio_sx1276.cpp.

Here is the call graph for this function:

◆ send_packet()

bool esphome::home_io_control::RadioSX1276::send_packet	(	const uint8_t *	data,
		uint8_t	len,
		const RadioTxConfig &	tx_config )

overridevirtual

Transmit a frame with specified frequency and preamble.

Parameters

data	Pointer to payload bytes.
len	Payload length.
tx_config	Transmission config (frequency, preamble).

Returns: true if transmit succeeded.

Implements esphome::home_io_control::RadioDriver.

Definition at line 256 of file radio_sx1276.cpp.

Here is the call graph for this function:

◆ set_mode_()

void esphome::home_io_control::RadioSX1276::set_mode_ ( uint8_t mode )

protected

Set the operating mode (sleep/standby/tx/rx) and wait for mode completion.

Parameters

mode	One of MODE_SLEEP, MODE_STDBY, MODE_TX, or MODE_RX.

Definition at line 41 of file radio_sx1276.cpp.

Here is the call graph for this function:

◆ set_mode_rx()

void esphome::home_io_control::RadioSX1276::set_mode_rx ( )

overridevirtual

Switch radio into continuous receive mode.

Implements esphome::home_io_control::RadioDriver.

Definition at line 58 of file radio_sx1276.cpp.

Here is the call graph for this function:

◆ set_mode_standby()

void esphome::home_io_control::RadioSX1276::set_mode_standby ( )

overridevirtual

Switch radio into standby mode.

Implements esphome::home_io_control::RadioDriver.

Definition at line 59 of file radio_sx1276.cpp.

Here is the call graph for this function:

◆ set_response_preamble_()

void esphome::home_io_control::RadioSX1276::set_response_preamble_ ( uint16_t preamble )

inlineprotected

Set the preamble length used for response/continuation frames within an exchange.

Parameters

preamble Preamble length in bytes.

Definition at line 166 of file radio_sx1276.h.

◆ set_rx_bandwidth_()

void esphome::home_io_control::RadioSX1276::set_rx_bandwidth_ ( SX1276RxBandwidth bandwidth )

protected

Apply the RX bandwidth selector to REG_RX_BW and REG_AFC_BW.

Parameters

bandwidth Bandwidth selector enum (register byte written verbatim).

Definition at line 247 of file radio_sx1276.cpp.

Here is the call graph for this function:

◆ wait_for_packet()

bool esphome::home_io_control::RadioSX1276::wait_for_packet	(	RadioRxPacket &	packet,
		uint32_t	timeout_ms )

overridevirtual

Blocking wait for a packet with timeout.

Parameters

packet	Output: received packet (freq, len, data).
timeout_ms	Maximum time to wait.

Returns: true if a packet was received; false on timeout.

Implements esphome::home_io_control::RadioDriver.

Definition at line 327 of file radio_sx1276.cpp.

Here is the call graph for this function:

◆ write_register_()

void esphome::home_io_control::RadioSX1276::write_register_	(	uint8_t	reg,
		uint8_t	value )

protected

Write an SX1276 register over SPI.

Parameters

reg	Register address (7 bits, MSB set for write).
value	Byte to write.

Definition at line 32 of file radio_sx1276.cpp.

Member Data Documentation

◆ dio0_pin_

InternalGPIOPin* esphome::home_io_control::RadioSX1276::dio0_pin_

protected

Definition at line 216 of file radio_sx1276.h.

◆ dio4_pin_

InternalGPIOPin* esphome::home_io_control::RadioSX1276::dio4_pin_

protected

Definition at line 217 of file radio_sx1276.h.

◆ failed_

bool esphome::home_io_control::RadioSX1276::failed_ {false}

protected

Definition at line 220 of file radio_sx1276.h.

◆ pa_pin_

uint8_t esphome::home_io_control::RadioSX1276::pa_pin_

protected

Definition at line 219 of file radio_sx1276.h.

◆ response_preamble_

uint16_t esphome::home_io_control::RadioSX1276::response_preamble_ {SX1276_RESPONSE_PREAMBLE}

protected

Runtime-tunable response preamble.

Definition at line 222 of file radio_sx1276.h.

◆ rx_bandwidth_

SX1276RxBandwidth esphome::home_io_control::RadioSX1276::rx_bandwidth_ {SX1276RxBandwidth::BW_41_7_KHZ}

protected

Runtime-tunable RX bandwidth.

Definition at line 221 of file radio_sx1276.h.

◆ spi_

SpiAccess* esphome::home_io_control::RadioSX1276::spi_

protected

Definition at line 215 of file radio_sx1276.h.

◆ sync_hold_since_us_

uint32_t esphome::home_io_control::RadioSX1276::sync_hold_since_us_ {0}

protected

First-sighting timestamp for reception_in_progress()'s un-stick bound.

Definition at line 223 of file radio_sx1276.h.

◆ tx_power_

uint8_t esphome::home_io_control::RadioSX1276::tx_power_

protected

Definition at line 218 of file radio_sx1276.h.

The documentation for this class was generated from the following files:

components/home_io_control/radio_sx1276.h
components/home_io_control/radio_sx1276.cpp

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ RadioSX1276()

Member Function Documentation

◆ apply_tuning()

◆ change_frequency()

◆ check_for_packet()

◆ chip_name()

◆ configure_radio_()

◆ dump_debug()

◆ fill_capture_info_()

◆ gpio_intr()

◆ has_fast_tx_rx_turnaround()

◆ hop_dwell_ms()

◆ init()

◆ is_failed()

◆ is_preamble_detected()

◆ is_sync_detected()

◆ poll_until_payload_ready_()

◆ read_fifo_packet_()

◆ read_register_()

◆ read_rssi()

◆ reception_in_progress()

◆ response_preamble()

◆ run_image_cal_()

◆ send_packet()

◆ set_mode_()

◆ set_mode_rx()

◆ set_mode_standby()

◆ set_response_preamble_()

◆ set_rx_bandwidth_()

◆ wait_for_packet()

◆ write_register_()

Member Data Documentation

◆ dio0_pin_

◆ dio4_pin_

◆ failed_

◆ pa_pin_

◆ response_preamble_

◆ rx_bandwidth_

◆ spi_

◆ sync_hold_since_us_

◆ tx_power_