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 "tuning_config.h"
 
#include <algorithm>
#include <array>
#include <cstdint>
#include <cstring>
#include <optional>
#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; }
 
/// Returns true for a frame that reports a device event rather than a status: a CMD_SET_CONFIG1_RESP,
/// or a well-formed CMD_STATUS_UPDATE whose event is not EVENT_STATUS_CHANGE (a subscribed sensor
/// report, see decode_status_update_event()). Such a frame is recorded on the "Last Device Event"
/// sensor and never decoded as a position, whether it arrives on its own or inside an exchange.
inline bool is_device_event_report(const IoFrame &frame) {
  if (frame.cmd == CMD_SET_CONFIG1_RESP)
    return true;
  StatusUpdateEvent event;
  return decode_status_update_event(frame, event) && event.event_id != EVENT_STATUS_CHANGE;
}
 
/// Returns true when @p response is the answer to the subscription @p request: the request is a
/// CMD_SUBSCRIBE_EVENT with the subscribe action, and the response a well-formed CMD_STATUS_UPDATE
/// carrying the same event, from the device the request went to. A device answers a subscription
/// with the event's current value (tests/corpus/captures/probe/somfy_rs100_probe_subscribe_event_*),
/// so inside the exchange the hub started for that request this event report is the reply; every
/// other event report is still recorded and never taken as a reply (is_device_event_report()).
inline bool is_subscription_answer(const IoFrame &request, const IoFrame &response) {
  if (request.cmd != CMD_SUBSCRIBE_EVENT || request.data_len != SUBSCRIBE_EVENT_DATA_SIZE ||
      request.data[0] != EVENT_SUBSCRIPTION_SUBSCRIBE)
    return false;
  if (memcmp(response.src, request.dst, NODE_ID_SIZE) != 0)
    return false;
  StatusUpdateEvent event;
  if (!decode_status_update_event(response, event))
    return false;
  const auto requested = static_cast<uint16_t>((request.data[1] << BITS_PER_BYTE) | request.data[2]);
  return event.event_id == requested;
}
 
/// Returns true for the commands that write to a device: an execute, a mode activation or a private
/// register write. A heard write changes the device's state, so this hub's view of it is stale; a heard
/// read (any other command) changes nothing on the device. Deliberately a short list of writes rather
/// than a list of reads, so an unknown command counts as a read.
inline bool overheard_command_writes(uint8_t cmd) {
  return cmd == CMD_EXECUTE || cmd == CMD_ACTIVATE_MODE || cmd == CMD_WRITE_PRIVATE;
}
 
// == 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, vent, partial and pedestrian
/// (every NAMED_POSITIONS entry): 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 and CMD_SUBSCRIBE_EVENT 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.
///
/// CMD_SUBSCRIBE_EVENT stores a subscription in the device, and the device answers it with the
/// event's current value (is_subscription_answer()). A try the device authenticated has stored the
/// subscription, but its answer may still have been lost, so it is sent once more
/// (UNCONFIRMED_SUBSCRIBE_MAX_RESENDS), never more: the device has accepted repeated subscriptions
/// (issue #156), and a reading is what the request is for.
///
/// @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_SUBSCRIBE_EVENT)
    return unconfirmed_tries <= UNCONFIRMED_SUBSCRIBE_MAX_RESENDS;
  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 True when a scheduler-owned status poll sits in the middle band of the backoff ladder.
///
/// See SCHEDULED_POLL_RETRY_GRACE_FIRST_FAILURE (proto_timing.h) for why the band is where a poll
/// is worth more than one attempt: the slot that lands just after a manoeuvre ends, rather than the
/// start or the tail of the ladder.
///
/// 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.
///
/// @param status_poll_failures Consecutive silent failures already recorded for this device.
/// @param auth_poll_failures   Consecutive challenge-seen failures already recorded.
[[nodiscard]] inline bool scheduled_poll_in_retry_band(uint8_t status_poll_failures, uint8_t auth_poll_failures) {
  return auth_poll_failures == 0 && status_poll_failures >= SCHEDULED_POLL_RETRY_GRACE_FIRST_FAILURE &&
         status_poll_failures <= SCHEDULED_POLL_RETRY_GRACE_LAST_FAILURE;
}
 
