hub_core.h

Go to the documentation of this file.

#pragma once
 
/// @file hub_core.h
/// @brief IO-Homecontrol ESPHome component — protocol controller.
/// @ingroup hioc_hub
///
/// This component manages the IO-Homecontrol 2W protocol: sending commands,
/// receiving responses with automatic authentication, device discovery/pairing,
/// and device state tracking. Radio hardware is delegated to a RadioDriver
/// implementation (SX1276, SX1262, etc.).
///
/// SPI configuration: MSB first, CPOL=0, CPHA=0 (Mode 0), 8 MHz clock.
/// The component inherits SPIDevice and implements SpiAccess to bridge
/// the ESPHome SPI framework to the radio driver.
///
/// Architecture notes:
///   - setup() initializes radio, waits for YAML-driven device registration, and enters RX mode.
///   - loop() drains the OperationQueue collaborator (serializes all radio work).
///   - All outbound commands go through send_and_receive_, a thin wrapper around
///     ExchangeEngine which owns retry, timing, and challenge-response auth.
///   - Inbound frames are processed in process_received_packet_ and may trigger
///     inbound authentication (ExchangeEngine::authenticate_request) if the device proves itself.
///   - DeviceRegistry and its callbacks provide fan-out to platform entities
///     (covers/lights/switches/locks); StatusPollPolicy schedules follow-up polls;
///     PairingEngine owns pairing; ManagementActions owns the rename/identify/force-open
///     hub-level Home Assistant actions.
 
#include "esphome/core/component.h"
#include "esphome/core/hal.h"
#include "esphome/components/api/custom_api_device.h"
#include "esphome/components/spi/spi.h"
#include "proto_codecs.h"
#include "proto_frame.h"
#include "proto_heating.h"
#include "radio_interface.h"
#include "tuning_config.h"
#include "hub_exchange.h"
#include "hub_decisions.h"
#include "hub_pairing.h"
#include "device_registry.h"
#include "status_poll_policy.h"
#include "operation_queue.h"
#include "exchange_engine.h"
#include "pairing_engine.h"
#include "management_actions.h"
#include "key_extraction_responder.h"
#include "oneway_controller.h"
#include "oneway_transmitter.h"
#include "oneway_key_adoption.h"
// lr1121_firmware_update_controller.h forward-declares FlashDecision / BootloaderUpgradePath /
// Lr1121FirmwareUpdater so lr1121_firmware_decisions.h and radio_lr1121_firmware_updater.h are
// NOT pulled into hub_core.h — that header weight stays in the collaborator's .cpp alone.
#include "lr1121_firmware_update_controller.h"
#include <map>
#include <vector>
#include <functional>
 
