Abstract radio driver for IO-Homecontrol. More...

#include <radio_interface.h>

Inheritance diagram for esphome::home_io_control::RadioDriver:

Collaboration diagram for esphome::home_io_control::RadioDriver:

Public Member Functions
	RadioDriver (InternalGPIOPin *rst_pin=nullptr)
virtual	~RadioDriver ()=default
virtual bool	init ()=0
	Initialize the radio hardware. Returns true on success.
virtual bool	send_packet (const uint8_t *data, uint8_t len, const RadioTxConfig &tx_config)=0
	Send a packet using the specified carrier frequency and preamble settings.
virtual bool	wait_for_packet (RadioRxPacket &packet, uint32_t timeout_ms)=0
	Wait (blocking) for a packet with timeout.
virtual bool	check_for_packet (RadioRxPacket &packet)=0
	Non-blocking check for a received packet.
virtual int16_t	read_rssi ()=0
	Read instantaneous RSSI (in dBm) while in RX mode.
virtual bool	is_sync_detected ()=0
	Check if sync word has been detected (while in RX).
virtual bool	is_preamble_detected ()=0
	Check if preamble has been detected (while in RX).
virtual uint16_t	response_preamble () const
	Return the preamble length for response/continuation frames.
virtual void	apply_tuning (const TuningConfig &tuning)
	Apply runtime tuning parameters to the driver.
virtual uint32_t	exchange_wait_slice_ms () const
	Per-channel dwell while waiting for an authenticated exchange response.
virtual uint16_t	discovery_hop_slice_ms (const TuningConfig &tuning) const =0
	Per-channel dwell while pairing discovery hops across channels.
virtual bool	has_fast_tx_rx_turnaround () const =0
	Whether the chip re-enters RX fast enough after a TX to catch an immediate reply through the standard exchange wait.
virtual void	change_frequency (uint32_t freq_hz)=0
	Change the carrier frequency using fast hop (no standby transition needed).
virtual void	set_mode_rx ()=0
	Switch to continuous receive mode.
virtual void	set_mode_standby ()=0
	Switch to standby mode.
virtual bool	is_failed () const =0
	Returns true if the radio failed to initialize or encountered a fatal error.
virtual const char *	chip_name () const =0
	Get a human‑readable chip name.
virtual void	dump_debug ()
	Optional chip-specific diagnostics emitted from dump_config.
uint32_t	get_current_freq () const
	Get the current RF frequency.
const RadioCaptureInfo &	get_last_capture () const
	Get the most recent radio capture info.
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	clear_last_capture_ ()
	Clear the last capture info (resets diagnostic buffer).
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	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.

Protected Attributes
uint32_t	current_freq_ {FREQ_CH2}
RadioCaptureInfo	last_capture_ {}
InternalGPIOPin *	rst_pin_ {nullptr}
volatile bool	dio_fired_ {false}

Detailed Description

Abstract radio driver for IO-Homecontrol.

Encapsulates all chip-specific operations: initialization, packet TX/RX, frequency control, and mode switching. Concrete implementations (RadioSX1276, RadioSX1262, RadioLR1121) handle the register-level details for each chip.

Definition at line 97 of file radio_interface.h.

Constructor & Destructor Documentation

◆ RadioDriver()

esphome::home_io_control::RadioDriver::RadioDriver ( InternalGPIOPin * rst_pin = nullptr )

inlineexplicit

Definition at line 99 of file radio_interface.h.

◆ ~RadioDriver()

virtual esphome::home_io_control::RadioDriver::~RadioDriver ( )

virtualdefault

Member Function Documentation

◆ apply_tuning()

virtual void esphome::home_io_control::RadioDriver::apply_tuning ( const TuningConfig & tuning )

inlinevirtual

Apply runtime tuning parameters to the driver.

Each driver consumes only the fields it understands; the default is a no-op for chips with no runtime-tunable radio parameters. This keeps the hub free of chip-specific tuning knowledge — it hands over the whole config and lets the driver pick what it needs.

Parameters

tuning Current tuning configuration.

Reimplemented in esphome::home_io_control::RadioLR1121, esphome::home_io_control::RadioSX1262, and esphome::home_io_control::RadioSX1276.

