pairing_advisor.h

Go to the documentation of this file.

#pragma once
 
/// @file pairing_advisor.h
/// @brief Read-only advisor that turns PairingTelemetry into actionable diagnostics.
/// @ingroup hioc_hub
///
/// PairingAdvisor is a pure, stateless consumer of a completed PairingTelemetry attempt: it
/// never touches the radio or the pairing state machine, only inspects the events already
/// recorded. It exists to convert the most common field failures (a 1W remote's PROG gesture
/// overheard while no device answers, issues #27/#121; a busy channel; a foreign controller
/// mid-pairing; dead RF)
/// from a hex-dump exercise into a self-explaining WARN line.
 
#include "pairing_telemetry.h"
#include "proto_frame.h"
 
#include <cstdint>
#include <string>
 
namespace esphome {
namespace home_io_control {
namespace advisor {
 
/// @brief Actionable diagnosis derived from a completed pairing attempt's telemetry.
enum class PairingAdviceCode : uint8_t {
  NONE,                        ///< Nothing actionable to report.
  ONE_WAY_PAIRING_TRAFFIC,     ///< A 1W remote's PROG gesture was overheard. Proves a gesture happened,
                               ///< not the device's state: the same frames also precede successful
                               ///< pairings (issue #19).
  CHANNEL_BUSY_LBT_DELAYED,    ///< LBT retries were consumed while a source kept repeating; the
                               ///< reported subject_node is a best-effort correlation (LBT's
                               ///< carrier-sense doesn't parse frames, so the actual jammer may
                               ///< not be among the parsed events attributed here).
  FOREIGN_CONTROLLER_PAIRING,  ///< A discovery response was seen addressed to another controller.
  RF_SILENT,                   ///< Nothing at all was heard during the whole window.
  KEY_PUSH_NOT_ACCEPTED,       ///< The device does not take a pushed key: it answered 0x32 with
                               ///< RESULT_COMMAND_UNKNOWN, or it answered discovery as a remote
                               ///< controller and the push failed. Suggests `pairing_key_transfer: pull` or `auto`.
  KEY_TRANSFER_REFUSED,        ///< The device answered the key transfer with any other CMD_ERROR_RESP.
  KEY_PULL_NOT_OFFERED,        ///< `pairing_key_transfer: pull` was refused with CMD_ERROR_RESP: the
                               ///< device does not hand out its key. Suggests forcing `pairing_key_transfer: push`.
  KEY_PULL_UNPROVEN,           ///< The device answered the pull with a key, but sent no 0x3D that
                               ///< verifies under it; the key is not printed.
  PULLED_KEY_RECEIVED,         ///< The pull got a different key that the device proved, and a roll-call
                               ///< under it found no registrable device (outcome KEY_RECEIVED). Says to
                               ///< put the key into the controlling entity's `system_key:`.
  HUB_KEY_NO_RESPONDER,        ///< The pull returned the hub's own key from a node no platform drives, and no
                               ///< device that holds it answered (outcome HUB_KEY_RETURNED). Says to run Scan
                               ///< Paired Devices.
};
 
/// @brief One piece of advice, with the node/RSSI it pertains to (if any).
struct PairingAdvice {
  PairingAdviceCode code{PairingAdviceCode::NONE};
  uint8_t subject_node[NODE_ID_SIZE]{};  ///< Node the advice is about; zero if not applicable.
  int16_t rssi{0};                       ///< RSSI associated with the observation; zero if not applicable.
  bool has_result_code{false};           ///< True when result_code carries the device's CMD_ERROR_RESP byte.
  uint8_t result_code{0};                ///< CMD_ERROR_RESP byte the advice is about.
  bool answered_as_controller{false};    ///< True when the device answered discovery as a remote controller.
};
 
/// @brief Maximum number of advice entries a single attempt can produce (each advice source adds at most one).
static constexpr uint8_t PAIRING_ADVICE_MAX = 6;
 
/// @brief Inspect a completed pairing attempt's telemetry and produce actionable advice.
///
/// Read-only: never mutates telemetry, never touches the radio or pairing state machine.
/// @param telemetry    Completed (or in-progress) telemetry for one pairing attempt.
/// @param own_node_id  This controller's node ID, used to detect discovery responses addressed
///                     to a different controller.
/// @param out          Output buffer, must hold at least PAIRING_ADVICE_MAX entries.
/// @return Number of advice entries written to `out` (0 if nothing actionable was found).
uint8_t analyze_pairing_telemetry(const PairingTelemetry &telemetry, const uint8_t own_node_id[NODE_ID_SIZE],
                                  PairingAdvice out[PAIRING_ADVICE_MAX]);
 
/// @return Short, stable code string for the `;advice=` result-sensor field (e.g. "1w_traffic").
const char *pairing_advice_code_name(PairingAdviceCode code);
 
/// @return The full actionable, human-readable WARN message for one piece of advice.
std::string pairing_advice_message(const PairingAdvice &advice);
 
}  // namespace advisor
}  // namespace home_io_control
}  // namespace esphome