namespace esphome {
namespace home_io_control {
 
inline constexpr uint8_t DEFAULT_TX_POWER_DBM = 17;       ///< Default TX power used unless YAML overrides it.
inline constexpr uint8_t DEFAULT_PA_PIN_PA_BOOST = 0x80;  ///< SX1276 PA_CONFIG selector for the PA_BOOST output path.
inline constexpr uint8_t DEFAULT_TCXO_VOLTAGE_SETTING_1P8V = 0x02;  ///< 0-based TCXO voltage code for 1.8 V,
                                                                    ///< passed verbatim to the SX1262/LR1121 chip.
inline constexpr size_t POSITION_TEXT_BUFFER_SIZE = 16;  ///< Buffer for formatted position strings such as "100%".
 
#ifdef IOHOME_LR1121_FIRMWARE_UPDATE
/// Max value representable by Component::warn_if_blocking_over_ (a centisecond uint8_t, ~2550 ms
/// ceiling). Raised for a flash excursion so the log fills with progress output rather than
/// component-blocking warnings — a flash still runs far longer than 2550 ms, so this reduces
/// warning spam, it cannot eliminate it. Lives here rather than in the collaborator because
/// warn_if_blocking_over_ is protected on ESPHome's Component and only the initializer-list lambda
/// below legitimately writes it.
inline constexpr uint8_t LR1121_FLASH_WARN_BLOCKING_MAX_CS = 255;
#endif
 
// ============================================================================
// Main Component
// ============================================================================
 
/// 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.
/// @ingroup hioc_hub
class IOHomeControlComponent : public Component,
                               public api::CustomAPIDevice,
                               public spi::SPIDevice<spi::BIT_ORDER_MSB_FIRST, spi::CLOCK_POLARITY_LOW,
                                                     spi::CLOCK_PHASE_LEADING, spi::DATA_RATE_8MHZ>,
                               public SpiAccess {
 public:
  /// Initialize ExchangeEngine, PairingEngine, and ManagementActions with double-pointer/
  /// reference indirection so that test assignments (`comp.radio_ = &mock`) propagate
  /// through all collaborators without calling setup().
  IOHomeControlComponent()
      : exchange_engine_(&radio_, node_id_, system_key_, &tuning_),
        pairing_engine_(&radio_, node_id_, system_key_, &tuning_, exchange_engine_, registry_, pairing_telemetry_,
                        recent_oneway_pairing_sighting_),
        management_actions_(node_id_, system_key_, &tuning_, exchange_engine_, registry_, &initialized_, this),
        // Capturing `this` is safe here: the callback is only ever invoked from send_burst(),
        // long after construction. It injects the *ability* to transmit rather than a reference
        // to whichever collaborator currently owns the radio. `&tuning_` is read per burst
        // (never cached), same pattern as exchange_engine_ above, so a live change to
        // `normal_start_preamble` takes effect on the next 1W command without a reboot.
        oneway_transmitter_([this](const IoFrame &frame, uint32_t freq,
                                   uint16_t preamble) { return this->transmit_frame_(frame, freq, preamble); },
                            &tuning_),
        // set_timeout() is protected on the real ESPHome Component (only public in the host stub),
        // so a lambda defined here — with protected access — is the one legitimate caller. See
        // oneway_key_adoption.h's NamedTimeoutFn.
        oneway_key_adoption_([this](const char *name, uint32_t delay_ms, std::function<void()> cb) {
          this->set_timeout(name, delay_ms, std::move(cb));
        }),
        key_extraction_(
            node_id_, &radio_, &tuning_, registry_,
            [this](const IoFrame &frame, uint32_t freq, uint16_t preamble) {
              return this->transmit_frame_(frame, freq, preamble);
            },
            [this](const char *name, uint32_t delay_ms, std::function<void()> cb) {
              this->set_timeout(name, delay_ms, std::move(cb));
            })
#ifdef IOHOME_LR1121_FIRMWARE_UPDATE
        // Guarded initializer for the guarded member. `busy_`/`warn_if_blocking_over_` are
        // protected: the busy pointer is taken here, and the lambda — with protected access — is
        // the one legitimate writer of warn_if_blocking_over_. `this` doubles as SpiAccess* and as
        // the self key for App.scheduler.set_timeout(), never to reach a protected member.
        ,
        lr1121_firmware_update_(
            &radio_, this, &rst_pin_, &busy_pin_, &busy_,
            [this]() { this->warn_if_blocking_over_ = LR1121_FLASH_WARN_BLOCKING_MAX_CS; }, this)
#endif
  {
    // The hub only supplies what it knows about a target; the engine draws its own decisions from
    // it (the wake belief and the re-send of an unconfirmed movement command). Installed here
    // rather than in setup() so a component that never runs setup() (the host tests) is wired
    // exactly like production.
    this->exchange_engine_.set_target_evidence_provider([this](const uint8_t *dst, decisions::TargetEvidence &out) {
      const IoDevice *dev = this->registry_.get(node_id_to_string(dst));
      if (dev == nullptr)
        return false;
      out = decisions::target_evidence(*dev);
      return true;
    });
  }
 
  /// @brief 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.
  using ManagementActionResult = esphome::home_io_control::ManagementActionResult;
 
  /// @brief Initialize hardware (radio and device registry).
  void setup() override;
  /// @brief Main loop: process pending operations and drive radio state machine.
  void loop() override;
  /// @brief Dump configuration and radio debug info to the log.
  void dump_config() override;
  /// @brief Get setup priority (HARDWARE to initialize early).
  /// @return setup_priority::HARDWARE.
  [[nodiscard]] float get_setup_priority() const override { return setup_priority::HARDWARE; }
 
  // --- SpiAccess implementation (delegates to SPIDevice) ---
  /// @brief Enable the SPI bus.
  void spi_enable() override { this->enable(); }
  /// @brief Disable the SPI bus.
  void spi_disable() override { this->disable(); }
  /// @brief Transfer one byte full‑duplex.
  /// @param data Byte to send.
  /// @return Received byte.
  uint8_t spi_transfer(uint8_t data) override { return this->transfer_byte(data); }
  /// @brief Write one byte (MOSI only).
  /// @param data Byte to send.
  void spi_write(uint8_t data) override { this->write_byte(data); }
  /// @brief Read one byte (MISO only).
  /// @return Received byte.
  uint8_t spi_read() override { return this->read_byte(); }
 
  /// @brief Suspend the hub's normal loop (packet processing, hopping, polling).
  /// Used by loopback test configs to take exclusive control of the radio.
  void set_radio_test_mode(bool active) { this->radio_test_mode_ = active; }
 
  /// @brief Get the underlying radio driver (for diagnostics and test tooling).
  [[nodiscard]] RadioDriver *get_radio() const { return this->radio_; }
 
  // --- YAML configuration setters (called by generated code) ---
  /// Set the radio reset pin.
  void set_rst_pin(InternalGPIOPin *pin) { this->rst_pin_ = pin; }
  /// Set the DIO0 interrupt pin (SX1276).
  void set_dio0_pin(InternalGPIOPin *pin) { this->dio0_pin_ = pin; }
  /// Set the DIO4 preamble‑detect pin (SX1276, optional).
  void set_dio4_pin(InternalGPIOPin *pin) { this->dio4_pin_ = pin; }
  /// Set the DIO1 interrupt pin (SX1262; also carries the LR1121's DIO9 IRQ line).
  void set_dio1_pin(InternalGPIOPin *pin) { this->dio1_pin_ = pin; }
  /// Set the BUSY pin (SX1262/LR1121).
  void set_busy_pin(InternalGPIOPin *pin) { this->busy_pin_ = pin; }
  /// Set the front‑end module enable pin.
  void set_fem_en_pin(InternalGPIOPin *pin) { this->fem_en_pin_ = pin; }
  /// Set the VFEM power pin.
  void set_vfem_pin(InternalGPIOPin *pin) { this->vfem_pin_ = pin; }
  /// Set the FEM PA switch pin.
  void set_fem_pa_pin(InternalGPIOPin *pin) { this->fem_pa_pin_ = pin; }
  /// Set which FEM part fem_pa_pin is wired to (`fem:` in YAML) — selects whether the SX1262
  /// driver drives that pin per-transmission (GC1109/KCT8103L/XY16P35) or leaves it static-HIGH
  /// (NONE, the legacy raw-pin behaviour).
  void set_fem_profile(FemProfile profile) { this->fem_profile_ = profile; }
  /// Set the controller's node ID (hex string).
  void set_node_id(const std::string &id) { this->node_id_str_ = id; }
  /// Set the system key (hex string).
  void set_system_key(const std::string &key) { this->system_key_str_ = key; }
  /// Set transmit power (dBm).
  void set_tx_power(uint8_t power) { this->tx_power_ = power; }
  /// Set PA boost pin configuration.
  void set_pa_pin(uint8_t pa_pin) { this->pa_pin_ = pa_pin; }
  /// Set radio type ("sx1276", "sx1262", or "lr1121"); required by the YAML schema.
  void set_radio_type(const std::string &type) { this->radio_type_ = type; }
  /// Set the SX1262/LR1121 TCXO control-voltage code (0-based, `TCXO_VOLTAGE_OPTIONS` in
  /// `hub_validators.py`: `1_6V`=0x00 .. `3_3V`=0x07), or `TCXO_VOLTAGE_NONE` (0xFF) for a board with a
  /// bare crystal and no DIO3-controlled TCXO.
  void set_tcxo_voltage(uint8_t voltage) { this->tcxo_voltage_ = voltage; }
 
  /// Apply the tuning configuration generated from YAML / UI entities.
  void set_tuning_config(const TuningConfig &config) { this->tuning_ = config; }
  /// Receive a numeric tuning update from a HA `number` entity.
  void update_tuning_number(const std::string &name, float value);
  /// Receive a select tuning update from a HA `select` entity.
  void update_tuning_select(const std::string &name, const std::string &value);
  /// Current value of a numeric tuning parameter, used to seed a HA `number` entity on boot.
  /// @param name YAML key of the parameter.
  /// @return Current value, or 0 for an unknown key.
  [[nodiscard]] float get_tuning_number_value(const std::string &name) const;
  /// Current option string of a select tuning parameter, used to seed a HA `select` entity on boot.
  /// @param name YAML key of the parameter.
  /// @return Current value formatted as its YAML option string, or empty for an unknown key.
  [[nodiscard]] std::string get_tuning_select_value(const std::string &name) const;
 
  /// @brief Render a device's "last commanded by" string, resolving this hub's own node ID.
  ///
  /// Thin wrapper over detail::describe_last_commander() (entity_helpers.h); exists because the
  /// hub's node ID is not reachable from a companion entity.
  /// @param dev Device record to read.
  /// @return See detail::describe_last_commander().
  [[nodiscard]] std::string describe_last_commander(const IoDevice &dev) const;
 
  /// 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.
  /// @param remote_id Node ID of the remote control.
  /// @param device_id Node ID of the device it controls.
  void add_linked_remote(const std::string &remote_id, const std::string &device_id) {
    this->registry_.add_linked_remote(remote_id, device_id);
  }
 
  /// Declare that a device class's typed 1W broadcasts (e.g. "all awnings") also apply to
  /// @p device_id, matching how 1W remotes address a device class rather than a single node.
  /// @param type      Device class the broadcast targets.
  /// @param device_id Node ID of the device to add to that class.
  void add_linked_remote_class(DeviceType type, const std::string &device_id) {
    this->registry_.add_linked_remote_class(type, device_id);
  }
 
  /// 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.
  /// @param device_id Target device ID.
  /// @param target_io_position Target position in IO units (0=open, 100=closed).
  /// @return true if the optimistic state was applied.
  virtual bool apply_optimistic_target(const std::string &device_id, float target_io_position) {
    return this->registry_.apply_optimistic_target(device_id, target_io_position);
  }
 
  /// Predict that a device has stopped (e.g. on STOP), and notify.
  /// No-op when the device is unknown or has `optimistic_state == false`. See
  /// DeviceRegistry::apply_optimistic_stop() for why this records a prediction rather than a clear.
  /// Restorable: if the STOP then fails, the movement prediction it replaced comes back.
  /// Virtual (like add_device/get_device) so platform unit tests can substitute a mock registry.
  /// @param device_id Target device ID.
  /// @return true if the optimistic stop was applied.
  virtual bool apply_optimistic_stop(const std::string &device_id) {
    // Restorable: this is the entity's own STOP, which the hub is about to send and which can fail.
    return this->registry_.apply_optimistic_stop(device_id, /*restorable=*/true);
  }
 
  /// 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.
  /// @param device_id    Target device ID.
  /// @param tilt_percent Slat angle in the same percent scale as `IoDevice::tilt` (0-100).
  /// @return true if the optimistic tilt was applied.
  virtual bool apply_optimistic_tilt(const std::string &device_id, float tilt_percent) {
    return this->registry_.apply_optimistic_tilt(device_id, tilt_percent);
  }
 
  /// 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.
  /// @param sender_id Node ID of the 1W sender (remote or sensor).
  void add_exposed_sender(const std::string &sender_id) { this->exposed_senders_.push_back(sender_id); }
 
  /// Register a configured 1W controller identity (see oneway_controller.h). Called once per
  /// `oneway_controllers:` entry from generated code. Both the source address and the key are
  /// already resolved at schema time — a derived address is computed there so a collision with
  /// the hub's own address or another identity fails the build rather than silently desyncing a
  /// transmitter at runtime.
  /// @param identity Fully-resolved controller identity.
  void add_oneway_controller(const OneWayControllerIdentity &identity) {
    this->oneway_transmitter_.add_identity(identity);
  }
 
  /// @return The configured 1W controller identities.
  [[nodiscard]] const OneWayControllerRegistry &oneway_controllers() const {
    return this->oneway_transmitter_.identities();
  }
 
  /// @brief Queue a 1W named command, sent as the given controller identity.
  ///
  /// Goes through the operation queue like every other radio operation (ADR 0013), so a 1W burst
  /// can never interleave with a 2W exchange. Unlike a 2W command this reports nothing back: 1W
  /// has no reply, so a queued command that a device ignores is indistinguishable from one it
  /// obeyed. The "Last 1W Command" diagnostic reports what was *transmitted*, which is the only
  /// half of that the hub can know.
  /// @param controller_id Controller-identity handle from `oneway_controllers:`.
  /// @param cmd Named command (STOP, FAVORITE, VENT, FORCE_OPEN).
  void send_oneway_command(const std::string &controller_id, CoverCommand cmd) {
    this->op_queue_.enqueue_oneway_command(controller_id, cmd);
  }
 
  /// @brief Queue a 1W numeric position, sent as the given controller identity.
  /// @param controller_id Controller-identity handle from `oneway_controllers:`.
  /// @param position Target position 0–100 (0 = fully open, 100 = fully closed).
  void send_oneway_position(const std::string &controller_id, uint8_t position) {
    this->op_queue_.enqueue_oneway_position(controller_id, position);
  }
 
  /// @brief Queue whichever of position/command a generated button's action resolves to.
  ///
  /// The mapping is applied here, at enqueue time, so the queue only ever holds concrete
  /// operations — OPEN and CLOSE are positions on the wire, not commands, and nothing downstream
  /// should have to know that twice.
  /// @param controller_id Controller-identity handle from `oneway_controllers:`.
  /// @param action Button action to send.
  void send_oneway_action(const std::string &controller_id, OneWayButtonAction action) {
    const OneWayActionEncoding encoding = encode_oneway_action(action);
    if (encoding.is_position) {
      this->send_oneway_position(controller_id, encoding.position);
    } else {
      this->send_oneway_command(controller_id, encoding.command);
    }
  }
 
  /// @brief Queue a 1W enrollment for the given controller identity — the enroll button's press
  /// handler.
  ///
  /// Sends `0x39` (self-directed) then `0x30`, back to back — see
  /// OneWayTransmitter::send_enrollment().
  /// @param controller_id Controller-identity handle from `oneway_controllers:`.
  void send_oneway_enroll(const std::string &controller_id) { this->op_queue_.enqueue_oneway_enroll(controller_id); }
 
  /// @brief Queue a standalone 1W un-enrollment (remove-controller) for the given controller
  /// identity, reached only through the explicitly-named `oneway_remove_controller` native API
  /// action — the same `0x39` send_oneway_enroll() also fires as its own prelude, but here alone.
  ///
  /// @warning **Unconfirmed standalone on real hardware.** Firing `0x39` alone has had no
  /// observable effect on this project's test hardware; the leading hypothesis is that it needs
  /// the same association-mode window enrollment does. See ADR 0026 § Consequences.
  /// @param controller_id Controller-identity handle from `oneway_controllers:`.
  void send_oneway_unenroll(const std::string &controller_id) {
    this->op_queue_.enqueue_oneway_unenroll(controller_id);
  }
 
  /// @brief Subscribe to the report emitted after every 1W command attempt.
  ///
  /// A list rather than a single slot: each identity gets its own "Last 1W Command" sensor, and
  /// each filters the reports down to its own handle.
  /// @param callback Invoked for every attempt, successful or not.
  void add_oneway_command_report_callback(OneWayCommandReportFn callback) {
    this->oneway_report_callbacks_.push_back(std::move(callback));
  }
 
  /// @return The 1W transmit collaborator, for diagnostics and the sequence-resync path.
  [[nodiscard]] OneWayTransmitter &oneway_transmitter() { return this->oneway_transmitter_; }
 
  /// @return The telemetry recorded for the most recent (or in-progress) pairing attempt.
  [[nodiscard]] const PairingTelemetry &pairing_telemetry() const { return this->pairing_telemetry_; }
 
  /// 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.
  /// @param cb Callable with no arguments.
  void set_pairing_result_callback(std::function<void()> cb) { this->pairing_result_callback_ = std::move(cb); }
 
  /// @brief Arm or disarm the "Recover System Key" (key extraction) responder.
  ///
  /// Thin forwarder to the KeyExtractionResponder collaborator (key_extraction_responder.h).
  /// 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.
  /// @param armed Desired state.
  virtual void set_key_extraction_armed(bool armed) { this->key_extraction_.set_armed(armed); }
 
  /// 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().
  /// @param cb Callable receiving the new armed state.
  void set_key_extraction_armed_callback(std::function<void(bool)> cb) {
    this->key_extraction_.set_armed_callback(std::move(cb));
  }
 
  /// Arm or disarm the 1W controller-key adoption listener. Thin forwarder to the OnewayKeyAdoption
  /// collaborator (oneway_key_adoption.h) — while armed, an overheard CMD_ONEWAY_ADD_CONTROLLER
  /// broadcast is decrypted and reported once, after which the listener disarms itself (one
  /// adoption per arm). Receive-only: unlike 2W key extraction this never transmits, it only
  /// listens for a frame a 1W device broadcasts of its own accord. Virtual so platform unit tests
  /// can substitute a mock hub, matching every other queue_*/set_* entry point on this component.
  /// @param armed Desired state.
  virtual void set_oneway_key_adoption_armed(bool armed) { this->oneway_key_adoption_.set_armed(armed); }
 
  /// Register a callback invoked whenever the 1W key-adoption armed state changes — manual
  /// toggle, successful adoption, or auto-off timeout — so the switch entity stays in sync when
  /// the hub disarms itself rather than the user. Single-slot, mirrors
  /// set_key_extraction_armed_callback().
  /// @param cb Callable receiving the new armed state.
  void set_oneway_key_adoption_armed_callback(std::function<void(bool)> cb) {
    this->oneway_key_adoption_.set_armed_callback(std::move(cb));
  }
 
  /// Whether the 1W key-adoption listener is currently armed.
  /// @return true while armed.
  [[nodiscard]] bool oneway_key_adoption_armed() const { return this->oneway_key_adoption_.armed(); }
 
  /// @brief Set whether ManagementActions::probe_device()/probe_sweep() are allowed to run.
  ///
  /// Set once from the `diagnostic_probes:` YAML boolean (`__init__.py`); off by default, so a
  /// build that doesn't opt in never sends an undecoded probe opcode. Not a runtime toggle: there
  /// is no entity and nothing else calls this after setup — the gate is "was this build
  /// configured with `diagnostic_probes: true`", not a state a user flips per session.
  /// @param enabled Desired state.
  void set_diagnostic_probes_enabled(bool enabled) { this->diagnostic_probes_enabled_ = enabled; }
 
  /// @brief Whether diagnostic probes are enabled for this build.
  [[nodiscard]] bool diagnostic_probes_enabled() const { return this->diagnostic_probes_enabled_; }
 
  // --- Device management (called by platform entities during setup) ---
  /// 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.
  /// @param device_id Hexadecimal node ID string.
  virtual void add_device(const std::string &device_id);
  /// Add a device to the registry with full metadata from a YAML declaration.
  /// @param device_id Hexadecimal node ID string.
  /// @param cfg Device type/subtype/inversion/optimistic-state metadata.
  virtual void add_device(const std::string &device_id, const DeviceConfig &cfg);
  /// Retrieve a device by ID; returns nullptr if not found.
  /// @param device_id Hexadecimal node ID.
  /// @return Pointer to IoDevice, or nullptr.
  virtual IoDevice *get_device(const std::string &device_id);
  /// 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.
  /// @param device_id Hexadecimal node ID string.
  /// @param dimmable New value for IoDevice::dimmable.
  virtual void set_device_dimmable(const std::string &device_id, bool dimmable);
 
  /// Select a device's travel profile at runtime (see IOHomeCoverSilentSwitch).
  /// Virtual for the same reason as set_device_dimmable: platform tests substitute a mock registry.
  /// @param device_id Hexadecimal node ID string.
  /// @param silent    True to send position moves in "silent operation" (slower) mode.
  virtual void set_device_silent(const std::string &device_id, bool silent);
  /// Register a callback invoked when any device updates.
  /// @param cb Callable with signature void(const std::string&, const IoDevice&).
  virtual void register_device_callback(DeviceUpdateCallback cb) { this->registry_.subscribe(std::move(cb)); }
  /// Configure the optional follow-up polling interval for a registered device.
  /// @param device_id Target device ID.
  /// @param poll_interval_ms Poll interval in milliseconds; zero keeps the legacy one-shot settle poll only.
  virtual void set_device_status_poll_interval(const std::string &device_id, uint32_t poll_interval_ms);
 
  // --- High-level operations ---
  /// Send a position command to a device.
  /// @param device_id Target device ID.
  /// @param position Desired position, 0–100 (open→closed). Named commands (STOP, FAVORITE,
  ///        VENT) go through execute_device_command_()/create_execute_command() instead.
  /// @return true if device acknowledged; false on timeout or radio error.
  virtual bool set_device_position(const std::string &device_id, uint8_t position);
  /// Send a tilt command to a tilt‑capable cover.
  /// @param device_id Target device ID.
  /// @param tilt_percent Desired tilt (0–100).
  /// @return true if device acknowledged; false otherwise.
  virtual bool set_device_tilt(const std::string &device_id, uint8_t tilt_percent);
  /// Set both position and tilt of a tilt-capable cover in one atomic command.
  /// @param device_id Target device ID.
  /// @param position Desired position (0–100, open→closed).
  /// @param tilt_percent Desired tilt (0–100).
  /// @return true if device acknowledged; false otherwise.
  virtual bool set_device_position_and_tilt(const std::string &device_id, uint8_t position, uint8_t tilt_percent);
  /// Request current status from a device.
  /// @param device_id Target device ID.
  /// @return true if status frame was received and processed.
  virtual bool request_device_status(const std::string &device_id);
  /// Request the stored device name from a device.
  /// @param device_id Target device ID.
  /// @return true if a name response frame was received and processed.
  virtual bool request_device_name(const std::string &device_id);
  /// Rename a device and verify the result by reading the name back.
  /// @param device_id Target device ID.
  /// @param new_name Requested UTF-8 device name.
  /// @return Structured result describing success, verification, and any validation failure.
  virtual ManagementActionResult rename_device(const std::string &device_id, const std::string &new_name) {
    return this->management_actions_.rename_device(device_id, new_name);
  }
  /// Trigger a device's physical identify (brief jog/flash) so a user can confirm which
  /// physical motor a device ID maps to.
  /// @param device_id Target device ID.
  /// @return Structured result describing success and any validation failure. `verified` is
  ///         always false — there is no readback for a physical identify jog.
  virtual ManagementActionResult identify_device(const std::string &device_id) {
    return this->management_actions_.identify_device(device_id);
  }
  /// @brief 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.
  /// @param device_id Target device ID.
  /// @return Structured result describing whether the command was queued.
  virtual ManagementActionResult force_open_device(const std::string &device_id) {
    return this->management_actions_.force_open_device(device_id);
  }
  /// 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).
  /// @return Structured result whose `message` is the full multi-line report.
  virtual ManagementActionResult scan_paired_devices() { return this->management_actions_.scan_paired_devices(); }
  /// Send a single diagnostic probe frame to a registered device and report the raw reply (see
  /// ManagementActions::probe_device() for the full contract, argument formats, and safety
  /// gating). Protocol-research instrumentation for opcodes this codebase has not decoded — see
  /// docs/diagnostic-probes.md and ADR 0024.
  /// @param device_id Target device ID.
  /// @param probe Probe name ("private_fn", "status_ext", "general_info3", "private2", or
  ///        "private2_short").
  /// @param index Function ID / selector block / modifier, as a decimal or `0x`-prefixed hex
  ///        string; ignored for "general_info3".
  /// @return Structured result whose `message` carries the reply's command byte and raw hex.
  virtual ManagementActionResult probe_device(const std::string &device_id, const std::string &probe,
                                              const std::string &index) {
    return this->management_actions_.probe_device(device_id, probe, index);
  }
  /// Walk a bounded index range, one probe_device() call per index (see
  /// ManagementActions::probe_sweep()).
  /// @param device_id Target device ID.
  /// @param probe Probe name, same as probe_device().
  /// @param first_index First index in the sweep (inclusive).
  /// @param last_index Last index in the sweep (inclusive).
  /// @return Structured result whose `message` is one line per index.
  virtual ManagementActionResult probe_sweep(const std::string &device_id, const std::string &probe,
                                             const std::string &first_index, const std::string &last_index) {
    return this->management_actions_.probe_sweep(device_id, probe, first_index, last_index);
  }
  /// @brief Run one 2W heating/climate function (CMD_WRITE_PRIVATE 0x20) against a registered
  /// climate device — the `heating_control` hub action.
  ///
  /// Experimental: the protocol is derived from the iohomecontrol project's Cozytouch support and
  /// has never been validated on real Atlantic/Thermor/Sauter hardware. `verified` is always
  /// false: the `set_*` functions are write-only — nothing decodes what the radiator did into an
  /// entity. (`power_on` and `midnight_sync` are register reads; their ACK payload is logged at
  /// DEBUG but not decoded.) See ManagementActions::heating_control() for argument formats.
  /// @param device_id Target device ID.
  /// @param function Heating function name.
  /// @param value Function-specific value string.
  /// @return Structured result describing success and any validation/exchange failure.
  virtual ManagementActionResult heating_control(const std::string &device_id, const std::string &function,
                                                 const std::string &value) {
    return this->management_actions_.heating_control(device_id, function, value);
  }
  /// Discover and pair a device that is in pairing mode.
  /// @return true if pairing completed successfully; false otherwise.
  virtual bool discover_and_pair();
  /// 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.
  /// @param device_id Target device ID.
  /// @param position Desired 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.
  /// @return true if device acknowledged.
  virtual bool set_light_position(const std::string &device_id, uint8_t position);
  /// Semantic binary helper for light entities. Internally mapped to the shared execute path.
  /// @param device_id Target device ID.
  /// @param on Desired on/off state.
  /// @return true if device acknowledged.
  virtual bool set_light_state(const std::string &device_id, bool on);
  /// Semantic binary helper for switch entities. Internally mapped to the shared execute path.
  /// @param device_id Target device ID.
  /// @param on Desired on/off state.
  /// @return true if device acknowledged.
  virtual bool set_switch_state(const std::string &device_id, bool on);
  /// Semantic lock helper for lock entities. Internally mapped to the shared execute path.
  /// @param device_id Target device ID.
  /// @param locked Desired locked/unlocked state.
  /// @return true if device acknowledged.
  virtual bool set_lock_state(const std::string &device_id, bool locked);
  /// @brief The single hub-side transmit path for 2W heating/climate control (CMD_WRITE_PRIVATE
  /// 0x20). Both the `heating_control` hub action and the climate entity call this — there is
  /// exactly one place that transmits heating frames and exactly one caller of
  /// create_write_private().
  ///
  /// Flow: registry lookup -> device_supports_climate_control() gate (rejected via
  /// detail::log_rejected_operation()) -> encode_heating_payload() -> create_write_private() (with
  /// the device's `low_power` flag) -> a plain send_and_receive_(). Deliberately NOT routed
  /// through execute_request_and_update_(): that helper is cover/position-shaped (status decode,
  /// poll backoff), and a heater has no position and no status poll. A CMD_WRITE_PRIVATE_ACK
  /// (0x21) reply is success; anything else (including CMD_ERROR_RESP) is failure. The exchange
  /// still feeds the device-agnostic Last Contact / Exchange Failures link-health sensors.
  ///
  /// Write-only semantics: this only reports whether the device acknowledged the write. The `set_*`
  /// functions decode nothing back into an entity, so callers publish "last commanded, never
  /// confirmed" state on success and never at request time. `power_on` and `midnight_sync` are
  /// register reads whose 0x21 ACK payload is logged at DEBUG (see the .cpp) but not decoded.
  /// @param device_id Target device ID (hex string).
  /// @param fn Heating function to send.
  /// @param value Function-specific value (degrees C, a HeatingMode as float, 0/1, or ignored) —
  ///        see encode_heating_payload().
  /// @return true only if the device answered with CMD_WRITE_PRIVATE_ACK.
  virtual bool send_heating_command(const std::string &device_id, HeatingFunction fn, float value);
  /// @brief 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.
  /// @param device_id Target device ID.
  /// @param position Desired position (0–100).
  virtual void queue_set_device_position(const std::string &device_id, uint8_t position);
  /// @brief 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.
  /// @param device_id Target device ID.
  /// @param cmd Named command to send.
  /// @return true if the hub is initialized, the device is registered, and the command matches
  ///         its capability class (so the command was enqueued); false otherwise.
  virtual bool queue_device_command(const std::string &device_id, CoverCommand cmd);
  /// @brief 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.
  /// @param device_id Target device ID.
  /// @param tilt_percent Desired tilt (0–100).
  virtual void queue_set_device_tilt(const std::string &device_id, uint8_t tilt_percent);
  /// Queue an async combined position+tilt update; returns immediately, executed in loop().
  /// @param device_id Target device ID.
  /// @param position Desired position (0–100).
  /// @param tilt_percent Desired tilt (0–100).
  virtual void queue_set_device_position_and_tilt(const std::string &device_id, uint8_t position, uint8_t tilt_percent);
  /// Queue an async status request; returns immediately, executed in loop().
  /// @param device_id Target device ID.
  virtual void queue_request_device_status(const std::string &device_id);
  /// Queue an async device-name request; returns immediately, executed in loop().
  /// @param device_id Target device ID.
  virtual void queue_request_device_name(const std::string &device_id);
  /// Queue a pairing operation; executed in loop() when radio idle.
  virtual void queue_discover_and_pair();
  /// @brief Entry point for the "Scan Paired Devices" button: run the roll-call and publish its
  /// report to the log and the Home Assistant result event, exactly as the native API action does.
  ///
  /// Deliberately not queued through OperationQueue, unlike queue_discover_and_pair(): the
  /// roll-call has no priority, coalescing or dedup semantics to preserve, and it already runs
  /// this way from the native API action. What it *is* guarded on is `busy_` — a button, unlike an
  /// API action, is also reachable from an ESPHome automation, which can fire from inside a
  /// blocking exchange (an entity callback -> on_value: -> button.press: chain) and would
  /// otherwise re-enter ExchangeEngine mid-exchange. See ADR 0013 for why one blocking radio
  /// operation at a time is the whole concurrency model. A press while `busy_` still fires the
  /// log/event pair (a failed result), matching every other rejected management action rather
  /// than going silent.
  ///
  /// Blocks the ESPHome loop for up to roughly 6 × `pairing_discovery_wait_ms` (both power-class
  /// passes, three channels each; fewer if `scan_power_classes` narrows the sweep) and will log the
  /// "operation took a long time" warning, same as the action — see docs/pairing.md.
  void trigger_scan_paired_devices();
  /// 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.
  /// @param device_id Target device ID.
  /// @param position Desired IO position (0-100).
  virtual void queue_set_light_position(const std::string &device_id, uint8_t position);
  /// Async form of set_light_state() that keeps radio work serialized on the main loop.
  /// @param device_id Target device ID.
  /// @param on Desired on/off state.
  virtual void queue_set_light_state(const std::string &device_id, bool on);
  /// Async form of set_switch_state() that keeps radio work serialized on the main loop.
  /// @param device_id Target device ID.
  /// @param on Desired on/off state.
  virtual void queue_set_switch_state(const std::string &device_id, bool on);
  /// Async form of set_lock_state() that keeps radio work serialized on the main loop.
  /// @param device_id Target device ID.
  /// @param locked Desired locked/unlocked state.
  virtual void queue_set_lock_state(const std::string &device_id, bool locked);
 
#ifdef IOHOME_LR1121_FIRMWARE_UPDATE
  /// @brief Entry point for the "Flash LR1121 Radio Firmware" button. Thin forwarder to the
  /// Lr1121FirmwareUpdateController collaborator (lr1121_firmware_update_controller.h).
  ///
  /// Only exists when a `lr1121_firmware_update:` block is configured. See
  /// lr1121_firmware_update_controller.cpp for the full contract, including the safety invariant
  /// that every bootloader excursion this triggers must end in either radio_->init() or
  /// App.safe_reboot() — there is no third option.
  void trigger_lr1121_firmware_update() { this->lr1121_firmware_update_.trigger(); }
 
#ifdef IOHOME_LR1121_BOOTLOADER_UPDATE
  /// @brief Set by the "Allow LR1121 Bootloader Rewrite (Irreversible)" switch's write_state().
  /// Thin forwarder to the Lr1121FirmwareUpdateController collaborator.
  ///
  /// A permission, not an override: this can only convert a cached
  /// BootloaderUpgradePath::AVAILABLE verdict into "run the three-stage sequence" (bootloader
  /// ADR 0021) -- it never affects REJECT_WRONG_CHIP, the post-entry sanity
  /// check, the busy_ guard, or any other verdict. Read once, at button-press time
  /// (trigger_lr1121_firmware_update()); the ESPHome loop is blocked for the whole three-stage
  /// sequence once it starts, so the switch cannot change mid-flash. Deliberately not named
  /// anything with "armed" -- lr1121_flash_confirmation_armed_ already means the two-press window
  /// this switch *replaces* for its own path, and a reader must never have to guess which is meant.
  void set_bootloader_rewrite_allowed(bool allowed) {
    this->lr1121_firmware_update_.set_bootloader_rewrite_allowed(allowed);
  }
#endif
#endif
 
 protected:
  // --- Protocol-level operations ---
  /// Transmit a raw IoFrame on the current frequency with given preamble length.
  /// @param frame IoFrame to transmit.
  /// @param freq RF frequency in Hz.
  /// @param preamble Preamble length in bytes (e.g. `LONG_PREAMBLE`, `SHORT_PREAMBLE`, or a
  ///        tuning-configured value such as `normal_start_preamble`).
  bool transmit_frame_(const IoFrame &frame, uint32_t freq, uint16_t preamble);
  /// Main request/response exchange with retry and automatic authentication.
  /// @param request Outbound request IoFrame.
  /// @param response Output: received response IoFrame.
  /// @param freq RF frequency in Hz.
  /// @param max_tries Transmit-attempt cap, forwarded to ExchangeEngine::send_and_receive().
  /// @return true if exchange succeeded; false otherwise.
  ExchangeOutcome send_and_receive_(const IoFrame &request, IoFrame &response, uint32_t freq,
                                    uint8_t max_tries = EXCHANGE_RETRY_COUNT);
  /// Handle an inbound authenticated command from a device (status updates, etc.).
  /// @param request Inbound authenticated request (e.g., CMD_STATUS_UPDATE).
  /// @param freq RF frequency the packet arrived on.
  /// @return true if authentication succeeded; false otherwise.
  bool authenticate_request_(const IoFrame &request, uint32_t freq);
  /// Parse a received frame, merge supported device state or metadata, and notify callbacks.
  /// @param packet Raw radio packet containing a parsed IoFrame.
  void process_received_packet_(const RadioRxPacket &packet);
 
  /// True while the key-extraction responder is mid-attempt and still within its bounded CH2-hold
  /// window. Thin forwarder to KeyExtractionResponder::awaiting_reply() (key_extraction_responder.h)
  /// — kept on the hub because defer_background_poll_() and tests/hub/hub_core_test.cpp reach it here,
  /// mirroring the two set_key_extraction_armed* bindings.
  [[nodiscard]] bool key_extraction_awaiting_reply_() const { return this->key_extraction_.awaiting_reply(); }
 
  /// Extract supported position or metadata info from a response frame and merge it into the device record.
  /// @param frame IoFrame containing a supported inbound command such as CMD_PRIVATE_RESP,
  /// CMD_STATUS_UPDATE, CMD_GET_NAME_RESP, or CMD_GET_INFO2_RESP.
  /// @param trust_position False 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/exchange/somfy_awning_exchange_ack_reports_stale_target_*.yaml), so
  /// execute_request_and_update_() passes false there; every other caller trusts as before.
  void update_device_status_(const IoFrame &frame, bool trust_position = true);
  /// Record that a 1W frame just went out on the radio — ours or someone else's — updating
  /// last_1w_activity_ms_ and — when this frame starts a new burst (see
  /// decisions::oneway_burst_started_fresh()) — first_1w_activity_ms_.
  ///
  /// Called both from process_received_packet_() for an overheard remote's frame and from
  /// execute_oneway_command_()/execute_oneway_position_() (hub_operations.cpp) for a frame this
  /// hub just transmitted itself. That second case is deliberate, not a misuse of a receive-path
  /// hook: our own burst should defer background polls exactly like a remote's does, because it
  /// puts the same 1W traffic on the same shared channel the polls would otherwise use, and the
  /// devices it targets need the same settling time either way.
  /// @param now millis() at which this frame was seen or sent.
  void record_1w_activity_(uint32_t now);
  /// If `frame` matches a 1W remote's pairing gesture (decisions::is_one_way_pairing_gesture()),
  /// remember it (src/dst/cmd plus the radio's last-capture RSSI) in
  /// recent_oneway_pairing_sighting_ so a fresh discover_and_pair() attempt can seed its telemetry
  /// with it — see RecentOneWayPairingSighting's doc comment (issue #27/#65). A no-op for any
  /// other frame. Called from process_received_packet_()'s 1W-frame path, unconditionally (before
  /// the burst-dedup check, like record_1w_activity_()) so a repeated gesture frame still
  /// refreshes the timestamp (and RSSI).
  /// @param frame Parsed 1W frame (CTRL0 1W bit already confirmed set by the caller).
  /// @param now millis() at which this frame was seen.
  void record_oneway_pairing_gesture_(const IoFrame &frame, uint32_t now);
  /// Schedule a delayed status poll for a registered device using the Component timeout API.
  /// @param device_id ID of the device to poll.
  /// @param delay_ms Delay 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.
  void schedule_status_poll_(const std::string &device_id, uint32_t delay_ms);
  /// Begin bounded follow-up polling for a device after a command or overheard remote activity.
  /// @param device_id ID of the device to poll.
  /// @param initial_delay_ms Delay before the first follow-up poll.
  void begin_status_poll_tracking_(const std::string &device_id, uint32_t initial_delay_ms);
  /// Arm the confirming poll that follows a command, because a CMD_EXECUTE reply is never trusted
  /// for position (see update_device_status_()'s trust_position parameter) and therefore leaves the
  /// hub with no idea where the device actually is. Re-arms the bounded tracking window rather than
  /// only setting a due time: the same untrusted reply clears that window whenever it claims the
  /// device is stopped, and pop_due_device() discards a due poll that has no active window. An
  /// already-scheduled earlier poll wins.
  /// @param device_id Device the command was sent to.
  /// @param for_stop True for STOP (and position POS_STOP), which settles under
  ///        STOP_SETTLE_POLL_CAP_MS instead of the normal settle cadence.
  void arm_execute_confirmation_poll_(const std::string &device_id, bool for_stop);
  /// 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_()).
  /// @param device_ids Devices to poll.
  /// @param delay_ms Poll delay in milliseconds.
  void schedule_device_polls_(const std::vector<std::string> &device_ids, uint32_t delay_ms);
  /// Whether loop() should skip dispatching the queue this iteration because the pending work is a
  /// background poll and either a 1W remote transmitted very recently, or a key-extraction attempt
  /// is mid-flight. Thin wrapper binding the component's state to
  /// decisions::defer_background_poll_for_1w_activity(), plus a second, independent yield condition:
  /// a background poll is a blocking exchange that owns the radio for 1-3 s, and dispatching one
  /// while the key-extraction responder is holding CH2 for an expected CMD_KEY_TRANSFER (0x32)
  /// would swallow it just as thoroughly as a mistimed hop — see loop()'s hop branch (hub_core.cpp)
  /// for the other half of that hold. Only background polls yield here, same as the 1W rule: a user
  /// command must never wait on either kind of background activity.
  [[nodiscard]] bool defer_background_poll_() const {
    const bool next_op_is_background =
        !this->op_queue_.empty() && OperationQueue::is_background_op(this->op_queue_.front().type);
    if (next_op_is_background && this->key_extraction_awaiting_reply_())
      return true;
    return decisions::defer_background_poll_for_1w_activity(next_op_is_background, this->first_1w_activity_ms_,
                                                            this->last_1w_activity_ms_, millis(),
                                                            ONEWAY_QUIET_PERIOD_MS, ONEWAY_POLL_DEFER_CAP_MS);
  }
  /// Schedule status polls for all devices associated with a linked remote.
  /// @param remote_id Source node ID of the remote.
  /// @param delay_ms Poll 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).
  void schedule_linked_remote_polls_(const std::string &remote_id,
                                     uint32_t delay_ms = REMOTE_ACTIVITY_STATUS_POLL_DELAY_MS);
  /// 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.
  /// @param info Already-decoded 1W frame info (see decode_1w_frame()).
  /// @param src_id Sender's node ID as a string (already computed by the caller).
  /// @return Deduplicated device IDs (may be empty).
  [[nodiscard]] std::vector<std::string> resolve_1w_target_devices_(const OneWayFrameInfo &info,
                                                                    const std::string &src_id) const;
  /// Apply optimistic target state to every device in @p 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()).
  /// @param info Already-decoded 1W frame info (see decode_1w_frame()).
  /// @param device_ids Devices to apply optimistic state to (see resolve_1w_target_devices_()).
  /// @return true if the intent resolved to a STOP (caller should poll immediately).
  bool apply_optimistic_linked_state_(const OneWayFrameInfo &info, const std::vector<std::string> &device_ids);
  /// 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".
  /// @param info Already-decoded 1W frame info (see decode_1w_frame()).
  /// @param linked True if the sender is linked to at least one registered device.
  /// @param src_id Sender's node ID as a string (already computed by the caller).
  void maybe_fire_sender_event_(const OneWayFrameInfo &info, bool linked, const std::string &src_id);
  /// Handle an explicit CMD_ERROR_RESP refusal from the device: record the result code, stamp link
  /// health, and schedule the poll backoff. Split out of execute_request_and_update_() to keep that
  /// function's outcome dispatch readable — a refusal is a distinct concern from "what did the
  /// exchange achieve".
  /// @param device_id Target device ID.
  /// @param request Outbound request frame that drew the refusal.
  /// @param response The CMD_ERROR_RESP frame.
  /// @param retry_after_fail_ms If non-zero, schedules next status poll after this delay.
  /// @return Always false; a refusal is never a success.
  bool handle_error_response_(const std::string &device_id, const IoFrame &request, const IoFrame &response,
                              uint32_t retry_after_fail_ms);
 
  /// Shared request/response helper for high-level operations.
  /// @param device_id Target device ID.
  /// @param request Outbound request frame.
  /// @param warn_on_no_response If true, logs a warning when no response is received.
  /// @param retry_after_fail_ms If non-zero, schedules next status poll after this delay on failure.
  /// @param max_tries Transmit-attempt cap, forwarded to send_and_receive_(). Defaults to the full
  ///        EXCHANGE_RETRY_COUNT; a scheduler-owned poll passes SCHEDULED_POLL_MAX_TRIES.
  /// @return true when the device replied, or when a CMD_EXECUTE was accepted without a reply —
  ///         every other command's unconfirmed acceptance is still a failure here (see
  ///         @ref ExchangeOutcome and decisions::retry_after_unconfirmed_accept_is_safe()).
  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, uint8_t max_tries = EXCHANGE_RETRY_COUNT);
 