/// @brief Transmit-attempt budget for a scheduler-owned status poll of a heater, by ladder position.
///
/// Heaters keep this count-based budget; a cover's polls take their plan from
/// scheduled_poll_read_kind() instead.
///
/// @param status_poll_failures Consecutive silent failures already recorded for this device.
/// @param auth_poll_failures   Consecutive challenge-seen failures already recorded.
/// @return EXCHANGE_RETRY_COUNT inside the band, SCHEDULED_POLL_MAX_TRIES everywhere else.
inline uint8_t scheduled_poll_max_tries(uint8_t status_poll_failures, uint8_t auth_poll_failures) {
  return scheduled_poll_in_retry_band(status_poll_failures, auth_poll_failures) ? EXCHANGE_RETRY_COUNT
                                                                                : SCHEDULED_POLL_MAX_TRIES;
}
 
// == Attempt plan ==
 
/// @brief What a request is for, which decides how its attempts are spent.
enum class ReadKind : uint8_t {
  PROGRESS,  ///< A look at a device that is probably still busy (a mid-travel poll): one attempt, the
             ///< backoff ladder is the retry.
  SETTLING,  ///< A read that decides where a device ended up: as many attempts as fit the budget.
  COMMAND,   ///< A request that is harmless to repeat (is_repeat_safe_command()): to a mains device
             ///< as many attempts as fit the budget, to a low-power one today's few with a gap.
};
 
/// @brief How one exchange spends its attempts. Handed to ExchangeEngine::send_and_receive().
struct AttemptPlan {
  uint8_t max_attempts{EXCHANGE_RETRY_COUNT};  ///< Most transmissions of the request, `[1, EXCHANGE_MAX_ATTEMPTS]`.
  uint16_t gap_ms{EXCHANGE_RETRY_DELAY_MS};    ///< Wait before each attempt after the first; 0 for none.
  uint16_t window_ms{RESPONSE_START_WAIT_MS};  ///< How long the last attempt listens for the first reply.
  /// How long every attempt before the last listens; 0 means the same as @ref window_ms. A mains
  /// target answers within tens of milliseconds or not at all, so the early attempts need not wait
  /// the whole window: the last one does, to still catch a device that answers late.
  uint16_t early_window_ms{0};
  /// True when the first attempt is a short lead to a low-power receiver in an unknown state
  /// (WakeBelief::UNKNOWN): the short start preamble, a brief window of its own
  /// (LOW_POWER_SHORT_LEAD_WINDOW_MS), and the wake-up attempts after it. A moving receiver hears
  /// the short one and a resting one the wake-up. It counts in @ref max_attempts.
  bool short_lead{false};
  /// True when the caller asked for the read to treat the receiver's state as unknown
  /// (AttemptRequest::with_state_unknown()). The exchange engine resolves the wake belief with it on
  /// sending too, so the plan and the tries agree (wake_belief()).
  bool state_unknown{false};
  /// Time the exchange may run past `exchange_total_budget_ms`. 0 unless the short lead does not fit
  /// with its wake-up attempts inside the budget; then the cost of the lead (short_lead_cost_ms()), so
  /// the attempts after it get the budget the plan without it had and none is dropped. The engine's
  /// guard adds it to the budget, so plan and guard agree. The exchange never runs past the budget by
  /// more than this.
  uint32_t budget_allowance_ms{0};
 
  /// @param attempt  1-based number of the attempt about to listen.
  /// @param attempts Attempts the exchange makes in all (the last one listens @ref window_ms).
  /// @return How long that attempt listens for the first reply.
  [[nodiscard]] uint16_t window_for_attempt(uint8_t attempt, uint8_t attempts) const {
    if (short_lead && attempt == 1)
      return LOW_POWER_SHORT_LEAD_WINDOW_MS;
    return (attempt < attempts && early_window_ms != 0) ? early_window_ms : window_ms;
  }
};
 
/// @brief What the short lead attempt costs the exchange: its transmission, its brief listen and the
/// attempt overhead (the same terms attempt_fits() counts for any attempt).
/// @param short_tx_ms The lead's transmit time as the radio estimates it (short start preamble).
[[nodiscard]] inline uint32_t short_lead_cost_ms(uint32_t short_tx_ms) {
  return short_tx_ms + EXCHANGE_ATTEMPT_OVERHEAD_MS + LOW_POWER_SHORT_LEAD_WINDOW_MS;
}
 
