proto_device_model.h

Go to the documentation of this file.

#pragma once
 
/// @file proto_device_model.h
/// @brief IO-Homecontrol device-type model, capabilities and runtime device state.
/// @ingroup hioc_protocol
///
/// DeviceType/DeviceCapabilityClass, the capability predicates, packed-metadata
/// decoders, cover commands, position/tilt report decoding and the IoDevice
/// runtime struct. The per-(type, subtype) names and flags live in the table in proto_device_types.h.
 
#include "proto_heating.h"
#include "proto_sizes.h"
 
#include <cstdint>
#include <string>
 
namespace esphome {
namespace home_io_control {
 
// ============================================================================
// Device Types — from the IO-Homecontrol specification
// ============================================================================
 
/// @brief IO-Homecontrol node types.
/// The numeric values follow the specification's 10-bit node-type field, so the enum is 16 bits
/// wide: a remote controller (1023) and the test type (1008) do not fit in 8 bits. Do not reassign
/// or reorder these. Names, subtype names and capabilities live in the table in proto_device_types.h.
enum class DeviceType : uint16_t {
  UNKNOWN = 0,                         ///< Unknown/unspecified device.
  INTERIOR_VENETIAN_BLIND = 1,         ///< Interior venetian blind.
  ROLLER_SHUTTER = 2,                  ///< Roller shutter.
  VERTICAL_EXTERIOR_AWNING = 3,        ///< Vertical exterior awning.
  WINDOW_OPENER = 4,                   ///< Window opening actuator.
  GARAGE_OPENER = 5,                   ///< Garage door opener.
  LIGHT = 6,                           ///< Light.
  GATE_OPENER = 7,                     ///< Gate opener.
  ROLLING_DOOR_OPENER = 8,             ///< Rolling door opener.
  LOCK = 9,                            ///< Lock.
  VERTICAL_INTERIOR_BLIND = 10,        ///< Vertical interior blind.
  SECURE_CONFIGURATION_DEVICE = 11,    ///< Secure configuration device (a commissioning tool, not an actuator).
  BEACON = 12,                         ///< Beacon (unpaired/announcement). Not YAML-selectable: a
                                       ///< discovery pseudo-type, not a configurable actuator.
  DUAL_ROLLER_SHUTTER = 13,            ///< Dual-section roller shutter.
  HEATING_TEMPERATURE_INTERFACE = 14,  ///< Heating temperature interface.
  ON_OFF_SWITCH = 15,                  ///< Generic on/off switch.
  HORIZONTAL_AWNING = 16,              ///< Horizontal awning (open/close inverted).
  EXTERIOR_VENETIAN_BLIND = 17,        ///< Exterior venetian blind.
  LOUVRE_BLIND = 18,                   ///< Louvre blind.
  CURTAIN_TRACK = 19,                  ///< Curtain track.
  VENTILATION_POINT = 20,              ///< Ventilation point.
  EXTERIOR_HEATING = 21,               ///< Exterior heating.
  HEAT_PUMP = 22,                      ///< Heat pump.
  INTRUSION_ALARM = 23,                ///< Intrusion alarm.
  SWINGING_SHUTTER = 24,               ///< Swinging shutter.
  // 25 and 26 are not defined; the enum is non-contiguous from here on.
  SLIDING_WINDOW = 27,             ///< Sliding window.
  ZONE_CONTROL = 28,               ///< Zone control.
  BIOCLIMATIC_PERGOLA = 29,        ///< Bioclimatic pergola (louvre opening as the position).
  SIREN = 30,                      ///< Siren.
  DOMESTIC_HOT_WATER = 51,         ///< Domestic hot water.
  ELECTRICAL_HEATER = 52,          ///< Electrical heater.
  HEAT_RECOVERY_VENTILATION = 53,  ///< Heat recovery ventilation.
  CENTRAL_HOUSE_CONTROL = 255,     ///< Central house control.
  TEST_AND_EVALUATION = 1008,      ///< Test and evaluation equipment.
  REMOTE_CONTROLLER = 1023,        ///< Remote controller (all ten type bits set, packed bytes `FF C0`). An
                                   ///< Atlantic AGILIA IO radiator answers discovery with this type while in
                                   ///< its display's pairing mode, and then refuses a pushed key with
                                   ///< RESULT_COMMAND_UNKNOWN (tests/corpus/captures/pairing/
                                   ///< atlantic_agilia_pairing_key_transfer_command_unknown.yaml).
};
 
/// @brief High‑level capability class derived from DeviceType.
enum class DeviceCapabilityClass : uint8_t {
  UNKNOWN = 0x00,       ///< Unknown capability.
  COVER = 0x01,         ///< Position‑controlled cover (shutter/blind/awning).
  LIGHT = 0x02,         ///< Binary on/off light.
  SWITCH = 0x03,        ///< Binary on/off switch.
  SENSOR = 0x04,        ///< Sensor device.
  BEACON = 0x05,        ///< Beacon.
  CLIMATE = 0x06,       ///< Climate device (heating/cooling).
  LOCK = 0x07,          ///< Lock.
  HEATER_LEVEL = 0x08,  ///< Heater with a heat level in the position field (exterior heating).
};
 
/// @brief Convert a DeviceType to a lowercase string identifier.
/// @param type Device type enum.
/// @return Null‑terminated string name (e.g., "roller_shutter"), or "unknown" for a value the
///         table does not name.
const char *device_type_name(DeviceType type);
 
/// @brief True when a raw 10-bit device-type value is a named DeviceType enumerator.
/// @details The enum is not contiguous (25 and 26 are undefined), so a range check is not enough.
///          UNKNOWN (0) is not "known".
/// @param raw Raw type value as decoded from an address or info frame.
bool is_known_device_type(uint16_t raw);
 
/// @brief Return the YAML-friendly device-type name for types exposed in the Python schema.
/// @param type Device type enum.
/// @return Null‑terminated string (e.g., "exterior_venetian_blind"), or nullptr if the type
///         has no symbolic YAML alias (user must use a raw numeric value).
const char *yaml_device_type_name(DeviceType type);
 
/// @brief Map a raw IO‑Homecontrol type to the closest ESPHome/Home Assistant entity family.
/// @param type Raw device type.
/// @return Capability class (COVER, LIGHT, SWITCH, etc.).
DeviceCapabilityClass device_capability_class(DeviceType type);
 
/// @brief Get a human‑readable name for a capability class.
/// @param type Device type (unused, kept for signature compatibility).
/// @return String like "cover", "light", "switch", "unknown".
const char *device_capability_class_name(DeviceType type);
 
/// @brief Does this device type support precise position control (0–100)?
/// @param type Device type.
/// @return true for cover‑family devices.
bool device_supports_position_control(DeviceType type);
 
/// @brief Does this device type support binary on/off control?
/// @param type Device type.
/// @return true for lights and switches.
bool device_supports_binary_control(DeviceType type);
 
/// @brief Does this device type support status request commands (0x03)?
/// @param type Device type.
/// @return true for covers, binary devices, and lock devices.
bool device_supports_status_requests(DeviceType type);
 
/// @brief Does this device type support binary lock/unlock control via execute commands?
/// @param type Device type.
/// @return true for lock devices.
bool device_supports_lock_control(DeviceType type);
 
/// @brief Does this device take a heat level as its position (exterior heating)?
/// @param type Device type.
/// @return true for the HEATER_LEVEL capability class.
bool device_supports_heat_level_control(DeviceType type);
 
/// @brief Does this device never move, so a status reply must not start the movement settle loop?
/// @details Heaters commanded with an EXECUTE (heating levels or temperatures; climate profile) and exterior heating (a
/// heat level in the
///          position field) have no motion; their status "stopped" flag is not consulted.
/// @param type Device type.
/// @param subtype Device subtype.
/// @return true when the device has no motion.
bool device_has_no_motion(DeviceType type, uint8_t subtype);
 
/// @brief Can a climate entity drive this device?
///
/// True exactly when a heating profile exists for (type, subtype) (proto_heating_profiles.h): the
/// electrical heater with an adjustable setpoint (52/1, private registers) and the plain electrical
/// heater (52/0, heating levels). This only says a climate entity may bind; whether the private
/// register protocol may be sent to the device is device_uses_heating_registers().
/// @param type Device type.
/// @param subtype Device subtype.
/// @return true for devices that have a heating profile.
bool device_supports_climate_control(DeviceType type, uint8_t subtype);
 
/// @brief Does this device type support tilt (slat angle) control?
/// @param type Device type.
/// @return true for interior venetian blinds, vertical interior blinds, exterior venetian blinds
///         and louvre blinds.
bool device_supports_tilt(DeviceType type);
 
/// @brief Does this device type support the ventilation position command?
///
/// The ventilation command moves window-type actuators to a predefined
/// partially-open position suitable for air exchange without fully opening.
/// @param type Device type.
/// @return true for WINDOW_OPENER and VENTILATION_POINT.
bool device_supports_vent(DeviceType type);
 
/// @brief Does this device take movement commands as the main parameter only?
///
/// True for every garage opener: a Wisniowski / Somfy MOTO 1000 io refuses the functional-parameter
/// block of the regular position execute (the travel-speed profile roller motors use) and the
/// "favourite" alias with RESULT_PARAMETER_UNKNOWN, and accepts a frame without them (issue #163).
/// True for subtype 58 of any node type too: the public KLF 200 API specification defines it as the
/// position-only variant. Other gate and rolling-door openers may behave the same but have no field
/// report yet, so they keep the regular frame.
/// @param type Device type.
/// @param subtype Device subtype.
/// @return true if movement must use create_execute_main_parameter() and FAVORITE is unsupported.
bool device_takes_main_parameter_only(DeviceType type, uint8_t subtype);
 
/// @brief Decode the 10-bit node type from two packed metadata bytes.
/// @param type_msb First metadata byte.
/// @param type_subtype Second metadata byte containing the remaining type bits and subtype.
/// @return Decoded node type; a value the enum has no enumerator for is returned as is.
DeviceType decode_packed_device_type(uint8_t type_msb, uint8_t type_subtype);
 
/// @brief Decode a protocol-packed device subtype from the second metadata byte.
/// @param type_subtype Second metadata byte containing subtype in bits [5:0].
/// @return Manufacturer-specific subtype.
uint8_t decode_packed_device_subtype(uint8_t type_subtype);
 
/// @brief Encode a DeviceType/subtype pair into the two-byte packed metadata format used by
/// discovery responses — the inverse of decode_packed_device_type()/decode_packed_device_subtype().
/// @param type Device type to encode.
/// @param subtype Manufacturer-specific subtype; only bits [5:0] are used.
/// @param type_msb Output: first metadata byte. Only the low ten bits of `type` fit the wire field;
///        higher bits are dropped.
/// @param type_subtype Output: second metadata byte (top 2 type bits + 6-bit subtype).
void encode_packed_device_type(DeviceType type, uint8_t subtype, uint8_t &type_msb, uint8_t &type_subtype);
 
/// @brief Human‑readable operation profile name for a device type.
/// Used for logging and diagnostics.
/// @param type Device type.
/// @return String such as "cover_position", "cover_position_tilt", "binary_on_off", "lock", etc.
const char *device_operation_profile_name(DeviceType type);
 
/// @brief Human-readable device type string for diagnostics, including the raw numeric value.
/// @param type Device type.
/// @return String such as "horizontal_awning (0x10)", or the raw hex form ("0x1A") when the
///         type has no symbolic name. The value is printed in full ("0x3FF").
std::string format_device_type_diagnostic(DeviceType type);
 
/// @brief Build the YAML value for a device's `io_device_type` key.
/// @param type Device type.
/// @return A quoted symbolic name (e.g. `"horizontal_awning"`) when one exists, otherwise the
///         raw hex form (e.g. `0x1A`, `0x3FF`) for a type with no YAML alias.
std::string format_device_type_for_yaml(DeviceType type);
 
/// @brief Build the ready-to-paste YAML block describing a device, for both a fully-decoded
/// device and one whose type/subtype wasn't reported.
///
/// With `metadata_complete == false`, the type/subtype are unknown, so the returned snippet
/// uses a `<cover|light|switch|lock>` platform placeholder and a commented-out
/// `io_device_type` explanation; `type`, `subtype`, and `inverted` are ignored in this case.
///
/// With `metadata_complete == true`, the snippet names the concrete ESPHome platform for
/// `type` and fills in `io_subtype`, `invert_position: true` for an inverted cover and
/// `dimmable: true` for a brightness-only light subtype. If the (type, subtype) has no ESPHome
/// platform yet (device_has_platform() in proto_device_types.h), an empty string is returned
/// instead — the caller decides what to say when there's no snippet to show.
///
/// `low_power: true` is emitted in **both** shapes when `low_power` is set (the device
/// self-reported POWER_SAVE_LOW_POWER in its discovery Multi Information Byte); it is omitted
/// entirely otherwise, since its absence is a valid, correct config.
///
/// The emitted keys must track the device-bound platform schemas (`platform_schema_extension()`
/// in platform_common.py, plus each of cover.py/light.py/switch.py/lock.py's own extra keys) by
/// hand. `make yaml-emitter-sync` (scripts/check-yaml-emitters.py) catches drift between the two
/// statically.
/// @param type Decoded device type.
/// @param subtype Decoded device subtype; only used when `metadata_complete` is true.
/// @param device_id Hex device ID string (e.g. "38B4A1").
/// @param metadata_complete Whether the discovery response included type/subtype metadata.
/// @param inverted Whether the device's open/close positions are swapped; only used when
///        `metadata_complete` is true and `type` is a cover.
/// @param low_power Whether the device self-reported a low-power / duty-cycled class; emits
///        `low_power: true` when set, in both snippet shapes.
/// @param system_key_hex The device's own system key as 32 hex characters, or empty when it uses the
///        hub's. Emits `system_key: "<hex>"` in both snippet shapes. Key material: a caller that
///        passes one must print the snippet only inside a DO-NOT-SHARE block.
/// @return Multi-line YAML snippet, or an empty string when `metadata_complete` is true but
///         the (type, subtype) maps to no ESPHome platform.
std::string build_device_yaml_snippet(DeviceType type, uint8_t subtype, const std::string &device_id,
                                      bool metadata_complete, bool inverted, bool low_power,
                                      const std::string &system_key_hex = std::string());
 
// ============================================================================
// Cover Commands
// ============================================================================
 
/// @brief Named device commands for cover-type actuators.
///
/// These represent the discrete non-positional actions a controller can send to
/// a cover device. Each maps to a specific wire encoding in the CMD_EXECUTE payload.
/// Using this enum avoids conflating numeric positions (0–100) with command codes.
enum class CoverCommand : uint8_t {
  STOP = 0,        ///< Stop movement immediately.
  FAVORITE = 1,    ///< Move to stored favorite/"My" position.
  VENT = 2,        ///< Move to ventilation position (window-type devices).
  FORCE_OPEN = 3,  ///< Move to fully open at elevated priority; intended to bypass soft locks
                   ///< and environmental limits (confirmed on real hardware to move correctly;
                   ///< bypassing an active lock is still unconfirmed — see create_force_open()
                   ///< in proto_commands.cpp).
};
 
/// @brief Get a human-readable name for a CoverCommand.
/// @param cmd The cover command to name.
/// @return Null-terminated string such as "STOP", "FAVORITE", or "VENT".
const char *cover_command_name(CoverCommand cmd);
 
/// @brief What the hub's latest minimum-limitation read says about a rain-protection limit.
enum class RainSensorState : uint8_t {
  UNKNOWN = 0,  ///< No usable reading: never read, or the last reads went unanswered.
  DRY = 1,      ///< The device answered and reports no rain-sized opening limit.
  RAIN = 2,     ///< The device answered and reports an opening limit of rain size.
};
 
/// @brief Get a human-readable name for a RainSensorState.
/// @param state The state to name.
/// @return Null-terminated lowercase string: "unknown", "dry" or "rain".
const char *rain_sensor_state_name(RainSensorState state);
 
/// @brief A device's coarse battery level, as it reports it in byte 1 of its status payload.
///
/// Three levels, not a percentage. Only FULL_CHARGE has been seen on real hardware so far (every
/// solar Somfy capture in the corpus, in daylight); LOW_CHARGE and NORMAL_CHARGE are the two values
/// below it and have not been observed. Mains devices report NOT_REPORTED.
/// The names avoid a bare `LOW`, which the Arduino core defines as a macro.
enum class BatteryState : uint8_t {
  NOT_REPORTED = 0,   ///< The device does not report a battery (mains powered), or no status was read yet.
  LOW_CHARGE = 1,     ///< Battery low.
  NORMAL_CHARGE = 2,  ///< Battery neither low nor full.
  FULL_CHARGE = 3,    ///< Battery full.
};
 
/// @brief Get the name a battery level is published under.
/// @param state The level to name.
/// @return "low", "normal" or "full", or "not_reported" for NOT_REPORTED.
const char *battery_state_name(BatteryState state);
 
/// @brief Decode the coarse battery level from byte 1 of a status payload (CMD_PRIVATE_RESP to a
/// status poll, or CMD_STATUS_UPDATE).
/// @param status_byte data[1] of the payload.
/// @return The level held in bits 5-6 (STATUS_BATTERY_MASK); the other bits are ignored.
BatteryState decode_battery_state(uint8_t status_byte);
 
// ============================================================================
// Position Report Decoding
// ============================================================================
 
/// In status responses, position is encoded as a 16-bit value where
/// 0x0000 = fully open (0%) and 0xC800 = fully closed (100%).
static constexpr uint16_t STATUS_POS_MAX = 0xC800;
/// Target-reached tolerance expressed in raw IO-homecontrol position units.
/// 100 raw units out of 51200 full-scale is about 0.195%, so this only absorbs
/// tiny target/current mismatches from device rounding or early stopped flags.
static constexpr uint16_t STATUS_POS_TOLERANCE_RAW = 100;
 
/// Packed device metadata uses two bytes where the high 8 bits carry the upper type bits and the
/// low byte carries both the remaining type bits and the 6-bit manufacturer subtype.
static constexpr uint8_t DEVICE_METADATA_SIZE = 2;
static constexpr uint8_t DEVICE_TYPE_LOW_BITS_SHIFT = 2;
static constexpr uint8_t DEVICE_TYPE_HIGH_BITS_SHIFT = 6;
static constexpr uint16_t DEVICE_TYPE_WIRE_MASK = 0x3FF;  ///< The node-type wire field is ten bits wide.
static constexpr uint8_t DEVICE_SUBTYPE_MASK = 0x3F;
 
// ============================================================================
// Device State
// ============================================================================
 
/// @brief Sentinel value meaning "position is not known yet".
/// Matches POS_UNKNOWN (0xD4 = 212 decimal) for easy debugging.
static constexpr float UNKNOWN_POSITION = 212.0F;
static constexpr uint8_t DEVICE_NAME_BUFFER_SIZE = 32;  ///< Device name storage including null terminator
 
/// @brief Sentinel value meaning "no RSSI sample recorded yet" for `last_rssi_dbm`/`rssi_ema_scaled`.
/// A real RSSI reading from these radios is always well above `INT16_MIN` — and so is any real
/// `rssi_ema_scaled` fixed-point value.
static constexpr int16_t RSSI_UNKNOWN_DBM = INT16_MIN;
 
/// @brief EMA weight denominator and fixed-point scale for `IoDevice::rssi_ema_scaled`.
/// One constant serves both roles by construction: the update `S += x − round(S/N)` blends each
/// new sample `x` in at weight 1/N while keeping `S = N × EMA`.
static constexpr int16_t RSSI_EMA_SCALE = 8;
 
/// @brief What the hub predicted ahead of confirmation, kept apart from what the device reported.
///
/// The observed fields on IoDevice (`position`, `target`, `tilt`, `is_stopped`) mean "this is what
/// the device last told us" and are never written by a guess. Anything the hub predicts — to give
/// the Home Assistant UI immediate feedback across the queue-dispatch and exchange gap — lands
/// here instead, so it can be withdrawn when the command that produced it fails
/// (DeviceRegistry::rollback_optimistic()) without risking a real observation.
///
/// Consumers read through effective_target() / effective_tilt() / effective_is_stopped() rather
/// than either set of fields directly.
struct OptimisticState {
  /// Predicted movement. NONE defers to the observed `is_stopped`; a bool could not express
  /// "predict stopped" (apply_optimistic_stop) distinctly from "no prediction".
  enum class Motion : uint8_t {
    NONE = 0,  ///< No movement prediction; the observed `is_stopped` decides.
    MOVING,    ///< Predicted to be travelling (a position command was issued).
    STOPPED,   ///< Predicted to be at rest (a STOP was issued).
  };
 