  /// @brief Everything one execute-family operation needs beyond its own guard and frame builder.
  struct ExecuteRequestSpec {
    const char *action;   ///< Verb/phrase for the "Sending ..." and rejection logs.
    bool settle_as_stop;  ///< Passed through to arm_execute_confirmation_poll_().
  };
  /// Funnel for the four execute-family operations: runs try_execute_operation_() and, on any
  /// false return (the command will not reach the device), withdraws the optimistic prediction the
  /// entity applied at control() time via DeviceRegistry::rollback_optimistic(). Wrapping rather
  /// than inlining the rollback keeps every current and future failure exit covered by one call.
  /// @param device_id Target device ID.
  /// @param spec Pre-formatted action phrase and the settle-as-stop flag.
  /// @param accepts Capability guard; returns false to reject the operation for this device.
  /// @param rejection_profile Expected-profile label for the rejection log.
  /// @param build Fills the request frame from the resolved device; returns false on failure.
  /// @return true when the exchange succeeded and the settle poll was armed.
  bool run_execute_operation_(const std::string &device_id, const ExecuteRequestSpec &spec,
                              const std::function<bool(const IoDevice &)> &accepts, const char *rejection_profile,
                              const std::function<bool(IoFrame &, const IoDevice &)> &build);
 
  /// Shared skeleton for the four execute-family operations (position, named command, tilt,
  /// position+tilt): device lookup + initialized guard, capability guard, poll-tracking start,
  /// "Sending ..." log, frame build, exchange, failure backoff, and the settle poll. The four
  /// public methods supply only their guard predicate, rejection profile label, and frame
  /// builder. Called only through run_execute_operation_(), which owns the failure rollback.
  /// @param device_id Target device ID.
  /// @param spec Pre-formatted action phrase and the settle-as-stop flag.
  /// @param accepts Capability guard; returns false to reject the operation for this device.
  /// @param rejection_profile Expected-profile label for the rejection log.
  /// @param build Fills the request frame from the resolved device; returns false on failure.
  /// @return true when the exchange succeeded and the settle poll was armed.
  bool try_execute_operation_(const std::string &device_id, const ExecuteRequestSpec &spec,
                              const std::function<bool(const IoDevice &)> &accepts, const char *rejection_profile,
                              const std::function<bool(IoFrame &, const IoDevice &)> &build);
 