/// @brief The attempt budget rule: an attempt starts only if the whole attempt, up to the end of the
/// last wait it can make, ends inside @p budget_ms.
///
/// Both the engine's guard (ExchangeEngine::try_fits_budget_()) and the plan that counts attempts
/// (attempts_that_fit()) use it, so a plan never promises an attempt the guard would refuse for a
/// target that stays silent. The attempt's overhead (EXCHANGE_ATTEMPT_OVERHEAD_MS) is counted here
/// and nowhere else.
///
/// @param elapsed_ms   Time since the exchange began.
/// @param gap_ms       Wait before the attempt is sent.
/// @param tx_ms        The attempt's transmit time as the radio estimates it.
/// @param window_ms    How long the attempt then listens for the first reply.
/// @param auth_tail_ms The final-reply window a challenged attempt adds, 0 until the target has challenged.
/// @param budget_ms    `exchange_total_budget_ms`.
[[nodiscard]] inline bool attempt_fits(uint32_t elapsed_ms, uint32_t gap_ms, uint32_t tx_ms, uint32_t window_ms,
                                       uint32_t auth_tail_ms, uint32_t budget_ms) {
  return elapsed_ms + gap_ms + tx_ms + EXCHANGE_ATTEMPT_OVERHEAD_MS + window_ms + auth_tail_ms < budget_ms;
}
 
/// @brief How many attempts to a silent target fit the budget when none waits a gap, capped at @p cap.
///
/// The first `n - 1` attempts listen @p early_window_ms and the last listens @p last_window_ms, and
/// the last must still pass attempt_fits(), so n is the largest with
/// `(n - 1) * (tx + overhead + early) + tx + overhead + last < budget`. At least one attempt: the
/// first always runs. A zero budget is no limit the plan can honour (the engine's guard still
/// applies), so it yields @p cap.
///
/// @param budget_ms        `exchange_total_budget_ms`.
/// @param attempt_tx_ms    One attempt's transmit time as the radio estimates it.
/// @param early_window_ms  Listen time of every attempt but the last.
/// @param last_window_ms   Listen time of the last attempt.
/// @param cap              Most attempts the caller allows.
[[nodiscard]] inline uint8_t attempts_that_fit(uint32_t budget_ms, uint32_t attempt_tx_ms, uint32_t early_window_ms,
                                               uint32_t last_window_ms, uint8_t cap) {
  const uint32_t early_ms = attempt_tx_ms + EXCHANGE_ATTEMPT_OVERHEAD_MS + early_window_ms;
  const uint32_t last_ms = attempt_tx_ms + EXCHANGE_ATTEMPT_OVERHEAD_MS + last_window_ms;
  if (budget_ms == 0 || early_ms == 0)
    return cap;
  if (last_ms >= budget_ms)
    return 1;
  const uint32_t fitting = 1 + ((budget_ms - 1 - last_ms) / early_ms);
  return static_cast<uint8_t>(std::max<uint32_t>(1, std::min<uint32_t>(fitting, cap)));
}
 
/// @brief The plan for a caller that names only a number of attempts: that many (at least one, at
/// most EXCHANGE_RETRY_COUNT), the default gap, and @p window_ms.
/// @param max_tries Attempts the caller asks for.
/// @param window_ms First-reply window of every attempt.
[[nodiscard]] inline AttemptPlan attempt_plan_for_tries(uint8_t max_tries, uint16_t window_ms) {
  AttemptPlan plan;
  plan.max_attempts = std::max<uint8_t>(1, std::min<uint8_t>(max_tries, EXCHANGE_RETRY_COUNT));
  plan.window_ms = window_ms;
  return plan;
}
 