Definition at line 160 of file radio_interface.h.

◆ change_frequency()

virtual void esphome::home_io_control::RadioDriver::change_frequency ( uint32_t freq_hz )

pure virtual

Change the carrier frequency using fast hop (no standby transition needed).

Implemented in esphome::home_io_control::RadioSX1276, and esphome::home_io_control::SoftPhyDriverBase.

◆ check_for_packet()

virtual bool esphome::home_io_control::RadioDriver::check_for_packet ( RadioRxPacket & packet )

pure virtual

Non-blocking check for a received packet.

Called from loop(). Returns true if a packet was read into packet. Contract:

Returns false immediately if no DIO interrupt has fired.
On success: populates packet and last_capture_, returns true.
On failure: may populate last_capture_ for diagnostics, returns false.

Implemented in esphome::home_io_control::RadioSX1276, and esphome::home_io_control::SoftPhyDriverBase.

◆ chip_name()

virtual const char * esphome::home_io_control::RadioDriver::chip_name ( ) const

nodiscardpure virtual

Get a human‑readable chip name.

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

Implemented in esphome::home_io_control::RadioLR1121, esphome::home_io_control::RadioSX1262, and esphome::home_io_control::RadioSX1276.

◆ clear_dio_fired()

void esphome::home_io_control::RadioDriver::clear_dio_fired ( )

inline

Definition at line 229 of file radio_interface.h.

◆ clear_last_capture_()

void esphome::home_io_control::RadioDriver::clear_last_capture_ ( )

inlineprotected

Clear the last capture info (resets diagnostic buffer).

Definition at line 250 of file radio_interface.h.

◆ discovery_hop_slice_ms()

virtual uint16_t esphome::home_io_control::RadioDriver::discovery_hop_slice_ms ( const TuningConfig & tuning ) const

nodiscardpure virtual

Per-channel dwell while pairing discovery hops across channels.

The right dwell is inherently chip-specific — it depends on how fast the chip can retune (fast hop vs. a standby→retune→RX cycle) — so there is no generic default: each driver must return its value, normally from its user-facing tuning field.

Parameters

tuning Current tuning configuration.

Returns: Slice length in milliseconds.

Implemented in esphome::home_io_control::RadioLR1121, esphome::home_io_control::RadioSX1262, and esphome::home_io_control::RadioSX1276.

◆ dump_debug()

virtual void esphome::home_io_control::RadioDriver::dump_debug ( )

inlinevirtual

Optional chip-specific diagnostics emitted from dump_config.

Reimplemented in esphome::home_io_control::RadioLR1121, esphome::home_io_control::RadioSX1262, and esphome::home_io_control::RadioSX1276.

Definition at line 210 of file radio_interface.h.

◆ exchange_wait_slice_ms()

virtual uint32_t esphome::home_io_control::RadioDriver::exchange_wait_slice_ms ( ) const

inlinenodiscardvirtual

Per-channel dwell while waiting for an authenticated exchange response.

The default RESPONSE_CHANNEL_WAIT_MS slice is correct for the baseline protocol flow and pairing. A driver overrides this with a longer dwell when its RX path needs more margin to catch the final post-auth response before hopping away (see the concrete drivers for the chip-specific rationale).

Returns: Slice length in milliseconds.

Reimplemented in esphome::home_io_control::RadioLR1121, and esphome::home_io_control::RadioSX1262.

Definition at line 169 of file radio_interface.h.

◆ get_current_freq()

uint32_t esphome::home_io_control::RadioDriver::get_current_freq ( ) const

inlinenodiscard

Get the current RF frequency.

Returns: Frequency in Hz.

Definition at line 214 of file radio_interface.h.

◆ get_last_capture()

const RadioCaptureInfo & esphome::home_io_control::RadioDriver::get_last_capture ( ) const

inlinenodiscard

Get the most recent radio capture info.

Returns: const reference to RadioCaptureInfo.

Definition at line 217 of file radio_interface.h.

◆ has_fast_tx_rx_turnaround()

virtual bool esphome::home_io_control::RadioDriver::has_fast_tx_rx_turnaround ( ) const

nodiscardpure virtual