  /// Execute a named device command (STOP, FAVORITE, VENT, FORCE_OPEN) via the authenticated exchange.
  /// @param device_id Target device ID.
  /// @param cmd Named command to execute.
  /// @return true if device acknowledged; false otherwise.
  bool execute_device_command_(const std::string &device_id, CoverCommand cmd);
  /// Shared bookkeeping for every 1W transmit: mark the radio busy for the duration of `send`,
  /// then record it as 1W activity so background polls back off for it exactly as they do for a
  /// remote's burst — the radio is equally busy either way. Every 1W execute must go through this;
  /// a future one that skips it would compile, pass, and silently break poll-deferral.
  /// @param send Callable that performs the actual transmit; takes no arguments.
  template<typename F> void execute_oneway_(F &&send) {
    this->busy_ = true;
    send();
    this->busy_ = false;
    this->record_1w_activity_(millis());
  }
  /// Send a queued 1W named command. Unlike its 2W sibling this returns nothing: there is no
  /// acknowledgement to report, and success here would only mean "bytes left the radio".
  /// @param controller_id Controller-identity handle.
  /// @param cmd Named command to send.
  void execute_oneway_command_(const std::string &controller_id, CoverCommand cmd);
  /// Send a queued 1W numeric position. See execute_oneway_command_().
  /// @param controller_id Controller-identity handle.
  /// @param position Target position 0–100.
  void execute_oneway_position_(const std::string &controller_id, uint8_t position);
  /// Send a queued 1W enrollment (add-controller). See execute_oneway_command_().
  /// @param controller_id Controller-identity handle.
  void execute_oneway_enroll_(const std::string &controller_id);
  /// Send a queued 1W un-enrollment (remove-controller). See execute_oneway_command_().
  /// @param controller_id Controller-identity handle.
  void execute_oneway_unenroll_(const std::string &controller_id);
  /// Fire all registered device update callbacks for the given device ID.
  /// @param id Device ID that updated.
  void notify_device_update_(const std::string &id);
  /// Apply backoff after a failed background status poll and log the result.
  /// @param device_id Target device ID.
  /// @param auth_like True when the failed exchange saw a 0x3C challenge.
  void schedule_background_poll_backoff_(const std::string &device_id, bool auth_like);
  /// Pop next pending operation from the queue and execute it (set position, request status, discover).
  void process_pending_operation_();
 