/// @brief The attempt plan for a request, from what it is for and who it asks.
///
/// A settling read, and a repeat-safe command to a mains device, repeat without a gap: every attempt
/// listens from the end of its own transmission, so a silent attempt is already followed by the next
/// one as soon as its window ends. The attempts before the last listen only
/// `exchange_early_response_wait_ms` (a mains device answers within tens of milliseconds or not at
/// all) and the last listens the whole window, so how many fit is attempts_that_fit(), capped at
/// EXCHANGE_MAX_ATTEMPTS. A settling read of a low-power device makes LOW_POWER_SETTLING_ATTEMPTS
/// attempts of LOW_POWER_RESPONSE_WAIT_MS each. The same rule the engine's guard applies at run time,
/// so a plan never promises an attempt the guard would refuse when the target stays silent. A
/// challenged attempt costs more (the final reply window), so the guard can still stop a plan early.
///
/// PROGRESS and a COMMAND to a low-power device keep today's shapes: one attempt, and
/// EXCHANGE_RETRY_COUNT attempts with the default gap, both with the tuned start window.
///
/// @param kind           What the request is for.
/// @param low_power      The target is a low-power receiver (YAML `low_power`, CTRL1 low-power bit).
/// @param tuning         Reply windows and exchange budget.
/// @param attempt_tx_ms  One attempt's transmit time as the radio estimates it (long wake-up
///                       preamble for a low-power target); only a gapless plan uses it.
/// @param last_window_ms Listen time of the last attempt of a mains target, or of every attempt of a
///                       gapped plan; 0 for the tuned start window.
/// @param short_lead_tx_ms Set to lead a settling read of a low-power target with one short attempt
///                       (the receiver's state is unknown, see WakeBelief::UNKNOWN): that attempt's
///                       transmit time. The lead is added to the wake-up attempts the budget admits,
///                       which are the same as without it; when all of them do not fit with the lead,
///                       the exchange may run past the budget by the lead's cost
///                       (AttemptPlan::budget_allowance_ms). No lead when only one wake-up attempt
///                       fits, or for any other read.
[[nodiscard]] inline AttemptPlan attempt_plan(ReadKind kind, bool low_power, const TuningConfig &tuning,
                                              uint32_t attempt_tx_ms, uint16_t last_window_ms = 0,
                                              std::optional<uint32_t> short_lead_tx_ms = std::nullopt) {
  AttemptPlan plan =
      attempt_plan_for_tries(kind == ReadKind::PROGRESS ? SCHEDULED_POLL_MAX_TRIES : EXCHANGE_RETRY_COUNT,
                             last_window_ms != 0 ? last_window_ms : tuning.exchange_start_response_wait_ms);
  if (kind == ReadKind::PROGRESS || (kind == ReadKind::COMMAND && low_power))
    return plan;
  plan.gap_ms = 0;
  if (low_power) {
    plan.window_ms = LOW_POWER_RESPONSE_WAIT_MS;
    plan.max_attempts = attempts_that_fit(tuning.exchange_total_budget_ms, attempt_tx_ms, plan.window_ms,
                                          plan.window_ms, LOW_POWER_SETTLING_ATTEMPTS);
    if (short_lead_tx_ms.has_value() && plan.max_attempts > 1) {
      const uint32_t lead_cost_ms = short_lead_cost_ms(*short_lead_tx_ms);
      const uint32_t budget_ms = tuning.exchange_total_budget_ms;
      // The wake-up attempts start after the lead, so they see the budget less its cost.
      const bool all_fit_with_lead =
          budget_ms == 0 || (budget_ms > lead_cost_ms &&
                             attempts_that_fit(budget_ms - lead_cost_ms, attempt_tx_ms, plan.window_ms, plan.window_ms,
                                               LOW_POWER_SETTLING_ATTEMPTS) >= plan.max_attempts);
      plan.short_lead = true;
      plan.max_attempts++;
      plan.budget_allowance_ms = all_fit_with_lead ? 0 : lead_cost_ms;
    }
    return plan;
  }
  plan.early_window_ms = std::min(tuning.exchange_early_response_wait_ms, plan.window_ms);
  plan.max_attempts = attempts_that_fit(tuning.exchange_total_budget_ms, attempt_tx_ms, plan.early_window_ms,
                                        plan.window_ms, EXCHANGE_MAX_ATTEMPTS);
  return plan;
}
 
/// @brief Whether a request may be sent again to a device that said nothing, without a second action.
///
/// A device that hears a request acts on it and answers; silence therefore means it did not hear,
/// or its reply was lost. For a request whose copies have one effect (an absolute position, open,
/// close, STOP, a read) repeating it is harmless either way. CMD_EXECUTE with POS_FAVORITE is not
/// (is_repeatable_execute()): on a Somfy motor it stops a moving cover, so a second copy can undo
/// the first. Every request the hub sends that is not a CMD_EXECUTE is idempotent.
///
/// @param request Outbound request frame.
[[nodiscard]] inline bool is_repeat_safe_command(const IoFrame &request) {
  return request.cmd != CMD_EXECUTE || is_repeatable_execute(request);
}
 
