hub_internal.h

Go to the documentation of this file.

#pragma once
 
/// @file hub_internal.h
/// @brief Helpers shared only by the hub's own implementation files (`hub_*.cpp`).
/// @ingroup hioc_hub
///
/// Collaborators and entities include log_helpers.h / entity_helpers.h instead; `make
/// include-graph` enforces this. Keeping these helpers here leaves hub_core.h focused on the
/// public component shape and the member-function declarations.
 
#include "hub_core.h"
#include "entity_helpers.h"
#include "log_frame.h"
#include "log_helpers.h"
#include "proto_codecs.h"
 
#include "esphome/core/log.h"
 
#include <algorithm>
#include <array>
#include <cstdio>
#include <cstring>
#include <map>
#include <string>
#include <vector>
 
namespace esphome {
namespace home_io_control {
namespace detail {
 
// ============================================================================
// Shared constants
// ============================================================================
 
/// Suppress a repeated 1W log/poll for the same remote *and the same intent* within this window.
/// Wide on purpose: it collapses both the 4×/40ms reliability burst and a held button into one
/// logical press. A *different* intent from the same remote (a stop after a move) is not a
/// duplicate and passes through immediately — see decisions::is_duplicate_1w_frame().
inline constexpr uint32_t ONEWAY_DEDUP_WINDOW_MS = 2000;
 
// ============================================================================
// Capability and entity-profile helpers
// ============================================================================
 
/// @brief Is the given position value an on/off binary encoding?
/// @param position Position value to test.
/// @return true if position equals BINARY_ENTITY_ON_POSITION or BINARY_ENTITY_OFF_POSITION.
inline bool is_binary_entity_position(uint8_t position) {
  return position == BINARY_ENTITY_ON_POSITION || position == BINARY_ENTITY_OFF_POSITION;
}
 
/// @brief Does the device's type match the expected HA entity class?
/// UNKNOWN devices always match to keep imported/discovered devices working.
/// @param dev IoDevice to check.
/// @param expected Desired capability class (COVER, LIGHT, SWITCH, etc.).
/// @return true if device type matches or is UNKNOWN.
inline bool known_device_matches_entity_class(const IoDevice &dev, DeviceCapabilityClass expected) {
  return dev.type == DeviceType::UNKNOWN || device_capability_class(dev.type) == expected;
}
 
/// @brief Does the device support status requests?
/// UNKNOWN devices pass through.
/// @param dev IoDevice to check.
/// @return true if device type supports status requests or is UNKNOWN.
inline bool known_device_supports_status_requests(const IoDevice &dev) {
  return dev.type == DeviceType::UNKNOWN || device_supports_status_requests(dev.type);
}
 
/// @brief Can this device accept an execute (position) command?
/// Checks capability and, for unknown types, allows binary positions for light/switch.
/// @param dev IoDevice to check.
/// @param position Position value being sent.
/// @return true if operation is appropriate for this device type.
inline bool known_device_accepts_execute_position(const IoDevice &dev, uint8_t position) {
  if (dev.type == DeviceType::UNKNOWN)
    return true;
  if (device_supports_position_control(dev.type))
    return true;
  // Dimmable lights (platform_light.cpp's dimmable: true) send arbitrary 0-100 IO positions, not
  // just the two binary extremes — accept the full range for LIGHT here and trust the entity
  // layer to only ever send binary values for a non-dimmable light. SWITCH and LOCK have no
  // continuous concept, so they stay restricted to the binary encoding below.
  if (device_capability_class(dev.type) == DeviceCapabilityClass::LIGHT)
    return position <= BINARY_ENTITY_OFF_POSITION;
  return is_binary_entity_position(position) &&
         (device_supports_binary_control(dev.type) || device_supports_lock_control(dev.type));
}
 
/// @brief Can this device accept a tilt command?
/// @param dev IoDevice to check.
/// @return true only if device type is known to support tilt.
inline bool known_device_accepts_execute_tilt(const IoDevice &dev) {
  return dev.type != DeviceType::UNKNOWN && device_supports_tilt(dev.type);
}
 
// ============================================================================
// Logging helpers
// ============================================================================
 
/// @brief Log a rejected operation with capability mismatch details.
/// @param device_id Device ID string.
/// @param dev IoDevice that rejected the command.
/// @param operation Human‑readable operation name (e.g., "set position").
/// @param expected Expected capability class or profile name.
inline void log_rejected_operation(const std::string &device_id, const IoDevice &dev, const char *operation,
                                   const char *expected) {
  ESP_LOGW(TAG, "Rejecting %s for device %s: type=%s (%u) class=%s profile=%s expected=%s", operation,
           device_id.c_str(), device_type_name(dev.type), static_cast<uint8_t>(dev.type),
           device_capability_class_name(dev.type), device_operation_profile_name(dev.type), expected);
}
 
/// @brief Log a frame‑level issue (unregistered endpoints, unsupported commands).
/// @param component Pointer to the component (for device lookup).
/// @param direction "tx" or "rx".
/// @param reason Short issue label (e.g., "unregistered_device").
/// @param frame Parsed frame.
/// @param len Serialized length.
inline void log_frame_issue(IOHomeControlComponent *component, const char *direction, const char *reason,
                            const IoFrame &frame, uint8_t len) {
  const std::string src_id = node_id_to_string(frame.src);
  const std::string dst_id = node_id_to_string(frame.dst);
  const bool src_registered = component->get_device(src_id) != nullptr;
  const bool dst_registered = component->get_device(dst_id) != nullptr;
 
  if (src_registered || dst_registered) {
    ESP_LOGW(TAG, "%s issue=%s cmd=%s(0x%02X) src=%s%s dst=%s%s len=%u data_len=%u", direction, reason,
             command_name(frame.cmd), frame.cmd, src_id.c_str(), src_registered ? " (registered)" : "", dst_id.c_str(),
             dst_registered ? " (registered)" : "", len, frame.data_len);
    return;
  }
 
  ESP_LOGD(TAG, "%s issue=%s cmd=%s(0x%02X) src=%s dst=%s len=%u data_len=%u", direction, reason,
           command_name(frame.cmd), frame.cmd, src_id.c_str(), dst_id.c_str(), len, frame.data_len);
}
 
// ============================================================================
// 1W remote frame decode
// ============================================================================
 
/// @brief Log an already-decoded 1W remote frame at DEBUG level.
///
/// Formats a concise DEBUG log line showing remote ID, destination class, command intent, and
/// priority. When the remote is linked to devices, appends the linked device IDs. Takes the
/// already-decoded OneWayFrameInfo so callers that also build a HA event (see
/// build_sender_event_data()) decode the frame once, not twice.
/// @param info Already-decoded 1W frame info (see decode_1w_frame()).
/// @param linked_devices Optional pointer to device IDs this remote is linked to.
inline void log_1w_remote_frame(const OneWayFrameInfo &info, const std::vector<std::string> *linked_devices = nullptr) {
  const std::string src_id = node_id_to_string(info.src);
 
  // Resolve the broadcast target label: "all" for BROADCAST_ALL, otherwise the device type name.
  // Shared with the TX path (OneWayTransmitter::send_burst()) via oneway_target_label() so the two
  // cannot render the same address differently.
  //
  // Rendered as `dst-class=`, never "targets X": this is the class encoded in the frame's
  // destination, not a statement about the device the remote drives. A Somfy remote sends every
  // press twice, once to the device-class broadcast and once to the all-devices broadcast,
  // whatever the channel actually controls — so an awning channel logs a light-class frame. Worded
  // as "targets light" it read as a claim about the device, and cost an issue reporter two rounds
  // chasing a channel mix-up that never happened.
  const char *target_label = oneway_target_label(info);
 
  // Build optional suffix showing linked devices.
  std::string suffix;
  if (linked_devices != nullptr && !linked_devices->empty()) {
    suffix = " (linked →";
    for (const auto &dev_id : *linked_devices) {
      suffix += ' ';
      suffix += dev_id;
    }
    suffix += ')';
  }
 
  if (info.has_intent) {
    ESP_LOGD(TAG, "rx 1W remote %s dst-class=%s: %s(0x%02X) %s originator=%s priority=%s%s", src_id.c_str(),
             target_label, command_name(info.cmd), info.cmd, info.intent, originator_name(info.originator),
             acei_level_name(info.acei_level), suffix.c_str());
    return;
  }
 
  ESP_LOGD(TAG, "rx 1W remote %s dst-class=%s: %s(0x%02X) data_len=%u%s", src_id.c_str(), target_label,
           command_name(info.cmd), info.cmd, info.data_len, suffix.c_str());
}
 
/// @brief Home Assistant event fired when a decoded 1W frame carries a command intent from an
/// exposed sender (a physical remote button press, or a wind/rain sensor's triggered command).
inline constexpr const char *ONEWAY_SENDER_EVENT = "esphome.home_io_control_sender_event";
 
/// @brief Whether a 1W sender is on the `exposed_senders` allowlist for the sender HA event.
///
/// "Sender" covers both remotes and wind/rain sensors — they use the identical 1W broadcast
/// mechanism and differ only in the `originator` byte inside the payload, not in addressing.
/// Overheard 1W traffic is always DEBUG-logged regardless of this check (see
/// log_1w_remote_frame()); this only gates whether the event reaches Home Assistant. Deliberately
/// separate from `linked_devices` — a sender can be event-enabled without controlling any
/// registered device (e.g. to trigger an HA automation with no matching cover/light/switch), or
/// vice versa.
/// @param exposed_senders Configured allowlist (`exposed_senders` YAML key, empty by default).
/// @param sender_id Node ID of the 1W sender that sent the frame.
/// @return true if the sender is in the allowlist.
inline bool is_exposed_sender(const std::vector<std::string> &exposed_senders, const std::string &sender_id) {
  return std::find(exposed_senders.begin(), exposed_senders.end(), sender_id) != exposed_senders.end();
}
 
/// Buffer size for describe_learned_device_type()'s hex fallback: "io_device_type: 0xXX" plus margin.
inline constexpr size_t LEARNED_DEVICE_TYPE_HEX_BUFFER_SIZE = 24;
 
/// @brief Build the YAML line to add once a device's type is learned at runtime.
///
/// Logged when `io_device_type` was left unset in YAML and an INFO2 response just resolved it
/// for the first time this boot (ADR 0018: nothing persists, so this repeats on every reboot
/// until the user copies the line in). Reuses yaml_device_type_name() so the exact syntax always
/// matches what the pairing snippet and the Python schema accept.
/// @param type The now-known device type. Must not be DeviceType::UNKNOWN.
/// @return The YAML line to add, e.g. `io_device_type: "venetian_blind"` or `io_device_type: 0x11`.
inline std::string describe_learned_device_type(DeviceType type) {
  const char *name = yaml_device_type_name(type);
  if (name != nullptr)
    return std::string("io_device_type: \"") + name + "\"";
  std::array<char, LEARNED_DEVICE_TYPE_HEX_BUFFER_SIZE> buffer{};
  std::snprintf(buffer.data(), buffer.size(), "io_device_type: 0x%02X", static_cast<uint8_t>(type));
  return std::string(buffer.data());
}
 
/// @brief Build the Home Assistant event data map for a decoded 1W sender frame.
///
/// Only meaningful when `info.has_intent` is true (the caller gates emission on that); the
/// `intent` field is only populated by decode_1w_frame() in that case.
/// @param info Already-decoded 1W frame info (see decode_1w_frame()).
/// @param linked True if this sender is linked to at least one registered device.
/// @return Event data map ready for fire_homeassistant_event().
inline std::map<std::string, std::string> build_sender_event_data(const OneWayFrameInfo &info, bool linked) {
  return {
      {"remote_id", node_id_to_string(info.src)},
      {"target_class", address_class_name(info.address_class)},
      {"target_type", device_type_name(info.target_type)},
      {"cmd", format_name_and_hex(command_name(info.cmd), info.cmd)},
      {"intent", info.intent},
      {"originator", originator_name(info.originator)},
      {"acei_level", acei_level_name(info.acei_level)},
      {"linked", linked ? "true" : "false"},
  };
}
 
// ============================================================================
// Status normalization helpers
// ============================================================================
 
/// @brief Normalize stopped state: some devices briefly report stopped before target/current converge.
///
/// Deliberately reads and writes observed fields only — never effective_*(). Its job is "the device
/// said stopped but its own reported target and current disagree", a statement about observations;
/// feeding it a prediction would push a guess back into an observed field. On the execute-ack path
/// (`trust_position = false`) `dev.target` does not hold the commanded value, so this function does
/// not use it to flip `is_stopped` back to false — effective_is_stopped() owns that.
/// @param dev Device record to update (may clear is_stopped if positions differ).
inline void normalize_stopped_state(IoDevice &dev) {
  // Some devices briefly report STATUS_STOPPED before current and target have numerically
  // converged. Keep the device in the moving state until the decoded values are effectively equal.
  if (dev.is_stopped && dev.target != UNKNOWN_POSITION && dev.position != UNKNOWN_POSITION &&
      !has_reached_target_position(dev.target, dev.position)) {
    dev.is_stopped = false;
  }
}
 
/// @brief Update per-device link-health stats from the radio's last capture.
///
/// Called for every frame whose `src` is a registered device, regardless of command type or
/// whether that command's own payload was well-formed — any such frame is real evidence the
/// device is reachable and at this signal strength. The call sites cover every way such a frame
/// arrives: update_device_status_() (inbound status path), execute_request_and_update_()'s
/// explicit-refusal branch (a CMD_ERROR_RESP reply to our own request, which returns before
/// reaching the status path), and its failure branch when a 0x3C challenge was seen (the device
/// transmitted, even though the exchange did not complete). Always stamps `last_seen_ms`; only
/// touches the RSSI fields when `radio` is non-null and its last capture is valid (real drivers
/// always populate a valid capture before a frame is handed off, but tests calling this path
/// directly without a radio, or without exercising RX through it, must not crash or fabricate
/// an RSSI).
/// @param dev Device that sent the frame.
/// @param radio Radio driver to read the last capture from; may be nullptr.
inline void update_link_health(IoDevice &dev, RadioDriver *radio) {
  dev.last_seen_ms = millis();
  if (radio == nullptr)
    return;
 
  const RadioCaptureInfo &capture = radio->get_last_capture();
  if (!capture.valid)
    return;
 
  dev.last_rssi_dbm = capture.rssi_dbm;
  if (dev.rssi_ema_scaled == RSSI_UNKNOWN_DBM) {
    // First sample: seed the EMA directly instead of blending from 0.
    dev.rssi_ema_scaled = static_cast<int16_t>(capture.rssi_dbm * RSSI_EMA_SCALE);
    return;
  }
  // Integer EMA kept in fixed point: `S += x − round(S/N)` blends each sample at weight 1/N
  // while S stays scaled by N, so sub-dBm contributions accumulate instead of truncating to
  // zero — a whole-dBm EMA would stall as soon as |sample − EMA| < N and never converge.
  dev.rssi_ema_scaled =
      static_cast<int16_t>(dev.rssi_ema_scaled + capture.rssi_dbm - rssi_scaled_to_dbm(dev.rssi_ema_scaled));
}
 
/// @brief Record that an outbound exchange to this device timed out (no valid response).
///
/// Called once per failed exchange from execute_request_and_update_()'s "no valid response"
/// branch — the single place every device-directed exchange already reads
/// ExchangeEngine::DebugInfo. Both counters saturate at UINT16_MAX instead of wrapping,
/// matching PairingTelemetry's counters.
/// @param dev Device the failed exchange was addressed to.
/// @param tries Number of attempts the failed exchange made (`DebugInfo::tries`, 1-based).
inline void record_exchange_timeout(IoDevice &dev, uint8_t tries) {
  if (dev.exchange_timeout_count < UINT16_MAX)
    dev.exchange_timeout_count++;
  dev.exchange_attempt_count =
      static_cast<uint16_t>(std::min<uint32_t>(static_cast<uint32_t>(dev.exchange_attempt_count) + tries, UINT16_MAX));
}
 
/// @brief Record what an outbound exchange's ending says about the device, whichever way the caller
/// then classifies the outcome.
///
/// - `ExchangeOutcome::SUCCESS_UNCONFIRMED` (the device answered the request with a challenge, we
///   answered that, and the closing reply never arrived) counts in exchange_unconfirmed_count. A
///   CMD_EXECUTE treats that outcome as success and records no failure, so this counter is the only
///   place it is visible to the diagnostics at all. Saturates at UINT16_MAX instead of wrapping,
///   like the counters above.
/// - A CMD_EXECUTE that got a reply (`ExchangeOutcome::SUCCESS_WITH_RESPONSE`, a status or an error
///   alike, since either one closes the exchange) marks the device as one that confirms, which is
///   what lets a later unconfirmed EXECUTE to it be sent again.
/// @param dev         Device the exchange was addressed to.
/// @param request_cmd Command byte of the request.
/// @param outcome     How the exchange ended.
inline void record_exchange_outcome(IoDevice &dev, uint8_t request_cmd, ExchangeOutcome outcome) {
  if (outcome == ExchangeOutcome::SUCCESS_UNCONFIRMED && dev.exchange_unconfirmed_count < UINT16_MAX)
    dev.exchange_unconfirmed_count++;
  if (outcome == ExchangeOutcome::SUCCESS_WITH_RESPONSE && request_cmd == CMD_EXECUTE)
    dev.confirms_execute = true;
}
 
/// @brief Store a decoded record on the device, if it is valid.
///
/// A short or unpopulated payload leaves whatever was last learned in place rather than clearing
/// it: the record is inherently last-writer-wins and only refreshes when something commands the
/// device, so a stale value is the honest answer and a blanked one is not.
inline void apply_last_command_record(IoDevice &dev, const LastCommandRecord &record) {
  if (!record.valid)
    return;
  memcpy(dev.last_commander, record.commander, NODE_ID_SIZE);
  dev.last_command_originator = record.originator;
  dev.has_last_command = true;
}
 
/// @brief Describe a 0x71 status update's Command Originator as "name(0xXX)".
///
/// Pure rather than inlined into the log line it feeds, so the offset is testable: ESP_LOG* is a
/// no-op stub in host tests, which makes the rendered line itself unobservable.
/// @param frame A CMD_STATUS_UPDATE frame.
/// @return "name(0xXX)", e.g. "user_remote(0x01)", or an empty string when the payload is too
///         short to carry the byte. Shorter frames still carry usable position data — the branch
///         gate is STATUS_UPDATE_MIN_DATA_LEN (11) — they just have no originator to report.
inline std::string describe_status_update_originator(const IoFrame &frame) {
  if (frame.data_len <= STATUS_UPDATE_ORIGINATOR_OFFSET)
    return {};
  return format_originator(frame.data[STATUS_UPDATE_ORIGINATOR_OFFSET]);
}
 
/// @brief Describe the hub's live optimistic predictions where they disagree with the observation.
///
/// Pure rather than inlined into log_status_update() so it is testable (ESP_LOG* is a no-op stub in
/// host tests). log_status_update() runs from the inbound frame handlers and reports what the device
/// said; a hub-side prediction must never be substituted into those observed fields, so it is
/// appended as a clearly-labelled annotation instead. Only terms that actually differ are rendered —
/// a prediction that merely confirms the observation adds nothing.
/// @param dev Device record to read.
/// @return e.g. " [predicted: target=100% stopped]", or an empty string when no prediction stands
///         or every prediction agrees with what the device reported.
inline std::string describe_prediction(const IoDevice &dev) {
  const bool target_differs = effective_target(dev) != dev.target;
  const bool motion_differs = effective_is_stopped(dev) != dev.is_stopped;
  if (!target_differs && !motion_differs)
    return {};
  std::string out = " [predicted:";
  if (target_differs)
    out += " target=" + format_position(effective_target(dev));
  if (motion_differs)
    out += effective_is_stopped(dev) ? " stopped" : " moving";
  out += "]";
  return out;
}
 
/// @brief Log a concise status‑update line used by inbound handlers.
///
/// The position/target/motion fields report what the device observed — never a hub prediction. A
/// diverging live prediction is appended by describe_prediction(), clearly labelled, not merged in.
/// @param id Device ID.
/// @param dev Current device state.
/// @param suffix Optional suffix added after the state string (e.g., " (status update)").
inline void log_status_update(const std::string &id, const IoDevice &dev, const char *suffix = "") {
  ESP_LOGI(TAG, "Device %s: position=%s target=%s %s%s%s", id.c_str(), format_position(dev.position).c_str(),
           format_position(dev.target).c_str(), dev.is_stopped ? "stopped" : "moving", describe_prediction(dev).c_str(),
           suffix);
}
 
/// @brief Log a decoded CMD_ERROR_RESP result with optional request-command context.
/// @param id Device ID.
/// @param result Result byte from CMD_ERROR_RESP data[0].
/// @param request_cmd Original outbound request command when known.
/// @param include_request_cmd True to include request_cmd in the log line.
inline void log_command_result(const std::string &id, uint8_t result, uint8_t request_cmd = 0,
                               bool include_request_cmd = false) {
  const char *kind = is_limitation_result(result) ? "limitation" : "error";
  if (include_request_cmd) {
    ESP_LOGW(TAG, "Device %s: %s (0x%02X) returned %s result=0x%02X %s (%s)", id.c_str(), command_name(request_cmd),
             request_cmd, kind, result, command_result_name(result), command_result_description(result));
    return;
  }
 
  ESP_LOGW(TAG, "Device %s: explicit %s result=0x%02X %s (%s)", id.c_str(), kind, result, command_result_name(result),
           command_result_description(result));
}
 
/// @brief Store a decoded CMD_ERROR_RESP result on the device and log it.
///
/// Single place both CMD_ERROR_RESP call sites (the unsolicited status path and the reply to
/// our own EXECUTE) route through, so the store-and-log policy cannot drift between them. Does
/// not notify subscribers itself — callers already call notify_device_update_() once per
/// handled frame; call it after this.
/// @param dev Device that returned the result.
/// @param id Device ID (for the log line).
/// @param result Result byte from CMD_ERROR_RESP data[0].
/// @param request_cmd Original outbound request command when known.
/// @param include_request_cmd True to include request_cmd context in the log line.
inline void record_command_result(IoDevice &dev, const std::string &id, uint8_t result, uint8_t request_cmd = 0,
                                  bool include_request_cmd = false) {
  dev.last_result_code = result;
  dev.last_result_at_ms = millis();
  log_command_result(id, result, request_cmd, include_request_cmd);
}
 
/// @brief Clear a previously recorded CMD_ERROR_RESP result, if any.
///
/// A stale limitation reason (e.g. a rain lockout from an hour ago) is worse than none once the
/// device has since replied normally, so every successful status/command reply for a device
/// clears it. Called from the CMD_PRIVATE_RESP and CMD_STATUS_UPDATE branches of
/// update_device_status_() — not from CMD_GET_NAME_RESP/CMD_GET_INFO2_RESP, which are metadata
/// lookups unrelated to whether the device's last movement command succeeded. Like
/// record_command_result(), does not notify subscribers itself — both existing call sites clear
/// before their own notify_device_update_() call, which is what actually publishes this change.
/// @param dev Device to clear.
inline void clear_command_result(IoDevice &dev) {
  dev.last_result_code = 0;
  dev.last_result_at_ms = 0;
}
 
}  // namespace detail
}  // namespace home_io_control
}  // namespace esphome