Home IO Control
ESPHome add-on for IO-Homecontrol devices
Loading...
Searching...
No Matches
esphome::home_io_control::IOHomeControlComponent Class Reference

The main IO-Homecontrol component. More...

#include <hub_core.h>

Inheritance diagram for esphome::home_io_control::IOHomeControlComponent:
Collaboration diagram for esphome::home_io_control::IOHomeControlComponent:

Public Types

using ManagementActionResult = esphome::home_io_control::ManagementActionResult
 Result payload used by hub-level management actions such as rename.

Public Member Functions

 IOHomeControlComponent ()
 Initialize ExchangeEngine, PairingEngine, and ManagementActions with double-pointer/ reference indirection so that test assignments (comp.radio_ = &mock) propagate through all collaborators without calling setup().
void setup () override
 Initialize hardware (radio and device registry).
void loop () override
 Main loop: process pending operations and drive radio state machine.
void dump_config () override
 Dump configuration and radio debug info to the log.
float get_setup_priority () const override
 Get setup priority (HARDWARE to initialize early).
void spi_enable () override
 Enable the SPI bus.
void spi_disable () override
 Disable the SPI bus.
uint8_t spi_transfer (uint8_t data) override
 Transfer one byte full‑duplex.
void spi_write (uint8_t data) override
 Write one byte (MOSI only).
uint8_t spi_read () override
 Read one byte (MISO only).
void set_radio_test_mode (bool active)
 Suspend the hub's normal loop (packet processing, hopping, polling).
RadioDriverget_radio () const
 Get the underlying radio driver (for diagnostics and test tooling).
void set_rst_pin (InternalGPIOPin *pin)
 Set the radio reset pin.
void set_dio0_pin (InternalGPIOPin *pin)
 Set the DIO0 interrupt pin (SX1276).
void set_dio4_pin (InternalGPIOPin *pin)
 Set the DIO4 preamble‑detect pin (SX1276, optional).