/// @brief What a cover's status poll is for, from where it sits and what it settles.
///
/// A read that decides where the cover ended up is a SETTLING read: the poll after an accepted STOP,
/// the one confirming a cover that stopped short of its target (@p settles_a_position), and the
/// polls in the ladder's retry band (scheduled_poll_in_retry_band()). Every other scheduled poll is
/// a look at a device that is probably still busy or unreachable (PROGRESS): the ladder is its
/// retry.
///
/// @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_position   True for the poll after an accepted STOP or one confirming a stop off
///                             target (StatusPollPolicy::take_settling_read()).
[[nodiscard]] inline ReadKind scheduled_poll_read_kind(uint8_t status_poll_failures, uint8_t auth_poll_failures,
                                                       bool settles_a_position) {
  return (settles_a_position || scheduled_poll_in_retry_band(status_poll_failures, auth_poll_failures))
             ? ReadKind::SETTLING
             : ReadKind::PROGRESS;
}
 
/// @brief What a caller asks of one exchange's attempts: a plain cap on tries (today's shape), or a
/// read kind whose plan the engine builds for the request (ExchangeEngine::plan_read()).
///
/// Converts implicitly from a number of tries, so callers that only name a count are unchanged.
struct AttemptRequest {
  uint8_t max_tries{EXCHANGE_RETRY_COUNT};  ///< Cap on attempts; ignored once @ref kind is set.
  bool planned{false};                      ///< True: build the plan for @ref kind instead of using a count.
  ReadKind kind{ReadKind::COMMAND};         ///< What the read is for; only read when @ref planned.
  /// True for the read at a moving cover's predicted end of travel (@ref with_wake_preamble_first()).
  bool wake_preamble_first{false};
  /// True for a read whose evidence about the receiver may be stale (@ref with_state_unknown()).
  bool state_unknown{false};
 
  AttemptRequest() = default;
  /// @param tries Cap on attempts (the `max_tries` form of ExchangeEngine::send_and_receive()).
  AttemptRequest(uint8_t tries)
      : max_tries(tries) {}  // NOLINT(google-explicit-constructor): count callers stay as they are
  /// @param read_kind What the read is for.
  [[nodiscard]] static AttemptRequest of_kind(ReadKind read_kind) {
    AttemptRequest request;
    request.planned = true;
    request.kind = read_kind;
    return request;
  }
  /// @brief Mark the read as aimed at the moment the receiver has just come to rest: to a low-power
  /// target every attempt sends the wake-up preamble, which a resting receiver hears, whatever the
  /// wake belief says (ADR 0077). Without effect for a target that is not low-power.
  /// \todo Untested on hardware: needs a low-power cover that reports a remaining time.
  [[nodiscard]] AttemptRequest with_wake_preamble_first() const {
    AttemptRequest request = *this;
    request.wake_preamble_first = true;
    return request;
  }
  /// @brief Mark a status read as made without trustworthy news of the receiver: activity the hub
  /// may have missed can have set it moving since its last report, so a recent "stopped" report
  /// does not prove it rests. The wake belief is then UNKNOWN unless fresh moving evidence says
  /// AWAKE (wake_belief()), and a settling read leads with one short attempt before the wake-up
  /// attempts. Only a planned read (@ref of_kind) carries it to the engine; without effect for a
  /// target that is not low-power, for a command, and wherever the belief is not applied: a fixed
  /// preamble (@ref with_wake_preamble_first() wins) or `low_power_wake_belief` switched off.
  /// \todo Untested on hardware, like WakeBelief::UNKNOWN itself.
  [[nodiscard]] AttemptRequest with_state_unknown() const {
    AttemptRequest request = *this;
    request.state_unknown = true;
    return request;
  }
  /// True for a look at a device that is probably still busy: one attempt, the ladder is the retry
  /// (ReadKind::PROGRESS, or a count of SCHEDULED_POLL_MAX_TRIES).
  [[nodiscard]] bool is_progress_look() const {
    return planned ? kind == ReadKind::PROGRESS : max_tries == SCHEDULED_POLL_MAX_TRIES;
  }
};
 