  // --- Exchange helpers (thin wrappers delegating to ExchangeEngine) ---
 
  /// Log the last exchange debug snapshot (delegates to exchange_engine_).
  void log_exchange_debug_(const char *device_id) const { this->exchange_engine_.log_debug(device_id); }
 
  /// Log the last exchange debug snapshot for an accepted-but-unconfirmed exchange, at INFO.
  void log_exchange_unconfirmed_debug_(const char *device_id) const {
    this->exchange_engine_.log_debug_unconfirmed(device_id);
  }
 
  // --- Tuning ---
  /// Apply the current tuning configuration to the active radio driver.
  void apply_tuning_to_radio_();
  /// @brief Resolve `normal_start_preamble` from the driver when YAML did not set it (ADR 0042).
  void resolve_start_preamble_default_();
 
  // --- Management actions (thin wrappers delegating to management_actions_) ---
  /// Register hub-level Home Assistant actions; called from setup().
  void register_management_actions_() { this->management_actions_.register_actions(); }
  /// Native API callback: rename a registered device.
  void api_rename_device_(const std::string &device_id, const std::string &new_name) {
    this->management_actions_.api_rename_device(device_id, new_name);
  }
  /// Native API callback: trigger a registered device's physical identify.
  void api_identify_device_(const std::string &device_id) { this->management_actions_.api_identify_device(device_id); }
  /// Native API callback: force-open a registered cover device.
  void api_force_open_device_(const std::string &device_id) {
    this->management_actions_.api_force_open_device(device_id);
  }
  /// Native API callback: broadcast a roll-call scan of already-paired devices.
  void api_scan_paired_devices_() { this->management_actions_.api_scan_paired_devices(); }
  /// Native API callback: queue a 1W position for a controller identity.
  void api_oneway_set_position_(const std::string &controller_id, const std::string &position) {
    this->management_actions_.api_oneway_set_position(controller_id, position);
  }
  /// Native API callback: queue a 1W un-enrollment (remove-controller) for a controller identity.
  void api_oneway_remove_controller_(const std::string &controller_id) {
    this->management_actions_.api_oneway_remove_controller(controller_id);
  }
  /// Native API callback: run a single diagnostic probe against a registered device.
  void api_probe_device_(const std::string &device_id, const std::string &probe, const std::string &index) {
    this->management_actions_.api_probe_device(device_id, probe, index);
  }
  /// Native API callback: run a bounded diagnostic probe sweep against a registered device.
  void api_probe_sweep_(const std::string &device_id, const std::string &probe, const std::string &first_index,
                        const std::string &last_index) {
    this->management_actions_.api_probe_sweep(device_id, probe, first_index, last_index);
  }
  /// Native API callback: run a heating/climate function (CMD_WRITE_PRIVATE 0x20) against a
  /// registered climate device.
  void api_heating_control_(const std::string &device_id, const std::string &function, const std::string &value) {
    this->management_actions_.api_heating_control(device_id, function, value);
  }
 
