pairing_engine.cpp

Go to the documentation of this file.

/// @file pairing_engine.cpp
/// @brief Device pairing orchestration — discovery, key exchange, and finalization.
/// @ingroup hioc_hub
///
/// Implements PairingEngine's three-phase pairing procedure and the low-level waiters.
/// All radio operations delegate to ExchangeEngine (which owns LBT and hop timing);
/// the PairingEngine focuses purely on protocol sequencing.
///
/// @todo Validate the full discovery and re-pair flow on freshly reset SX1276-backed devices.
/// @todo Validate the full discovery and re-pair flow on freshly reset SX1262-backed devices.
/// @todo Add first-class platform coverage for additional paired device classes once hardware is available.
 
#include "pairing_engine.h"
 
#include "hub_decisions.h"
#include "proto_commands.h"
#include "tuning_config.h"
#include "esphome/core/application.h"
#include "esphome/core/log.h"
 
#include <algorithm>
#include <cinttypes>
#include <cstring>
 
namespace esphome {
namespace home_io_control {
 
namespace {
 
const char *const TAG = "home_io_control";
 
/// Check if frame is a 0x33 key-confirm message.
bool frame_is_key_confirm(const IoFrame &frame) { return frame.cmd == CMD_KEY_CONFIRM; }
 
/// Log discovery-phase failure based on disposition.
void log_discovery_diagnostic(decisions::PairingDiscoveryDisposition disp) {
  switch (disp) {
    case decisions::PairingDiscoveryDisposition::NO_RESPONSE:
      ESP_LOGW(TAG, "No device responded to discovery");
      break;
    case decisions::PairingDiscoveryDisposition::INVALID:
      ESP_LOGW(TAG, "No valid discovery response received");
      break;
    case decisions::PairingDiscoveryDisposition::ACCEPT:
      break;
  }
}
 
/// Block for `ms`, feeding the watchdog between chunks of at most 1000 ms each — a single
/// multi-second delay() would trip the loop-task watchdog, and `pairing_key_init_delay_ms` allows
/// up to 10000. Used only by the discover-confirm step's post-step pause: every other wait in this
/// file is short enough (a few hundred ms) that App.feed_wdt() inside the retry loop is enough.
void delay_feeding_wdt(uint32_t ms) {
  while (ms > 0) {
    App.feed_wdt();
    const uint32_t chunk = ms < 1000 ? ms : 1000;
    delay(chunk);
    ms -= chunk;
  }
}
 
}  // namespace
 
// --- Constructor ---
 
PairingEngine::PairingEngine(RadioDriver **radio_ptr, const uint8_t *node_id, const uint8_t *system_key,
                             const TuningConfig *tuning, ExchangeEngine &engine, DeviceRegistry &registry,
                             PairingTelemetry &telemetry, const RecentOneWayPairingSighting &recent_oneway_sighting)
    : radio_ptr_(radio_ptr),
      node_id_(node_id),
      system_key_(system_key),
      tuning_(tuning),
      engine_(engine),
      registry_(registry),
      telemetry_(telemetry),
      recent_oneway_sighting_(recent_oneway_sighting) {}
 
uint16_t PairingEngine::pairing_start_preamble_(const IoFrame &frame) const {
  return std::min(engine_.request_preamble_for(frame), tuning_->pairing_discovery_preamble);
}
 
// --- Low-level waiters ---
 
/// Wait for a valid discovery response (0x29) within timeout_ms.
///
/// Listens with per-chip frequency hopping between slices. Distinguishes between
/// NO_RESPONSE (no packets at all) and INVALID (packets seen but none valid).
///
/// Frequency hopping: hops between the 2 non-request IO-homecontrol channels after each slice —
/// the request always goes out on FREQ_CH2 (see run_discovery_phase_()), and a discovery reply
/// essentially never lands back on that channel (see ListenPolicy's own doc comment for why), so
/// dwelling there is wasted listening time. Same policy as collect_broadcast_responses()'s
/// default. The slice length comes from
/// RadioDriver::hop_dwell_ms() (spec.dwell_ms left at 0, so listen() asks the driver). When
/// preamble or sync detection fires, the dwell extends by PREAMBLE_LINGER_DWELL_MS so the
/// incoming frame can complete without interruption.
decisions::PairingDiscoveryDisposition PairingEngine::wait_for_discovery_response_(uint32_t timeout_ms,
                                                                                   RadioRxPacket &packet,
                                                                                   IoFrame &response_frame) {
  ListenSpec spec;
  spec.window_ms = timeout_ms;
  // Skipping the request channel is the default because a broadcast's answers are almost never
  // on it (ListenPolicy's own doc has the 1-in-149 measurement). `all` is the escape hatch for a
  // device that has never answered at all: that measurement is drawn from responders we already
  // hear, so it cannot speak for one whose replies we might be missing entirely.
  spec.policy = tuning_->pairing_discovery_listen_channels == DiscoveryListenChannels::ALL
                    ? ListenPolicy::ROTATE_ALL_CHANNELS
                    : ListenPolicy::ROTATE_SKIPPING_REQUEST;
  spec.request_freq = FREQ_CH2;
  // dwell_ms left at 0: no measured reason to dwell differently from the roll-call, so listen()
  // asks the driver (radio_()->hop_dwell_ms(*tuning_)) the same way collect_broadcast_responses()
  // does.
  spec.linger_on_preamble = true;
  spec.linger_dwell_ms = PREAMBLE_LINGER_DWELL_MS;
  spec.on_hop = [this]() { this->telemetry_.record_hop(); };
 
  bool saw_traffic = false;
  auto outcome =
      engine_.listen(spec, packet, response_frame, [&](const IoFrame *parsed, const RadioRxPacket & /*packet*/) {
        saw_traffic = true;
        if (parsed == nullptr)
          return ReplyDisposition::IGNORE;
        const bool accepted = decisions::classify_pairing_discovery_response(*parsed, node_id_) ==
                              decisions::PairingDiscoveryDisposition::ACCEPT;
        this->record_discovery_rx_telemetry_(*parsed, accepted, radio_()->get_last_capture().rssi_dbm);
        return accepted ? ReplyDisposition::ACCEPT : ReplyDisposition::IGNORE;
      });
 
  if (outcome == ListenOutcome::ACCEPTED)
    return decisions::PairingDiscoveryDisposition::ACCEPT;
  return saw_traffic ? decisions::PairingDiscoveryDisposition::INVALID
                     : decisions::PairingDiscoveryDisposition::NO_RESPONSE;
}
 
/// Wait for a key-challenge (0x3C) or direct key-confirm (0x33) from target device.
///
/// During key exchange the device typically responds to 0x31 with a random 6-byte
/// challenge (0x3C). Some devices skip the challenge and send 0x33 directly —
/// indicating immediate key acceptance (observed mostly when the controller's
/// TX→RX turnaround is slow enough that the 0x3C is missed). Both are accepted.
///
/// Uses `ExchangeEngine::listen()` with `ListenPolicy::HOLD_REQUEST_CHANNEL`: this is a unicast
/// reply to a unicast request (the 0x31 key-init), and every measured unicast pairing reply came
/// back on the request channel, so there is nothing here to hop for — same reasoning as
/// `listen_for_key_confirm_()`. This loop runs on all three chips (it is called before the
/// `has_fast_tx_rx_turnaround()` branch in `run_key_exchange_phase_()`), unlike the dedicated
/// confirm wait, which only slow-turnaround radios reach.
bool PairingEngine::wait_for_key_challenge_(uint32_t timeout_ms, RadioRxPacket &packet, IoFrame &challenge_frame,
                                            const uint8_t device_node_id[NODE_ID_SIZE]) {
  ListenSpec spec;
  spec.window_ms = timeout_ms;
  spec.policy = ListenPolicy::HOLD_REQUEST_CHANNEL;
 
  bool saw_traffic = false;
  auto outcome =
      engine_.listen(spec, packet, challenge_frame, [&](const IoFrame *parsed, const RadioRxPacket & /*packet*/) {
        saw_traffic = true;
        if (parsed == nullptr)
          return ReplyDisposition::IGNORE;
        const int16_t rssi = radio_()->get_last_capture().rssi_dbm;
        if (parsed->cmd == CMD_KEY_CONFIRM && memcmp(parsed->src, device_node_id, NODE_ID_SIZE) == 0 &&
            memcmp(parsed->dst, node_id_, NODE_ID_SIZE) == 0) {
          this->telemetry_.record_rx(*parsed, rssi);
          return ReplyDisposition::ACCEPT;
        }
        if (decisions::classify_pairing_key_challenge(*parsed, device_node_id, node_id_) !=
            decisions::PairingKeyChallengeDisposition::ACCEPT) {
          this->telemetry_.record_rx_reject(*parsed, rssi);
          return ReplyDisposition::IGNORE;
        }
        this->telemetry_.record_rx(*parsed, rssi);
        return ReplyDisposition::ACCEPT;
      });
 
  if (outcome == ListenOutcome::ACCEPTED)
    return true;
  ESP_LOGW(TAG, saw_traffic ? "Key exchange: no valid challenge received" : "Key exchange: no challenge received");
  return false;
}
 
/// Wait for one discover-confirm (0x2C) try's answer.
///
/// Listen policy alternates per try (`decisions::discover_confirm_try_rotates()`): the one
/// rotating try hedges against a 0x2D landing off the request channel — Somfy answers on the
/// request channel, VELUX is unmeasured — while the rest hold, matching every other unicast
/// pairing wait in this file (a 0x2D is a unicast reply to a unicast 0x2C). Only parsed frames are
/// recorded to telemetry, same as the other pairing waits.
decisions::PairingDiscoverConfirmDisposition PairingEngine::wait_for_discover_confirm_ack_(
    uint8_t try_index, pairing::PairingContext &context) {
  ListenSpec spec;
  spec.window_ms = PAIRING_DISCOVER_CONFIRM_ACK_TIMEOUT_MS;
  if (decisions::discover_confirm_try_rotates(try_index)) {
    spec.policy = ListenPolicy::ROTATE_ALL_CHANNELS;
    // Same shape as the discovery listen's rotating spec: a short rotating dwell needs the
    // preamble/sync linger guard so an incoming reply is not cut off mid-retune.
    spec.linger_on_preamble = true;
    spec.linger_dwell_ms = PREAMBLE_LINGER_DWELL_MS;
    spec.on_hop = [this]() { this->telemetry_.record_hop(); };
  } else {
    spec.policy = ListenPolicy::HOLD_REQUEST_CHANNEL;
  }
 
  auto disposition = decisions::PairingDiscoverConfirmDisposition::IGNORE;
  auto outcome =
      engine_.listen(spec, context.packet, context.rx, [&](const IoFrame *parsed, const RadioRxPacket & /*packet*/) {
        if (parsed == nullptr)
          return ReplyDisposition::IGNORE;
        const int16_t rssi = radio_()->get_last_capture().rssi_dbm;
        disposition = decisions::classify_pairing_discover_confirm_reply(*parsed, context.device.node_id, node_id_);
        if (disposition == decisions::PairingDiscoverConfirmDisposition::IGNORE) {
          this->telemetry_.record_rx_reject(*parsed, rssi);
          return ReplyDisposition::IGNORE;
        }
        this->telemetry_.record_rx(*parsed, rssi);
        return ReplyDisposition::ACCEPT;
      });
 
  if (outcome != ListenOutcome::ACCEPTED)
    return decisions::PairingDiscoverConfirmDisposition::IGNORE;  // Timeout: no reply this try.
  return disposition;
}
 
/// One HOLD_REQUEST_CHANNEL listen for the key-transfer confirm wait — see the header doc for why
/// this is a shared helper rather than an inline lambda repeated at each of its two call sites.
///
/// Deliberately holds the request channel rather than hopping: a key confirm is a unicast reply to
/// a unicast request, and every measured unicast pairing reply — the 0x33 in the corpus pairing
/// captures on all three chips, every 0x3C, field-logged 0xFE error replies — came back on the
/// channel the request went out on. Only replies to *broadcasts* are measured off the request
/// channel, so there is nothing here to hop for, and hopping loses any device that answers later
/// than one slice (real devices answer some requests at 246+ ms). HOLD also does not slice the
/// wait: slicing exists so a hopping loop gets a chance to hop between dwells, and to keep the
/// watchdog fed during a long silent wait; neither applies here, and wait_for_packet() already
/// feeds the watchdog internally while it blocks.
decisions::PairingKeyConfirmDisposition PairingEngine::listen_for_key_confirm_(pairing::PairingContext &context,
                                                                               uint8_t try_number,
                                                                               bool after_challenge) {
  ListenSpec spec;
  spec.window_ms = PAIRING_KEY_CONFIRM_TIMEOUT_MS;
  spec.policy = ListenPolicy::HOLD_REQUEST_CHANNEL;
 
  bool saw_any = false;
  auto disposition = decisions::PairingKeyConfirmDisposition::IGNORE;
  auto outcome =
      engine_.listen(spec, context.packet, context.resp, [&](const IoFrame *parsed, const RadioRxPacket &packet) {
        saw_any = true;
        ESP_LOGD(TAG, "Key confirm wait: got %u bytes on freq=%" PRIu32, packet.len, packet.freq_hz);
        if (parsed == nullptr) {
          ESP_LOGD(TAG, "Key confirm wait: parse failed");
          return ReplyDisposition::IGNORE;
        }
        ESP_LOGD(TAG, "Key confirm wait: parsed cmd=0x%02X src=%02X%02X%02X dst=%02X%02X%02X", parsed->cmd,
                 parsed->src[0], parsed->src[1], parsed->src[2], parsed->dst[0], parsed->dst[1], parsed->dst[2]);
        disposition = decisions::classify_pairing_key_confirm_reply(context.req, *parsed);
        if (disposition == decisions::PairingKeyConfirmDisposition::IGNORE)
          return ReplyDisposition::IGNORE;
 
        const int16_t rssi = radio_()->get_last_capture().rssi_dbm;
        if (disposition == decisions::PairingKeyConfirmDisposition::REFUSE) {
          this->telemetry_.record_rx_reject(*parsed, rssi);
          ESP_LOGW(TAG, "Key transfer: device responded with cmd=%s(0x%02X) (expected KEY_CONFIRM 0x33)",
                   command_name(parsed->cmd), parsed->cmd);
          if (parsed->cmd == CMD_ERROR_RESP && parsed->data_len > 0)
            ESP_LOGW(TAG, "Key transfer: error code=0x%02X", parsed->data[0]);
          return ReplyDisposition::ABORT;
        }
        // CONFIRM (0x33) or CHALLENGE (a well-formed 0x3C): both are legitimate answers, not
        // rejections. No TX happens in this callback — a CHALLENGE is answered by the caller
        // after this listen ends, per the header doc.
        this->telemetry_.record_rx(*parsed, rssi);
        return disposition == decisions::PairingKeyConfirmDisposition::CONFIRM ? ReplyDisposition::ACCEPT
                                                                               : ReplyDisposition::ABORT;
      });
 
  if (outcome == ListenOutcome::TIMED_OUT) {
    ESP_LOGI(TAG, "Try %u%s: no response for key transfer (0x32) within %" PRIu32 " ms (saw_any=%d)", try_number,
             after_challenge ? " (post-challenge)" : "", PAIRING_KEY_CONFIRM_TIMEOUT_MS, saw_any);
    return decisions::PairingKeyConfirmDisposition::IGNORE;
  }
  return disposition;
}
 
/// Transmit the 0x32 key transfer and wait for 0x33 key confirm (with retry).
///
/// Only reached on slow-turnaround radios (`RadioDriver::has_fast_tx_rx_turnaround() == false`,
/// i.e. SX1262/LR1121): fast-turnaround radios (SX1276) catch the 0x33 through the standard
/// `ExchangeEngine::send_and_receive_()` / `wait_for_first_response_()` path instead and never
/// call this function — see `run_key_exchange_phase_()`. Uses the driver's response_preamble()
/// (drivers whose TX waveform needs more lock-on margin return a longer preamble). Retries up to
/// EXCHANGE_RETRY_COUNT times on timeout.
bool PairingEngine::wait_for_key_confirm_(pairing::PairingContext &context) {
  for (uint8_t tries = 0; tries < EXCHANGE_RETRY_COUNT; tries++) {
    if (tries > 0) {
      App.feed_wdt();
      delay(EXCHANGE_RETRY_DELAY_MS);
    }
    if (!engine_.transmit_frame(context.req, FREQ_CH2, radio_()->response_preamble()))
      continue;
 
    const uint8_t try_number = tries + 1;
    decisions::PairingKeyConfirmDisposition disposition = listen_for_key_confirm_(context, try_number, false);
    if (disposition == decisions::PairingKeyConfirmDisposition::CHALLENGE) {
      ESP_LOGI(TAG, "Key transfer: device challenged the key transfer, answering 0x3D");
      // "Rest of the window" would leave almost nothing after a late challenge plus the 0x3D TX,
      // so this is a fresh full window, same as ExchangeEngine::wait_for_final_response_() gets
      // after handle_authentication_(). A failed 0x3D build/TX leaves `disposition` at CHALLENGE,
      // which the checks below treat the same as a second challenge: this try ends without
      // confirming, and the next try re-sends 0x32.
      if (engine_.answer_challenge(context.req, context.resp, FREQ_CH2))
        disposition = listen_for_key_confirm_(context, try_number, true);
    }
 
    if (disposition == decisions::PairingKeyConfirmDisposition::CONFIRM)
      return true;
    if (disposition == decisions::PairingKeyConfirmDisposition::REFUSE)
      return false;  // An explicit refusal must not spend the remaining retries; a challenge is
                     // not a refusal, so neither branch above returns false for it.
    // IGNORE (timeout) or a second CHALLENGE in the same try: spend the next try.
  }
  return false;
}
 
/// Build CMD_KEY_TRANSFER against the challenge currently held in `context.rx.data` and wait for
/// the 0x33 confirm, routing through the fast- or slow-turnaround path. Shared by
/// run_key_exchange_phase_()'s first attempt and its slow-turnaround retry loop, which calls this
/// again against a freshly re-issued challenge (see that function's doc comment) rather than
/// discarding it.
bool PairingEngine::transfer_key_and_wait_confirm_(pairing::PairingContext &context) {
  context.state = pairing::PairingState::TX_KEY_TRANSFER;
  engine_.record_debug(pairing_stage_name(context.state), 1, true);
  this->telemetry_.set_phase(context.state);
  if (!create_key_transfer(context.req, context.key_init, context.device.node_id, node_id_, system_key_,
                           context.rx.data)) {
    return false;
  }
 
  context.state = pairing::PairingState::WAIT_KEY_CONFIRM;
  engine_.record_debug(pairing_stage_name(context.state), 1, true);
  this->telemetry_.set_phase(context.state);
  // Fast-turnaround radios catch the 0x33 through the standard exchange wait. Slow-turnaround
  // radios miss it while re-entering RX, so run_key_exchange_phase_()'s retry loop calls this
  // helper again instead, rather than using the dedicated wait loop directly.
  if (radio_()->has_fast_tx_rx_turnaround()) {
    // Key exchange is the one caller that genuinely needs the payload: without the 0x33 there is
    // no confirmation the device took the key, so an unconfirmed acceptance is not good enough.
    return engine_.send_and_receive(context.req, context.resp, FREQ_CH2) == ExchangeOutcome::SUCCESS_WITH_RESPONSE &&
           frame_is_key_confirm(context.resp);
  }
  return wait_for_key_confirm_(context);
}
 
// --- Discovery metadata ---
 
/// Parse a discovery response frame into device metadata and ID.
///
/// Decodes node ID, device type, subtype, and the extended fields (manufacturer, backbone,
/// Multi Information Byte) via decode_discovery_response(), then emits pairing's diagnostic log
/// lines for whichever extended fields the payload actually included.
/// The inversion flag is derived from the type via `default_inverted_for_type()`.
DiscoveryResponseInfo PairingEngine::parse_device_from_discovery(const IoFrame &frame, IoDevice &device,
                                                                 std::string &device_id) {
  const DiscoveryResponseInfo info = decode_discovery_response(frame, device, device_id);
 
  if (frame.data_len > DISCOVERY_RESP_MANUFACTURER_OFFSET) {
    const char *mfr_name = manufacturer_name(info.manufacturer);
    ESP_LOGI(TAG, "Discovery: device %s manufacturer=%u (%s)", device_id.c_str(), info.manufacturer, mfr_name);
    if (info.manufacturer == 0 || info.manufacturer > MANUFACTURER_ID_MAX) {
      ESP_LOGW(TAG,
               "Unknown manufacturer ID %u reported by device %s. "
               "Please file a GitHub issue with this ID and your device model so support can be added.",
               info.manufacturer, device_id.c_str());
    }
  }
  if (frame.data_len > DISCOVERY_RESP_BACKBONE_OFFSET + NODE_ID_SIZE - 1) {
    ESP_LOGD(TAG, "Discovery: backbone=%02X%02X%02X", info.backbone[0], info.backbone[1], info.backbone[2]);
  }
  if (frame.data_len > DISCOVERY_RESP_FLAGS_OFFSET) {
    uint8_t const att = discovery_att_class(info.flags);
    uint8_t const power_save = discovery_power_save_mode(info.flags);
    ESP_LOGI(TAG, "Discovery: device %s turnaround=%s power_save=%s flags=0x%02X", device_id.c_str(),
             att_class_name(att), power_save_mode_name(power_save), info.flags);
    if (power_save == POWER_SAVE_LOW_POWER) {
      ESP_LOGI(TAG,
               "Device %s reports low-power mode: add 'low_power: true' to its YAML entry. "
               "The pairing snippet below pre-fills it when one is printed.",
               device_id.c_str());
    }
  }
  return info;
}
 
// --- Phase helpers ---
 
/// Phase 1: broadcast discovery command(s) and wait for a device response (0x29).
///
/// Sends each configured discovery command in order, waiting up to
/// `pairing_discovery_wait_ms` for a valid response after each TX.
/// Retries up to PAIRING_DISCOVERY_MAX_ATTEMPTS times per command.
decisions::PairingDiscoveryDisposition PairingEngine::run_discovery_phase_(pairing::PairingContext &context) {
  if (tuning_->pairing_discovery_initial_dwell_ms > 0) {
    ESP_LOGD(TAG, "Discovery: initial dwell %u ms", tuning_->pairing_discovery_initial_dwell_ms);
    delay(tuning_->pairing_discovery_initial_dwell_ms);
  }
 
  // Tracks whether any single attempt saw traffic that failed to classify as a valid discovery
  // response, so the final "gave up after retries" return can distinguish INVALID (something was
  // heard, just not a valid response) from NO_RESPONSE (nothing heard at all) instead of always
  // collapsing to NO_RESPONSE.
  bool saw_invalid = false;
 
  for (size_t command_index = 0; command_index < tuning_->pairing_discovery_commands.size(); ++command_index) {
    auto command = static_cast<uint8_t>(tuning_->pairing_discovery_commands[command_index]);
    const uint8_t *destination = resolve_discovery_destination(command, tuning_->pairing_discovery_destination_auto,
                                                               tuning_->pairing_discovery_destination.data());
    ESP_LOGD(TAG, "Discovery command %zu/%zu: cmd=0x%02X dst=%02X%02X%02X", command_index + 1,
             tuning_->pairing_discovery_commands.size(), command, destination[0], destination[1], destination[2]);
 
    for (uint8_t attempt = 1; attempt <= PAIRING_DISCOVERY_MAX_ATTEMPTS; ++attempt) {
      this->telemetry_.increment_discovery_attempt();
      context.state = pairing::PairingState::TX_DISCOVER;
      engine_.record_debug(pairing_stage_name(context.state), attempt, false);
      this->telemetry_.set_phase(context.state);
      if (!create_discovery_request(context.req, node_id_, command, destination, tuning_->pairing_discovery_low_power,
                                    tuning_->pairing_discovery_ack_capable, tuning_->pairing_discovery_payload_enabled,
                                    tuning_->pairing_discovery_payload, system_key_) ||
          !engine_.transmit_frame(context.req, FREQ_CH2, tuning_->pairing_discovery_preamble)) {
        return decisions::PairingDiscoveryDisposition::NO_RESPONSE;
      }
 
      context.state = pairing::PairingState::WAIT_DISCOVER_RESPONSE;
      engine_.record_debug(pairing_stage_name(context.state), attempt, false);
      this->telemetry_.set_phase(context.state);
      auto result = wait_for_discovery_response_(tuning_->pairing_discovery_wait_ms, context.packet, context.rx);
      if (result == decisions::PairingDiscoveryDisposition::ACCEPT) {
        const DiscoveryResponseInfo info = parse_device_from_discovery(context.rx, context.device, context.device_id);
        context.discovery_metadata_complete = context.rx.data_len >= DEVICE_METADATA_SIZE;
        context.discovery_low_power =
            info.has_extended && discovery_power_save_mode(info.flags) == POWER_SAVE_LOW_POWER;
        return result;
      }
      if (result == decisions::PairingDiscoveryDisposition::INVALID) {
        saw_invalid = true;
      }
 
      if (attempt < PAIRING_DISCOVERY_MAX_ATTEMPTS) {
        ESP_LOGI(TAG, "Discovery attempt %u/%u for cmd=0x%02X: no response, retrying...", attempt,
                 PAIRING_DISCOVERY_MAX_ATTEMPTS, command);
      }
    }
  }
  return saw_invalid ? decisions::PairingDiscoveryDisposition::INVALID
                     : decisions::PairingDiscoveryDisposition::NO_RESPONSE;
}
 
/// Discover-confirm step (0x2C → 0x2D): sent directly to the device discovery just found, once
/// per discover_and_pair() attempt, before the key-exchange retry loop begins (so a retry of that
/// loop never repeats this step).
///
/// Never fails a pairing attempt: `skip` mode, a timeout, and an explicit CMD_ERROR_RESP all still
/// let discover_and_pair() proceed to run_key_exchange_phase_() — this function only decides how
/// long that takes and what gets logged. CTRL1_ACK follows the *target's* power class, not the
/// mode alone: a low-power target's 0x2C carries `CTRL1_LOW_POWER` only in both `send` and
/// `send_with_ack` (every corpus hub's own shape for that class); only an always-alive target's
/// ACK bit changes between the two modes (see create_discover_confirm()'s doxygen for the
/// byte-shape cross-check against real captures).
///
/// `set_phase()` fires at most once per state for the whole step (not per try): the confirm step
/// can spend up to PAIRING_DISCOVER_CONFIRM_TRIES transmits, and PAIRING_TELEMETRY_MAX_EVENTS is a
/// fixed 32-event budget the pairing advisor scans — a per-try phase would spend events on exactly
/// the failure paths it is meant to diagnose. record_debug() (not telemetry) still runs every try.
pairing::DiscoverConfirmResult PairingEngine::run_discover_confirm_step_(pairing::PairingContext &context) {
  if (tuning_->pairing_discover_confirm == DiscoverConfirmMode::SKIP)
    return pairing::DiscoverConfirmResult::SKIPPED;
 
  const bool ack =
      tuning_->pairing_discover_confirm == DiscoverConfirmMode::SEND_WITH_ACK && !context.discovery_low_power;
 
  context.state = pairing::PairingState::TX_DISCOVER_CONFIRM;
  this->telemetry_.set_phase(context.state);
 
  bool wait_phase_started = false;
  pairing::DiscoverConfirmResult result = pairing::DiscoverConfirmResult::NO_REPLY;
  for (uint8_t try_index = 1; try_index <= PAIRING_DISCOVER_CONFIRM_TRIES; try_index++) {
    if (try_index > 1)
      App.feed_wdt();  // No extra retry gap: the 1.5 s windows already space the retransmissions.
 
    engine_.record_debug(pairing_stage_name(pairing::PairingState::TX_DISCOVER_CONFIRM), try_index, false);
    if (!create_discover_confirm(context.req, node_id_, context.device.node_id, context.discovery_low_power, ack) ||
        !engine_.transmit_frame(context.req, FREQ_CH2, pairing_start_preamble_(context.req))) {
      continue;  // A failed build/TX counts as a silent try, like wait_for_key_confirm_() does for 0x32.
    }
 
    context.state = pairing::PairingState::WAIT_DISCOVER_CONFIRM;
    if (!wait_phase_started) {
      this->telemetry_.set_phase(context.state);
      wait_phase_started = true;
    }
    engine_.record_debug(pairing_stage_name(context.state), try_index, false);
 
    const uint32_t wait_start_ms = millis();
    const decisions::PairingDiscoverConfirmDisposition disposition = wait_for_discover_confirm_ack_(try_index, context);
 
    if (disposition == decisions::PairingDiscoverConfirmDisposition::ACK) {
      ESP_LOGI(TAG, "Discover confirm: 0x2D from %s on freq=%" PRIu32 " after %" PRIu32 " ms (try %u/%u)",
               context.device_id.c_str(), context.packet.freq_hz, millis() - wait_start_ms, try_index,
               PAIRING_DISCOVER_CONFIRM_TRIES);
      result = pairing::DiscoverConfirmResult::ACKED;
      break;
    }
    if (disposition == decisions::PairingDiscoverConfirmDisposition::ERROR) {
      const uint8_t error_code = context.rx.data_len > 0 ? context.rx.data[0] : 0;
      ESP_LOGW(TAG, "Discover confirm: device %s answered 0x2C with error 0x%02X, continuing with key exchange",
               context.device_id.c_str(), error_code);
      result = pairing::DiscoverConfirmResult::ERROR_REPLY;
      break;
    }
    // IGNORE: timeout or an unrelated frame this try — spend the next try.
  }
 
  if (result == pairing::DiscoverConfirmResult::NO_REPLY) {
    ESP_LOGI(TAG, "Discover confirm: no 0x2D from %s after %u tries, continuing with key exchange",
             context.device_id.c_str(), PAIRING_DISCOVER_CONFIRM_TRIES);
  }
 
  // Applied for every result reaching here (i.e. every result except SKIPPED, which already
  // returned above), including NO_REPLY — one simple rule instead of a per-outcome one.
  if (tuning_->pairing_key_init_delay_ms > 0)
    delay_feeding_wdt(tuning_->pairing_key_init_delay_ms);
 
  return result;
}
 
/// Phase 2: authenticated key exchange (0x31 → 0x3C → 0x32 → 0x33).
///
/// Steps:
///   1. Transmit CMD_KEY_INIT (0x31), preamble per pairing_start_preamble_()
///   2. Wait for device challenge (0x3C)
///   3. Transmit CMD_KEY_TRANSFER (0x32) with encrypted system key
///   4. Wait for CMD_KEY_CONFIRM (0x33)
///
/// Step 4 depends on the driver's TX→RX turnaround: fast-turnaround radios await
/// the 0x33 through the standard send_and_receive() exchange; slow-turnaround
/// radios use the dedicated wait_for_key_confirm_() path with a key-init
/// re-trigger, because the 0x33 would otherwise arrive while the receiver is
/// still settling (see RadioDriver::has_fast_tx_rx_turnaround()).
///
/// The slow-turnaround re-trigger loop below (`for (int re = 0; ...)`) has two distinct outcomes
/// for its re-sent CMD_KEY_INIT, and they are handled differently:
///   - The device replies with CMD_KEY_CONFIRM (0x33) directly — it already had the key from the
///     first 0x32 and is just auto-confirming again. Nothing more to send.
///   - The device replies with a *fresh* CMD_CHALLENGE_REQ (0x3C) instead — proof it never received
///     the first 0x32 at all (a device that already holds the key doesn't re-challenge), so there
///     is no key transfer for it to confirm yet. The loop calls transfer_key_and_wait_confirm_()
///     again here, replaying CMD_KEY_TRANSFER against this new challenge, rather than discarding
///     the 0x3C and burning the retry for nothing — the device's next 0x31 would just produce
///     another fresh challenge either way, so retrying without resending 0x32 could never succeed.
///
/// That replay roughly doubles this function's worst-case blocking time when every wait times out
/// (approximately 3.5s -> 6.6s: two of the loop's iterations can now each wait out a full
/// key-transfer-and-confirm cycle instead of returning immediately on a missed 0x33). This is a
/// known, accepted trade-off: pairing already tolerates multi-second blocking exchanges (see
/// EXCHANGE_TOTAL_BUDGET_MS's own reasoning, proto_timing.h), and the alternative — leaving a
/// slow-turnaround device that never got its key stuck retrying forever — is worse than the
/// occasional slower failure path.
bool PairingEngine::run_key_exchange_phase_(pairing::PairingContext &context) {
  context.state = pairing::PairingState::TX_KEY_INIT;
  engine_.record_debug(pairing_stage_name(context.state), 1, false);
  this->telemetry_.set_phase(context.state);
  if (!create_key_init(context.key_init, node_id_, context.device.node_id) ||
      !engine_.transmit_frame(context.key_init, FREQ_CH2, pairing_start_preamble_(context.key_init))) {
    return false;
  }
 
  context.state = pairing::PairingState::WAIT_KEY_CHALLENGE;
  engine_.record_debug(pairing_stage_name(context.state), 1, true);
  this->telemetry_.set_phase(context.state);
  if (!wait_for_key_challenge_(PAIRING_KEY_CHALLENGE_TIMEOUT_MS, context.packet, context.rx, context.device.node_id)) {
    return false;
  }
 
  // Some devices send 0x33 directly after 0x31 without requiring 0x32.
  if (context.rx.cmd == CMD_KEY_CONFIRM) {
    ESP_LOGI(TAG, "Device accepted key immediately (0x33 without 0x32 exchange)");
    context.resp = context.rx;
    return true;
  }
 
  // No challenge bytes here: the raw 0x3C payload plus the 0x3D response it provokes is a
  // known-plaintext/known-ciphertext pair under the system key (see redaction.h). The generic
  // frame-log helpers (log_frame()/log_component_capture()) already mask both commands.
  ESP_LOGI(TAG, "Challenge (0x3C) received: data_len=%u freq=%" PRIu32 " rssi=%d", context.rx.data_len,
           context.packet.freq_hz, radio_()->get_last_capture().rssi_dbm);
 
  bool key_ok = transfer_key_and_wait_confirm_(context);
  // Fast-turnaround radios catch the 0x33 through the standard exchange wait inside the helper
  // above and never reach this loop. Slow-turnaround radios miss it while re-entering RX, so on a
  // miss they re-send the key-init to trigger the device's auto-confirm.
  if (!radio_()->has_fast_tx_rx_turnaround()) {
    for (int re = 0; !key_ok && re < 2; re++) {
      ESP_LOGI(TAG, "Key confirm missed, re-sending key-init to trigger auto-confirm (attempt %d/2)", re + 1);
      App.feed_wdt();
      delay(EXCHANGE_RETRY_DELAY_MS);
      if (!engine_.transmit_frame(context.key_init, FREQ_CH2, pairing_start_preamble_(context.key_init)))
        continue;
      if (!wait_for_key_challenge_(PAIRING_KEY_CHALLENGE_TIMEOUT_MS, context.packet, context.rx,
                                   context.device.node_id))
        continue;
      if (context.rx.cmd == CMD_KEY_CONFIRM) {
        key_ok = true;
        continue;
      }
      // A fresh CHALLENGE_REQ (0x3C), not a direct KEY_CONFIRM (0x33): the device never received
      // our first 0x32 in the first place, so there is no key for it to auto-confirm yet -- a
      // fresh 0x3C is exactly the signal that the right response is "resend 0x32 against this new
      // challenge", not "give up and burn the retry for nothing".
      key_ok = transfer_key_and_wait_confirm_(context);
    }
  }
  if (!key_ok) {
    ESP_LOGW(TAG, "Key exchange failed");
    return false;
  }
  return true;
}
 
/// Phase 3: send SetConfig1 (0x6F) once. Optional — see the header. Its preamble follows
/// pairing_start_preamble_(), like the other directed pairing start frames.
void PairingEngine::finalize_pairing_configuration_(pairing::PairingContext &context) {
  if (!create_set_config1(context.req, node_id_, context.device.node_id))
    return;
  // Its reply is never read: an explicit refusal and silence are equally harmless here.
  if (engine_.send_and_receive(context.req, context.resp, FREQ_CH2, PAIRING_SET_CONFIG1_MAX_TRIES,
                               pairing_start_preamble_(context.req)) == ExchangeOutcome::FAILED) {
    ESP_LOGI(TAG, "Pairing: no reply from %s to the optional SetConfig1 (0x6F); the pairing is complete",
             context.device_id.c_str());
  }
}
 
// --- Orchestrator ---
 
/// Pairing orchestrator — high-level three-phase flow.
///
/// Phase 1: run_discovery_phase_() finds a device in pairing mode.
/// Phase 2: run_key_exchange_phase_() performs authenticated key establishment.
/// Phase 3: finalize_pairing_configuration_() sends the optional SetConfig1 once.
///
/// On success the device is added to the registry and a YAML snippet is printed to the log.
/// The hub's thin wrapper manages the busy_ flag before and after this call.
bool PairingEngine::discover_and_pair() {
  this->telemetry_.begin();
  this->engine_.set_transmit_observer(&this->telemetry_);
 
  // Seed telemetry with a 1W pairing-gesture frame the hub overheard shortly before this call
  // (issue #27/#65): without this, a PROG press completed a few seconds before "Discover & Pair"
  // is pressed in the app is invisible to the advisor purely because the telemetry window opens
  // here, even though the radio heard it just fine — the false rf_silent advice this produced was
  // field-confirmed against a real trace (issue #27, miljaar).
  if (this->recent_oneway_sighting_.seen_ms != 0 &&
      (millis() - this->recent_oneway_sighting_.seen_ms) < PAIRING_RECENT_ONE_WAY_SIGHTING_WINDOW_MS) {
    this->telemetry_.record_recent_one_way_sighting(this->recent_oneway_sighting_);
  }
 
  ESP_LOGI(TAG, "Starting device discovery...");
  ESP_LOGI(TAG, "%s", tuning_config_full_snapshot(*tuning_).c_str());
 
  pairing::PairingContext context;
 
  // Phase 1: Discovery
  auto disc_disp = run_discovery_phase_(context);
  if (disc_disp != decisions::PairingDiscoveryDisposition::ACCEPT) {
    log_discovery_diagnostic(disc_disp);
    this->finish_pairing_attempt_(disc_disp == decisions::PairingDiscoveryDisposition::INVALID
                                      ? PairingOutcome::INVALID_RESPONSE
                                      : PairingOutcome::NO_RESPONSE);
    return false;
  }
 
  if (tuning_->pairing_discovery_preamble < LONG_PREAMBLE) {
    ESP_LOGI(TAG, "Pairing: directed frames to %s use the %u-byte discovery preamble it just answered",
             context.device_id.c_str(), tuning_->pairing_discovery_preamble);
  }
 
  // Discover-confirm (0x2C -> 0x2D): once per attempt, before the key-exchange retry loop below,
  // so a retry of that loop never repeats it. Never fails the attempt — see the function's doc.
  this->run_discover_confirm_step_(context);
 
  // Phase 2: Key exchange — retry up to the configured number of times.
  bool key_exchanged = false;
  for (uint8_t ke_attempt = 0; ke_attempt < tuning_->pairing_key_exchange_retries; ke_attempt++) {
    if (ke_attempt > 0) {
      ESP_LOGI(TAG, "Retrying key exchange (attempt %d/%u)...", ke_attempt + 1, tuning_->pairing_key_exchange_retries);
      App.feed_wdt();
      delay(EXCHANGE_RETRY_DELAY_MS);
    }
    if (run_key_exchange_phase_(context)) {
      key_exchanged = true;
      break;
    }
  }
  if (!key_exchanged) {
    this->finish_pairing_attempt_(PairingOutcome::KEY_EXCHANGE_FAILED);
    return false;
  }
 
  // Phase 3: optional SetConfig1. The 0x33 above completed the pairing.
  finalize_pairing_configuration_(context);
 
  context.state = pairing::PairingState::REGISTER_DEVICE;
  engine_.record_debug(pairing_stage_name(context.state), 1, true);
  this->telemetry_.set_phase(context.state);
 
  // The device just sent its 0x33, so it counts as heard from: its wake belief starts at "maybe
  // awake" for the follow-up exchanges rather than "asleep" (same stamp update_link_health() sets).
  context.device.last_seen_ms = millis();
  registry_.put(context.device_id, context.device);
  this->telemetry_.set_paired_device(context.device.node_id, context.device.type);
 
  const std::string type_diag = format_device_type_diagnostic(context.device.type);
  const std::string type_yaml = format_device_type_for_yaml(context.device.type);
  const std::string snippet = build_device_yaml_snippet(context.device.type, context.device.subtype, context.device_id,
                                                        context.discovery_metadata_complete, context.device.inverted,
                                                        context.discovery_low_power);
 
  if (snippet.empty()) {
    // metadata_complete is true here (build_device_yaml_snippet() never returns empty for
    // metadata_complete == false), so this is specifically "we know the type, but there's no
    // ESPHome platform for it yet".
    ESP_LOGW(TAG,
             "Device %s paired successfully, but this repo does not yet expose an ESPHome platform for type=%s "
             "class=%s subtype=%u.",
             context.device_id.c_str(), type_diag.c_str(), device_capability_class_name(context.device.type),
             context.device.subtype);
    ESP_LOGW(TAG,
             "No ready-to-paste YAML was generated. If you want to experiment manually, choose the most likely "
             "platform and set io_device_type: %s.",
             type_yaml.c_str());
    ESP_LOGW(TAG, "Please file a GitHub issue with this device type, subtype, model, and the pairing log so support "
                  "can be added.");
 
    context.state = pairing::PairingState::COMPLETE;
    engine_.record_debug(pairing_stage_name(context.state), 1, true);
    this->telemetry_.set_phase(context.state);
    this->finish_pairing_attempt_(PairingOutcome::PAIRED);
    return true;
  }
 
  if (!context.discovery_metadata_complete) {
    ESP_LOGW(TAG,
             "Device %s paired successfully, but the discovery response did not include type/subtype "
             "metadata, so the platform (cover/light/switch/lock) can't be determined automatically.",
             context.device_id.c_str());
    ESP_LOGI(TAG, "Add this to your YAML once you know what kind of device it is:\n%s", snippet.c_str());
    ESP_LOGW(TAG, "Please file a GitHub issue with the pairing log and device model so this discovery edge case can "
                  "be investigated.");
 
    context.state = pairing::PairingState::COMPLETE;
    engine_.record_debug(pairing_stage_name(context.state), 1, true);
    this->telemetry_.set_phase(context.state);
    this->finish_pairing_attempt_(PairingOutcome::PAIRED);
    return true;
  }
 
  ESP_LOGI(TAG, "Device %s paired successfully! Add this to your YAML:\n%s", context.device_id.c_str(),
           snippet.c_str());
 
  if (yaml_device_type_name(context.device.type) == nullptr) {
    ESP_LOGW(TAG,
             "This snippet uses the raw device type %s because the project does not yet expose a named YAML alias "
             "for %s.",
             type_yaml.c_str(), type_diag.c_str());
    ESP_LOGW(TAG, "Please file a GitHub issue with this type, subtype, device model, and the pairing log so support "
                  "can be added.");
  }
 
  context.state = pairing::PairingState::COMPLETE;
  engine_.record_debug(pairing_stage_name(context.state), 1, true);
  this->telemetry_.set_phase(context.state);
  this->finish_pairing_attempt_(PairingOutcome::PAIRED);
  return true;
}
 
void PairingEngine::finish_pairing_attempt_(PairingOutcome outcome) {
  this->telemetry_.set_outcome(outcome);
  this->engine_.set_transmit_observer(nullptr);
  this->telemetry_.log_summary();
 
  advisor::PairingAdvice advice[advisor::PAIRING_ADVICE_MAX];
  const uint8_t advice_count = advisor::analyze_pairing_telemetry(this->telemetry_, this->node_id_, advice);
  std::string advice_codes;
  for (uint8_t i = 0; i < advice_count; i++) {
    ESP_LOGW(TAG, "Pairing advisor: %s", advisor::pairing_advice_message(advice[i]).c_str());
    if (!advice_codes.empty())
      advice_codes += ',';
    advice_codes += advisor::pairing_advice_code_name(advice[i].code);
  }
  this->telemetry_.set_advice_codes(advice_codes);
}
 
void PairingEngine::record_discovery_rx_telemetry_(const IoFrame &frame, bool accepted, int16_t rssi) {
  if (accepted) {
    this->telemetry_.record_rx(frame, rssi);
  } else {
    this->telemetry_.record_rx_reject(frame, rssi);
  }
}
 
}  // namespace home_io_control
}  // namespace esphome