// == 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.
  /// A status read to a receiver the hub has no recent news of (no moving evidence, and either no status
  /// report within LOW_POWER_MAX_TRAVEL_MS — boot, a status refresh — or a read its caller marked with
  /// AttemptRequest::with_state_unknown(), such as a catch-up read): it may be travelling,
  /// when it ignores the wake-up preamble, or at rest, when it hears only that one. Every try of a
  /// single-try read keeps the wake-up preamble; a settling read leads with one short attempt of its
  /// own (AttemptPlan::short_lead) and then sends the wake-up attempts.
  /// \todo Experimental: rests on a moving VELUX screen ignoring the wake-up preamble (issues #114
  ///       and #209); no bench run has met a read to a receiver in this state yet.
  UNKNOWN,
};
 
/// @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.
  uint32_t moving_until_ms{0};       ///< When the remaining time of its last trusted moving report has run
                                     ///< out (`millis()`), 0 = unknown (see moving_until_holds()).
  uint32_t last_status_ms{0};        ///< Last status report from the receiver (`millis()`), 0 = never. A recent
                                     ///< one is news of its state, so a status read is not UNKNOWN then.
};
 
/// 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, dev.moving_until_ms, dev.last_status};
}
 
/// True while the remaining time the receiver last reported has not run out: by its own account it
/// is still travelling, so a silent exchange is not evidence that it has come to rest. False when no
/// remaining time is known (0). Wrap-safe.
/// \todo Untested on hardware: needs a low-power cover that reports a remaining time (ADR 0077).
/// @param evidence Stamps for the target device.
/// @param now      Current millis().
[[nodiscard]] inline bool moving_until_holds(const TargetEvidence &evidence, uint32_t now) {
  return evidence.moving_until_ms != 0 && static_cast<int32_t>(evidence.moving_until_ms - now) > 0;
}
 
/// 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. For a status read with neither moving evidence nor
/// a status report within that time the answer is `UNKNOWN`; otherwise `ASLEEP`. 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()).
/// @param is_status_read True when the request is a status read (CMD_PRIVATE): only a read can be
///                 UNKNOWN, a command keeps the rule it had.
/// @param state_unknown True when the caller marked the read as made without trustworthy news
///                 (AttemptRequest::with_state_unknown()): a recent status report then does not make
///                 the belief ASLEEP. Only a status read takes it; fresh moving evidence still wins.
[[nodiscard]] inline WakeBelief wake_belief(const TargetEvidence &evidence, uint32_t now, bool is_stop,
                                            bool is_status_read = false, bool state_unknown = false) {
  const uint32_t moving = evidence.last_moving_evidence_ms;
  if (is_stop || (moving != 0 && (now - moving) < LOW_POWER_MAX_TRAVEL_MS))
    return WakeBelief::AWAKE;
  const uint32_t reported = evidence.last_status_ms;
  if (is_status_read && (state_unknown || reported == 0 || (now - reported) >= LOW_POWER_MAX_TRAVEL_MS))
    return WakeBelief::UNKNOWN;
  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 and UNKNOWN wake on
/// every try (the short lead of an UNKNOWN settling read is an attempt of its own, AttemptPlan::short_lead). 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::UNKNOWN:
      return "unknown";
    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;
}
 
/// The order in which a 0x72 status-update acknowledgement is sent on the three channels: the channel
/// the 0x71 exchange ran on first, then the other two in their usual CH1, CH2, CH3 order. The device
/// is still listening on the channel its exchange used, so the copy that matters is not left to the
/// end of the sequence. A frequency that is not one of the three channels gives the usual order.
///
/// @param receive_freq_hz Frequency the 0x71 frame (and the challenge exchange) arrived on.
/// @return The three channel frequencies in transmit order.
inline std::array<uint32_t, 3> status_update_ack_channel_order(uint32_t receive_freq_hz) {
  std::array<uint32_t, 3> order{FREQ_CH1, FREQ_CH2, FREQ_CH3};
  if (receive_freq_hz != FREQ_CH1 && receive_freq_hz != FREQ_CH2 && receive_freq_hz != FREQ_CH3)
    return order;
  std::array<uint32_t, 3> result{receive_freq_hz, 0, 0};
  size_t next = 1;
  for (const uint32_t freq : order) {
    if (freq != receive_freq_hz)
      result[next++] = freq;
  }
  return result;
}
 
