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 "proto_heating_profiles.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 "periodic_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
 
/// @brief How long after a pairing attempt ends a Discover & Pair press counts as made during it.
///
/// Pairing blocks loop() for up to about 20 s, so a press made meanwhile is handled a few milliseconds
/// after the attempt ends (issue #165: the queued second attempt found nothing, the radiator had left
/// its pairing mode). A press a person makes after reading the result comes seconds later.
static constexpr uint32_t PAIRING_STALE_PRESS_MS = 1000;
 
// ============================================================================
// 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;
    });
    this->exchange_engine_.set_device_key_provider([this](const uint8_t *node) -> const uint8_t * {
      const IoDevice *dev = this->registry_.get(node_id_to_string(node));
      return dev != nullptr && dev->has_system_key ? dev->system_key : nullptr;
    });
    this->exchange_engine_.set_wake_evidence_spent_handler([this](const uint8_t *dst) {
      if (IoDevice *dev = this->registry_.get(node_id_to_string(dst)); dev != nullptr)
        clear_moving_evidence(*dev);
    });
  }
 
  /// @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); PARTIAL and PEDESTRIAN have no 1W
  ///        encoding and are not transmitted.
  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), as the user means it;
  ///        the transmitter mirrors it on the wire for an inverted identity (effective_inverted()).
  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 **Works only inside the receiver's programming window.** Confirmed on a Somfy Izymo
  /// dimmer only: put the receiver in its programming mode first, then fire this; with no window
  /// open it changes nothing. Other receivers are untested. 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); }
 
  /// @return How many device events record_device_event_() has recorded since boot.
  [[nodiscard]] uint32_t device_event_count() const { return this->device_event_count_; }
 
  /// @return The most recent device event rendered as `#<n> t=<uptime s> <SRC> <cmd> <payload hex>`,
  /// or an empty string before the first one. The counter makes a repeated identical report a new
  /// value, which Home Assistant's history needs (it records state changes only).
  [[nodiscard]] const std::string &last_device_event() const { return this->last_device_event_; }
 
  /// Record a diagnostic probe's reply on the "Last Device Event" sensor when it is a device event
  /// report (decisions::is_device_event_report()), such as the event a `subscribe_event` probe draws
  /// at once. The reply is only recorded, never applied.
  /// @param reply The probe's reply frame.
  /// @return true when it was recorded.
  bool record_probe_reply_event(const IoFrame &reply);
 
  /// Register a callback invoked after every recorded device event, used by the "Last Device Event"
  /// text sensor. Single-slot, mirrors set_pairing_result_callback().
  /// @param cb Callable with no arguments.
  void set_device_event_callback(std::function<void()> cb) { this->device_event_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 DiagnosticProbes::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 and optimistic_state default to UNKNOWN / 0 / true, with no overrides; 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/overrides/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);
  /// True once loop() has seen the radio latch a failure after setup (a runtime BUSY timeout, for
  /// example). Sticky: a failed driver never recovers without a reboot. Every device's Active Issue
  /// sensor reports it.
  [[nodiscard]] bool radio_stopped_responding() const { return this->radio_failure_reported_; }
  /// Select a device's travel speed at runtime (see IOHomeCoverTravelSpeedSelect and
  /// IOHomeCoverSilentSwitch). Virtual so platform tests can substitute a mock registry.
  /// @param device_id Hexadecimal node ID string.
  /// @param speed     Speed profile of the device's position moves.
  virtual void set_device_travel_speed(const std::string &device_id, TravelSpeed speed);
  /// 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);
  /// Opt a registered device into the periodic rain sensor poll (a read of its minimum limitation).
  /// @param device_id Target device ID.
  /// @param interval_ms Poll interval in milliseconds; zero removes the device from the schedule.
  virtual void set_device_rain_poll_interval(const std::string &device_id, uint32_t interval_ms);
  /// Opt a registered device into the periodic sun level poll (a subscription to EVENT_LOCAL_SENSOR,
  /// whose answer carries the value; ADR 0064).
  /// @param device_id Target device ID.
  /// @param interval_ms Poll interval in milliseconds; zero removes the device from the schedule.
  virtual void set_device_sun_poll_interval(const std::string &device_id, uint32_t interval_ms);
  /// Opt a registered device into the periodic battery level poll (a subscription to
  /// EVENT_BATTERY_LEVEL_CHANGE, whose answer carries the level; ADR 0064).
  /// @param device_id Target device ID.
  /// @param interval_ms Poll interval in milliseconds; zero removes the device from the schedule.
  virtual void set_device_battery_level_poll_interval(const std::string &device_id, uint32_t interval_ms);
  /// Opt a registered device into the status refresh at rest: a status read whenever the device has
  /// not reported its status for a whole interval.
  /// @param device_id Target device ID.
  /// @param interval_ms Refresh interval in milliseconds; zero removes the device from the schedule.
  virtual void set_device_status_refresh_interval(const std::string &device_id, uint32_t 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, or when the device's
  ///         features do not accept the value (an intermediate position on a device without
  ///         device_feature::LEVELS): nothing is sent and the optimistic target is withdrawn.
  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);
  /// Read the device's minimum limitation and derive its rain sensor state from the reply.
  ///
  /// Unauthenticated read (CMD_LIMITATION_STATUS_REQ); the reply is accepted only inside this
  /// exchange (ADR 0022) and never reaches update_device_status_(), so a poll cannot move the
  /// device's position or target. A moving device is not asked: the poll is deferred instead.
  /// @param device_id Target device ID.
  /// @return true if a usable limitation reply arrived and was applied.
  virtual bool request_device_limitation(const std::string &device_id);
  /// Subscribe the device to EVENT_LOCAL_SENSOR and publish the sun value its answer carries.
  ///
  /// The answer is accepted only inside this exchange (decisions::is_subscription_answer(),
  /// ADR 0064) and never reaches the position decode. A moving device is not asked: the poll is
  /// deferred instead.
  /// @param device_id Target device ID.
  /// @return true if an answer of the captured shape arrived and was applied.
  virtual bool request_device_sun_level(const std::string &device_id);
  /// Subscribe the device to EVENT_BATTERY_LEVEL_CHANGE and publish the level its answer carries.
  /// Same rules as request_device_sun_level().
  /// @param device_id Target device ID.
  /// @return true if an answer of the captured shape arrived and was applied.
  virtual bool request_device_battery_level(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
  /// DiagnosticProbes::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",
  ///        "private2_short", "status_mp_fp", "status_fp_high", "limitation", "register_00", or "register_01"; the full
  ///        list is in DiagnosticProbes::probe_device()).
  /// @param index Function ID / selector block / modifier, as a decimal or `0x`-prefixed hex
  ///        string; ignored for "general_info3" and "status_mp_fp"; the FPI2 bitmap for
  ///        "status_fp_high"; 0 (minimum) or 1 (maximum) for "limitation".
  /// @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
  /// DiagnosticProbes::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 register protocol is unvalidated on real Atlantic/Thermor/Sauter hardware.
  /// A write is reported as acknowledged by the device, never as confirmed; the register reads
  /// (`window_open`) put the decoded value into the result message, and `power_on` / `midnight_sync`
  /// log their ACK payload at DEBUG. 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);
  /// Send a heat level to an exterior heater (a fan entity) as an IO position. Mapped to the shared
  /// execute path, like set_light_position().
  /// @param device_id Target device ID.
  /// @param position Desired IO position (0-100): 0 = full heat, 100 = off (the KLF 200 exterior
  ///        heating mapping, MP = position x 0x200).
  /// @return true if device acknowledged.
  virtual bool set_fan_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 Run one heating function on the heater's private register protocol (CMD_WRITE_PRIVATE
  /// 0x20): a write for a settable register, a read for a read-only one (`power_on`, `midnight_sync`).
  /// Both the `heating_control` hub action and the climate entity's writes call this; together with
  /// read_heating_register() it is the only place heating frames are built and sent, through one
  /// shared exchange helper.
  ///
  /// 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). 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. The ack carries no state: a caller that wants the
  /// value the heater now holds reads it back with read_heating_register(). An acknowledged write
  /// also moves the heater's next poll to HEATING_POST_WRITE_POLL_DELAY_MS from now, so the regulator
  /// state (heating / idle) follows the change.
  /// @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 Set the heating level of a heater that is commanded with levels (the plain electrical heater).
  ///
  /// A main-parameter-only EXECUTE through the execute-family funnel; the settle poll that follows
  /// reads the level back with the ordinary status read, and the climate entity shows that reading.
  /// Experimental: unconfirmed on hardware.
  /// @param device_id Target device ID (hex string).
  /// @param level Heating level low byte (heating_level::*).
  /// @return true when the device accepted the command.
  virtual bool set_heating_level(const std::string &device_id, uint8_t level);
  /// @brief Command a heater that carries a temperature or an alias in its main parameter (the heating
  /// temperature interface and the heat pump).
  ///
  /// A main-parameter-only EXECUTE, or one that also carries functional parameter 9 when the profile
  /// sends mode flags, through the execute-family funnel; the settle poll that follows reads the
  /// state back with the ordinary status read. Experimental: unconfirmed on hardware.
  /// @param device_id Target device ID (hex string).
  /// @param main_parameter The 16-bit main parameter (encode_temperature_main_parameter() or an alias).
  /// @param fp The functional parameter that accompanies it, if any (kind NONE sends a main-parameter-only
  ///        EXECUTE).
  /// @return true when the device accepted the command.
  virtual bool set_heating_temperature(const std::string &device_id, uint16_t main_parameter, const HeatingFp &fp);
  /// @brief Set a water heater's target temperature.
  ///
  /// A main-parameter-only EXECUTE with the target on the relative scale over DHW_TARGET_MIN_C..
  /// DHW_TARGET_MAX_C (encode_dhw_target()), through the execute-family exchange without the cover's
  /// movement bookkeeping. The settle poll that follows (poll_dhw_device_()) reads the target back from
  /// the status reply. Gated on device_feature::WATER_HEATER. The heater's display follows the target
  /// (issue #198).
  /// @param device_id Target device ID (hex string).
  /// @param celsius Target in degrees Celsius; a value outside the heater's range is refused, not clamped.
  /// @return true when the device accepted the command.
  virtual bool set_water_heater_target(const std::string &device_id, float celsius);
  /// @brief Set a water heater's operating mode: a write of register 0x0006 (encode_dhw_mode_write()).
  ///
  /// The register is read back at once, so the entity shows what the heater then holds, and so is the
  /// target (the status read of the poll), which the mode decides. The next poll moves to
  /// HEATING_POST_WRITE_POLL_DELAY_MS from now so the heating state follows the change. Gated on
  /// device_feature::WATER_HEATER. The heater's display follows the mode (issue #198).
  /// @param device_id Target device ID (hex string).
  /// @param mode Mode to write.
  /// @return true only if the device acknowledged the write; a missed read-back does not change that.
  virtual bool set_water_heater_mode(const std::string &device_id, DhwMode mode);
  /// @brief Start or end a water heater's boost: a duration write of register 0x0000, then an EXECUTE with
  /// the operating-mode word FP16 (DHW_OPERATING_MODE_BOOST_ON, or DHW_OPERATING_MODE_OFF to end).
  ///
  /// See set_dhw_operating_mode_() for the sequence. Ending a boost also ends away, because the off word
  /// switches both (ADR 0081). Gated on device_feature::WATER_HEATER.
  /// \todo Experimental: confirm on a real water heater that this starts and ends a boost.
  /// @param device_id Target device ID (hex string).
  /// @param on true to start a boost, false to end it.
  /// @return true when the device accepted the EXECUTE; false for a refused or unacknowledged command.
  virtual bool set_water_heater_boost(const std::string &device_id, bool on);
  /// @brief Start or end a water heater's away (holiday) mode: a duration write of register 0x0005 (255, until
  /// turned off), then an EXECUTE with FP16 DHW_OPERATING_MODE_AWAY_ON, or DHW_OPERATING_MODE_OFF to end.
  ///
  /// See set_dhw_operating_mode_() for the sequence. Ending away also ends a boost (ADR 0081). Gated on
  /// device_feature::WATER_HEATER.
  /// \todo Experimental: confirm on a real water heater that this starts and ends the holiday mode.
  /// @param device_id Target device ID (hex string).
  /// @param on true to start away, false to end it.
  /// @return true when the device accepted the EXECUTE; false for a refused or unacknowledged command.
  virtual bool set_water_heater_away(const std::string &device_id, bool on);
  /// @brief Set the temperature encoding range of a heater that carries a temperature in its main
  /// parameter (YAML `min_temperature:` / `max_temperature:`).
  /// @param device_id Target device ID.
  /// @param min_c Lower end of the range in degrees Celsius.
  /// @param max_c Upper end; must exceed `min_c`.
  virtual void set_device_temperature_range(const std::string &device_id, float min_c, float max_c);
  /// @brief Read one register of a heater and fold the decoded value into IoDevice::heating.
  ///
  /// Same gate as send_heating_command(); the read itself is read_private_register_(). A reply that
  /// decodes (decode_heating_reply()) updates the device record and notifies the entity callbacks,
  /// so what an entity shows is what the heater reported.
  /// @param device_id Target device ID (hex string).
  /// @param fn Register to read; must be readable (see heating_function_is_readable()).
  /// @param[out] value_out Decoded value (NaN for a room-temperature sensor fault); pass nullptr when
  ///        only the stored reading is wanted.
  /// @param max_tries Transmit-attempt cap: EXCHANGE_RETRY_COUNT for a read the user waits on (the
  ///        action, the read-back of a write), the scheduled-poll band for the background poll.
  /// @return true only if the device answered and the reply decoded to a value for `fn`.
  virtual bool read_heating_register(const std::string &device_id, HeatingFunction fn, float *value_out,
                                     uint8_t max_tries);
  /// @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, PARTIAL, PEDESTRIAN, FORCE_OPEN);
  /// returns immediately, executed in loop(). PEDESTRIAN is experimental.
  ///
  /// Existing entity/button callers (cover, favorite, vent, partial and pedestrian buttons) 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 minimum-limitation read for the rain sensor poll; executed in loop() as a
  /// background operation (yields to commands and 1W activity).
  /// @param device_id Target device ID.
  virtual void queue_request_device_limitation(const std::string &device_id);
  /// Queue an async sun level poll; executed in loop() as a background operation.
  /// @param device_id Target device ID.
  virtual void queue_request_device_sun_level(const std::string &device_id);
  /// Queue an async battery level poll; executed in loop() as a background operation.
  /// @param device_id Target device ID.
  virtual void queue_request_device_battery_level(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.
  ///
  /// A press handled within PAIRING_STALE_PRESS_MS of the end of an attempt is dropped with a log
  /// line: pairing blocks loop(), so a press made while it ran is only handled once it ends, when the
  /// device has usually left its pairing mode.
  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_fan_position() that keeps radio work serialized on the main loop.
  /// @param device_id Target device ID.
  /// @param position Desired IO position (0-100).
  virtual void queue_set_fan_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 attempts A transmit-attempt cap (forwarded to ExchangeEngine::send_and_receive()), or a
  ///        read kind whose plan the engine builds for @p request (ExchangeEngine::plan_read()).
  /// @return true if exchange succeeded; false otherwise.
  ExchangeOutcome send_and_receive_(const IoFrame &request, IoFrame &response, uint32_t freq,
                                    const decisions::AttemptRequest &attempts = 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);
 
  /// Handle an authenticated CMD_STATUS_UPDATE from a registered device: a device event report
  /// (decisions::is_device_event_report()) is recorded, any other 0x71 is applied as a position update.
  /// @param id The device's node ID string.
  /// @param dev The device record.
  /// @param frame The status update.
  void apply_status_update_(const std::string &id, IoDevice &dev, const IoFrame &frame);
 
  /// Record @p frame as a device event when it qualifies: its source is a registered device and it is
  /// either a device event report (decisions::is_device_event_report()), or any frame that reached
  /// the unhandled-command fallback while `diagnostic_probes` is on.
  /// @param frame The received frame.
  /// @param reached_unhandled_fallback True from the fallback after every other handler declined.
  /// @return true when the frame was recorded.
  bool record_if_device_event_(const IoFrame &frame, bool reached_unhandled_fallback);
 
  /// Record a device event report, or a frame from a registered device that nothing else here
  /// handles: log it raw, count it, and publish it on the "Last Device Event" sensor. The recording
  /// never answers the frame and never applies it to the device record, whatever it claims to carry
  /// (ADR 0022, ADR 0060). The one acknowledgement is the ordinary one: a CMD_STATUS_UPDATE addressed
  /// to this hub is authenticated and acknowledged with CMD_STATUS_UPDATE_RESP before it gets here,
  /// whatever event it carries. Logs at INFO with `diagnostic_probes: true` and at DEBUG otherwise, since a
  /// subscription outlives the build that made it and must not fill a normal build's log.
  /// @param frame The received frame; its source is a registered device.
  void record_device_event_(const IoFrame &frame);
 
  /// True while the key-extraction responder is mid-attempt and still within its bounded listen
  /// 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(); }
 
  /// One idle pass of listening for the key-extraction responder's peer, in place of the generic idle
  /// hop while key_extraction_awaiting_reply_(). Inside the session window
  /// (KeyExtractionResponder::in_session_hold()) it keeps the radio on the session's channel, where
  /// the peer's in-session frame comes; after it, a rotating listen over all three channels for one
  /// KEY_EXTRACTION_SCAN_SLICE_MS slice, handing a received frame to process_received_packet_().
  /// While a discovery answer waits for its slot, the slice ends at that slot (and is skipped once
  /// it has come), so the scheduler sends the answer on time.
  void listen_for_key_extraction_peer_();
 
  /// 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);
  /// The device just reported its status: move its status refresh (if it has one) a whole interval out.
  /// @param device_id Device that reported.
  void note_status_reported_(const std::string &device_id);
  /// 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);
  /// Arm the heater's regular-cadence poll timer. Own timer id (decisions::heating_poll_timer_id()),
  /// so remote-activity polls scheduled by schedule_status_poll_() never replace it.
  /// @param device_id ID of the heater.
  /// @param delay_ms Delay in milliseconds before the poll is queued.
  void schedule_heating_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);
  /// Settle every device whose polling window ran out (StatusPollPolicy::pop_ended_device()).
  /// A device still settling — its last report said "stopped" off its target and the confirming
  /// poll never came back — is taken as at rest there: with no poll left, the device's own flag
  /// stands. Any other device is left as it is.
  void settle_ended_status_tracking_();
  /// 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).
  /// @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 listening for its peer's next frame (an expected
  /// CMD_KEY_TRANSFER (0x32), say) would swallow it — see listen_for_key_extraction_peer_() for the
  /// other half of that listen. 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);
  }
  /// Decide, and act on, what a frame of another controller means for one registered device: a
  /// heard write, or a device challenge that follows no heard read, arms a tracked poll; any other
  /// frame arms one only if the device was not read recently (StatusPollPolicy::on_foreign_frame());
  /// while such a poll is pending the frame only pushes its timer out. A frame that arms nothing
  /// changes neither the tracking window nor the failure streaks.
  /// @param device_id Registered device the frame concerns.
  /// @param kind Request to the device, or the device's challenge to another controller.
  /// @param controller The other controller's node ID (request source, or challenge destination).
  /// @param cmd Command of the heard frame.
  void act_on_foreign_frame_(const std::string &device_id, ForeignFrameKind kind, const std::string &controller,
                             uint8_t cmd);
  /// Hand a registered device's challenge (0x3C) to another controller to act_on_foreign_frame_().
  /// A challenge addressed to this hub, from an unregistered node, or a 0x3D is left alone.
  /// @param frame An exchange-internal frame (is_exchange_internal_command()).
  void note_foreign_challenge_(const IoFrame &frame);
  /// Hand another controller's frame to act_on_foreign_frame_(): per the registered device it is
  /// addressed to, or per device linked to its source when that is a linked 2W controller.
  /// @param frame A parsed 2W frame that is not a status reply.
  /// @return true when the frame was another controller's request and has been handled.
  bool act_on_overheard_request_(const IoFrame &frame);
  /// 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);
  /// React to a deduplicated 1W press from a remote: apply the optimistic state to the devices it
  /// controls (resolve_1w_target_devices_()), schedule their status polls (at once after a STOP,
  /// otherwise after `remote_activity_poll_delay_ms`) and, when switched on, open the catch-up burst
  /// (StatusPollPolicy::on_linked_remote_activity(), ADR 0080). No-op for a remote that controls none.
  /// @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).
  void follow_linked_remote_press_(const OneWayFrameInfo &info, const std::string &src_id);
  /// 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 exchange_and_record_() 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);
 
  /// Fold one rain poll outcome into the device's rain sensor state and tell subscribers.
  /// @param device_id Target device ID.
  /// @param reading DRY or RAIN for an answered poll, UNKNOWN for a miss.
  /// @param limit_text Rendering of the reported limit for the state-change log, empty for a miss.
  /// @param unanswered True when the device sent nothing usable back at all (no reply, no error),
  ///        so the miss is retried once after PERIODIC_POLL_MISS_RETRY_MS before it counts.
  void apply_rain_poll_result_(const std::string &device_id, RainSensorState reading, const std::string &limit_text,
                               bool unanswered);
 
  /// @brief The two subscription-answer sensor polls (ADR 0064).
  enum class EventReading : uint8_t {
    SUN_LEVEL,      ///< EVENT_LOCAL_SENSOR, IoDevice::sun_level.
    BATTERY_LEVEL,  ///< EVENT_BATTERY_LEVEL_CHANGE, IoDevice::battery_level.
  };
 
  /// Shared body of request_device_sun_level() and request_device_battery_level(): defer while the
  /// device moves, subscribe, decode the answer, fold the result into the device record.
  /// @param device_id Target device ID.
  /// @param kind Which reading to poll.
  /// @return true if an answer of the captured shape arrived and was applied.
  bool request_event_reading_(const std::string &device_id, EventReading kind);
 
  /// The schedule of @p kind's poll.
  /// @param kind Which reading.
  /// @return The PeriodicPollPolicy instance that schedules it.
  PeriodicPollPolicy &event_reading_policy_(EventReading kind);
 
  /// Fold one poll outcome into the device record: a reading replaces the value and clears the miss
  /// count; a miss keeps the last value until PERIODIC_POLL_FAILURES_BEFORE_UNKNOWN. Logs a change
  /// at INFO and tells subscribers in every case.
  /// @param device_id Target device ID.
  /// @param kind Which reading.
  /// @param reading The decoded value of an answered poll, empty for a miss.
  /// @param unanswered True when the device sent nothing back at all, so the miss is retried once
  ///        after PERIODIC_POLL_MISS_RETRY_MS before it counts.
  void apply_event_reading_(const std::string &device_id, EventReading kind, const std::optional<uint16_t> &reading,
                            bool unanswered);
 
  /// Queue every periodic poll that is due: the sensor polls (rain, sun level, battery level) and the
  /// status refresh at rest.
  void queue_due_periodic_polls_();
  /// Read every device with `linked_remotes` once, when a burst of linked-remote activity has been
  /// followed by `remote_activity_catchup_poll_ms` without an exchange (ADR 0080). Each read is a
  /// one-off status read marked state-unknown (StatusPollPolicy::mark_state_unknown()); it opens no
  /// follow-up window of its own, an answer that says moving does.
  void queue_due_catchup_reads_();
 
  /// @brief What exchange_and_record_() found.
  enum class RequestResult : uint8_t {
    FAILED,       ///< No usable reply (silence, or an unconfirmed acceptance of a request that needs a payload).
    UNCONFIRMED,  ///< A CMD_EXECUTE the device accepted but never closed; counted as success, no reply frame.
    ERROR_REPLY,  ///< The device refused with CMD_ERROR_RESP; handle_error_response_() has recorded it.
    REPLY,        ///< The device answered; the caller interprets the reply frame.
  };
 
  /// @brief Per-request knobs of exchange_and_record_().
  struct RequestOptions {
    bool warn_on_no_response;            ///< Log a warning when no response arrives.
    uint32_t retry_after_fail_ms;        ///< If non-zero, drives the status-poll backoff and failure streaks.
    decisions::AttemptRequest attempts;  ///< Attempt cap or read kind forwarded to send_and_receive_().
  };
 
  /// send_and_receive_() on the command channel, except that a device event report
  /// (decisions::is_device_event_report()) taken as the reply is recorded (record_device_event_())
  /// and the request asked once more; a second report in a row, or one answering an EXECUTE that is
  /// not safe to repeat, ends it as FAILED.
  /// @param request Outbound request frame.
  /// @param response Filled with the reply on SUCCESS_WITH_RESPONSE; never a device event report then.
  /// @param attempts Attempt budget per send, as for send_and_receive_().
  /// @return The exchange outcome.
  ExchangeOutcome exchange_past_device_event_(const IoFrame &request, IoFrame &response,
                                              const decisions::AttemptRequest &attempts);
 
  /// Run one authenticated request/response exchange on the standard command channel and record
  /// its outcome: exchange-outcome and timeout counters, link health, challenge-seen handling,
  /// CMD_ERROR_RESP handling, debug logs and (when requested) the status-poll backoff. It does not
  /// interpret a reply — callers decide what a REPLY means.
  /// @param device_id Target device ID.
  /// @param request Outbound request frame.
  /// @param[out] response The device's reply, valid for RequestResult::REPLY and ERROR_REPLY.
  /// @param options See RequestOptions.
  /// @return What happened, see RequestResult.
  RequestResult exchange_and_record_(const std::string &device_id, const IoFrame &request, IoFrame &response,
                                     const RequestOptions &options);
 
  /// Shared request/response helper for high-level operations: exchange_and_record_() plus
  /// update_device_status_() on a reply.
  /// @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 attempts Attempt cap or read kind, forwarded to send_and_receive_(). Defaults to the full
  ///        EXCHANGE_RETRY_COUNT; a cover's status poll passes its read kind
  ///        (decisions::scheduled_poll_read_kind()).
  /// @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,
                                   const decisions::AttemptRequest &attempts = 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);
 
  /// Attempts for a cover's status read: its read kind (a settling read or a look at a busy device,
  /// decisions::scheduled_poll_read_kind()), consuming the poll's STOP and confirming-read marks.
  /// @param device_id Device being polled.
  /// @param scheduler_managed True when StatusPollPolicy is tracking the device (a ladder stands behind the poll).
  /// @param state_unknown True for a catch-up read (StatusPollPolicy::take_state_unknown()).
  [[nodiscard]] decisions::AttemptRequest cover_poll_attempts_(const std::string &device_id, bool scheduler_managed,
                                                               bool state_unknown = false);
  /// Attempts for a heater's status read: the count-based budget heaters keep
  /// (decisions::scheduled_poll_max_tries()).
  /// @param device_id Device being polled.
  /// @param scheduler_managed True when StatusPollPolicy is tracking the device.
  [[nodiscard]] decisions::AttemptRequest heater_poll_attempts_(const std::string &device_id, bool scheduler_managed);
 
  /// Execute a named device command (STOP, FAVORITE, VENT, PARTIAL, PEDESTRIAN, FORCE_OPEN) via the
  /// authenticated exchange.
  /// A named position (NAMED_POSITIONS) goes out only to a device whose features include its bit.
  /// @param device_id Target device ID.
  /// @param cmd Named command to execute.
  /// @return true if device acknowledged; false otherwise, including a named position the device's
  ///         features lack (nothing is sent).
  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.
  /// @param device_moving True when the failed request was a single-try status poll of a device
  ///        the hub believes is travelling; its first misses keep the normal cadence
  ///        (StatusPollPolicy::on_exchange_failed()).
  void schedule_background_poll_backoff_(const std::string &device_id, bool auth_like, bool device_moving = false);
  /// @brief The exchange every heating frame shares: send on the command channel, record the
  /// outcome (exchange counters, link health, error result code), notify the entities and report
  /// whether the device answered with CMD_WRITE_PRIVATE_ACK.
  /// @param device_id Target device ID.
  /// @param label What was sent, for the log ("set_temperature", "read room_temperature").
  /// @param request The framed CMD_WRITE_PRIVATE request.
  /// @param[out] response The device's reply; valid when true is returned.
  /// @param max_tries Transmit-attempt cap forwarded to send_and_receive_().
  /// @return true only if the reply is a CMD_WRITE_PRIVATE_ACK.
  bool exchange_heating_(const std::string &device_id, const char *label, const IoFrame &request, IoFrame &response,
                         uint8_t max_tries);
  /// @brief Read one private register raw: build the read request, run exchange_heating_() and check that
  /// the reply echoes the register.
  ///
  /// The one place a register read is framed and sent; read_heating_register() decodes on top of it, and
  /// the reads no HeatingFunction describes (a model name in ASCII, "is there a value at all") use it
  /// directly. Gated by device_accepts_register_probe(); the request is built by
  /// encode_heating_register_read(), which cannot produce a write.
  /// @param device_id Target device ID.
  /// @param reg_hi High byte of the register.
  /// @param reg_lo Low byte of the register.
  /// @param label What is read, for the log ("model_name").
  /// @param[out] response The reply; its value bytes start at HEATING_REPLY_VALUE_OFFSET (none for a
  ///        register the device does not hold).
  /// @param max_tries Transmit-attempt cap forwarded to exchange_heating_().
  /// @return true when the device answered with the register's echo.
  bool read_private_register_(const std::string &device_id, uint8_t reg_hi, uint8_t reg_lo, const char *label,
                              IoFrame &response, uint8_t max_tries);
  /// @brief The one-off model check of a heater kind that has model rows (device_offers_models()).
  ///
  /// Reads the model name (register 0x0119) and logs it at INFO, and compares whether the towel-dryer mode
  /// register (0x0136) holds a value with the declared `io_model:` (decisions::classify_heater_model_hint()),
  /// logging a WARN when they disagree. Nothing it finds changes behaviour. Done once both reads were
  /// answered, or after decisions::HEATER_MODEL_CHECK_MAX_RUNS runs.
  /// @param device_id Target device ID.
  /// @param max_tries Transmit-attempt cap of each read (the poll's).
  void check_heater_model_(const std::string &device_id, uint8_t max_tries);
  /// @brief Read the temperature in force of a heater's programme, when the programme runs.
  /// @details Sends nothing unless programme_period_active() holds for the readings the poll just made.
  ///          When the temperature fits neither period it forgets the eco setback, so the boot registers
  ///          read it again.
  /// @param device_id Target device ID.
  /// @param profile The device's profile; its programme_period must not be nullptr.
  /// @param max_tries Transmit-attempt cap of the read (the poll's).
  void poll_programme_period_(const std::string &device_id, const HeatingProfile &profile, uint8_t max_tries);
  /// @brief Poll a heater: read its profile's poll registers (stopping at the first failure), then the
  /// programme's temperature in force (poll_programme_period_()), then its
  /// boot registers until each has been read once, then, on a heater kind with model rows, the one-off
  /// model check (check_heater_model_()) once the device has answered a read.
  ///
  /// A failure moves the retry onto the StatusPollPolicy ladder; either way the next regular poll
  /// is armed one interval out (the device's `status_poll_interval`, else
  /// HEATING_POLL_DEFAULT_INTERVAL_MS). Called from request_device_status() for climate devices.
  /// @param device_id Target device ID.
  /// @return true when all four registers were read.
  bool poll_heating_device_(const std::string &device_id);
  /// @brief Read one family-0x00 register of a water heater raw (read_private_register_() gated on
  /// device_feature::WATER_HEATER).
  /// @param device_id Target device ID.
  /// @param index Low byte of the register.
  /// @param label What is read, for the log ("dhw_water_temperature").
  /// @param[out] response The reply; its value bytes start at HEATING_REPLY_VALUE_OFFSET.
  /// @param max_tries Transmit-attempt cap forwarded to read_private_register_().
  /// @return true when the device answered with the register's echo.
  bool read_dhw_register_(const std::string &device_id, uint8_t index, const char *label, IoFrame &response,
                          uint8_t max_tries);
  /// @brief Read one family-0x00 register of a water heater and fold its value into IoDevice::dhw.
  /// @details A value the decoder does not take (an empty value, a mode byte never seen) is logged at
  ///          DEBUG and leaves the reading as it was; it is still an answer, not a failed read.
  /// @param device_id Target device ID.
  /// @param index One of the DHW_REG_* registers.
  /// @param max_tries Transmit-attempt cap.
  /// @return true when the device answered.
  bool read_dhw_reading_(const std::string &device_id, uint8_t index, uint8_t max_tries);
  /// @brief Read a water heater's target, capabilities and boost and away state: the status read
  /// DHW_STATUS_FPI1 / DHW_STATUS_FPI2 (create_status_mp_fp_read()), whose reply update_device_status_()
  /// folds into IoDevice::dhw.
  /// @param device_id Target device ID.
  /// @param max_tries Transmit-attempt cap.
  /// @return true when the device answered.
  bool read_dhw_status_(const std::string &device_id, uint8_t max_tries);
  /// @brief Write one family-0x00 register of a water heater, then read it back.
  ///
  /// Shared by the mode setter and the boost and away duration writes, each of which encodes its own payload. Gated on
  /// device_feature::WATER_HEATER; the write has the full retry budget, the read-back (read_dhw_reading_())
  /// updates IoDevice::dhw, and the next poll moves to HEATING_POST_WRITE_POLL_DELAY_MS from now.
  /// @param device_id Target device ID.
  /// @param operation What is written, for the log ("hot water mode").
  /// @param index The register written, which is also the one read back.
  /// @param payload The encoded write (`0C 61 00 <index> <value>`).
  /// @param payload_len Its length.
  /// @return true only if the device acknowledged the write; a missed read-back does not change that.
  bool write_dhw_register_(const std::string &device_id, const char *operation, uint8_t index, const uint8_t *payload,
                           size_t payload_len);
  /// @brief Switch a water heater's boost or away through the operating-mode word (ADR 0081).
  ///
  /// Refused and logged when FP15 has been read and lacks the feature's capability bit. On: the duration
  /// register write (its ack is logged, a missed one does not stop the sequence), then one EXECUTE with
  /// MAIN_PARAMETER_KEEP and the feature's FP16. Off: the EXECUTE with DHW_OPERATING_MODE_OFF only. After
  /// an accepted EXECUTE the status is read at once and the next poll moves to HEATING_POST_WRITE_POLL_DELAY_MS
  /// from now.
  /// @param device_id Target device ID.
  /// @param which Boost or away.
  /// @param on true to start it, false to end it (which ends the other too).
  /// @return true when the device accepted the EXECUTE.
  bool set_dhw_operating_mode_(const std::string &device_id, DhwOperatingFeature which, bool on);
  /// @brief The water heater `device_id` names, or nullptr when it is unknown, the hub is not set up yet, or
  /// the device is no water heater (that case is logged). The gate of every water heater write.
  /// @param device_id Target device ID.
  /// @param operation What is being written, for the rejection log line.
  /// @return The device record, or nullptr.
  const IoDevice *water_heater_for_write_(const std::string &device_id, const char *operation);
  /// @brief Send one water heater EXECUTE (target or operating mode) through try_execute_operation_(), which
  /// gates on device_feature::WATER_HEATER and arms the settle poll; on acceptance the next poll moves to
  /// HEATING_POST_WRITE_POLL_DELAY_MS from now so the heating state follows.
  /// @param device_id Target device ID.
  /// @param action Operation name for the logs.
  /// @param build Builds the EXECUTE for the device.
  /// @return true when the device accepted the EXECUTE.
  bool execute_dhw_(const std::string &device_id, const char *action,
                    const std::function<bool(IoFrame &, const IoDevice &)> &build);
  /// @brief Poll a water heater: the status read for its target, capabilities and boost and away state
  /// (read_dhw_status_()), then its water temperature, mode, heating state, boost and away duration and
  /// energy registers (stopping at the first failure), then its brand until it has been read once (logged at INFO).
  ///
  /// The same ladder, try band and cadence as poll_heating_device_(): a failure moves the retry onto the
  /// StatusPollPolicy ladder, and the next regular poll is armed one interval out. Called from
  /// request_device_status() for a device with device_feature::WATER_HEATER.
  /// @param device_id Target device ID.
  /// @return true when the status read and every register were answered.
  bool poll_dhw_device_(const std::string &device_id);
  /// 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_;
  /// Set once loop() has reported a radio that latched a failure after setup, so the report (an
  /// error line, ESPHome's warning status and a republish of every device) is made once, not on
  /// every loop.
  bool radio_failure_reported_{false};
  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};
  /// millis() when the last pairing attempt ended; 0 before the first one (see queue_discover_and_pair()).
  uint32_t last_pairing_end_ms_{0};
  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_;
  /// Device events recorded since boot, the last one's text and its subscriber; see record_device_event_().
  uint32_t device_event_count_{0};
  std::string last_device_event_;
  std::function<void()> device_event_callback_;
  /// Whether diagnostic probes (DiagnosticProbes::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_;
  PeriodicPollPolicy rain_poll_policy_;           ///< Schedule of the opt-in rain sensor poll.
  PeriodicPollPolicy sun_poll_policy_;            ///< Schedule of the opt-in sun level poll.
  PeriodicPollPolicy battery_level_poll_policy_;  ///< Schedule of the opt-in battery level poll.
  PeriodicPollPolicy status_refresh_policy_;      ///< Schedule of the opt-in status refresh at rest.
  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