  // --- Frequency hopping ---
  void hop_frequency_();
 
  // --- Radio driver selection (called once from setup()) ---
  /// 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.
  /// @param chip_name_out Output: human-readable chip name for logging (always set,
  ///                      even on failure, to the best-known name for error messages).
  /// @return Newly allocated RadioDriver, or nullptr if pin validation or allocation failed.
  RadioDriver *select_and_construct_radio_(const char **chip_name_out);
 
  /// @brief Emit the 1W controller identities to the config dump — node, class, and the resolved
  /// ACEI / broadcast (ADR 0031). Factored out of dump_config() to keep its cognitive complexity
  /// under the clang-tidy threshold.
  void dump_oneway_controllers_config_() const;
 
#ifdef IOHOME_LR1121_FIRMWARE_UPDATE
  // --- LR1121 firmware update: thin forwarders to the Lr1121FirmwareUpdateController collaborator
  //     (lr1121_firmware_update_controller.h). setup()/dump_config() keep calling these names; the
  //     orchestration and every safety invariant live in the collaborator's .cpp. ---
  /// Boot-time bootloader-version excursion — forwards. Called from setup() after
  /// select_and_construct_radio_() and before radio_->init().
  void run_lr1121_boot_time_bootloader_read_() { this->lr1121_firmware_update_.run_boot_time_bootloader_read(); }
  /// Compute and cache the flash verdict once radio_->init() has produced (or failed to produce)
  /// an installed-firmware-version read — forwards. Called from setup() regardless of whether
  /// init() succeeded.
  void cache_lr1121_flash_verdict_() { this->lr1121_firmware_update_.cache_flash_verdict(); }
  /// Emit the bootloader version and cached flash verdict to the config dump — forwards. Called
  /// from dump_config(), next to the existing radio_->dump_debug() call.
  void dump_lr1121_firmware_update_debug_() const { this->lr1121_firmware_update_.dump_debug(); }
#endif
 