Whether the chip re-enters RX fast enough after a TX to catch an immediate reply through the standard exchange wait.

Some chips need a standby/settle cycle between TX and RX, so a device's immediate response (e.g. the pairing key-confirm 0x33) can arrive while the receiver is still settling and be lost. Callers choose between the standard exchange wait and a dedicated wait-and-retrigger strategy based on this. There is no safe generic default — each driver must declare it.

Returns: true if an immediate reply after TX is reliably received.

Implemented in esphome::home_io_control::RadioLR1121, esphome::home_io_control::RadioSX1262, and esphome::home_io_control::RadioSX1276.

◆ init()

virtual bool esphome::home_io_control::RadioDriver::init ( )

pure virtual

Initialize the radio hardware. Returns true on success.

Implemented in esphome::home_io_control::RadioLR1121, esphome::home_io_control::RadioSX1262, and esphome::home_io_control::RadioSX1276.

◆ is_dio_fired()

bool esphome::home_io_control::RadioDriver::is_dio_fired ( ) const

inlinenodiscard

Set by the ISR when DIO fires.

Using access helpers instead of touching the flag directly keeps the ISR/main-loop handoff explicit and lets ESP32 builds use atomic storage.

Definition at line 221 of file radio_interface.h.

◆ is_failed()

virtual bool esphome::home_io_control::RadioDriver::is_failed ( ) const

nodiscardpure virtual

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

Returns: true on failure.

Implemented in esphome::home_io_control::RadioLR1121, esphome::home_io_control::RadioSX1262, and esphome::home_io_control::RadioSX1276.

◆ is_preamble_detected()

virtual bool esphome::home_io_control::RadioDriver::is_preamble_detected ( )

pure virtual

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

Used together with sync detection to gate frequency hopping.

Implemented in esphome::home_io_control::RadioSX1276, and esphome::home_io_control::SoftPhyDriverBase.

◆ is_sync_detected()

virtual bool esphome::home_io_control::RadioDriver::is_sync_detected ( )

pure virtual

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

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

Implemented in esphome::home_io_control::RadioSX1276, and esphome::home_io_control::SoftPhyDriverBase.

◆ mark_dio_fired_from_isr()

void esphome::home_io_control::RadioDriver::mark_dio_fired_from_isr ( )

inline

Definition at line 239 of file radio_interface.h.

◆ populate_capture_base_()

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

inlineprotected

Populate the common fields of RadioCaptureInfo from raw telemetry.

Chip‑specific fields (rx_done, crc_error, irq_flags*, irq_status, packet_status, etc.) must be set by the derived driver after calling this helper.

Parameters

blocking_wait	if this was a blocking receive.
freq_hz	RF frequency of the capture.
rssi_dbm	Received signal strength.
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 281 of file radio_interface.h.

◆ prepare_blocking_receive_()

void esphome::home_io_control::RadioDriver::prepare_blocking_receive_ ( RadioRxPacket & packet )

inlineprotected

Common preamble for blocking receive: clear diagnostics and output packet.

Parameters

packet Output packet buffer to zero and prepare.

Definition at line 254 of file radio_interface.h.

Here is the call graph for this function:

◆ prepare_nonblocking_receive_()

void esphome::home_io_control::RadioDriver::prepare_nonblocking_receive_ ( RadioRxPacket & packet )

inlineprotected

Common preamble for non‑blocking receive: clear diagnostics, output packet, and DIO latch.

Parameters

packet Output packet buffer to zero and prepare.

Definition at line 261 of file radio_interface.h.

Here is the call graph for this function:

◆ read_rssi()

virtual int16_t esphome::home_io_control::RadioDriver::read_rssi ( )

pure virtual

Read instantaneous RSSI (in dBm) while in RX mode.

Used for listen-before-talk (LBT) carrier sense before transmitting.

Returns: RSSI in dBm (negative value).

Implemented in esphome::home_io_control::RadioSX1276, and esphome::home_io_control::SoftPhyDriverBase.

◆ reset_hardware_()

void esphome::home_io_control::RadioDriver::reset_hardware_ ( )

protected

Shared hardware reset sequence for chips with an active-low RST pin.

Drives RST pin low → 10 ms → high → 10 ms. Called from derived driver init().