/// Whether a frame issue (a frame the hub did not act on) is logged at WARN rather than DEBUG. WARN only
/// when the frame is addressed to a registered device or to the hub itself: those are exchanges the hub
/// is part of, so an unhandled or rejected frame is worth a look. A frame from a registered device to a
/// broadcast address or to another controller is traffic the hub merely overheard (a heater's menu
/// beacon, a gateway polling the same device), so it stays at DEBUG however well the source is known.
///
/// @param dst_registered Frame destination is a registered device.
/// @param dst_is_us      Frame destination is the hub's own node ID.
inline bool frame_issue_is_warning(bool dst_registered, bool dst_is_us) { return dst_registered || dst_is_us; }
 
/// 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);
}
 
// === Heater model check ===
 
/// @brief Runs of the one-off heater model check before the hub gives up on it for this boot. Each run
/// costs at most two register reads, and runs only on a poll the device answered.
constexpr uint8_t HEATER_MODEL_CHECK_MAX_RUNS = 3;
 
/// @brief What the model check suggests about a heater's declared `io_model:`.
enum class HeaterModelHint : uint8_t {
  NONE,                    ///< The answer fits the declaration: nothing to say.
  LOOKS_LIKE_RADIATOR,     ///< Declared a towel dryer, but the towel-dryer mode register holds no value.
  LOOKS_LIKE_TOWEL_DRYER,  ///< Declared as no towel dryer, but the towel-dryer mode register holds a value.
};
 
/// @brief Compare a heater's declared model with whether it answered the towel-dryer mode register
/// (0x0136) with a value.
/// @details Two Atlantic Adelis towel dryers answer that register with their mode; an AGILIA radiator
///          and a heater with a night light have not been read there yet, so the hint is worded "looks like" and never
///          changes behaviour. The caller only asks after the device answered the read (with or without a value).
/// @param declared The YAML model.
/// @param towel_mode_has_value True when the register's reply carried a value byte.
/// @return The hint to log, or NONE.
inline HeaterModelHint classify_heater_model_hint(DeviceModel declared, bool towel_mode_has_value) {
  if (declared == DeviceModel::TOWEL_DRYER && !towel_mode_has_value)
    return HeaterModelHint::LOOKS_LIKE_RADIATOR;
  if (declared != DeviceModel::TOWEL_DRYER && towel_mode_has_value)
    return HeaterModelHint::LOOKS_LIKE_TOWEL_DRYER;
  return HeaterModelHint::NONE;
}
 
/// First and last byte format_heater_model_name() prints as itself: printable ASCII, space to '~'.
constexpr uint8_t MODEL_NAME_PRINTABLE_FIRST = 0x20;
constexpr uint8_t MODEL_NAME_PRINTABLE_LAST = 0x7E;  ///< See MODEL_NAME_PRINTABLE_FIRST.
 
/// @brief Render a heater's model-name register (0x0119, ASCII) for a log line.
/// @details Stops at the first NUL, turns any other non-printable byte into '?', and trims trailing
///          spaces, so a padded or garbled reply still logs as one readable line.
/// @param bytes The value bytes of the reply.
/// @param len Their number.
/// @return The name; empty when the reply carried none.
inline std::string format_heater_model_name(const uint8_t *bytes, size_t len) {
  std::string name;
  for (size_t i = 0; i < len && bytes[i] != 0; i++) {
    const bool printable = bytes[i] >= MODEL_NAME_PRINTABLE_FIRST && bytes[i] <= MODEL_NAME_PRINTABLE_LAST;
    name.push_back(printable ? static_cast<char>(bytes[i]) : '?');
  }
  while (!name.empty() && name.back() == ' ')
    name.pop_back();
  return name;
}
 
// === 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);
}
 
// === Execution state ===
 
/// @brief True when a device in this state is moving or about to: waiting for its turn (2), waiting for
/// power (3) or executing (4).
///
/// A queued cover is part of the move that follows, so it is followed like a running one. 0 (unable to
/// execute), 1 (error during the last move) and 5 (done) are at rest. UNDEFINED is not a state; the
/// caller falls back on the stopped bit (reads_stopped_by_status_byte()).
/// @param state State read from byte 0 of a status reply (execution_state_of()).
[[nodiscard]] inline bool is_executing(ExecutionState state) {
  return state == ExecutionState::WAITING_FOR_EXECUTING || state == ExecutionState::WAITING_FOR_POWER ||
         state == ExecutionState::EXECUTING;
}
 