  float target{UNKNOWN_POSITION};  ///< Predicted main-position target, or UNKNOWN_POSITION.
  float tilt{UNKNOWN_POSITION};    ///< Predicted slat angle, or UNKNOWN_POSITION.
  Motion motion{Motion::NONE};     ///< Predicted movement state.
  /// True while a pending STOP replaced a `Motion::MOVING` prediction that a failed STOP should
  /// bring back (DeviceRegistry::rollback_optimistic()). A failed STOP means the device keeps
  /// travelling, and a device that reports nothing mid-travel has no observation to fall back on
  /// that still carries the direction. Only set alongside `Motion::STOPPED`.
  bool stop_replaced_movement{false};
  float stop_replaced_target{UNKNOWN_POSITION};  ///< The replaced `target`; meaningful only with the flag.
 
  /// @return true when nothing is predicted, so a rollback would be a no-op.
  [[nodiscard]] bool empty() const {
    return target == UNKNOWN_POSITION && tilt == UNKNOWN_POSITION && motion == Motion::NONE && !stop_replaced_movement;
  }
  /// Withdraw every prediction.
  void clear() { *this = {}; }
  /// Withdraw the position prediction; call when a decoded position observation supersedes it.
  /// Clears `motion` with `target` because apply_optimistic_target() sets the two together, and
  /// the replaced movement with them: an observation outranks every guess about travel.
  void clear_position() {
    target = UNKNOWN_POSITION;
    motion = Motion::NONE;
    forget_replaced_movement();
  }
  /// Drop the movement a STOP replaced, once nothing can roll the STOP back any more.
  void forget_replaced_movement() {
    stop_replaced_movement = false;
    stop_replaced_target = UNKNOWN_POSITION;
  }
  /// Withdraw the tilt prediction; call when a decoded tilt observation supersedes it.
  void clear_tilt() { tilt = UNKNOWN_POSITION; }
};
 
/// @brief Runtime state of a paired IO‑Homecontrol device.
struct IoDevice {
  uint8_t node_id[NODE_ID_SIZE]{};       ///< Device's 3‑byte radio address.
  DeviceType type{DeviceType::UNKNOWN};  ///< Device type (shutter, awning, etc.).
  uint8_t subtype{0};                    ///< Device subtype (manufacturer‑specific).
  char name[DEVICE_NAME_BUFFER_SIZE]{};  ///< Cached UTF-8 device name decoded from Latin-1 wire payloads.
  float position{UNKNOWN_POSITION};      ///< Current position: 0=open, 100=closed, or UNKNOWN_POSITION.
  float tilt{UNKNOWN_POSITION};          ///< Current tilt: 0=closed, 100=open, or UNKNOWN_POSITION.
  float target{UNKNOWN_POSITION};        ///< Target position the device is moving toward.
  bool is_stopped{true};                 ///< True if device is not moving.
  bool inverted{false};                  ///< True if open/close positions are swapped (e.g., horizontal awning).
  bool silent{false};                    ///< True to send position moves with the reference hub's "silent
                                         ///< operation" extended block, which makes the motor travel more
                                         ///< slowly. Like `inverted`/`dimmable` this is a YAML-declared
                                         ///< preference, not a protocol-reported fact — nothing on the wire
                                         ///< tells us whether a device is in that mode.
  bool optimistic_state{true};           ///< True if `target` may be set ahead of a confirming poll/response.
  bool low_power{false};                 ///< YAML-declared: this target is a low-power / duty-cycled receiver, so
                                         ///< directed frames set CTRL1_LOW_POWER and use the long wake-up preamble.
                                         ///< A protocol-reported class exists (discovery Multi Information Byte) but
                                         ///< is surfaced through the pairing/scan snippet, never applied at runtime.
  bool dimmable{false};                  ///< True for a LIGHT-class device configured `dimmable: true` in YAML.
                                         ///< Set from platform_light.cpp's YAML config via
                                         ///< DeviceRegistry::set_dimmable(), purely for accurate profile-name
                                         ///< logging. Light subtype 58 (0x01BA) is defined as on/off only
                                         ///< (VELUX KLF 200 API v3.18, App. 2); the discovery subtype is
                                         ///< not consulted for this flag yet.
  uint8_t last_result_code{0};           ///< Last CMD_ERROR_RESP result byte (0 = none recorded). See
                                ///< command_result_name()/is_limitation_result() in proto_constants.h. Cleared by
                                ///< the next successful status/command reply for this device. Note: 0 is also the
                                ///< real RESULT_UNKNOWN_STATUS_REPLY wire value, so that specific explicit reply is
                                ///< indistinguishable here from "nothing recorded yet" — a known, accepted tradeoff.
  uint32_t last_result_at_ms{0};              ///< millis() timestamp of last_result_code, 0 when none recorded.
  uint8_t last_commander[NODE_ID_SIZE]{};     ///< Node ID of the controller that last commanded this device, as
                                              ///< reported verbatim by the device in its own status payload. All
                                              ///< zeroes until a status reply carrying the record has been decoded
                                              ///< (see decode_last_command_record() in proto_codecs.h).
  uint8_t last_command_originator{0};         ///< That command's Command Originator byte (ORIGINATOR_* in
                                              ///< proto_constants.h). Only meaningful when `has_last_command`.
  bool has_last_command{false};               ///< True once a status reply carried a well-formed last-command record.
  bool limited_by_rain{false};                ///< Derived from observed status replies, never from a prediction
                                              ///< (decisions::is_rain_limited(); ADR 0030 keeps predictions apart):
                                              ///< the last move was ordered by the rain sensor, or a position
                                              ///< command was clamped while rain protection was recently active.
                                              ///< Separate from `last_result_code`, which only an explicit
                                              ///< CMD_ERROR_RESP sets.
  uint32_t last_rain_evidence_ms{0};          ///< millis() of the last status reply that named the rain sensor as the
                                              ///< last commander; 0 = never. Memory for the clamp rule, aged out
                                              ///< by RAIN_EVIDENCE_HOLD_MS.
  uint32_t last_status{0};                    ///< millis() timestamp of last received status.
  int16_t last_rssi_dbm{RSSI_UNKNOWN_DBM};    ///< Most recent raw RSSI sample (dBm), or RSSI_UNKNOWN_DBM.
  int16_t rssi_ema_scaled{RSSI_UNKNOWN_DBM};  ///< Smoothed RSSI as fixed point in 1/RSSI_EMA_SCALE dBm — read
                                              ///< through device_rssi_ema_dbm(), updated by
                                              ///< detail::update_link_health() in hub_internal.h. Fixed point
                                              ///< (rather than whole dBm) keeps sub-dBm EMA contributions from
                                              ///< vanishing to integer truncation, so the average converges on a
                                              ///< stable signal instead of stalling up to RSSI_EMA_SCALE−1 dBm
                                              ///< away. RSSI_UNKNOWN_DBM before the first sample.
  uint32_t last_seen_ms{0};  ///< millis() of the last frame received from this device (any command), 0 = never.
  uint32_t last_moving_evidence_ms{
      0};  ///< millis() of the last sign this device is travelling (see
           ///< note_moving_evidence(), clear_moving_evidence()), 0 = never. Hub-side belief, not observation.
  uint16_t exchange_timeout_count{0};      ///< Cumulative count of outbound exchanges to this device with no valid
                                           ///< response (see detail::record_exchange_timeout() in hub_internal.h).
  uint16_t exchange_attempt_count{0};      ///< Cumulative attempts (`ExchangeEngine::DebugInfo::tries`, 1-based per
                                           ///< exchange) across those timed-out exchanges only — attempts within an
                                           ///< ultimately successful exchange are not counted (deliberate scope limit).
  uint16_t exchange_unconfirmed_count{0};  ///< Cumulative count of exchanges this device authenticated and then never
                                           ///< closed: it answered with a 0x3C challenge, we answered that, and no
                                           ///< final reply arrived. Counted separately from exchange_timeout_count
                                           ///< because the two have different causes and different fixes — silence
                                           ///< from the start means the device never heard us, while silence after a
                                           ///< challenge means the reply was lost on the way back (or our challenge
                                           ///< answer never landed). For a CMD_EXECUTE this outcome is treated as
                                           ///< success and raises no failure count, so without this counter it is
                                           ///< invisible in the diagnostics.
  bool confirms_execute{false};  ///< True once this device has answered a CMD_EXECUTE with a reply that closed the
                                 ///< exchange (a status, or an error). Learned at runtime and never stored: it
                                 ///< separates a device whose missing reply is an anomaly from one that never sends
                                 ///< one (see decisions::retry_after_unconfirmed_accept_is_safe()).
  OptimisticState optimistic{};  ///< Hub-side predictions; see OptimisticState. Never observation.
  RainSensorState rain_sensor{RainSensorState::UNKNOWN};  ///< Rain state from the opt-in minimum-limitation poll.
                                                          ///< Set only from a limitation reply inside an exchange the
                                                          ///< hub started; independent of `limited_by_rain`, which is
                                                          ///< derived from status replies.
  BatteryState battery{BatteryState::NOT_REPORTED};       ///< Coarse battery level from byte 1 of the device's own
                                                          ///< status: a reply to a status poll or an authenticated
                                                          ///< CMD_STATUS_UPDATE. Never from an execute ack (its layout
                                                          ///< follows the request) or an overheard frame (ADR 0022).
  float temperature_range_min_c{
      HEATING_TEMPERATURE_RANGE_MIN_C};  ///< Lower end of the temperature encoding range of a heater that
                                         ///< carries a temperature in its main parameter (YAML `min_temperature:`).
  float temperature_range_max_c{
      HEATING_TEMPERATURE_RANGE_MAX_C};  ///< Upper end of that range (YAML `max_temperature:`).
  HeatingReadings heating{};             ///< What the hub has read from a heater over the private register protocol
                                         ///< (room temperature, setpoint, mode, regulator state). Set only from decoded
                                         ///< replies; stays "never read" for every other device type.
  bool battery_entities{false};  ///< YAML-declared (`battery: true`): the battery entities exist, so the status log
                                 ///< line names the level even when the device reports none.
  bool has_system_key{false};    ///< YAML-declared (`system_key:`): this device keeps a key of its own. Every
                                 ///< exchange with it uses `system_key` below instead of the hub's key.
  uint8_t system_key[AES_KEY_SIZE]{};  ///< The device's own key; meaningful only when `has_system_key`. Key material:
                                       ///< never logged outside a bannered report block.
  bool registered_by_pairing{false};   ///< Added by a pairing in this boot, not declared in YAML. The record is
                                       ///< lost at reboot, so reports still print its YAML block, and a later
                                       ///< pairing may replace it (DeviceRegistry::get_declared()).
};
 
/// @brief Record that a device is (believed to be) travelling right now.
///
/// With clear_moving_evidence(), one of the two writers of IoDevice::last_moving_evidence_ms.
/// Called wherever the hub learns a receiver is moving *because of something that reached it*: a
/// decoded status that says "not stopped", a movement command the device accepted, or an overheard
/// linked-remote movement command. Deliberately NOT called for the hub's own optimistic prediction:
/// that is applied before the command is even sent, so treating it as proof of movement would make a
/// resting receiver look awake to the very command that starts it. A low-power receiver that is
/// moving ignores the long wake-up preamble, so this stamp steers the exchange engine to the short
/// one first (decisions::wake_belief()).
/// @param dev    Device to stamp.
/// @param now_ms Current millis(). Must be non-zero in practice; 0 would read as "never".
inline void note_moving_evidence(IoDevice &dev, uint32_t now_ms) { dev.last_moving_evidence_ms = now_ms; }
 
/// @brief Forget that a device was travelling: it reported itself stopped (including in the ack to a
/// STOP), a linked remote was heard stopping it, or it stayed silent to an exchange sent while it
/// was believed moving.
///
/// The counterpart of note_moving_evidence(). Without it a receiver that has demonstrably stopped
/// would keep reading as "moving" for the rest of LOW_POWER_MAX_TRAVEL_MS, although it goes back to
/// duty-cycling within seconds and then hears only the wake-up preamble.
/// @param dev Device to clear.
inline void clear_moving_evidence(IoDevice &dev) { dev.last_moving_evidence_ms = 0; }
 
/// @brief Convert an `rssi_ema_scaled` fixed-point value to whole dBm (round half away from zero).
/// @param scaled Fixed-point EMA value in 1/RSSI_EMA_SCALE dBm units (not the sentinel).
/// @return Rounded dBm value.
inline int16_t rssi_scaled_to_dbm(int16_t scaled) {
  constexpr int16_t half = RSSI_EMA_SCALE / 2;
  return static_cast<int16_t>((scaled + (scaled >= 0 ? half : -half)) / RSSI_EMA_SCALE);
}
 
/// @brief A device's smoothed RSSI in whole dBm.
/// @param dev Device record to read.
/// @return Rounded EMA in dBm, or RSSI_UNKNOWN_DBM when no sample has been recorded yet.
inline int16_t device_rssi_ema_dbm(const IoDevice &dev) {
  return dev.rssi_ema_scaled == RSSI_UNKNOWN_DBM ? RSSI_UNKNOWN_DBM : rssi_scaled_to_dbm(dev.rssi_ema_scaled);
}
 
/// @brief The main-position target a consumer should act on: the prediction when one stands,
/// otherwise the device's own last reported target.
/// @param dev Device record to read.
/// @return The predicted target when set, otherwise `dev.target`.
inline float effective_target(const IoDevice &dev) {
  return dev.optimistic.target != UNKNOWN_POSITION ? dev.optimistic.target : dev.target;
}
 
/// @brief The slat angle a consumer should act on, prediction first.
/// @param dev Device record to read.
/// @return The predicted tilt when set, otherwise `dev.tilt`.
inline float effective_tilt(const IoDevice &dev) {
  return dev.optimistic.tilt != UNKNOWN_POSITION ? dev.optimistic.tilt : dev.tilt;
}
 
/// @brief Whether a consumer should treat the device as at rest, prediction first.
/// @param dev Device record to read.
/// @return The predicted movement state when one stands, otherwise `dev.is_stopped`.
inline bool effective_is_stopped(const IoDevice &dev) {
  switch (dev.optimistic.motion) {
    case OptimisticState::Motion::MOVING:
      return false;
    case OptimisticState::Motion::STOPPED:
      return true;
    case OptimisticState::Motion::NONE:
    default:
      return dev.is_stopped;
  }
}
 
/// @brief Determine whether a device type has inverted position mapping by default.
/// @param type Device type.
/// @return true for horizontal awnings; false otherwise.
bool default_inverted_for_type(DeviceType type);
 
/// @brief Decode target/current position values from a status frame.
/// @param target_raw 16‑bit raw target value.
/// @param current_raw 16‑bit raw current value.
/// @param is_stopped True if device reports stopped.
/// @param target Output target position (0–100 or UNKNOWN_POSITION).
/// @param position Output current position (0–100 or UNKNOWN_POSITION).
void decode_position_report(uint16_t target_raw, uint16_t current_raw, bool is_stopped, float &target, float &position);
/// @brief Has the device reached its target within tolerance?
/// @param target Target position (0–100 or UNKNOWN_POSITION).
/// @param position Current position (0–100 or UNKNOWN_POSITION).
/// @return true if positions match within STATUS_POS_TOLERANCE_RAW.
bool has_reached_target_position(float target, float position);
/// @brief Decode tilt angle from raw 16‑bit value.
/// @param tilt_raw Raw tilt value from status frame.
/// @return Tilt percentage (0 = closed, 100 = open) or UNKNOWN_POSITION.
float decode_tilt_report(uint16_t tilt_raw);
 
}  // namespace home_io_control
}  // namespace esphome