Definition at line 18 of file radio_interface.cpp.

◆ response_preamble()

virtual uint16_t esphome::home_io_control::RadioDriver::response_preamble ( ) const

inlinenodiscardvirtual

Return the preamble length for response/continuation frames.

Callers use this instead of hardcoding SHORT_PREAMBLE for any frame sent as an immediate reply within an exchange (challenge responses, key transfers, and any future non-START continuation frames — i.e. tight RX→TX turnaround).

The default is the protocol's standard SHORT_PREAMBLE. Drivers whose TX waveform gives the peer device less synchronization margin override this with a longer preamble (see the concrete drivers for the chip-specific rationale).

Returns: Preamble length in bytes.

Reimplemented in esphome::home_io_control::RadioSX1276, and esphome::home_io_control::SoftPhyDriverBase.

Definition at line 151 of file radio_interface.h.

◆ send_packet()

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

pure virtual

Send a packet using the specified carrier frequency and preamble settings.

The driver is responsible for appending the protocol CRC on the air (in hardware or software, depending on the chip).

Implemented in esphome::home_io_control::RadioSX1276, and esphome::home_io_control::SoftPhyDriverBase.

◆ set_mode_rx()

virtual void esphome::home_io_control::RadioDriver::set_mode_rx ( )

pure virtual

Switch to continuous receive mode.

Implemented in esphome::home_io_control::RadioLR1121, esphome::home_io_control::RadioSX1262, and esphome::home_io_control::RadioSX1276.

◆ set_mode_standby()

virtual void esphome::home_io_control::RadioDriver::set_mode_standby ( )

pure virtual

Switch to standby mode.

Implemented in esphome::home_io_control::RadioLR1121, esphome::home_io_control::RadioSX1262, and esphome::home_io_control::RadioSX1276.

◆ wait_for_packet()

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

pure virtual

Wait (blocking) for a packet with timeout.

Returns true if a packet was received. Contract:

Clears last_capture_ and output packet before waiting.
On success: populates packet and last_capture_, returns true.
On timeout/failure: may populate last_capture_ for diagnostics, returns false.
Radio remains in RX mode on return (regardless of outcome).

Implemented in esphome::home_io_control::RadioSX1276, and esphome::home_io_control::SoftPhyDriverBase.

Member Data Documentation

◆ current_freq_

uint32_t esphome::home_io_control::RadioDriver::current_freq_ {FREQ_CH2}

protected

Definition at line 299 of file radio_interface.h.

◆ dio_fired_

volatile bool esphome::home_io_control::RadioDriver::dio_fired_ {false}

protected

Definition at line 306 of file radio_interface.h.

◆ last_capture_

RadioCaptureInfo esphome::home_io_control::RadioDriver::last_capture_ {}

protected

Definition at line 300 of file radio_interface.h.

◆ rst_pin_

InternalGPIOPin* esphome::home_io_control::RadioDriver::rst_pin_ {nullptr}

protected

Definition at line 301 of file radio_interface.h.

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

components/home_io_control/radio_interface.h
components/home_io_control/radio_interface.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ RadioDriver()

◆ ~RadioDriver()

Member Function Documentation

◆ apply_tuning()

◆ change_frequency()

◆ check_for_packet()

◆ chip_name()

◆ clear_dio_fired()

◆ clear_last_capture_()

◆ discovery_hop_slice_ms()

◆ dump_debug()

◆ exchange_wait_slice_ms()

◆ get_current_freq()

◆ get_last_capture()

◆ has_fast_tx_rx_turnaround()

◆ init()

◆ is_dio_fired()

◆ is_failed()

◆ is_preamble_detected()

◆ is_sync_detected()

◆ mark_dio_fired_from_isr()

◆ populate_capture_base_()

◆ prepare_blocking_receive_()

◆ prepare_nonblocking_receive_()

◆ read_rssi()

◆ reset_hardware_()

◆ response_preamble()

◆ send_packet()

◆ set_mode_rx()

◆ set_mode_standby()

◆ wait_for_packet()

Member Data Documentation

◆ current_freq_

◆ dio_fired_

◆ last_capture_

◆ rst_pin_