hub_decisions.h

Go to the documentation of this file.

#pragma once
 
/// @file hub_decisions.h
/// @brief Pure transition helpers for hub-owned exchange and pairing frame decisions.
/// @ingroup hioc_hub
///
/// This header contains inline, testable decision logic: frame classification
/// for exchange and pairing flows, plus shared timing utilities. No state, no
/// side effects — suitable for unit testing without radio hardware.
 
#include "proto_codecs.h"
#include "proto_constants.h"
#include "proto_device_model.h"
#include "proto_frame.h"
#include "proto_timing.h"
 
#include <algorithm>
#include <cstdint>
#include <cstring>
#include <string>
 
namespace esphome {
namespace home_io_control {
namespace decisions {
 
/// @brief Disposition for the first response in an authenticated exchange.
enum class ExchangeFirstResponseDisposition : uint8_t {
  IGNORE_UNRELATED,  ///< Frame doesn't match endpoints or failed parse — keep waiting.
  COMPLETE_DIRECT,   ///< Matching non-challenge frame — operation complete, no auth needed.
  REQUIRE_AUTH,      ///< Matching 0x3C challenge — device demands authentication.
};
 
/// @brief Disposition for the final response after authentication.
enum class ExchangeFinalResponseDisposition : uint8_t {
  IGNORE_UNRELATED,  ///< Frame doesn't match endpoints — ignore.
  ACCEPT,            ///< Frame matches expected response — exchange succeeds.
};
 
/// @brief Disposition during pairing discovery phase.
enum class PairingDiscoveryDisposition : uint8_t {
  NO_RESPONSE,  ///< No packets received on the channel within timeout.
  INVALID,      ///< Packets seen but none were valid discovery (0x29) frames.
  ACCEPT,       ///< Valid discovery response received.
};
 
/// @brief Disposition during pairing key-challenge phase.
enum class PairingKeyChallengeDisposition : uint8_t {
  IGNORE,  ///< Not a valid challenge (wrong cmd, length, or sender).
  ACCEPT,  ///< Valid 0x3C challenge from target device.
};
 
/// @brief Disposition for a candidate reply to a discovery-confirm request (0x2C).
enum class PairingDiscoverConfirmDisposition : uint8_t {
  IGNORE,  ///< Not from/to the expected endpoints, or a frame the step does not act on (e.g. a
           ///< repeated 0x29) — keep waiting.
  ACK,     ///< CMD_DISCOVER_CONFIRM_ACK (0x2D) from the device — it wants to proceed.
  ERROR,   ///< CMD_ERROR_RESP from the device — an explicit, named refusal.
};
 
/// @brief Disposition for a candidate reply to the key-transfer (0x32) confirm wait — the
/// slow-turnaround path's expanded classification of @ref PairingKeyChallengeDisposition's device
/// challenge to also cover a direct confirm or an explicit refusal.
enum class PairingKeyConfirmDisposition : uint8_t {
  IGNORE,     ///< Not from/to the expected endpoints — keep waiting.
  CONFIRM,    ///< CMD_KEY_CONFIRM (0x33) — the device accepted the key.
  CHALLENGE,  ///< A fresh CMD_CHALLENGE_REQ (0x3C) — the device may challenge the key transfer
              ///< before confirming it; answered via ExchangeEngine::answer_challenge().
  REFUSE,     ///< Anything else (including CMD_ERROR_RESP) — an explicit or implicit refusal;
              ///< ends the whole wait, not just the current try.
};
 
// == Passive RX filtering ==
 
/// Returns true for commands that are internal to an exchange handshake and carry
/// no useful information for a passive observer (challenge request/response).
/// These frames appear in every authenticated exchange between other controllers and
/// devices on the network, but contain only ephemeral cryptographic data.
inline bool is_exchange_internal_command(uint8_t cmd) { return cmd == CMD_CHALLENGE_REQ || cmd == CMD_CHALLENGE_RESP; }
 
// == Utility: endpoint matching ==
 
/// Check if two frames have identical src/dst node IDs.
inline bool frame_matches_nodes(const IoFrame &frame, const uint8_t expected_src[NODE_ID_SIZE],
                                const uint8_t expected_dst[NODE_ID_SIZE]) {
  return std::memcmp(frame.src, expected_src, NODE_ID_SIZE) == 0 &&
         std::memcmp(frame.dst, expected_dst, NODE_ID_SIZE) == 0;
}
 
/// Check if candidate frame endpoints are the reverse of the request (dst==request.src, src==request.dst).
inline bool frame_matches_exchange_endpoints(const IoFrame &request, const IoFrame &candidate) {
  return frame_matches_nodes(candidate, request.dst, request.src);
}
 
// == Exchange first-response classification ==
 
/// Decide how to handle the first response packet in an authenticated exchange.
///
/// Used by wait_for_first_response_() to determine whether the exchange:
/// - completes immediately (direct response),
/// - requires authentication (challenge received), or
/// - should ignore the frame and keep waiting.
///
/// @param request  Original outbound request frame.
/// @param candidate Parsed IoFrame from the device.
/// @return Disposition indicating next step.
inline ExchangeFirstResponseDisposition classify_exchange_first_response(const IoFrame &request,
                                                                         const IoFrame &candidate) {
  if (!frame_matches_exchange_endpoints(request, candidate))
    return ExchangeFirstResponseDisposition::IGNORE_UNRELATED;
  // A matching non-0x3C frame is the entire answer for direct-response exchanges such as plain
  // status reads, so the caller must not force it through the authenticated path.
  if (candidate.cmd == CMD_CHALLENGE_REQ)
    return ExchangeFirstResponseDisposition::REQUIRE_AUTH;
  return ExchangeFirstResponseDisposition::COMPLETE_DIRECT;
}
 
/// Decide if a candidate frame is an acceptable final response after authentication.
///
/// Only endpoint matching is checked here; command validity is encoded in the
/// disposition mapping by the caller.
///
/// @param request  Original outbound request frame.
/// @param candidate Parsed IoFrame from the device.
/// @return ACCEPT if endpoints match; IGNORE_UNRELATED otherwise.
inline ExchangeFinalResponseDisposition classify_exchange_final_response(const IoFrame &request,
                                                                         const IoFrame &candidate) {
  return frame_matches_exchange_endpoints(request, candidate) ? ExchangeFinalResponseDisposition::ACCEPT
                                                              : ExchangeFinalResponseDisposition::IGNORE_UNRELATED;
}
 
/// True for a CMD_EXECUTE that has the same effect sent twice as sent once. Every EXECUTE this hub
/// sends names an absolute target (a position, open/close, STOP, a tilt angle, a light level)
/// except the stored-position selector POS_FAVORITE, used by favourite and vent: on a Somfy motor
/// "My" while moving means stop, so a second copy can undo what the first one started.
/// @param request Outbound request frame.
[[nodiscard]] inline bool is_repeatable_execute(const IoFrame &request) {
  return request.cmd == CMD_EXECUTE && request.data_len > EXECUTE_MAIN_BYTE_OFFSET &&
         request.data[EXECUTE_MAIN_BYTE_OFFSET] != POS_FAVORITE;
}
 
/// Whether an authenticated-but-unanswered request may be sent again.
///
/// Every request except CMD_EXECUTE is idempotent (status polls, name reads, management actions,
/// config writes) and keeps its full retry budget when the device authenticates but never closes
/// the exchange.
///
/// CMD_EXECUTE moves something, and a missing closing reply means two different things depending
/// on the device. Some devices never close an EXECUTE exchange within the response window and
/// report through a later status update instead; for them silence is normal and a re-send only
/// repeats a command already being carried out. For a device that normally does close it, silence
/// can mean our challenge answer never arrived and the command was not carried out at all (a STOP
/// that left an awning moving). So an EXECUTE is sent again only to a device known to confirm,
/// only when repeating it is harmless (is_repeatable_execute()), and at most
/// UNCONFIRMED_EXECUTE_MAX_RESENDS times per exchange.
/// @param request                  Outbound request frame.
/// @param target_confirms_execute  The target has closed an EXECUTE exchange with a reply before
///                                 (TargetEvidence::confirms_execute).
/// @param unconfirmed_tries        Tries of this exchange that ended accepted without a closing
///                                 reply, including the one just ended (1-based).
/// @return true when the exchange should spend another try.
[[nodiscard]] inline bool retry_after_unconfirmed_accept_is_safe(const IoFrame &request, bool target_confirms_execute,
                                                                 uint8_t unconfirmed_tries) {
  if (request.cmd != CMD_EXECUTE)
    return true;
  return target_confirms_execute && is_repeatable_execute(request) &&
         unconfirmed_tries <= UNCONFIRMED_EXECUTE_MAX_RESENDS;
}
 
// == Pairing discovery & key-challenge classification ==
 
/// Decide if a frame is a valid discovery response (0x29) during pairing.
///
/// Only the destination is checked, not the source: the discovery request goes out to a
/// shared broadcast address, so a response arriving during the same window may be a device
/// answering a *different* controller's concurrent discovery rather than ours — real hardware
/// addresses its response back to the requesting controller's own node ID, so checking that is
/// both possible and sufficient to reject it. The source can't be checked here — the device's
/// node ID is exactly what discovery exists to learn, so there is nothing yet to compare it to.
///
/// @param candidate      Parsed IoFrame.
/// @param controller_id  Node ID of this controller (expected destination).
/// @return ACCEPT if the command is CMD_DISCOVER_RESP and addressed to this controller; INVALID otherwise.
inline PairingDiscoveryDisposition classify_pairing_discovery_response(const IoFrame &candidate,
                                                                       const uint8_t controller_id[NODE_ID_SIZE]) {
  return candidate.cmd == CMD_DISCOVER_RESP && std::memcmp(candidate.dst, controller_id, NODE_ID_SIZE) == 0
             ? PairingDiscoveryDisposition::ACCEPT
             : PairingDiscoveryDisposition::INVALID;
}
 
/// Decide if a frame is a valid key-challenge (0x3C) during pairing key exchange.
///
/// The challenge must:
///   - be CMD_CHALLENGE_REQ,
///   - have data_len == HMAC_SIZE (6),
///   - originate from the discovered device node ID,
///   - be addressed to this controller's node ID.
///
/// @param candidate      Parsed IoFrame.
/// @param device_id      Node ID of the device being paired (expected sender).
/// @param controller_id  Node ID of this controller (expected destination).
/// @return ACCEPT if all criteria met; IGNORE otherwise.
inline PairingKeyChallengeDisposition classify_pairing_key_challenge(const IoFrame &candidate,
                                                                     const uint8_t device_id[NODE_ID_SIZE],
                                                                     const uint8_t controller_id[NODE_ID_SIZE]) {
  // Pairing reuses the normal 0x3C primitive, but here the challenge is only valid when it comes
  // from the device we just discovered and targets this controller. That keeps foreign traffic from
  // contaminating key exchange on a busy channel.
  return candidate.cmd == CMD_CHALLENGE_REQ && candidate.data_len == HMAC_SIZE &&
                 frame_matches_nodes(candidate, device_id, controller_id)
             ? PairingKeyChallengeDisposition::ACCEPT
             : PairingKeyChallengeDisposition::IGNORE;
}
 
/// Decide how to handle a candidate reply to a discovery-confirm request (0x2C) during pairing.
///
/// A non-matching or unrecognised frame is IGNORE, keeping the listen open rather than ending it:
/// the discover-confirm step never fails a pairing attempt (see run_discover_confirm_step_()'s
/// doc) — this classification only decides whether to keep listening or stop early.
///
/// @param candidate      Parsed IoFrame.
/// @param device_id      Node ID of the device being paired (expected sender).
/// @param controller_id  Node ID of this controller (expected destination).
/// @return ACK for a matching 0x2D, ERROR for a matching CMD_ERROR_RESP, IGNORE otherwise.
inline PairingDiscoverConfirmDisposition classify_pairing_discover_confirm_reply(
    const IoFrame &candidate, const uint8_t device_id[NODE_ID_SIZE], const uint8_t controller_id[NODE_ID_SIZE]) {
  if (!frame_matches_nodes(candidate, device_id, controller_id))
    return PairingDiscoverConfirmDisposition::IGNORE;
  if (candidate.cmd == CMD_DISCOVER_CONFIRM_ACK)
    return PairingDiscoverConfirmDisposition::ACK;
  if (candidate.cmd == CMD_ERROR_RESP)
    return PairingDiscoverConfirmDisposition::ERROR;
  // E.g. a repeated CMD_DISCOVER_RESP (0x29) from a device that missed our 0x2C and is still
  // announcing itself — not an answer to this step, but not a foreign frame either.
  return PairingDiscoverConfirmDisposition::IGNORE;
}
 
/// Decide how to handle a candidate reply to the key-transfer (0x32) confirm wait
/// (wait_for_key_confirm_(), slow-turnaround chips only).
///
/// @param request   The outbound CMD_KEY_TRANSFER (0x32) this reply answers.
/// @param candidate Parsed IoFrame from the device.
/// @return CONFIRM/CHALLENGE/REFUSE for a matching frame of that shape; IGNORE for a frame from
///         the wrong endpoints.
inline PairingKeyConfirmDisposition classify_pairing_key_confirm_reply(const IoFrame &request,
                                                                       const IoFrame &candidate) {
  if (!frame_matches_exchange_endpoints(request, candidate))
    return PairingKeyConfirmDisposition::IGNORE;
  if (candidate.cmd == CMD_KEY_CONFIRM)
    return PairingKeyConfirmDisposition::CONFIRM;
  if (classify_pairing_key_challenge(candidate, request.dst, request.src) == PairingKeyChallengeDisposition::ACCEPT)
    return PairingKeyConfirmDisposition::CHALLENGE;
  return PairingKeyConfirmDisposition::REFUSE;
}
 
/// @brief Whether discover-confirm try `try_index` (1-based) should rotate channels rather than
/// hold the request channel.
///
/// Tries 1 and 3 hold: a 0x2D is a unicast reply to a unicast 0x2C, and every other unicast
/// pairing wait in this project holds the request channel on that same expectation (see
/// listen_for_key_confirm_()'s own reasoning), and every 0x2D a Somfy Izymo dimmer sent came back on
/// the request channel. But the one real VELUX-system sample on record (from a hopping monitor, a
/// weak source) logged a 0x2D on a *different* channel than its own 0x2C, so the middle try hedges
/// by rotating instead, until a VELUX device's reply channel is measured.
/// See ADR 0039 for why this is not simply one fixed policy for every try, unlike every other
/// listen in this project (ADR 0028).
/// @param try_index 1-based try number (1..PAIRING_DISCOVER_CONFIRM_TRIES).
/// @return true if this try should use ListenPolicy::ROTATE_ALL_CHANNELS; false for
///         ListenPolicy::HOLD_REQUEST_CHANNEL.
[[nodiscard]] inline bool discover_confirm_try_rotates(uint8_t try_index) { return try_index == 2; }
 
// == One-way (1W) remote frame handling ==
 
/// @brief Key fields of the last processed 1W frame, used to collapse a remote's repeat burst.
///
/// 1W remotes repeat each command 4× at ~40ms intervals for reliability, and a held button keeps
/// resending, so one logical press arrives as many identical frames. The key deliberately includes
/// the decoded intent bytes and not just the command byte: a move and a stop are *both*
/// CMD_EXECUTE and differ only in `main0`, so a command-only key silently discards a stop that
/// follows a move within the window — losing the sender event, the optimistic-target clear, and
/// the immediate poll that a stop is supposed to trigger.
///
/// For a frame with no decoded intent the destination is part of the key as well. A VELUX KLI's
/// Gear press sends its `0x2E` to several device classes a few hundred ms apart, and the classes it
/// names are the ones a new controller has to enroll on; keying on src+cmd alone would log only the
/// first of them.
/// Intent-bearing frames keep ignoring the destination: they fire sender events and optimistic
/// state, where one press must stay one press.
struct OneWayDedupState {
  std::string src_id;           ///< Source node ID of the last processed frame; empty before the first.
  uint8_t cmd{0};               ///< Command byte.
  bool has_intent{false};       ///< Whether main0/main1 were decoded (execute / activate-mode only).
  uint8_t main0{0};             ///< First main byte — what distinguishes a move from a stop.
  uint8_t main1{0};             ///< Second main byte.
  uint32_t timestamp{0};        ///< millis() when the frame was processed.
  uint8_t dst[NODE_ID_SIZE]{};  ///< Destination address; compared only when `has_intent` is false.
};
 
/// Decide whether an incoming 1W frame repeats the previous one inside the burst window.
///
/// @param last     State recorded for the previously processed 1W frame.
/// @param incoming Candidate frame's key fields, with `timestamp` set to now.
/// @param window_ms Burst-suppression window.
/// @return true if the frame should be dropped as a repeat of `last`.
inline bool is_duplicate_1w_frame(const OneWayDedupState &last, const OneWayDedupState &incoming, uint32_t window_ms) {
  // `last.src_id` is empty until the first 1W frame is processed, so a real frame never matches it.
  if (last.src_id != incoming.src_id || last.cmd != incoming.cmd || last.has_intent != incoming.has_intent)
    return false;
  if (incoming.has_intent && (last.main0 != incoming.main0 || last.main1 != incoming.main1))
    return false;
  if (!incoming.has_intent && std::memcmp(last.dst, incoming.dst, NODE_ID_SIZE) != 0)
    return false;
  // Unsigned arithmetic makes this correct across the millis() wrap.
  return (incoming.timestamp - last.timestamp) < window_ms;
}
 
/// Decide whether to hold back a queued background poll because a 1W remote is still transmitting.
///
/// The radio is half-duplex and an authenticated exchange blocks for 1–3 s, during which no frame
/// can be received at all. A press on a linked remote schedules a status poll, so without this gate
/// the hub's own poll can start on top of the burst that triggered it and go deaf to the rest of it.
///
/// Only background polls are deferred. A user command must never wait on a remote the user may not
/// even own — 1W broadcasts carry no ownership marker, so the activity could be a neighbour's.
///
/// The hold re-arms on every 1W frame received while it is already active, so a real burst from one
/// remote (~160 ms, well under `quiet_ms`) never gets cut short mid-transmission. Left unchecked
/// that re-arming has no cap: sustained sub-`quiet_ms` 1W traffic from any source — including a
/// neighbour's, since these broadcasts carry no ownership marker — would hold background polls back
/// indefinitely. @p max_defer_ms bounds that: once that much time has passed since the burst
/// *started* (not the most recent frame), the poll is let through regardless of ongoing traffic.
/// The gate only ever delays a poll, never drops one — it stays queued and fires as soon as it is
/// no longer deferred.
///
/// @param next_op_is_background True if the queue front is a background poll (OperationQueue::is_background_op()).
/// @param first_1w_activity_ms  millis() of the first frame in the current 1W burst; 0 if none seen
///                               since boot.
/// @param last_1w_activity_ms   millis() of the most recent 1W frame; 0 if none seen since boot.
/// @param now                   Current millis().
/// @param quiet_ms              How long after 1W activity to hold background polls back.
/// @param max_defer_ms          Hard cap on total defer time, measured from first_1w_activity_ms.
/// @return true if the caller should skip dispatching this loop iteration.
inline bool defer_background_poll_for_1w_activity(bool next_op_is_background, uint32_t first_1w_activity_ms,
                                                  uint32_t last_1w_activity_ms, uint32_t now, uint32_t quiet_ms,
                                                  uint32_t max_defer_ms) {
  if (!next_op_is_background || last_1w_activity_ms == 0)
    return false;
  if (now - first_1w_activity_ms >= max_defer_ms)
    return false;
  return (now - last_1w_activity_ms) < quiet_ms;
}
 
/// @brief Transmit-attempt budget for a scheduler-owned status poll, by backoff-ladder position.
///
/// See SCHEDULED_POLL_MAX_TRIES and SCHEDULED_POLL_RETRY_GRACE_FIRST_FAILURE (proto_timing.h) for
/// why the full budget belongs to a middle band of the ladder rather than to its start or its tail.
///
/// The two counters are mutually exclusive by construction — StatusPollPolicy::on_exchange_failed()
/// zeroes one while incrementing the other — so an auth-shaped streak reads status_poll_failures
/// as 0 and would otherwise fall into the band's own "fresh window" case. It is rejected first,
/// deliberately, so the predicate stays correct even if that exclusivity is ever relaxed.
///
/// The settle poll after an accepted STOP (@p settles_a_stop) gets the full budget whatever the
/// counters say: see STOP_SETTLE_POLL_TRIES (proto_timing.h).
///
/// @param status_poll_failures Consecutive silent failures already recorded for this device.
/// @param auth_poll_failures   Consecutive challenge-seen failures already recorded.
/// @param settles_a_stop       True for the first poll after an accepted STOP
///                             (StatusPollPolicy::take_stop_settle()).
/// @return EXCHANGE_RETRY_COUNT inside the band or after a STOP, SCHEDULED_POLL_MAX_TRIES everywhere else.
inline uint8_t scheduled_poll_max_tries(uint8_t status_poll_failures, uint8_t auth_poll_failures,
                                        bool settles_a_stop = false) {
  if (settles_a_stop)
    return STOP_SETTLE_POLL_TRIES;
  if (auth_poll_failures != 0)
    return SCHEDULED_POLL_MAX_TRIES;
  if (status_poll_failures < SCHEDULED_POLL_RETRY_GRACE_FIRST_FAILURE ||
      status_poll_failures > SCHEDULED_POLL_RETRY_GRACE_LAST_FAILURE)
    return SCHEDULED_POLL_MAX_TRIES;
  return EXCHANGE_RETRY_COUNT;
}
 
// == Low-power wake belief ==
 
/// @brief Whether a low-power receiver is believed to be travelling right now, judged from what this
/// hub has seen of it. Orders the tries of a directed exchange: a moving receiver hears the short
/// start preamble and ignores the long wake-up one, a resting one needs the long one.
///
/// Having merely heard from the device recently is deliberately not a reason to lead short: a
/// resting VELUX SSL solar roller shutter ignored the short preamble on every try in field logs,
/// including tries sent 34 ms after it had answered (ADR 0040, amendment).
enum class WakeBelief : uint8_t {
  ASLEEP,  ///< Not known to be moving — lead with the wake-up preamble.
  AWAKE,   ///< Moving, or about to be stopped — the short preamble is the one it hears.
};
 
/// @brief What the hub knows about the device an exchange is addressed to, as the exchange engine
/// sees it. The engine has no device registry of its own; the hub hands this over through
/// ExchangeEngine::set_target_evidence_provider(), and every per-target decision the engine makes
/// reads from it: wake_belief() and retry_after_unconfirmed_accept_is_safe(). Timestamps are `millis()` values, 0 =
/// never.
struct TargetEvidence {
  uint32_t last_moving_evidence_ms;  ///< Last sign the receiver is travelling (see note_moving_evidence(),
                                     ///< clear_moving_evidence()).
  uint32_t last_seen_ms;             ///< Last frame received from the receiver, any command. Only logged
                                     ///< (`age_ms=`); it does not feed the belief.
  bool confirms_execute;             ///< The device has closed a CMD_EXECUTE exchange with a reply before.
};
 
/// Build the exchange engine's view of a device record.
/// @param dev Device record to read.
[[nodiscard]] inline TargetEvidence target_evidence(const IoDevice &dev) {
  return {dev.last_moving_evidence_ms, dev.last_seen_ms, dev.confirms_execute};
}
 
/// True for a CMD_EXECUTE whose main byte is POS_STOP. A STOP is only ever sent to a receiver that
/// is (believed) moving, so it is treated as awake whatever the stamps say.
/// @param request Outbound request frame.
[[nodiscard]] inline bool is_stop_request(const IoFrame &request) {
  return request.cmd == CMD_EXECUTE && request.data_len > EXECUTE_MAIN_BYTE_OFFSET &&
         request.data[EXECUTE_MAIN_BYTE_OFFSET] == POS_STOP;
}
 
/// Judge whether a low-power receiver is travelling. `AWAKE` for a STOP request or while moving
/// evidence is younger than LOW_POWER_MAX_TRAVEL_MS; `ASLEEP` otherwise. A zero stamp means never and
/// is never recent. Ages use unsigned subtraction, so `millis()` wrap-around is safe.
/// @param evidence Stamps for the target device.
/// @param now      Current millis().
/// @param is_stop  True when the request being sent is a STOP (see is_stop_request()).
[[nodiscard]] inline WakeBelief wake_belief(const TargetEvidence &evidence, uint32_t now, bool is_stop) {
  const uint32_t moving = evidence.last_moving_evidence_ms;
  if (is_stop || (moving != 0 && (now - moving) < LOW_POWER_MAX_TRAVEL_MS))
    return WakeBelief::AWAKE;
  return WakeBelief::ASLEEP;
}
 
/// Start-preamble length for one try of a directed exchange to a low-power receiver. The plans
/// (short = `short_preamble`, wake = `wake_preamble`): AWAKE short/wake/wake, ASLEEP wake on every
/// try. A moving receiver answers the first short try; when it does not, it has most likely come to
/// rest, where only the wake-up preamble reaches it, so every later try uses that one. A single-try
/// exchange (most scheduler-owned status polls) sends only try 1's preamble; its backoff ladder, and
/// the evidence a silent AWAKE exchange spends (ExchangeEngine::set_wake_evidence_spent_handler()),
/// cover a wrong belief there.
/// @param belief         See wake_belief().
/// @param try_index      1-based try number, clamped to [1, EXCHANGE_RETRY_COUNT].
/// @param short_preamble Preamble for a receiver known to be moving (`normal_start_preamble`).
/// @param wake_preamble  Wake-up preamble for a resting receiver (`low_power_wake_preamble`).
[[nodiscard]] inline uint16_t low_power_try_preamble(WakeBelief belief, uint8_t try_index, uint16_t short_preamble,
                                                     uint16_t wake_preamble) {
  const uint8_t try_1based = std::max<uint8_t>(1, std::min<uint8_t>(try_index, EXCHANGE_RETRY_COUNT));
  if (belief == WakeBelief::AWAKE && try_1based == 1)
    return short_preamble;
  return wake_preamble;
}
 
/// Lowercase name of a belief for log lines.
[[nodiscard]] inline const char *wake_belief_name(WakeBelief belief) {
  switch (belief) {
    case WakeBelief::AWAKE:
      return "awake";
    case WakeBelief::ASLEEP:
    default:
      return "asleep";
  }
}
 
/// True if a frame's shape matches a 1W remote's pairing gesture (issue #27/#65): CTRL0 1W bit
/// set, addressed to the 1W broadcast address (0x00003F), with one of the three command bytes
/// observed in the field capture — 0x20 (WRITE_PRIVATE), 0x39 (1W remove), or 0x2E (alternate
/// discovery, 1W-flagged). Shared between PairingAdvisor (classifying recorded telemetry events,
/// pairing_advisor.cpp) and the hub's normal passive RX path (hub_status.cpp), which remembers a
/// recent sighting so a PROG press completed just before "Discover & Pair" is pressed isn't
/// invisible to the advisor purely because of when the discovery telemetry window happened to
/// open — see PairingTelemetry::record_recent_one_way_sighting().
///
/// @param oneway CTRL0 1W-protocol bit.
/// @param dst    Frame destination node ID.
/// @param cmd    Frame command byte.
inline bool is_one_way_pairing_gesture(bool oneway, const uint8_t dst[NODE_ID_SIZE], uint8_t cmd) {
  if (!oneway)
    return false;
  if (std::memcmp(dst, BROADCAST_DISCOVER_ALT, NODE_ID_SIZE) != 0)
    return false;
  return cmd == CMD_WRITE_PRIVATE || cmd == CMD_ONEWAY_REMOVE || cmd == CMD_DISCOVER_ALT_REQ;
}
 
/// Whether a 1W frame arriving at `now` starts a new burst rather than extending the current one
/// — true if no frame has been seen yet, or the gap since the last one reached `quiet_ms` (the
/// previous burst already released any deferred poll). Callers use this to decide whether to
/// reset a burst's start-time tracking; see defer_background_poll_for_1w_activity() for why the
/// burst start (not just the latest frame) needs its own timestamp.
///
/// @param last_1w_activity_ms millis() of the most recent 1W frame before this one; 0 if none
///                             seen since boot.
/// @param now                 Current millis() (this frame's arrival time).
/// @param quiet_ms            Gap after which a previous burst is considered over.
[[nodiscard]] inline bool oneway_burst_started_fresh(uint32_t last_1w_activity_ms, uint32_t now, uint32_t quiet_ms) {
  return last_1w_activity_ms == 0 || (now - last_1w_activity_ms) >= quiet_ms;
}
 
/// Namespace tag for `remote_poll_timer_id()` below: the node address occupies the low 24 bits,
/// and this is OR-ed in above them. Each numeric-id timer caller has its own tag (see
/// HEATING_POLL_TIMER_ID_TAG), so two timers for the same device never replace one another and an id
/// says which caller it belongs to.
constexpr uint32_t REMOTE_POLL_TIMER_ID_TAG = 0x01000000;
 
/// Namespace tag for `heating_poll_timer_id()`: the same node-address scheme under its own bit, so
/// a heater's regular-cadence timer and a remote-activity poll timer for the same device never replace
/// one another.
constexpr uint32_t HEATING_POLL_TIMER_ID_TAG = 0x02000000;
 
/// @brief Numeric `set_timeout()` id for a device's remote-activity poll timer (hub_status.cpp's
/// `schedule_status_poll_()`).
///
/// Keyed by the device's node address rather than a name, because `Component::set_timeout(const
/// char *name, ...)` stores the caller's *pointer*, not a copy of the string (its header documents
/// this: static lifetime required, use the numeric-id overload for a dynamically-built name) — see
/// `schedule_status_poll_()`'s own comment for why a per-device name can't satisfy that here. A
/// node address is unique per device, so this id is collision-free by construction.
///
/// @param node_id 3-byte device node address.
/// @return Numeric timer id, unique per device.
inline uint32_t remote_poll_timer_id(const uint8_t node_id[NODE_ID_SIZE]) {
  return REMOTE_POLL_TIMER_ID_TAG | (static_cast<uint32_t>(node_id[0]) << (2 * BITS_PER_BYTE)) |
         (static_cast<uint32_t>(node_id[1]) << BITS_PER_BYTE) | static_cast<uint32_t>(node_id[2]);
}
 
/// @brief Numeric `set_timeout()` id for a heater's regular-cadence poll timer
/// (`IOHomeControlComponent::schedule_heating_poll_()`). Same keying as remote_poll_timer_id(), in
/// the HEATING_POLL_TIMER_ID_TAG namespace, so a poll that a linked remote triggers cannot cancel it.
/// @param node_id 3-byte device node address.
/// @return Numeric timer id, unique per device and distinct from remote_poll_timer_id().
inline uint32_t heating_poll_timer_id(const uint8_t node_id[NODE_ID_SIZE]) {
  return HEATING_POLL_TIMER_ID_TAG | (remote_poll_timer_id(node_id) & ~REMOTE_POLL_TIMER_ID_TAG);
}
 
// === Pairing: the device behind a pairing node ===
 
/// @brief Does a pairing node that answered discovery this way control a heater at the next address?
///
/// An Atlantic radiator in its display's pairing mode answers discovery as a remote controller (node
/// type 1023), hands over its key, and is controlled at the next node address up: three AGILIA IO
/// radiators follow this (issue #165,
/// tests/corpus/captures/pairing/atlantic_agilia_pairing_key_pull_heater_rollcall.yaml). The heater
/// answers a roll-call only now and then, so the pairing asks that address directly first.
/// @param type Node type the pairing node answered discovery with.
/// @param manufacturer Manufacturer byte of that discovery reply (0 when the reply carried none).
/// @return true for an Atlantic remote-controller node.
inline bool pairing_node_has_heater_at_next_address(DeviceType type, uint8_t manufacturer) {
  return type == DeviceType::REMOTE_CONTROLLER && manufacturer == MANUFACTURER_ATLANTIC_GROUP;
}
 
/// @brief The node address one above `node`, as a 24-bit number (`B6BDFB` -> `B6BDFC`).
///
/// A carry into the higher bytes (`xxxxFF`) is computed as plain arithmetic; no radiator with such an
/// address has been seen, so whether the device counts the same way is unconfirmed.
/// @param node Address to count from.
/// @param[out] next The next address; untouched when `false` is returned.
/// @return false for `FFFFFF`, which has no next address.
inline bool next_node_id(const uint8_t node[NODE_ID_SIZE], uint8_t next[NODE_ID_SIZE]) {
  uint8_t up[NODE_ID_SIZE];
  memcpy(up, node, NODE_ID_SIZE);
  // Count up from the last byte; a byte that wraps to 0 carries into the one before it.
  for (size_t i = NODE_ID_SIZE; i-- > 0;) {
    if (++up[i] != 0) {
      memcpy(next, up, NODE_ID_SIZE);
      return true;
    }
  }
  return false;  // FFFFFF wrapped to 000000.
}
 
// === Rain limitation ===
 
/// @brief Which evidence path labelled a device as limited by rain.
enum class RainLimitationRule : uint8_t {
  NONE = 0,         ///< No evidence of a rain limitation.
  RAIN_ORIGINATOR,  ///< The device names the rain sensor as the originator of its last command.
  CLAMPED_COMMAND,  ///< A position command was accepted but the stopped device ended elsewhere, while
                    ///< rain protection was recently active.
};
 
/// @brief What one decoded status reply said, plus what the hub had predicted.
struct RainLimitationInput {
  bool has_last_command;      ///< The device record holds a well-formed last-command record.
  uint8_t originator;         ///< Its Command Originator (ORIGINATOR_* in proto_constants.h).
  bool rain_evidence_recent;  ///< A rain originator was seen from this device within RAIN_EVIDENCE_HOLD_MS.
  float predicted_target;     ///< Hub's prediction before this reply (UNKNOWN_POSITION when none stood).
  float observed_target;      ///< dev.target after decoding this reply.
  bool stopped;               ///< The device reported itself stopped.
};
 
/// @brief Decide which rain-limitation evidence, if any, a status reply provides.
///
/// A rain limitation is an *inference from observations*, never a prediction (ADR 0030 keeps
/// predictions apart): windows clamp an `open` to their ventilation position without sending
/// CMD_ERROR_RESP / RESULT_LIMITATION_BY_RAIN, so the only evidence is what the device reports
/// in its ordinary status replies. Rule order matters: the originator rule is the direct
/// evidence and wins; the clamp rule only applies while earlier rain evidence is still fresh.
/// @param in What the reply said and what had been predicted.
/// @return The rule that fired, or RainLimitationRule::NONE.
[[nodiscard]] inline RainLimitationRule rain_limitation_rule(const RainLimitationInput &in) {
  if (in.has_last_command && in.originator == ORIGINATOR_RAIN_SENSOR)
    return RainLimitationRule::RAIN_ORIGINATOR;
  if (in.rain_evidence_recent && in.stopped && in.predicted_target != UNKNOWN_POSITION &&
      in.observed_target != UNKNOWN_POSITION && !has_reached_target_position(in.predicted_target, in.observed_target))
    return RainLimitationRule::CLAMPED_COMMAND;
  return RainLimitationRule::NONE;
}
 
/// @brief True when rain_limitation_rule() finds evidence of a rain limitation.
[[nodiscard]] inline bool is_rain_limited(const RainLimitationInput &in) {
  return rain_limitation_rule(in) != RainLimitationRule::NONE;
}
 
/// @brief Name of a rain-limitation rule for log lines.
[[nodiscard]] inline const char *rain_limitation_rule_name(RainLimitationRule rule) {
  switch (rule) {
    case RainLimitationRule::RAIN_ORIGINATOR:
      return "rain_originator";
    case RainLimitationRule::CLAMPED_COMMAND:
      return "clamped_command";
    case RainLimitationRule::NONE:
      break;
  }
  return "none";
}
 
// === Rain sensor from the minimum limitation ===
 
/// A window with a wired rain sensor limits its own opening while it rains. Home Assistant's VELUX
/// integration reads that limit and calls it rain from this minimum limit upward (observed values
/// 89, 91, 93 and 100 %).
static constexpr uint8_t RAIN_MINIMUM_LIMIT_PERCENT = 89;
/// Percent value of a fully limited position, the divisor of the raw position coding.
static constexpr uint16_t POSITION_FULL_PERCENT = 100;
/// Raw position units per percent (512).
static constexpr uint16_t POSITION_RAW_PER_PERCENT = STATUS_POS_MAX / POSITION_FULL_PERCENT;
static_assert(POSITION_RAW_PER_PERCENT * POSITION_FULL_PERCENT == STATUS_POS_MAX,
              "the raw rain threshold must be an exact multiple of one percent");
/// RAIN_MINIMUM_LIMIT_PERCENT in the raw position coding (0xB200).
static constexpr uint16_t RAIN_MINIMUM_LIMIT_RAW = POSITION_RAW_PER_PERCENT * RAIN_MINIMUM_LIMIT_PERCENT;
 
/// @brief Rain state from the raw value of a minimum-limitation reply.
/// @param value_raw Big-endian raw value in position coding (LimitationStatus::value_raw).
/// @return UNKNOWN for a value above STATUS_POS_MAX (not a percentage), RAIN at or above
///         RAIN_MINIMUM_LIMIT_RAW, DRY below it.
[[nodiscard]] inline RainSensorState rain_state_from_minimum_limit(uint16_t value_raw) {
  if (value_raw > STATUS_POS_MAX)
    return RainSensorState::UNKNOWN;
  return value_raw >= RAIN_MINIMUM_LIMIT_RAW ? RainSensorState::RAIN : RainSensorState::DRY;
}
 
/// @brief Rain state from a decoded limitation reply: the one place that knows which reply fields
/// decide. Only the main parameter's value counts; originator and remaining time do not.
/// @param status A decoded CMD_LIMITATION_STATUS_RESP payload.
/// @return UNKNOWN unless the reply is for the main parameter, else rain_state_from_minimum_limit().
[[nodiscard]] inline RainSensorState rain_state_from_limitation_reply(const LimitationStatus &status) {
  if (status.parameter_id != LIMITATION_PARAM_MP)
    return RainSensorState::UNKNOWN;
  return rain_state_from_minimum_limit(status.value_raw);
}
 
}  // namespace decisions
}  // namespace home_io_control
}  // namespace esphome