void set_dio1_pin (InternalGPIOPin *pin)
 Set the DIO1 interrupt pin (SX1262; also carries the LR1121's DIO9 IRQ line).
void set_busy_pin (InternalGPIOPin *pin)
 Set the BUSY pin (SX1262/LR1121).
void set_fem_en_pin (InternalGPIOPin *pin)
 Set the front‑end module enable pin.
void set_vfem_pin (InternalGPIOPin *pin)
 Set the VFEM power pin.
void set_fem_pa_pin (InternalGPIOPin *pin)
 Set the FEM PA switch pin.
void set_node_id (const std::string &id)
 Set the controller's node ID (hex string).
void set_system_key (const std::string &key)
 Set the system key (hex string).
void set_tx_power (uint8_t power)
 Set transmit power (dBm).
void set_pa_pin (uint8_t pa_pin)
 Set PA boost pin configuration.
void set_radio_type (const std::string &type)
 Set radio type ("sx1276", "sx1262", or "lr1121"); required by the YAML schema.
void set_tcxo_voltage (uint8_t voltage)
 Set TCXO voltage for SX1262/LR1121 (1.8V / 3.3V).
void set_tuning_config (const TuningConfig &config)
 Apply the tuning configuration generated from YAML / UI entities.
void update_tuning_number (const std::string &name, float value)
 Receive a numeric tuning update from a HA number entity.
void update_tuning_select (const std::string &name, const std::string &value)
 Receive a select tuning update from a HA select entity.
float get_tuning_number_value (const std::string &name) const
 Current value of a numeric tuning parameter, used to seed a HA number entity on boot.
std::string get_tuning_select_value (const std::string &name) const
 Current option string of a select tuning parameter, used to seed a HA select entity on boot.
void add_linked_remote (const std::string &remote_id, const std::string &device_id)
 Declare that a remote (identified by its node ID) controls a registered device.
void add_linked_remote_class (DeviceType type, const std::string &device_id)
 Declare that a device class's typed 1W broadcasts (e.g.
virtual bool apply_optimistic_target (const std::string &device_id, float target_io_position)
 Set an optimistic target position ahead of a confirming poll/response, and notify.
virtual bool clear_optimistic_target (const std::string &device_id)
 Clear a device's optimistic target (e.g.
virtual bool apply_optimistic_tilt (const std::string &device_id, float tilt_percent)
 Set an optimistic slat angle ahead of a confirming status poll, and notify.
void add_exposed_sender (const std::string &sender_id)
 Allow a 1W sender (identified by its node ID) to fire the esphome.home_io_control_sender_event event to Home Assistant.
const PairingTelemetrypairing_telemetry () const
void set_pairing_result_callback (std::function< void()> cb)
 Register a callback invoked once, right after every discover_and_pair() attempt completes — used by the "Last Pairing Result" text sensor to publish a fresh value.
virtual void set_key_extraction_armed (bool armed)
 Arm or disarm the "Accept Foreign Pairing (Key Extraction)" responder.
void set_key_extraction_armed_callback (std::function< void(bool)> cb)
 Register a callback invoked whenever the key-extraction armed state changes — manual toggle, successful extraction, or auto-off timeout — so the switch entity can keep its displayed state in sync when the hub disarms itself rather than the user.
virtual void add_device (const std::string &device_id)
 Add a device to the registry by device ID only (undeclared/legacy path).
virtual void add_device (const std::string &device_id, const DeviceConfig &cfg)
 Add a device to the registry with full metadata from a YAML declaration.
virtual IoDeviceget_device (const std::string &device_id)
 Retrieve a device by ID; returns nullptr if not found.
virtual void set_device_dimmable (const std::string &device_id, bool dimmable)
 Set a device's dimmable flag (see IoDevice::dimmable).
virtual void register_device_callback (DeviceUpdateCallback cb)
 Register a callback invoked when any device updates.
virtual void set_device_status_poll_interval (const std::string &device_id, uint32_t poll_interval_ms)
 Configure the optional follow-up polling interval for a registered device.
virtual bool set_device_position (const std::string &device_id, uint8_t position)
 Send a position command to a device.
virtual bool set_device_tilt (const std::string &device_id, uint8_t tilt_percent)
 Send a tilt command to a tilt‑capable cover.
virtual bool set_device_position_and_tilt (const std::string &device_id, uint8_t position, uint8_t tilt_percent)
 Set both position and tilt of a tilt-capable cover in one atomic command.
virtual bool request_device_status (const std::string &device_id)
 Request current status from a device.
virtual bool request_device_name (const std::string &device_id)
 Request the stored device name from a device.
virtual ManagementActionResult rename_device (const std::string &device_id, const std::string &new_name)
 Rename a device and verify the result by reading the name back.
virtual ManagementActionResult identify_device (const std::string &device_id)
 Trigger a device's physical identify (brief jog/flash) so a user can confirm which physical motor a device ID maps to.
virtual ManagementActionResult force_open_device (const std::string &device_id)
 Move a cover device to fully open at elevated priority, intended to bypass wind/rain soft locks.
virtual ManagementActionResult scan_paired_devices ()
 Broadcast a roll-call and report every device that answers (see ManagementActions::scan_paired_devices() for the full contract: only key-holding devices answer, DeviceRegistry is never written, and zero replies is a successful result).
virtual bool discover_and_pair ()
 Discover and pair a device that is in pairing mode.
virtual bool set_light_position (const std::string &device_id, uint8_t position)
 Send an arbitrary IO position (0-100) to a light entity.
virtual bool set_light_state (const std::string &device_id, bool on)
 Semantic binary helper for light entities.
virtual bool set_switch_state (const std::string &device_id, bool on)
 Semantic binary helper for switch entities.
virtual bool set_lock_state (const std::string &device_id, bool locked)
 Semantic lock helper for lock entities.
virtual void queue_set_device_position (const std::string &device_id, uint8_t position)
 Queue an async position update; returns immediately, executed in loop().
virtual bool queue_device_command (const std::string &device_id, CoverCommand cmd)
 Queue an async named command (STOP, FAVORITE, VENT, FORCE_OPEN); returns immediately, executed in loop().
virtual void queue_set_device_tilt (const std::string &device_id, uint8_t tilt_percent)
 Queue an async tilt update; returns immediately, executed in loop().
virtual void queue_set_device_position_and_tilt (const std::string &device_id, uint8_t position, uint8_t tilt_percent)
 Queue an async combined position+tilt update; returns immediately, executed in loop().
virtual void queue_request_device_status (const std::string &device_id)
 Queue an async status request; returns immediately, executed in loop().
virtual void queue_request_device_name (const std::string &device_id)
 Queue an async device-name request; returns immediately, executed in loop().
virtual void queue_discover_and_pair ()
 Queue a pairing operation; executed in loop() when radio idle.
virtual void queue_set_light_position (const std::string &device_id, uint8_t position)
 Async form of set_light_position() that keeps radio work serialized on the main loop.
virtual void queue_set_light_state (const std::string &device_id, bool on)
 Async form of set_light_state() that keeps radio work serialized on the main loop.
virtual void queue_set_switch_state (const std::string &device_id, bool on)
 Async form of set_switch_state() that keeps radio work serialized on the main loop.
virtual void queue_set_lock_state (const std::string &device_id, bool locked)
 Async form of set_lock_state() that keeps radio work serialized on the main loop.
Public Member Functions inherited from esphome::home_io_control::SpiAccess
virtual ~SpiAccess ()=default

Protected Member Functions

bool transmit_frame_ (const IoFrame &frame, uint32_t freq, uint16_t preamble)
 Transmit a raw IoFrame on the current frequency with given preamble length.
bool send_and_receive_ (const IoFrame &request, IoFrame &response, uint32_t freq)
 Main request/response exchange with retry and automatic authentication.
bool authenticate_request_ (const IoFrame &request, uint32_t freq)
 Handle an inbound authenticated command from a device (status updates, etc.).
void process_received_packet_ (const RadioRxPacket &packet)
 Parse a received frame, merge supported device state or metadata, and notify callbacks.
bool try_handle_key_extraction_frame_ (const IoFrame &frame)
 Dispatch a frame to the key-extraction responder if it's one of its 0x28/0x2C/0x31/0x32 frames and the responder is armed.
void handle_key_extraction_discover_ (const IoFrame &frame)
 Handle an inbound CMD_DISCOVER_REQ (0x28) while the key-extraction responder is armed.
void handle_key_extraction_discover_confirm_ (const IoFrame &frame)
 Handle an inbound CMD_DISCOVER_CONFIRM (0x2C) addressed to our throwaway node ID while armed.
void handle_key_extraction_key_init_ (const IoFrame &frame)
 Handle an inbound CMD_KEY_INIT (0x31) addressed to our throwaway node ID while armed.
void handle_key_extraction_key_transfer_ (const IoFrame &frame)
 Handle an inbound CMD_KEY_TRANSFER (0x32) addressed to our throwaway node ID while armed.
void generate_key_extraction_throwaway_id_ (uint8_t out[NODE_ID_SIZE])
 Generate a random throwaway node ID for one key-extraction arm cycle, avoiding collisions with the broadcast addresses, this hub's own real node ID, and any registered device.
void broadcast_key_extraction_reply_ (const IoFrame &frame)
 Transmit a key-extraction reply frame on all 3 IO-homecontrol channels, using the radio driver's response_preamble() rather than a fixed SHORT_PREAMBLE/LONG_PREAMBLE constant — long enough that a channel-hopping receiver reliably lands on it, short enough that 3 sequential transmissions don't block the main loop for the better part of a second (see the implementation comment in hub_key_extraction.cpp for the hardware-confirmed reasoning).
void log_key_extraction_result_ ()
 Emit the security-sensitive "system key extracted" log block (see redaction.h — this is the one deliberate, explicit exception to that file's masking, not a loosening of it).
void update_device_status_ (const IoFrame &frame, bool trust_position=true)
 Extract supported position or metadata info from a response frame and merge it into the device record.
void record_1w_activity_ (uint32_t now)
 Record that a 1W frame just arrived, updating last_1w_activity_ms_ and — when this frame starts a new burst (see decisions::oneway_burst_started_fresh()) — first_1w_activity_ms_.
void schedule_status_poll_ (const std::string &device_id, uint32_t delay_ms)
 Schedule a delayed status poll for a registered device using the Component timeout API.
void begin_status_poll_tracking_ (const std::string &device_id, uint32_t initial_delay_ms)
 Begin bounded follow-up polling for a device after a command or overheard remote activity.
void schedule_device_polls_ (const std::vector< std::string > &device_ids, uint32_t delay_ms)
 Schedule status polls for a fixed list of devices (shared by the id-linked and class-linked 1W paths, and by schedule_linked_remote_polls_()).
bool defer_background_poll_ () const
 Whether loop() should skip dispatching the queue this iteration because the pending work is a background poll and a 1W remote transmitted very recently.
void schedule_linked_remote_polls_ (const std::string &remote_id, uint32_t delay_ms=REMOTE_ACTIVITY_STATUS_POLL_DELAY_MS)
 Schedule status polls for all devices associated with a linked remote.
std::vector< std::string > resolve_1w_target_devices_ (const OneWayFrameInfo &info, const std::string &src_id) const
 Resolve the set of devices a 1W frame should affect: devices linked to the sending remote by node ID, plus — when the frame targets a typed broadcast (e.g.
bool apply_optimistic_linked_state_ (const OneWayFrameInfo &info, const std::vector< std::string > &device_ids)
 Apply optimistic target state to every device in device_ids, when the decoded frame carries a resolvable intent.
void maybe_fire_sender_event_ (const OneWayFrameInfo &info, bool linked, const std::string &src_id)
 Fire the sender HA event for a decoded 1W frame, if the sender is exposed.
bool execute_request_and_update_ (const std::string &device_id, const IoFrame &request, bool warn_on_no_response, uint32_t retry_after_fail_ms=0)
 Shared request/response helper for high-level operations.
bool execute_device_command_ (const std::string &device_id, CoverCommand cmd)
 Execute a named device command (STOP, FAVORITE, VENT, FORCE_OPEN) via the authenticated exchange.
void notify_device_update_ (const std::string &id)
 Fire all registered device update callbacks for the given device ID.
void schedule_background_poll_backoff_ (const std::string &device_id, bool auth_like)
 Apply backoff after a failed background status poll and log the result.
void process_pending_operation_ ()
 Pop next pending operation from the queue and execute it (set position, request status, discover).
void log_exchange_debug_ (const char *device_id) const
 Log the last exchange debug snapshot (delegates to exchange_engine_).
void apply_tuning_to_radio_ ()
 Apply the current tuning configuration to the active radio driver.
void register_management_actions_ ()
 Register hub-level Home Assistant actions; called from setup().
void api_rename_device_ (const std::string &device_id, const std::string &new_name)
 Native API callback: rename a registered device.
void api_identify_device_ (const std::string &device_id)
 Native API callback: trigger a registered device's physical identify.
void api_force_open_device_ (const std::string &device_id)
 Native API callback: force-open a registered cover device.
void api_scan_paired_devices_ ()
 Native API callback: broadcast a roll-call scan of already-paired devices.
void hop_frequency_ ()
 Delegate channel hop to ExchangeEngine (which owns last_hop_us_).
RadioDriverselect_and_construct_radio_ (const char **chip_name_out)
 Select and construct the radio driver named by the required radio_type config field.

Protected Attributes

RadioDriverradio_ {nullptr}
InternalGPIOPin * rst_pin_ {nullptr}
InternalGPIOPin * dio0_pin_ {nullptr}
 SX1276 DIO0 interrupt.
InternalGPIOPin * dio4_pin_ {nullptr}
 SX1276 DIO4 preamble detect (optional).
InternalGPIOPin * dio1_pin_ {nullptr}
 SX1262 DIO1 interrupt; also carries the LR1121's DIO9 IRQ line.
InternalGPIOPin * busy_pin_ {nullptr}
 SX1262/LR1121 BUSY pin.
InternalGPIOPin * fem_en_pin_ {nullptr}
 Front-end module enable.
InternalGPIOPin * vfem_pin_ {nullptr}
 Front-end module power.
InternalGPIOPin * fem_pa_pin_ {nullptr}
 Front-end module PA switch.
std::string node_id_str_
std::string system_key_str_
std::string radio_type_
 "sx1276", "sx1262", or "lr1121"; required by the YAML schema.
uint8_t node_id_ [NODE_ID_SIZE] {}
uint8_t system_key_ [AES_KEY_SIZE] {}
uint8_t tx_power_ {DEFAULT_TX_POWER_DBM}
uint8_t pa_pin_ {DEFAULT_PA_PIN_PA_BOOST}
uint8_t tcxo_voltage_ {DEFAULT_TCXO_VOLTAGE_SETTING_1P8V}
 SX1262/LR1121 TCXO voltage setting (default 1.8 V).
bool initialized_ {false}
bool busy_ {false}
bool radio_test_mode_ {false}
 When true, loop() is suspended for loopback testing.
TuningConfig tuning_ {}
 Runtime tuning overrides.
DeviceRegistry registry_
std::vector< std::string > exposed_senders_
 1W sender node IDs (remotes or sensors) allowed to fire the sender HA event (add_exposed_sender).
std::function< void()> pairing_result_callback_
 Invoked once after every pairing attempt completes; see set_pairing_result_callback().
pairing_responder::ResponderContext key_extraction_ctx_
 State for the current "Accept Foreign Pairing" (key-extraction) arm cycle; DISARMED by default so a fresh boot never responds to foreign pairing traffic.
std::function< void(bool)> key_extraction_armed_callback_
 Invoked whenever the key-extraction armed state changes; see set_key_extraction_armed_callback().
StatusPollPolicy poll_policy_
OperationQueue op_queue_
PairingTelemetry pairing_telemetry_
 Per-attempt pairing telemetry, shared with ExchangeEngine/PairingEngine.
ExchangeEngine exchange_engine_
 Owns all authenticated exchange and LBT/hop logic.
PairingEngine pairing_engine_
 Owns the three-phase device pairing flow.
ManagementActions management_actions_
 Owns rename, identify, force-open, scan_paired_devices, and other hub-level HA actions.
decisions::OneWayDedupState last_1w_logged_ {}
 Identity of the last processed 1W frame, for burst suppression; see decisions::is_duplicate_1w_frame() for why the intent bytes are part of the key.
uint32_t last_1w_activity_ms_ {0}
 millis() of the most recent 1W frame of any kind, including ones dropped as duplicates — a repeat still means the remote is transmitting.
uint32_t first_1w_activity_ms_ {0}
 millis() of the first 1W frame in the current burst.

Detailed Description

The main IO-Homecontrol component.

Manages the protocol layer and delegates radio operations to a RadioDriver instance.

Inherits SPIDevice so that ESPHome's Python codegen can configure SPI pins. Implements SpiAccess to provide the radio driver with SPI bus access.

Definition at line 70 of file hub_core.h.

Member Typedef Documentation

◆ ManagementActionResult

Result payload used by hub-level management actions such as rename.

Alias of the standalone esphome::home_io_control::ManagementActionResult struct so that callers using the nested name IOHomeControlComponent::ManagementActionResult continue to work.

Definition at line 87 of file hub_core.h.

Constructor & Destructor Documentation

◆ IOHomeControlComponent()

esphome::home_io_control::IOHomeControlComponent::IOHomeControlComponent ( )
inline

Initialize ExchangeEngine, PairingEngine, and ManagementActions with double-pointer/ reference indirection so that test assignments (comp.radio_ = &mock) propagate through all collaborators without calling setup().

Definition at line 79 of file hub_core.h.

Member Function Documentation

◆ add_device() [1/2]

void esphome::home_io_control::IOHomeControlComponent::add_device ( const std::string & device_id)
virtual

Add a device to the registry by device ID only (undeclared/legacy path).

Type, subtype, inverted, and optimistic_state default to UNKNOWN / 0 / false / true; use the DeviceConfig overload when metadata comes from a YAML declaration.

Parameters
device_idHexadecimal node ID string.

Definition at line 298 of file hub_core.cpp.

◆ add_device() [2/2]

void esphome::home_io_control::IOHomeControlComponent::add_device ( const std::string & device_id,
const DeviceConfig & cfg )
virtual

Add a device to the registry with full metadata from a YAML declaration.

Parameters
device_idHexadecimal node ID string.
cfgDevice type/subtype/inversion/optimistic-state metadata.

Definition at line 300 of file hub_core.cpp.

◆ add_exposed_sender()

void esphome::home_io_control::IOHomeControlComponent::add_exposed_sender ( const std::string & sender_id)
inline

Allow a 1W sender (identified by its node ID) to fire the esphome.home_io_control_sender_event event to Home Assistant.

"Sender" is deliberately broader than "remote": the same 1W broadcast mechanism carries handheld/wall remotes and wind/rain sensors alike (they differ only in the originator byte inside the payload, not in how they address the radio) — see decode_1w_frame(). Overheard 1W traffic is always DEBUG-logged regardless of this list; this only controls which senders are allowed to reach Home Assistant as an event, independent of whether the sender is also linked to a device via add_linked_remote. Empty by default — a sender must be explicitly opted in.

Parameters
sender_idNode ID of the 1W sender (remote or sensor).

Definition at line 226 of file hub_core.h.

◆ add_linked_remote()

void esphome::home_io_control::IOHomeControlComponent::add_linked_remote ( const std::string & remote_id,
const std::string & device_id )
inline

Declare that a remote (identified by its node ID) controls a registered device.

When activity from this remote is overheard, a status poll is scheduled for the device. This is needed for 1W remotes whose destination address differs from the device's 2W ID.

Parameters
remote_idNode ID of the remote control.
device_idNode ID of the device it controls.

Definition at line 172 of file hub_core.h.

◆ add_linked_remote_class()

void esphome::home_io_control::IOHomeControlComponent::add_linked_remote_class ( DeviceType type,
const std::string & device_id )
inline

Declare that a device class's typed 1W broadcasts (e.g.

"all awnings") also apply to device_id, matching how 1W remotes address a device class rather than a single node.

Parameters
typeDevice class the broadcast targets.
device_idNode ID of the device to add to that class.

Definition at line 180 of file hub_core.h.

◆ api_force_open_device_()

void esphome::home_io_control::IOHomeControlComponent::api_force_open_device_ ( const std::string & device_id)
inlineprotected

Native API callback: force-open a registered cover device.

Definition at line 622 of file hub_core.h.

◆ api_identify_device_()

void esphome::home_io_control::IOHomeControlComponent::api_identify_device_ ( const std::string & device_id)
inlineprotected

Native API callback: trigger a registered device's physical identify.

Definition at line 620 of file hub_core.h.

◆ api_rename_device_()

void esphome::home_io_control::IOHomeControlComponent::api_rename_device_ ( const std::string & device_id,
const std::string & new_name )
inlineprotected

Native API callback: rename a registered device.

Definition at line 616 of file hub_core.h.

◆ api_scan_paired_devices_()

void esphome::home_io_control::IOHomeControlComponent::api_scan_paired_devices_ ( )
inlineprotected

Native API callback: broadcast a roll-call scan of already-paired devices.

Definition at line 626 of file hub_core.h.

◆ apply_optimistic_linked_state_()

bool esphome::home_io_control::IOHomeControlComponent::apply_optimistic_linked_state_ ( const OneWayFrameInfo & info,
const std::vector< std::string > & device_ids )
protected

Apply optimistic target state to every device in device_ids, when the decoded frame carries a resolvable intent.

Skips devices whose known type doesn't match the frame's typed-broadcast target (an "all awnings" press must not optimistically move a linked shutter — it is still polled by schedule_device_polls_()). No-op per device when that device has optimistic_state == false (see DeviceRegistry::apply_optimistic_target()).

Parameters
infoAlready-decoded 1W frame info (see decode_1w_frame()).
device_idsDevices to apply optimistic state to (see resolve_1w_target_devices_()).
Returns
true if the intent resolved to a STOP (caller should poll immediately).

Definition at line 259 of file hub_status.cpp.

Here is the call graph for this function:

◆ apply_optimistic_target()

virtual bool esphome::home_io_control::IOHomeControlComponent::apply_optimistic_target ( const std::string & device_id,
float target_io_position )
inlinevirtual

Set an optimistic target position ahead of a confirming poll/response, and notify.

No-op when the device is unknown or has optimistic_state == false. See DeviceRegistry::apply_optimistic_target() for the full contract. Virtual (like add_device/get_device) so platform unit tests can substitute a mock registry.

Parameters
device_idTarget device ID.
target_io_positionTarget position in IO units (0=open, 100=closed).
Returns
true if the optimistic state was applied.

Definition at line 191 of file hub_core.h.

◆ apply_optimistic_tilt()

virtual bool esphome::home_io_control::IOHomeControlComponent::apply_optimistic_tilt ( const std::string & device_id,
float tilt_percent )
inlinevirtual

Set an optimistic slat angle ahead of a confirming status poll, and notify.

No-op when the device is unknown, has optimistic_state == false, or is not tilt-capable. See DeviceRegistry::apply_optimistic_tilt() for the full contract and for why a tilt command cannot rely on its own reply the way a position command can. Virtual like the other device-registry accessors so a test double can override it if it needs to; MockPlatformHubBase deliberately does not, and exercises the real registry.

Parameters
device_idTarget device ID.
tilt_percentSlat angle in the same percent scale as IoDevice::tilt (0-100).
Returns
true if the optimistic tilt was applied.

Definition at line 213 of file hub_core.h.

◆ apply_tuning_to_radio_()

void esphome::home_io_control::IOHomeControlComponent::apply_tuning_to_radio_ ( )
protected

Apply the current tuning configuration to the active radio driver.

Only chip-specific parameters are forwarded; the rest are consumed by the pairing flow and LBT logic. This is called once at the end of setup() and again whenever a UI-driven change modifies a radio parameter.

Definition at line 182 of file hub_core.cpp.

◆ authenticate_request_()

bool esphome::home_io_control::IOHomeControlComponent::authenticate_request_ ( const IoFrame & request,
uint32_t freq )
protected

Handle an inbound authenticated command from a device (status updates, etc.).

Delegate inbound authentication to ExchangeEngine.

Parameters
requestInbound authenticated request (e.g., CMD_STATUS_UPDATE).
freqRF frequency the packet arrived on.
Returns
true if authentication succeeded; false otherwise.

Definition at line 272 of file hub_core.cpp.

◆ begin_status_poll_tracking_()

void esphome::home_io_control::IOHomeControlComponent::begin_status_poll_tracking_ ( const std::string & device_id,
uint32_t initial_delay_ms )
protected

Begin bounded follow-up polling for a device after a command or overheard remote activity.

Parameters
device_idID of the device to poll.
initial_delay_msDelay before the first follow-up poll.

Definition at line 214 of file hub_status.cpp.

Here is the call graph for this function:

◆ broadcast_key_extraction_reply_()

void esphome::home_io_control::IOHomeControlComponent::broadcast_key_extraction_reply_ ( const IoFrame & frame)
protected

Transmit a key-extraction reply frame on all 3 IO-homecontrol channels, using the radio driver's response_preamble() rather than a fixed SHORT_PREAMBLE/LONG_PREAMBLE constant — long enough that a channel-hopping receiver reliably lands on it, short enough that 3 sequential transmissions don't block the main loop for the better part of a second (see the implementation comment in hub_key_extraction.cpp for the hardware-confirmed reasoning).

Shared by every RX handler so the preamble choice and channel list are defined once.

Parameters
frameFrame to broadcast (already built by the caller).

Definition at line 167 of file hub_key_extraction.cpp.

Here is the call graph for this function:

◆ clear_optimistic_target()

virtual bool esphome::home_io_control::IOHomeControlComponent::clear_optimistic_target ( const std::string & device_id)
inlinevirtual

Clear a device's optimistic target (e.g.

on STOP), and notify. No-op when the device is unknown or has optimistic_state == false. Virtual (like add_device/get_device) so platform unit tests can substitute a mock registry.

Parameters
device_idTarget device ID.
Returns
true if the optimistic target was cleared.

Definition at line 200 of file hub_core.h.

◆ defer_background_poll_()

bool esphome::home_io_control::IOHomeControlComponent::defer_background_poll_ ( ) const
inlinenodiscardprotected

Whether loop() should skip dispatching the queue this iteration because the pending work is a background poll and a 1W remote transmitted very recently.

Thin wrapper binding the component's state to decisions::defer_background_poll_for_1w_activity().

Definition at line 543 of file hub_core.h.

Here is the call graph for this function:

◆ discover_and_pair()

bool esphome::home_io_control::IOHomeControlComponent::discover_and_pair ( )
virtual

Discover and pair a device that is in pairing mode.

Discover and pair a device in pairing mode.

Returns
true if pairing completed successfully; false otherwise.

The hub wrapper manages the busy_ flag so loop() stops hopping and polling while the blocking pairing exchange is in progress. All protocol logic is in PairingEngine::discover_and_pair().

Definition at line 20 of file hub_pairing.cpp.

◆ dump_config()

void esphome::home_io_control::IOHomeControlComponent::dump_config ( )
override

Dump configuration and radio debug info to the log.

Definition at line 347 of file hub_core.cpp.

◆ execute_device_command_()

bool esphome::home_io_control::IOHomeControlComponent::execute_device_command_ ( const std::string & device_id,
CoverCommand cmd )
protected

Execute a named device command (STOP, FAVORITE, VENT, FORCE_OPEN) via the authenticated exchange.

Parameters
device_idTarget device ID.
cmdNamed command to execute.
Returns
true if device acknowledged; false otherwise.

Definition at line 170 of file hub_operations.cpp.

Here is the call graph for this function:

◆ execute_request_and_update_()

bool esphome::home_io_control::IOHomeControlComponent::execute_request_and_update_ ( const std::string & device_id,
const IoFrame & request,
bool warn_on_no_response,
uint32_t retry_after_fail_ms = 0 )
protected

Shared request/response helper for high-level operations.

Parameters
device_idTarget device ID.
requestOutbound request frame.
warn_on_no_responseIf true, logs a warning when no response is received.
retry_after_fail_msIf non-zero, schedules next status poll after this delay on failure.
Returns
true if device acknowledged; false otherwise.

Definition at line 83 of file hub_operations.cpp.

Here is the call graph for this function:

◆ force_open_device()

IOHomeControlComponent::ManagementActionResult esphome::home_io_control::IOHomeControlComponent::force_open_device ( const std::string & device_id)
virtual

Move a cover device to fully open at elevated priority, intended to bypass wind/rain soft locks.

Safety-sensitive: queues CoverCommand::FORCE_OPEN through the normal cover-command dispatch path. Only confirms the command was queued; the movement outcome arrives later via the device's normal cover-state/polling pipeline, so verified is always false. The lock-bypass behavior itself is experimental and unconfirmed against an active lock — see ManagementActions::force_open_device()'s doxygen for details.

Parameters
device_idTarget device ID.
Returns
Structured result describing whether the command was queued.

Thin wrapper that delegates to management_actions_.force_open_device() so that the virtual dispatch defined in hub_core.h is fulfilled.

Definition at line 36 of file hub_management.cpp.

◆ generate_key_extraction_throwaway_id_()

void esphome::home_io_control::IOHomeControlComponent::generate_key_extraction_throwaway_id_ ( uint8_t out[NODE_ID_SIZE])
protected

Generate a random throwaway node ID for one key-extraction arm cycle, avoiding collisions with the broadcast addresses, this hub's own real node ID, and any registered device.

Parameters
outOutput: 3-byte node ID.

Definition at line 81 of file hub_key_extraction.cpp.

Here is the call graph for this function:

◆ get_device()

IoDevice * esphome::home_io_control::IOHomeControlComponent::get_device ( const std::string & device_id)
virtual

Retrieve a device by ID; returns nullptr if not found.

Parameters
device_idHexadecimal node ID.
Returns
Pointer to IoDevice, or nullptr.

Definition at line 304 of file hub_core.cpp.

◆ get_radio()

RadioDriver * esphome::home_io_control::IOHomeControlComponent::get_radio ( ) const
inlinenodiscard

Get the underlying radio driver (for diagnostics and test tooling).

Definition at line 120 of file hub_core.h.

◆ get_setup_priority()

float esphome::home_io_control::IOHomeControlComponent::get_setup_priority ( ) const
inlinenodiscardoverride

Get setup priority (HARDWARE to initialize early).

Returns
setup_priority::HARDWARE.

Definition at line 97 of file hub_core.h.

◆ get_tuning_number_value()

float esphome::home_io_control::IOHomeControlComponent::get_tuning_number_value ( const std::string & name) const
nodiscard

Current value of a numeric tuning parameter, used to seed a HA number entity on boot.

Return the current value of a numeric tuning parameter.

Parameters
nameYAML key of the parameter.
Returns
Current value, or 0 for an unknown key.

Mirror of update_tuning_number(); used by IOHomeTuningNumber::setup() to publish the boot-time value so the Home Assistant slider reflects the active configuration (default or YAML override) without restating any default on the Python side.

Definition at line 229 of file hub_core.cpp.

Here is the call graph for this function:

◆ get_tuning_select_value()

std::string esphome::home_io_control::IOHomeControlComponent::get_tuning_select_value ( const std::string & name) const
nodiscard

Current option string of a select tuning parameter, used to seed a HA select entity on boot.

Return the current option string of a select tuning parameter.

Parameters
nameYAML key of the parameter.
Returns
Current value formatted as its YAML option string, or empty for an unknown key.

Mirror of update_tuning_select(); used by IOHomeTuningSelect::setup() to publish the boot-time option so the Home Assistant dropdown reflects the active configuration. The returned strings match the YAML/UI option labels exactly. The command list is returned as a comma-separated preset string (e.g. "0x28,0x2E") matching the dropdown options.

Definition at line 244 of file hub_core.cpp.

Here is the call graph for this function:

◆ handle_key_extraction_discover_()

void esphome::home_io_control::IOHomeControlComponent::handle_key_extraction_discover_ ( const IoFrame & frame)
protected

Handle an inbound CMD_DISCOVER_REQ (0x28) while the key-extraction responder is armed.

Parameters
frameParsed inbound discovery broadcast.

Definition at line 184 of file hub_key_extraction.cpp.

Here is the call graph for this function:

◆ handle_key_extraction_discover_confirm_()

void esphome::home_io_control::IOHomeControlComponent::handle_key_extraction_discover_confirm_ ( const IoFrame & frame)
protected

Handle an inbound CMD_DISCOVER_CONFIRM (0x2C) addressed to our throwaway node ID while armed.

Parameters
frameParsed inbound discovery-confirm frame.

Definition at line 200 of file hub_key_extraction.cpp.

Here is the call graph for this function:

◆ handle_key_extraction_key_init_()

void esphome::home_io_control::IOHomeControlComponent::handle_key_extraction_key_init_ ( const IoFrame & frame)
protected

Handle an inbound CMD_KEY_INIT (0x31) addressed to our throwaway node ID while armed.

Parameters
frameParsed inbound key-init frame.

Definition at line 214 of file hub_key_extraction.cpp.

Here is the call graph for this function:

◆ handle_key_extraction_key_transfer_()

void esphome::home_io_control::IOHomeControlComponent::handle_key_extraction_key_transfer_ ( const IoFrame & frame)
protected

Handle an inbound CMD_KEY_TRANSFER (0x32) addressed to our throwaway node ID while armed.

Parameters
frameParsed inbound key-transfer frame.

Definition at line 230 of file hub_key_extraction.cpp.

Here is the call graph for this function:

◆ hop_frequency_()

void esphome::home_io_control::IOHomeControlComponent::hop_frequency_ ( )
protected

Delegate channel hop to ExchangeEngine (which owns last_hop_us_).

Definition at line 256 of file hub_core.cpp.

◆ identify_device()

IOHomeControlComponent::ManagementActionResult esphome::home_io_control::IOHomeControlComponent::identify_device ( const std::string & device_id)
virtual

Trigger a device's physical identify (brief jog/flash) so a user can confirm which physical motor a device ID maps to.

Trigger a registered device's physical identify (jog/flash).

Parameters
device_idTarget device ID.
Returns
Structured result describing success and any validation failure. verified is always false — there is no readback for a physical identify jog.

Thin wrapper that delegates to management_actions_.identify_device() so that the virtual dispatch defined in hub_core.h is fulfilled.

Definition at line 27 of file hub_management.cpp.

◆ log_exchange_debug_()

void esphome::home_io_control::IOHomeControlComponent::log_exchange_debug_ ( const char * device_id) const
inlineprotected

Log the last exchange debug snapshot (delegates to exchange_engine_).

Definition at line 606 of file hub_core.h.

◆ log_key_extraction_result_()

void esphome::home_io_control::IOHomeControlComponent::log_key_extraction_result_ ( )
protected

Emit the security-sensitive "system key extracted" log block (see redaction.h — this is the one deliberate, explicit exception to that file's masking, not a loosening of it).

Definition at line 263 of file hub_key_extraction.cpp.

Here is the call graph for this function:

◆ loop()

void esphome::home_io_control::IOHomeControlComponent::loop ( )
override

Main loop: process pending operations and drive radio state machine.

Definition at line 312 of file hub_core.cpp.

Here is the call graph for this function:

◆ maybe_fire_sender_event_()

void esphome::home_io_control::IOHomeControlComponent::maybe_fire_sender_event_ ( const OneWayFrameInfo & info,
bool linked,
const std::string & src_id )
protected

Fire the sender HA event for a decoded 1W frame, if the sender is exposed.

DEBUG-logs the reason when it does not fire (API disconnected / sender not exposed) so a live log capture can distinguish "never reached this check" from "reached it and skipped".

Parameters
infoAlready-decoded 1W frame info (see decode_1w_frame()).
linkedTrue if the sender is linked to at least one registered device.
src_idSender's node ID as a string (already computed by the caller).

Definition at line 282 of file hub_status.cpp.

Here is the call graph for this function:

◆ notify_device_update_()

void esphome::home_io_control::IOHomeControlComponent::notify_device_update_ ( const std::string & id)
protected

Fire all registered device update callbacks for the given device ID.

Parameters
idDevice ID that updated.

Definition at line 276 of file hub_core.cpp.

◆ pairing_telemetry()

const PairingTelemetry & esphome::home_io_control::IOHomeControlComponent::pairing_telemetry ( ) const
inlinenodiscard
Returns
The telemetry recorded for the most recent (or in-progress) pairing attempt.

Definition at line 229 of file hub_core.h.

◆ process_pending_operation_()

void esphome::home_io_control::IOHomeControlComponent::process_pending_operation_ ( )
protected

Pop next pending operation from the queue and execute it (set position, request status, discover).

Definition at line 485 of file hub_operations.cpp.

Here is the call graph for this function:

◆ process_received_packet_()

void esphome::home_io_control::IOHomeControlComponent::process_received_packet_ ( const RadioRxPacket & packet)
protected

Parse a received frame, merge supported device state or metadata, and notify callbacks.

Parameters
packetRaw radio packet containing a parsed IoFrame.

Definition at line 410 of file hub_status.cpp.

Here is the call graph for this function:

◆ queue_device_command()

bool esphome::home_io_control::IOHomeControlComponent::queue_device_command ( const std::string & device_id,
CoverCommand cmd )
virtual

Queue an async named command (STOP, FAVORITE, VENT, FORCE_OPEN); returns immediately, executed in loop().

Existing entity/button callers (cover, favorite button, vent button) intentionally ignore the return value — they always target a known, already-registered device. It exists so force_open_device() can report enqueue rejection distinctly from a queued-but-not-yet-run command.

Parameters
device_idTarget device ID.
cmdNamed command to send.
Returns
true if the hub is initialized, the device is registered, and the command matches its capability class (so the command was enqueued); false otherwise.

Definition at line 383 of file hub_operations.cpp.

Here is the call graph for this function:

◆ queue_discover_and_pair()

void esphome::home_io_control::IOHomeControlComponent::queue_discover_and_pair ( )
virtual

Queue a pairing operation; executed in loop() when radio idle.

Queue a discovery-and-pair request with elevated priority.

Flushes any pending status/name poll operations (which would consume time during the device's limited pairing window) and pushes discovery to the front of the queue. Duplicate requests are suppressed.

Definition at line 452 of file hub_operations.cpp.

◆ queue_request_device_name()

void esphome::home_io_control::IOHomeControlComponent::queue_request_device_name ( const std::string & device_id)
virtual

Queue an async device-name request; returns immediately, executed in loop().

Parameters
device_idTarget device ID.

Definition at line 441 of file hub_operations.cpp.

Here is the call graph for this function:

◆ queue_request_device_status()

void esphome::home_io_control::IOHomeControlComponent::queue_request_device_status ( const std::string & device_id)
virtual

Queue an async status request; returns immediately, executed in loop().

Parameters
device_idTarget device ID.

Definition at line 430 of file hub_operations.cpp.

Here is the call graph for this function:

◆ queue_set_device_position()

void esphome::home_io_control::IOHomeControlComponent::queue_set_device_position ( const std::string & device_id,
uint8_t position )
virtual

Queue an async position update; returns immediately, executed in loop().

If a pending SET_TILT operation for the same device is already in the queue, the two are coalesced into a single SET_POSITION_AND_TILT command to avoid two radio exchanges. This transparently handles Home Assistant sending cover.set_cover_position and cover.set_cover_tilt_position as separate rapid calls.

Parameters
device_idTarget device ID.
positionDesired position (0–100).

Definition at line 360 of file hub_operations.cpp.

Here is the call graph for this function:

◆ queue_set_device_position_and_tilt()

void esphome::home_io_control::IOHomeControlComponent::queue_set_device_position_and_tilt ( const std::string & device_id,
uint8_t position,
uint8_t tilt_percent )
virtual

Queue an async combined position+tilt update; returns immediately, executed in loop().

Parameters
device_idTarget device ID.
positionDesired position (0–100).
tilt_percentDesired tilt (0–100).

Definition at line 420 of file hub_operations.cpp.

Here is the call graph for this function:

◆ queue_set_device_tilt()

void esphome::home_io_control::IOHomeControlComponent::queue_set_device_tilt ( const std::string & device_id,
uint8_t tilt_percent )
virtual

Queue an async tilt update; returns immediately, executed in loop().

If a pending SET_POSITION operation for the same device is already in the queue, the two are coalesced into a single SET_POSITION_AND_TILT command to avoid two radio exchanges. This transparently handles Home Assistant sending cover.set_cover_position and cover.set_cover_tilt_position as separate rapid calls.

Parameters
device_idTarget device ID.
tilt_percentDesired tilt (0–100).

Definition at line 397 of file hub_operations.cpp.

Here is the call graph for this function:

◆ queue_set_light_position()

void esphome::home_io_control::IOHomeControlComponent::queue_set_light_position ( const std::string & device_id,
uint8_t position )
virtual

Async form of set_light_position() that keeps radio work serialized on the main loop.

queue_set_light_state() is a thin binary-position wrapper around this.

Parameters
device_idTarget device ID.
positionDesired IO position (0-100).

Definition at line 454 of file hub_operations.cpp.

Here is the call graph for this function:

◆ queue_set_light_state()

void esphome::home_io_control::IOHomeControlComponent::queue_set_light_state ( const std::string & device_id,
bool on )
virtual

Async form of set_light_state() that keeps radio work serialized on the main loop.

Parameters
device_idTarget device ID.
onDesired on/off state.

Definition at line 463 of file hub_operations.cpp.

Here is the call graph for this function:

◆ queue_set_lock_state()

void esphome::home_io_control::IOHomeControlComponent::queue_set_lock_state ( const std::string & device_id,
bool locked )
virtual

Async form of set_lock_state() that keeps radio work serialized on the main loop.

Parameters
device_idTarget device ID.
lockedDesired locked/unlocked state.

Definition at line 467 of file hub_operations.cpp.

Here is the call graph for this function:

◆ queue_set_switch_state()

void esphome::home_io_control::IOHomeControlComponent::queue_set_switch_state ( const std::string & device_id,
bool on )
virtual

Async form of set_switch_state() that keeps radio work serialized on the main loop.

Parameters
device_idTarget device ID.
onDesired on/off state.

Definition at line 476 of file hub_operations.cpp.

Here is the call graph for this function:

◆ record_1w_activity_()

void esphome::home_io_control::IOHomeControlComponent::record_1w_activity_ ( uint32_t now)
protected

Record that a 1W frame just arrived, updating last_1w_activity_ms_ and — when this frame starts a new burst (see decisions::oneway_burst_started_fresh()) — first_1w_activity_ms_.

Parameters
nowmillis() at which this frame arrived.

Definition at line 401 of file hub_status.cpp.

Here is the call graph for this function:

◆ register_device_callback()

virtual void esphome::home_io_control::IOHomeControlComponent::register_device_callback ( DeviceUpdateCallback cb)
inlinevirtual

Register a callback invoked when any device updates.

Parameters
cbCallable with signature void(const std::string&, const IoDevice&).

Definition at line 281 of file hub_core.h.

◆ register_management_actions_()

void esphome::home_io_control::IOHomeControlComponent::register_management_actions_ ( )
inlineprotected

Register hub-level Home Assistant actions; called from setup().

Definition at line 614 of file hub_core.h.

◆ rename_device()

IOHomeControlComponent::ManagementActionResult esphome::home_io_control::IOHomeControlComponent::rename_device ( const std::string & device_id,
const std::string & new_name )
virtual

Rename a device and verify the result by reading the name back.

Rename a registered device and verify by reading the name back.

Parameters
device_idTarget device ID.
new_nameRequested UTF-8 device name.
Returns
Structured result describing success, verification, and any validation failure.

Thin wrapper that delegates to management_actions_.rename_device() so that the virtual dispatch defined in hub_core.h is fulfilled.

Definition at line 18 of file hub_management.cpp.

◆ request_device_name()

bool esphome::home_io_control::IOHomeControlComponent::request_device_name ( const std::string & device_id)
virtual

Request the stored device name from a device.

Parameters
device_idTarget device ID.
Returns
true if a name response frame was received and processed.

Definition at line 301 of file hub_operations.cpp.

Here is the call graph for this function:

◆ request_device_status()

bool esphome::home_io_control::IOHomeControlComponent::request_device_status ( const std::string & device_id)
virtual

Request current status from a device.

Parameters
device_idTarget device ID.
Returns
true if status frame was received and processed.

Definition at line 278 of file hub_operations.cpp.

Here is the call graph for this function:

◆ resolve_1w_target_devices_()

std::vector< std::string > esphome::home_io_control::IOHomeControlComponent::resolve_1w_target_devices_ ( const OneWayFrameInfo & info,
const std::string & src_id ) const
nodiscardprotected

Resolve the set of devices a 1W frame should affect: devices linked to the sending remote by node ID, plus — when the frame targets a typed broadcast (e.g.

"all awnings") — devices linked to that device class, deduplicated so a device linked both ways is touched once.

Parameters
infoAlready-decoded 1W frame info (see decode_1w_frame()).
src_idSender's node ID as a string (already computed by the caller).
Returns
Deduplicated device IDs (may be empty).

Definition at line 242 of file hub_status.cpp.

◆ scan_paired_devices()

IOHomeControlComponent::ManagementActionResult esphome::home_io_control::IOHomeControlComponent::scan_paired_devices ( )
virtual

Broadcast a roll-call and report every device that answers (see ManagementActions::scan_paired_devices() for the full contract: only key-holding devices answer, DeviceRegistry is never written, and zero replies is a successful result).

Broadcast a roll-call and report every device that answers.

Returns
Structured result whose message is the full multi-line report.

Thin wrapper that delegates to management_actions_.scan_paired_devices() so that the virtual dispatch defined in hub_core.h is fulfilled.

Definition at line 44 of file hub_management.cpp.

◆ schedule_background_poll_backoff_()

void esphome::home_io_control::IOHomeControlComponent::schedule_background_poll_backoff_ ( const std::string & device_id,
bool auth_like )
protected

Apply backoff after a failed background status poll and log the result.

Parameters
device_idTarget device ID.
auth_likeTrue when the failed exchange saw a 0x3C challenge.

Definition at line 286 of file hub_core.cpp.

◆ schedule_device_polls_()

void esphome::home_io_control::IOHomeControlComponent::schedule_device_polls_ ( const std::vector< std::string > & device_ids,
uint32_t delay_ms )
protected

Schedule status polls for a fixed list of devices (shared by the id-linked and class-linked 1W paths, and by schedule_linked_remote_polls_()).

Parameters
device_idsDevices to poll.
delay_msPoll delay in milliseconds.

Definition at line 228 of file hub_status.cpp.

Here is the call graph for this function:

◆ schedule_linked_remote_polls_()

void esphome::home_io_control::IOHomeControlComponent::schedule_linked_remote_polls_ ( const std::string & remote_id,
uint32_t delay_ms = REMOTE_ACTIVITY_STATUS_POLL_DELAY_MS )
protected

Schedule status polls for all devices associated with a linked remote.

Parameters
remote_idSource node ID of the remote.
delay_msPoll delay; default REMOTE_ACTIVITY_STATUS_POLL_DELAY_MS. A STOP intent passes 0 (position settles immediately, no need to wait out the usual travel-time assumption behind the default delay).

Definition at line 235 of file hub_status.cpp.

Here is the call graph for this function:

◆ schedule_status_poll_()

void esphome::home_io_control::IOHomeControlComponent::schedule_status_poll_ ( const std::string & device_id,
uint32_t delay_ms )
protected

Schedule a delayed status poll for a registered device using the Component timeout API.

Parameters
device_idID of the device to poll.
delay_msDelay in milliseconds before polling.
Note
Uses ESPHome's set_timeout() mechanism; the callback executes in loop(). A zero delay schedules immediately on the next loop iteration.

Definition at line 220 of file hub_status.cpp.

◆ select_and_construct_radio_()

RadioDriver * esphome::home_io_control::IOHomeControlComponent::select_and_construct_radio_ ( const char ** chip_name_out)
protected

Select and construct the radio driver named by the required radio_type config field.

Kept as its own method rather than inlined into setup(): the three-way chip branch (SX1276/SX1262/LR1121) is enough logic on its own that folding it into setup() pushes that function's cognitive complexity past clang-tidy's threshold. Validates the pins each driver needs and logs a clear error (without calling mark_failed() itself — the caller decides how to react) when a required pin is missing. On success, *chip_name_out is set to a static string naming the selected chip (used for logging), and the returned pointer is the heap-allocated (not yet initialized) driver instance.

Parameters
chip_name_outOutput: human-readable chip name for logging (always set, even on failure, to the best-known name for error messages).
Returns
Newly allocated RadioDriver, or nullptr if pin validation or allocation failed.

Definition at line 129 of file hub_core.cpp.

◆ send_and_receive_()

bool esphome::home_io_control::IOHomeControlComponent::send_and_receive_ ( const IoFrame & request,
IoFrame & response,
uint32_t freq )
protected

Main request/response exchange with retry and automatic authentication.

Delegate outbound exchange to ExchangeEngine and manage the busy_ flag.

Parameters
requestOutbound request IoFrame.
responseOutput: received response IoFrame.
freqRF frequency in Hz.
Returns
true if exchange succeeded; false otherwise.

Definition at line 264 of file hub_core.cpp.

◆ set_busy_pin()

void esphome::home_io_control::IOHomeControlComponent::set_busy_pin ( InternalGPIOPin * pin)
inline

Set the BUSY pin (SX1262/LR1121).

Definition at line 132 of file hub_core.h.

◆ set_device_dimmable()

void esphome::home_io_control::IOHomeControlComponent::set_device_dimmable ( const std::string & device_id,
bool dimmable )
virtual

Set a device's dimmable flag (see IoDevice::dimmable).

Called by platform_light.cpp's setup(), not folded into add_device() since it's a light-only YAML choice. No-op if the device isn't registered.

Parameters
device_idHexadecimal node ID string.
dimmableNew value for IoDevice::dimmable.

Definition at line 306 of file hub_core.cpp.

◆ set_device_position()

bool esphome::home_io_control::IOHomeControlComponent::set_device_position ( const std::string & device_id,
uint8_t position )
virtual

Send a position command to a device.

Parameters
device_idTarget device ID.
positionDesired position, 0–100 (open→closed). Named commands (STOP, FAVORITE, VENT) go through execute_device_command_()/create_execute_command() instead.
Returns
true if device acknowledged; false on timeout or radio error.

Definition at line 134 of file hub_operations.cpp.

Here is the call graph for this function:

◆ set_device_position_and_tilt()

bool esphome::home_io_control::IOHomeControlComponent::set_device_position_and_tilt ( const std::string & device_id,
uint8_t position,
uint8_t tilt_percent )
virtual

Set both position and tilt of a tilt-capable cover in one atomic command.

Parameters
device_idTarget device ID.
positionDesired position (0–100, open→closed).
tilt_percentDesired tilt (0–100).
Returns
true if device acknowledged; false otherwise.

Definition at line 247 of file hub_operations.cpp.

Here is the call graph for this function:

◆ set_device_status_poll_interval()

void esphome::home_io_control::IOHomeControlComponent::set_device_status_poll_interval ( const std::string & device_id,
uint32_t poll_interval_ms )
virtual

Configure the optional follow-up polling interval for a registered device.

Parameters
device_idTarget device ID.
poll_interval_msPoll interval in milliseconds; zero keeps the legacy one-shot settle poll only.

Definition at line 280 of file hub_core.cpp.

Here is the call graph for this function:

◆ set_device_tilt()

bool esphome::home_io_control::IOHomeControlComponent::set_device_tilt ( const std::string & device_id,
uint8_t tilt_percent )
virtual

Send a tilt command to a tilt‑capable cover.

Parameters
device_idTarget device ID.
tilt_percentDesired tilt (0–100).
Returns
true if device acknowledged; false otherwise.

Definition at line 217 of file hub_operations.cpp.

Here is the call graph for this function:

◆ set_dio0_pin()

void esphome::home_io_control::IOHomeControlComponent::set_dio0_pin ( InternalGPIOPin * pin)
inline

Set the DIO0 interrupt pin (SX1276).

Definition at line 126 of file hub_core.h.

◆ set_dio1_pin()

void esphome::home_io_control::IOHomeControlComponent::set_dio1_pin ( InternalGPIOPin * pin)
inline

Set the DIO1 interrupt pin (SX1262; also carries the LR1121's DIO9 IRQ line).

Definition at line 130 of file hub_core.h.

◆ set_dio4_pin()

void esphome::home_io_control::IOHomeControlComponent::set_dio4_pin ( InternalGPIOPin * pin)
inline

Set the DIO4 preamble‑detect pin (SX1276, optional).

Definition at line 128 of file hub_core.h.

◆ set_fem_en_pin()

void esphome::home_io_control::IOHomeControlComponent::set_fem_en_pin ( InternalGPIOPin * pin)
inline

Set the front‑end module enable pin.

Definition at line 134 of file hub_core.h.

◆ set_fem_pa_pin()

void esphome::home_io_control::IOHomeControlComponent::set_fem_pa_pin ( InternalGPIOPin * pin)
inline

Set the FEM PA switch pin.

Definition at line 138 of file hub_core.h.

◆ set_key_extraction_armed()

void esphome::home_io_control::IOHomeControlComponent::set_key_extraction_armed ( bool armed)
virtual

Arm or disarm the "Accept Foreign Pairing (Key Extraction)" responder.

Arming picks a fresh throwaway node ID, resets the pairing_responder state machine to ARMED_IDLE, and schedules a 10-minute auto-off. While armed, the 0x28/0x2C/0x31/0x32 branches in process_received_packet_() emulate an unpaired device so a user's existing hub can pair to it and hand over its node_id/system_key (see pairing_responder.h). Disarming — manual, via the HA switch, on successful extraction, or on auto-off — immediately stops those branches from responding; it never touches the real device registry or the hub's own node_id_/ system_key_. Virtual so platform unit tests can substitute a mock hub, matching every other queue_*‍/set_* entry point on this component.

Parameters
armedDesired state.

Definition at line 101 of file hub_key_extraction.cpp.

Here is the call graph for this function:

◆ set_key_extraction_armed_callback()

void esphome::home_io_control::IOHomeControlComponent::set_key_extraction_armed_callback ( std::function< void(bool)> cb)
inline

Register a callback invoked whenever the key-extraction armed state changes — manual toggle, successful extraction, or auto-off timeout — so the switch entity can keep its displayed state in sync when the hub disarms itself rather than the user.

Single-slot, mirrors set_pairing_result_callback().

Parameters
cbCallable receiving the new armed state.

Definition at line 255 of file hub_core.h.

◆ set_light_position()

bool esphome::home_io_control::IOHomeControlComponent::set_light_position ( const std::string & device_id,
uint8_t position )
virtual

Send an arbitrary IO position (0-100) to a light entity.

Internally mapped to the shared execute path. set_light_state() is a thin binary-position wrapper around this, used by dimmable lights to send anything other than the two binary extremes.

Parameters
device_idTarget device ID.
positionDesired IO position (0-100); this device family's convention maps 0 to full brightness and 100 to off, the same 0-100 scale platform_cover.cpp uses.
Returns
true if device acknowledged.

Definition at line 312 of file hub_operations.cpp.

Here is the call graph for this function:

◆ set_light_state()

bool esphome::home_io_control::IOHomeControlComponent::set_light_state ( const std::string & device_id,
bool on )
virtual

Semantic binary helper for light entities.

Internally mapped to the shared execute path.

Parameters
device_idTarget device ID.
onDesired on/off state.
Returns
true if device acknowledged.

Definition at line 327 of file hub_operations.cpp.

Here is the call graph for this function:

◆ set_lock_state()

bool esphome::home_io_control::IOHomeControlComponent::set_lock_state ( const std::string & device_id,
bool locked )
virtual

Semantic lock helper for lock entities.

Internally mapped to the shared execute path.

Parameters
device_idTarget device ID.
lockedDesired locked/unlocked state.
Returns
true if device acknowledged.

Definition at line 345 of file hub_operations.cpp.

Here is the call graph for this function:

◆ set_node_id()

void esphome::home_io_control::IOHomeControlComponent::set_node_id ( const std::string & id)
inline

Set the controller's node ID (hex string).

Definition at line 140 of file hub_core.h.

◆ set_pa_pin()

void esphome::home_io_control::IOHomeControlComponent::set_pa_pin ( uint8_t pa_pin)
inline

Set PA boost pin configuration.

Definition at line 146 of file hub_core.h.

◆ set_pairing_result_callback()

void esphome::home_io_control::IOHomeControlComponent::set_pairing_result_callback ( std::function< void()> cb)
inline

Register a callback invoked once, right after every discover_and_pair() attempt completes — used by the "Last Pairing Result" text sensor to publish a fresh value.

Single-slot: only one platform instance is expected per hub.

Parameters
cbCallable with no arguments.

Definition at line 235 of file hub_core.h.

◆ set_radio_test_mode()

void esphome::home_io_control::IOHomeControlComponent::set_radio_test_mode ( bool active)
inline

Suspend the hub's normal loop (packet processing, hopping, polling).

Used by loopback test configs to take exclusive control of the radio.

Definition at line 117 of file hub_core.h.

◆ set_radio_type()

void esphome::home_io_control::IOHomeControlComponent::set_radio_type ( const std::string & type)
inline

Set radio type ("sx1276", "sx1262", or "lr1121"); required by the YAML schema.

Definition at line 148 of file hub_core.h.

◆ set_rst_pin()

void esphome::home_io_control::IOHomeControlComponent::set_rst_pin ( InternalGPIOPin * pin)
inline

Set the radio reset pin.

Definition at line 124 of file hub_core.h.

◆ set_switch_state()

bool esphome::home_io_control::IOHomeControlComponent::set_switch_state ( const std::string & device_id,
bool on )
virtual

Semantic binary helper for switch entities.

Internally mapped to the shared execute path.

Parameters
device_idTarget device ID.
onDesired on/off state.
Returns
true if device acknowledged.

Definition at line 331 of file hub_operations.cpp.

Here is the call graph for this function:

◆ set_system_key()

void esphome::home_io_control::IOHomeControlComponent::set_system_key ( const std::string & key)
inline

Set the system key (hex string).

Definition at line 142 of file hub_core.h.

◆ set_tcxo_voltage()

void esphome::home_io_control::IOHomeControlComponent::set_tcxo_voltage ( uint8_t voltage)
inline

Set TCXO voltage for SX1262/LR1121 (1.8V / 3.3V).

Definition at line 150 of file hub_core.h.

◆ set_tuning_config()

void esphome::home_io_control::IOHomeControlComponent::set_tuning_config ( const TuningConfig & config)
inline

Apply the tuning configuration generated from YAML / UI entities.

Definition at line 153 of file hub_core.h.

◆ set_tx_power()

void esphome::home_io_control::IOHomeControlComponent::set_tx_power ( uint8_t power)
inline

Set transmit power (dBm).

Definition at line 144 of file hub_core.h.

◆ set_vfem_pin()

void esphome::home_io_control::IOHomeControlComponent::set_vfem_pin ( InternalGPIOPin * pin)
inline

Set the VFEM power pin.

Definition at line 136 of file hub_core.h.

◆ setup()

void esphome::home_io_control::IOHomeControlComponent::setup ( )
override

Initialize hardware (radio and device registry).

Initialize the IO‑Homecontrol component and radio hardware.

This is the main setup entry point called by ESPHome during startup. The sequence:

  1. Parse node_id and system_key from hex strings (fails early if malformed).
  2. Initialize the SPI bus via spi_setup().
  3. Construct the driver named by the required radio_type YAML field ("sx1276", "sx1262", or "lr1121").
  4. Allocate the appropriate RadioDriver (SX1276 needs DIO0; SX1262/LR1121 need BUSY+DIO1, DIO1 carrying the LR1121's DIO9 IRQ line).
  5. Call radio_->init() which performs chip reset, calibration, and register configuration.
  6. Enter normal loop() operation with radio in RX mode.
Note
Blocking operations in setup() temporarily raise the ESPHome WDT threshold to 250 ms (warn_if_blocking_over_) because radio init can exceed the default 30–50 ms budget.

Definition at line 57 of file hub_core.cpp.

Here is the call graph for this function:

◆ spi_disable()

void esphome::home_io_control::IOHomeControlComponent::spi_disable ( )
inlineoverridevirtual

Disable the SPI bus.

Implements esphome::home_io_control::SpiAccess.

Definition at line 103 of file hub_core.h.

◆ spi_enable()

void esphome::home_io_control::IOHomeControlComponent::spi_enable ( )
inlineoverridevirtual

Enable the SPI bus.

Implements esphome::home_io_control::SpiAccess.

Definition at line 101 of file hub_core.h.

◆ spi_read()

uint8_t esphome::home_io_control::IOHomeControlComponent::spi_read ( )
inlineoverridevirtual

Read one byte (MISO only).

Returns
Received byte.

Implements esphome::home_io_control::SpiAccess.

Definition at line 113 of file hub_core.h.

◆ spi_transfer()

uint8_t esphome::home_io_control::IOHomeControlComponent::spi_transfer ( uint8_t data)
inlineoverridevirtual

Transfer one byte full‑duplex.

Parameters
dataByte to send.
Returns
Received byte.

Implements esphome::home_io_control::SpiAccess.

Definition at line 107 of file hub_core.h.

◆ spi_write()

void esphome::home_io_control::IOHomeControlComponent::spi_write ( uint8_t data)
inlineoverridevirtual

Write one byte (MOSI only).

Parameters
dataByte to send.

Implements esphome::home_io_control::SpiAccess.

Definition at line 110 of file hub_core.h.

◆ transmit_frame_()

bool esphome::home_io_control::IOHomeControlComponent::transmit_frame_ ( const IoFrame & frame,
uint32_t freq,
uint16_t preamble )
protected

Transmit a raw IoFrame on the current frequency with given preamble length.

Delegate LBT transmit to ExchangeEngine.

Parameters
frameIoFrame to transmit.
freqRF frequency in Hz.
preamblePreamble length in bytes (LONG_PREAMBLE or SHORT_PREAMBLE).

Definition at line 259 of file hub_core.cpp.

◆ try_handle_key_extraction_frame_()

bool esphome::home_io_control::IOHomeControlComponent::try_handle_key_extraction_frame_ ( const IoFrame & frame)
protected

Dispatch a frame to the key-extraction responder if it's one of its 0x28/0x2C/0x31/0x32 frames and the responder is armed.

Factored out of process_received_packet_() purely to keep that function's cognitive complexity under the clang-tidy threshold, mirroring PairingEngine::record_discovery_rx_telemetry_()'s reason for existing.

Parameters
frameParsed inbound frame.
Returns
true if the frame was handled (caller should stop further dispatch for it).

Definition at line 142 of file hub_key_extraction.cpp.

Here is the call graph for this function:

◆ update_device_status_()

void esphome::home_io_control::IOHomeControlComponent::update_device_status_ ( const IoFrame & frame,
bool trust_position = true )
protected

Extract supported position or metadata info from a response frame and merge it into the device record.

Parameters
frameIoFrame containing a supported inbound command such as CMD_PRIVATE_RESP, CMD_STATUS_UPDATE, CMD_GET_NAME_RESP, or CMD_GET_INFO2_RESP.
trust_positionFalse to apply is_stopped but skip target/position decode for a CMD_PRIVATE_RESP — the immediate reply to our own just-sent CMD_EXECUTE echoes stale pre-command target/current values on at least some devices (see tests/corpus/captures/somfy_awning/execute_ack_reports_stale_target_*.yaml), so execute_request_and_update_() passes false there; every other caller trusts as before.

Definition at line 305 of file hub_status.cpp.

Here is the call graph for this function:

◆ update_tuning_number()

void esphome::home_io_control::IOHomeControlComponent::update_tuning_number ( const std::string & name,
float value )

Receive a numeric tuning update from a HA number entity.

Update a numeric tuning parameter from a Home Assistant number entity.

Parses the parameter name and applies the new value to the in-memory tuning configuration. Radio-affecting parameters are forwarded to the active driver immediately; the change is logged in YAML-compatible form so it can be copied back into the configuration file.

Definition at line 194 of file hub_core.cpp.

Here is the call graph for this function:

◆ update_tuning_select()

void esphome::home_io_control::IOHomeControlComponent::update_tuning_select ( const std::string & name,
const std::string & value )

Receive a select tuning update from a HA select entity.

Update a select tuning parameter from a Home Assistant select entity.

Parses the selected option string and applies it to the in-memory tuning configuration. Radio-affecting parameters are forwarded to the active driver immediately; the change is logged in YAML-compatible form.

Definition at line 211 of file hub_core.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ busy_

bool esphome::home_io_control::IOHomeControlComponent::busy_ {false}
protected

Definition at line 746 of file hub_core.h.

◆ busy_pin_

InternalGPIOPin* esphome::home_io_control::IOHomeControlComponent::busy_pin_ {nullptr}
protected

SX1262/LR1121 BUSY pin.

Definition at line 729 of file hub_core.h.

◆ dio0_pin_

InternalGPIOPin* esphome::home_io_control::IOHomeControlComponent::dio0_pin_ {nullptr}
protected

SX1276 DIO0 interrupt.

Definition at line 726 of file hub_core.h.

◆ dio1_pin_

InternalGPIOPin* esphome::home_io_control::IOHomeControlComponent::dio1_pin_ {nullptr}
protected

SX1262 DIO1 interrupt; also carries the LR1121's DIO9 IRQ line.

Definition at line 728 of file hub_core.h.

◆ dio4_pin_

InternalGPIOPin* esphome::home_io_control::IOHomeControlComponent::dio4_pin_ {nullptr}
protected

SX1276 DIO4 preamble detect (optional).

Definition at line 727 of file hub_core.h.

◆ exchange_engine_

ExchangeEngine esphome::home_io_control::IOHomeControlComponent::exchange_engine_
protected

Owns all authenticated exchange and LBT/hop logic.

Definition at line 763 of file hub_core.h.

◆ exposed_senders_

std::vector<std::string> esphome::home_io_control::IOHomeControlComponent::exposed_senders_
protected

1W sender node IDs (remotes or sensors) allowed to fire the sender HA event (add_exposed_sender).

Config-time list (populated once from YAML), not a per-frame allocation.

Definition at line 752 of file hub_core.h.

◆ fem_en_pin_

InternalGPIOPin* esphome::home_io_control::IOHomeControlComponent::fem_en_pin_ {nullptr}
protected

Front-end module enable.

Definition at line 730 of file hub_core.h.

◆ fem_pa_pin_

InternalGPIOPin* esphome::home_io_control::IOHomeControlComponent::fem_pa_pin_ {nullptr}
protected

Front-end module PA switch.

Definition at line 732 of file hub_core.h.

◆ first_1w_activity_ms_

uint32_t esphome::home_io_control::IOHomeControlComponent::first_1w_activity_ms_ {0}
protected

millis() of the first 1W frame in the current burst.

Advances to the new frame's timestamp whenever the gap since last_1w_activity_ms_ reaches ONEWAY_QUIET_PERIOD_MS (the previous burst has already released any deferred poll, so this one starts fresh); otherwise holds at the burst's start. Bounds defer_background_poll_() via ONEWAY_POLL_DEFER_CAP_MS.

Definition at line 779 of file hub_core.h.

◆ initialized_

bool esphome::home_io_control::IOHomeControlComponent::initialized_ {false}
protected

Definition at line 745 of file hub_core.h.

◆ key_extraction_armed_callback_

std::function<void(bool)> esphome::home_io_control::IOHomeControlComponent::key_extraction_armed_callback_
protected

Invoked whenever the key-extraction armed state changes; see set_key_extraction_armed_callback().

Definition at line 759 of file hub_core.h.

◆ key_extraction_ctx_

pairing_responder::ResponderContext esphome::home_io_control::IOHomeControlComponent::key_extraction_ctx_
protected

State for the current "Accept Foreign Pairing" (key-extraction) arm cycle; DISARMED by default so a fresh boot never responds to foreign pairing traffic.

See pairing_responder.h.

Definition at line 757 of file hub_core.h.

◆ last_1w_activity_ms_

uint32_t esphome::home_io_control::IOHomeControlComponent::last_1w_activity_ms_ {0}
protected

millis() of the most recent 1W frame of any kind, including ones dropped as duplicates — a repeat still means the remote is transmitting.

0 until the first is seen. Gates background polls in loop(); see decisions::defer_background_poll_for_1w_activity().

Definition at line 774 of file hub_core.h.

◆ last_1w_logged_

decisions::OneWayDedupState esphome::home_io_control::IOHomeControlComponent::last_1w_logged_ {}
protected

Identity of the last processed 1W frame, for burst suppression; see decisions::is_duplicate_1w_frame() for why the intent bytes are part of the key.

Definition at line 770 of file hub_core.h.

◆ management_actions_

ManagementActions esphome::home_io_control::IOHomeControlComponent::management_actions_
protected

Owns rename, identify, force-open, scan_paired_devices, and other hub-level HA actions.

Definition at line 765 of file hub_core.h.

◆ node_id_

uint8_t esphome::home_io_control::IOHomeControlComponent::node_id_[NODE_ID_SIZE] {}
protected

Definition at line 738 of file hub_core.h.

◆ node_id_str_

std::string esphome::home_io_control::IOHomeControlComponent::node_id_str_
protected

Definition at line 735 of file hub_core.h.

◆ op_queue_

OperationQueue esphome::home_io_control::IOHomeControlComponent::op_queue_
protected

Definition at line 761 of file hub_core.h.

◆ pa_pin_

uint8_t esphome::home_io_control::IOHomeControlComponent::pa_pin_ {DEFAULT_PA_PIN_PA_BOOST}
protected

Definition at line 741 of file hub_core.h.

◆ pairing_engine_

PairingEngine esphome::home_io_control::IOHomeControlComponent::pairing_engine_
protected

Owns the three-phase device pairing flow.

Definition at line 764 of file hub_core.h.

◆ pairing_result_callback_

std::function<void()> esphome::home_io_control::IOHomeControlComponent::pairing_result_callback_
protected

Invoked once after every pairing attempt completes; see set_pairing_result_callback().

Definition at line 754 of file hub_core.h.

◆ pairing_telemetry_

PairingTelemetry esphome::home_io_control::IOHomeControlComponent::pairing_telemetry_
protected

Per-attempt pairing telemetry, shared with ExchangeEngine/PairingEngine.

Definition at line 762 of file hub_core.h.

◆ poll_policy_

StatusPollPolicy esphome::home_io_control::IOHomeControlComponent::poll_policy_
protected

Definition at line 760 of file hub_core.h.

◆ radio_

RadioDriver* esphome::home_io_control::IOHomeControlComponent::radio_ {nullptr}
protected

Definition at line 722 of file hub_core.h.

◆ radio_test_mode_

bool esphome::home_io_control::IOHomeControlComponent::radio_test_mode_ {false}
protected

When true, loop() is suspended for loopback testing.

Definition at line 747 of file hub_core.h.

◆ radio_type_

std::string esphome::home_io_control::IOHomeControlComponent::radio_type_
protected

"sx1276", "sx1262", or "lr1121"; required by the YAML schema.

Definition at line 737 of file hub_core.h.

◆ registry_

DeviceRegistry esphome::home_io_control::IOHomeControlComponent::registry_
protected

Definition at line 749 of file hub_core.h.

◆ rst_pin_

InternalGPIOPin* esphome::home_io_control::IOHomeControlComponent::rst_pin_ {nullptr}
protected

Definition at line 725 of file hub_core.h.

◆ system_key_

uint8_t esphome::home_io_control::IOHomeControlComponent::system_key_[AES_KEY_SIZE] {}
protected

Definition at line 739 of file hub_core.h.

◆ system_key_str_

std::string esphome::home_io_control::IOHomeControlComponent::system_key_str_
protected

Definition at line 736 of file hub_core.h.

◆ tcxo_voltage_

uint8_t esphome::home_io_control::IOHomeControlComponent::tcxo_voltage_ {DEFAULT_TCXO_VOLTAGE_SETTING_1P8V}
protected

SX1262/LR1121 TCXO voltage setting (default 1.8 V).

Definition at line 742 of file hub_core.h.

◆ tuning_

TuningConfig esphome::home_io_control::IOHomeControlComponent::tuning_ {}
protected

Runtime tuning overrides.

Definition at line 748 of file hub_core.h.

◆ tx_power_

uint8_t esphome::home_io_control::IOHomeControlComponent::tx_power_ {DEFAULT_TX_POWER_DBM}
protected

Definition at line 740 of file hub_core.h.

◆ vfem_pin_

InternalGPIOPin* esphome::home_io_control::IOHomeControlComponent::vfem_pin_ {nullptr}
protected

Front-end module power.

Definition at line 731 of file hub_core.h.


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