  // --- Radio driver ---
  RadioDriver *radio_{nullptr};
 
  // --- Hardware pins (set by YAML codegen, passed to radio driver in setup) ---
  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
  FemProfile fem_profile_{FemProfile::NONE};  ///< Which FEM part fem_pa_pin_ belongs to, if any.
 
  // --- Configuration (from YAML) ---
  std::string node_id_str_;
  std::string system_key_str_;
  std::string radio_type_;  ///< "sx1276", "sx1262", or "lr1121"; required by the YAML schema.
  /// Why setup() gave up on the radio, or empty. Printed by dump_config so log clients that connect
  /// after boot see the cause, not only ESPHome's generic "marked FAILED" line.
  std::string radio_failure_reason_;
  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)
 
  // --- Runtime state ---
  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_;
  /// 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.
  std::vector<std::string> exposed_senders_;
  /// Invoked once after every pairing attempt completes; see set_pairing_result_callback().
  std::function<void()> pairing_result_callback_;
  /// Whether diagnostic probes (ManagementActions::probe_device()/probe_sweep()) are enabled.
  /// False by default so a build that didn't opt in via `diagnostic_probes: true` never sends an
  /// undecoded probe opcode. See set_diagnostic_probes_enabled().
  bool diagnostic_probes_enabled_{false};
  StatusPollPolicy poll_policy_;
  OperationQueue op_queue_;
  /// Per-attempt pairing telemetry. PairingEngine records into it and, during an attempt, attaches it
  /// to ExchangeEngine as its TransmitObserver.
  PairingTelemetry pairing_telemetry_;
  /// Most recent 1W pairing-gesture frame seen on the hub's normal passive RX path (e.g. a PROG
  /// press's WRITE_PRIVATE/1W-remove/discover-alt broadcast), remembered so PairingEngine can seed
  /// a fresh discover_and_pair() attempt's telemetry with it — see record_oneway_pairing_gesture_()
  /// and RecentOneWayPairingSighting's doc comment (issue #27/#65). Declared before pairing_engine_,
  /// which holds a reference to it, so member-init order matches the initializer list.
  RecentOneWayPairingSighting recent_oneway_pairing_sighting_{};
  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.
  /// Owns the 1W controller identities, their rolling-sequence counters and the transmit burst.
  /// The third collaborator that drives the radio (ADR 0004), and the only one that awaits
  /// nothing — 1W has no reply to wait for.
  OneWayTransmitter oneway_transmitter_;
  /// Opt-in, receive-only 1W controller-key adoption listener (oneway_key_adoption.cpp). Armed via
  /// the "Recover 1W Controller Key" switch; observes an overheard CMD_ONEWAY_ADD_CONTROLLER and
  /// reports the key once, then disarms. Declared after oneway_transmitter_ so member-init order
  /// matches the initializer list.
  OnewayKeyAdoption oneway_key_adoption_;
  /// Device-role responder for the "Recover System Key" feature (key_extraction_responder.cpp).
  /// Owns the pairing_responder::ResponderContext, the throwaway-ID/auto-off/grace-window
  /// machinery, and the device-role reply TX. Declared after registry_/radio_/tuning_/node_id_
  /// (which it references) and after oneway_key_adoption_ so member-init order matches the
  /// initializer list.
  KeyExtractionResponder key_extraction_;
#ifdef IOHOME_LR1121_FIRMWARE_UPDATE
  /// Orchestrates the compile-gated LR1121 transceiver-firmware-update feature
  /// (lr1121_firmware_update_controller.cpp): boot-time bootloader read, cached flash verdict,
  /// two-press confirmation window, and the button-triggered flash/bootloader-rewrite sequences.
  /// Guarded member AND guarded initializer — an unguarded initializer for a guarded member is the
  /// classic way this breaks only under make firmware-test.
  Lr1121FirmwareUpdateController lr1121_firmware_update_;
#endif
  /// Subscribers to the per-command 1W report; one per "Last 1W Command" sensor.
  std::vector<OneWayCommandReportFn> oneway_report_callbacks_;
 
  /// 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.
  decisions::OneWayDedupState last_1w_logged_{};
  /// 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().
  uint32_t last_1w_activity_ms_{0};
  /// 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.
  uint32_t first_1w_activity_ms_{0};
};
 
// ----------------------------------------------------------------------------
// Test-visible helpers (inline for host unit tests)
// ----------------------------------------------------------------------------
 
/// Format a position float as a human‑readable string (e.g. "50%", "unknown").
/// @param pos Position value (0–100 or UNKNOWN_POSITION).
/// @return String like "50%" or "unknown".
inline std::string format_position(float pos) {
  if (pos == UNKNOWN_POSITION) {
    return "unknown";
  }
  char buf[POSITION_TEXT_BUFFER_SIZE];
  snprintf(buf, sizeof(buf), "%.0f%%", pos);
  return buf;
}
 
}  // namespace home_io_control
}  // namespace esphome