/// @brief Does byte 0 of a status reply say the device is at rest?
///
/// The execution state decides (is_executing()). A byte whose bits [2:0] hold 6 or 7 has no state, and
/// its STATUS_STOPPED bit decides as it did before the state was read.
/// @param status_byte Byte 0 of the reply's payload.
[[nodiscard]] inline bool reads_stopped_by_status_byte(uint8_t status_byte) {
  const ExecutionState state = execution_state_of(status_byte);
  if (state == ExecutionState::UNDEFINED)
    return (status_byte & STATUS_STOPPED) != 0;
  return !is_executing(state);
}
 
// === Stopped reports ===
 
/// @brief What the hub makes of one status report's movement state.
enum class StoppedReport : uint8_t {
  MOVING,                 ///< The device reports itself moving.
  STOPPED,                ///< Stopped on its target (within STATUS_POS_TOLERANCE_RAW), or with no
                          ///< known target or position to compare.
  STOPPED_CONFIRMED,      ///< Stopped off its target, as in the remembered report: at rest there.
  STOPPED_UNCONFIRMABLE,  ///< Stopped off its target and no follow-up poll will run, so the
                          ///< device's own flag stands.
  SETTLING,               ///< Stopped off its target for the first time: treated as moving until
                          ///< the next report confirms it.
};
 
/// @brief One decoded status report, plus what the hub remembers and whether it will poll again.
struct StoppedReportInput {
  bool reported_stopped{true};       ///< The report says at rest (decisions::reads_stopped_by_status_byte()).
  float target{UNKNOWN_POSITION};    ///< Decoded target, or UNKNOWN_POSITION.
  float position{UNKNOWN_POSITION};  ///< Decoded current position, or UNKNOWN_POSITION.
  StopCandidate candidate{};         ///< The last off-target "stopped" report, if any.
  bool follow_up_possible{false};    ///< A tracked follow-up poll will run (StatusPollPolicy is tracking).
  bool has_motion{true};             ///< False for a device without motion (device_has_no_motion()): a
                                     ///< heater's target and current are a setpoint and a reading, and
                                     ///< their difference is no movement.
};
 
/// @brief Decide whether a "stopped" report means at rest.
///
/// A cover can come to rest off its target and report STOPPED there (corpus captures named on
/// StopCandidate). The device's flag is trusted once two reports agree on the same target
/// and the same current position; the first such report keeps the device "moving" for one more
/// poll. Comparing the target as well keeps a device safe that answers "stopped" with a newly
/// commanded target before its motor starts: the report before the command had the old target,
/// so it can never confirm. With no follow-up poll to confirm by, the device's flag stands, or the
/// device would read moving with nothing left to correct it.
///
/// Known bound: a device that answers "stopped, new target, old position" on two polls in a row
/// before its motor starts (a start delay longer than one settle poll, about 3 s) is taken as at
/// rest and polling ends. No captured device does this.
/// @param in The report and the hub's memory of the previous one.
/// @return The verdict; stopped_report_at_rest() says whether it means at rest.
[[nodiscard]] inline StoppedReport classify_stopped_report(const StoppedReportInput &in) {
  if (!in.reported_stopped)
    return StoppedReport::MOVING;
  if (!in.has_motion || in.target == UNKNOWN_POSITION || in.position == UNKNOWN_POSITION ||
      has_reached_target_position(in.target, in.position))
    return StoppedReport::STOPPED;
  if (in.candidate.armed() && has_reached_target_position(in.candidate.target, in.target) &&
      has_reached_target_position(in.candidate.position, in.position))
    return StoppedReport::STOPPED_CONFIRMED;
  if (!in.follow_up_possible)
    return StoppedReport::STOPPED_UNCONFIRMABLE;
  return StoppedReport::SETTLING;
}
 
/// @brief True when a verdict means the device is at rest.
[[nodiscard]] inline bool stopped_report_at_rest(StoppedReport report) {
  return report != StoppedReport::MOVING && report != StoppedReport::SETTLING;
}
 
/// @brief True when a verdict leaves an off-target report to remember for the next one.
///
/// Kept after a confirmation too, so a later poll that finds the device still resting at the same
/// place confirms at once instead of settling again.
[[nodiscard]] inline bool stopped_report_keeps_candidate(StoppedReport report) {
  return report == StoppedReport::STOPPED_CONFIRMED || report == StoppedReport::STOPPED_UNCONFIRMABLE ||
         report == StoppedReport::SETTLING;
}
 
}  // namespace decisions
}  // namespace home_io_control
}  // namespace esphome