proto_heating_profiles.h

Go to the documentation of this file.

#pragma once
 
/// @file proto_heating_profiles.h
/// @brief Heating profiles: what a climate card offers for each kind of heater, and how.
/// @ingroup hioc_protocol
///
/// A profile is one row per (node type, subtype, model) that a `climate:` entity can drive. It names the
/// control path (the private register protocol of proto_heating.h, or the standard EXECUTE with a
/// heating level as the main parameter), the HVAC modes and presets the card shows, how each maps to
/// a wire value in both directions, which registers a poll reads and which companion entities exist.
/// The platform asks the profile and never branches on a device type.
///
/// The enums here are protocol-side: they carry no ESPHome type. The platform maps HeatingHvacMode
/// and HeatingPresetId onto ESPHome's climate modes and presets.
///
/// \todo Heating-level control of the plain electrical heater (node type 52, subtype 0) has no capture
///       or hardware report yet. Confirm with one before calling it supported.
/// \todo Every 52/1 seen is an Atlantic heater. A non-Atlantic 52/1 would need the heating-level
///       path instead; the profile keys on (type, subtype, model), and the model is the YAML's.
 
#include "proto_constants.h"
#include "proto_device_model.h"
#include "proto_heating.h"
#include "proto_sizes.h"
 
#include <cstddef>
#include <cstdint>
#include <span>
 
namespace esphome {
namespace home_io_control {
 
/// @brief How a heater is commanded and read.
enum class HeatingControlPath : uint8_t {
  PRIVATE_REGISTERS,    ///< CMD_WRITE_PRIVATE register reads and writes (proto_heating.h).
  HEATING_LEVEL,        ///< Standard EXECUTE with a heating level as the main parameter; read with 0x03.
  TEMPERATURE_EXECUTE,  ///< Standard EXECUTE with a temperature or an alias as the main parameter; read with 0x03.
};
 
/// @brief HVAC modes a profile can offer.
enum class HeatingHvacMode : uint8_t {
  OFF,   ///< Heater off.
  HEAT,  ///< Heating on.
  AUTO,  ///< The device decides.
};
 
/// @brief Presets a profile can offer. CUSTOM entries carry their own name.
enum class HeatingPresetId : uint8_t {
  NONE,     ///< No preset: selecting it ends the one that runs (a towel dryer's boost or drying).
  AWAY,     ///< Nobody is in the room (the frost-protection level on a level heater).
  COMFORT,  ///< Comfort level.
  ECO,      ///< Economy level.
  BOOST,    ///< Boost level.
  CUSTOM,   ///< Named by HeatingPresetEntry::custom_name.
};
 
/// @brief Main-parameter prefix byte of a heating level: the level occupies the low byte.
static constexpr uint8_t HEATING_LEVEL_MP_PREFIX = 0xFC;
 
/// @brief Heating levels (low byte of the main parameter, prefix HEATING_LEVEL_MP_PREFIX).
namespace heating_level {
static constexpr uint8_t OFF = 0x00;               ///< Off.
static constexpr uint8_t FROST_PROTECTION = 0x01;  ///< Frost protection.
static constexpr uint8_t ECO = 0x02;               ///< Economy.
static constexpr uint8_t COMFORT_MINUS_2 = 0x03;   ///< Comfort, two degrees lower.
static constexpr uint8_t COMFORT_MINUS_1 = 0x04;   ///< Comfort, one degree lower.
static constexpr uint8_t COMFORT = 0x05;           ///< Comfort.
static constexpr uint8_t BOOST = 0x07;             ///< Boost.
static constexpr uint8_t SECURED = 0x3F;           ///< Secured; reported by the device, never commanded.
}  // namespace heating_level
 
/// @brief Main-parameter prefix byte of a setpoint alias: the alias occupies the low byte.
static constexpr uint8_t HEATING_ALIAS_MP_PREFIX = 0xD8;
 
/// @brief Setpoint aliases (low byte of the main parameter, prefix HEATING_ALIAS_MP_PREFIX).
namespace heating_alias {
static constexpr uint8_t COMFORT = 0x0F;            ///< The device's comfort setpoint.
static constexpr uint8_t THERMOSTAT_ECO = 0x0E;     ///< Heating temperature interface: the economy setpoint.
static constexpr uint8_t SECURED = 0x0A;            ///< Heating temperature interface: the secured setpoint.
static constexpr uint8_t HEAT_PUMP_SETBACK = 0x0E;  ///< Heat pump: the setback setpoint.
static constexpr uint8_t HEAT_PUMP_ECO = 0x12;      ///< Heat pump: the economy setpoint.
static constexpr uint8_t HEAT_PUMP_HALTED = 0x13;   ///< Heat pump: halted.
}  // namespace heating_alias
 
/// @brief Main parameter of a heat pump's off command: MAIN_PARAMETER_KEEP, which the command pairs with the
/// off value of a functional parameter.
static constexpr uint16_t HEATING_OFF_MP = MAIN_PARAMETER_KEEP;
 
/// @brief Sentinel for HeatingModeEntry::main_parameter: send the entity's target temperature, encoded
/// over the device's range, as the main parameter.
static constexpr uint16_t HEATING_MP_FROM_TARGET = 0xFFFF;
 
/// @brief Values of functional parameter 9 on the heating temperature interface: the active mode.
/// @details The heating / cooling bits (`4`, `8`) belong to a separate operating-mode command (main
///          parameter `0xD400` with FP9 `4`, `8` or `0xC`); they are never combined into these values and
///          this component sends no operating-mode command.
namespace heating_mode_flags {
static constexpr uint8_t OFF = 0x00;     ///< Off.
static constexpr uint8_t AUTO = 0x01;    ///< The device follows its own schedule.
static constexpr uint8_t MANUAL = 0x02;  ///< The device follows the commanded setpoint.
}  // namespace heating_mode_flags
 
/// @brief Values of functional parameter 16 on the heat pump: the on/off state.
/// @details FP16 is the last functional parameter (the last bit of the second bitmap). FP15 reports the
///          device's capabilities (`1` heating, `2` cooling, `4` away, `8` pool, `0x10` hot water) and
///          FP16's other bits report its state; both are read-only here: no command selects cooling,
///          and this component does not read FP15.
namespace heating_fp16 {
static constexpr uint16_t ON = 0x4000;   ///< On: sent with a setpoint alias to select it.
static constexpr uint16_t OFF = 0x8000;  ///< Off: sent with HEATING_OFF_MP.
}  // namespace heating_fp16
 
/// @brief Which functional parameter, if any, accompanies a TEMPERATURE_EXECUTE command.
enum class HeatingFpKind : uint8_t {
  NONE,  ///< A main-parameter-only command.
  FP9,   ///< Functional parameter 9, one byte.
  FP16,  ///< Functional parameter 16, two bytes.
};
 
/// @brief A functional parameter and its value.
struct HeatingFp {
  HeatingFpKind kind{HeatingFpKind::NONE};  ///< Which parameter; NONE sends none.
  uint16_t value{0};                        ///< Its value (one byte for FP9, two for FP16).
};
 
/// @brief Number of main-parameter steps across the encoding range (the full position scale, 0xC800).
static constexpr uint16_t HEATING_TEMPERATURE_MP_SPAN = 51200;
 
/// @brief One HVAC mode the card offers and the wire value that selects it.
struct HeatingModeEntry {
  HeatingHvacMode hvac;        ///< Mode shown on the card.
  uint8_t wire;                ///< PRIVATE_REGISTERS: mode register value. HEATING_LEVEL: level low byte.
                               ///< TEMPERATURE_EXECUTE: unused.
  uint16_t main_parameter{0};  ///< TEMPERATURE_EXECUTE: the main parameter the mode sends, or
                               ///< HEATING_MP_FROM_TARGET.
  HeatingFp fp{};              ///< TEMPERATURE_EXECUTE: the functional parameter the mode sends.
};
 
/// @brief One preset the card offers.
struct HeatingPresetEntry {
  const char *custom_name;   ///< Name of a CUSTOM preset; nullptr otherwise.
  HeatingPresetId id;        ///< Standard preset, or CUSTOM.
  HeatingFunction write_fn;  ///< PRIVATE_REGISTERS: register the preset writes. Unused for levels.
  uint8_t wire;              ///< Value written: register value, or the low byte of a level or alias.
  bool commandable;          ///< False for a preset the device only reports (secured).
  HeatingFp fp{};            ///< TEMPERATURE_EXECUTE: the functional parameter sent with the alias.
};
 
/// @brief What a device-reported wire value shows on the card.
struct HeatingObservedState {
  uint8_t wire;          ///< Mode register value, or level low byte, as the device reports it.
  HeatingHvacMode hvac;  ///< HVAC mode shown.
  int8_t preset;         ///< Index into the profile's presets shown with it, or -1 for none.
};
 
/// @brief Where a register heater's "heating" / "idle" comes from.
enum class HeatingActionSource : uint8_t {
  REGULATOR,     ///< The regulator register (HeatingFunction::REGULATOR_STATE): heating at state 2.
  WORKING_RATE,  ///< The working rate (HeatingFunction::WORKING_RATE): heating above 0 %. A towel dryer's
                 ///< regulator reads 0 during boost and drying, while the element runs at 100 %.
};
 
/// @brief Companion entities and traits a profile has.
struct HeatingProfileFeatures {
  bool target_temperature;   ///< The card has a setpoint.
  bool current_temperature;  ///< The card shows a measured temperature.
  bool action;               ///< The card shows heating / idle.
  bool mode_observed;        ///< A device reading decides the card's mode; false when the mode is the
                             ///< last command (nothing reads it back).
};
 
/// @brief How a heater's own weekly programme shows which period runs: the registers that tell, and the
/// presets that name the periods.
/// @details While the mode register reads `programme_mode` and the preset register reads
///          `idle_preset_state` (no timed run on top), `in_force_fn` holds the temperature the heater
///          heats to. It equals the `comfort_fn` temperature in a comfort period and that temperature
///          minus the `setback_fn` one in an eco period. Outside the programme `in_force_fn` is not a
///          temperature (it reads 1 in boost and 2 in drying on a towel dryer).
struct HeatingProgrammePeriod {
  uint8_t programme_mode;       ///< Value of HeatingProfile::mode_fn while the programme runs.
  uint8_t idle_preset_state;    ///< Value of HeatingProfile::preset_fn with no timed run on top.
  HeatingFunction in_force_fn;  ///< Register of the temperature in force.
  HeatingFunction comfort_fn;   ///< Register of the comfort setpoint.
  HeatingFunction setback_fn;   ///< Register of the eco setback, a distance below the comfort setpoint.
  int8_t comfort_preset;        ///< Index into HeatingProfile::presets shown in a comfort period.
  int8_t eco_preset;            ///< Index into HeatingProfile::presets shown in an eco period.
};
 
/// @brief One heater kind.
/// @details A row is written with designated initializers, in declaration order. The fields before
///          `setpoint_fp` have no default, so a row that leaves one out does not compile; every other field has
///          one and is left out where unused. Each list is a span over a `constexpr` array, which carries its
///          own length.
struct HeatingProfile {
  // --- Required: every row states these ---
  DeviceType type;                          ///< Node type.
  uint8_t subtype;                          ///< Subtype (0 = the type's own row).
  DeviceModel model;                        ///< Model (NONE = the (type, subtype) row's own profile).
  HeatingControlPath path;                  ///< How the heater is commanded and read.
  HeatingProfileFeatures features;          ///< What the card and its companions offer.
  std::span<const HeatingModeEntry> modes;  ///< HVAC modes offered, with the value each writes.
 
  // --- Optional: a default stands for "unused". The byte-sized fields come last, so they pack. ---
  HeatingFp setpoint_fp{};   ///< TEMPERATURE_EXECUTE: the functional parameter sent with a setpoint.
  float visual_min_c{0.0F};  ///< Lowest target temperature the card offers (0 without a setpoint).
  float visual_max_c{0.0F};  ///< Highest target temperature the card offers (0 without a setpoint).
  /// PRIVATE_REGISTERS: how the heater's own programme names the comfort or eco period it is in;
  /// nullptr for a heater that does not report it.
  const HeatingProgrammePeriod *programme_period{nullptr};
  // NOLINTBEGIN(readability-redundant-member-init): a span's own default is empty, but g++'s
  // -Wmissing-field-initializers still wants the member initializer before a row may leave it out.
  std::span<const HeatingPresetEntry> presets{};     ///< Presets offered.
  std::span<const HeatingObservedState> observed{};  ///< Device-reported value -> card state.
  /// PRIVATE_REGISTERS: registers every poll reads, in order.
  std::span<const HeatingFunction> poll_registers{};
  /// PRIVATE_REGISTERS: registers read once until they have been read.
  std::span<const HeatingFunction> boot_registers{};
  /// Device-reported value of `preset_fn` -> preset; empty when the mode register names the preset too
  /// (`observed`). With it, `observed` sets only the mode and this table alone sets the preset, since
  /// mode and preset live in separate registers.
  std::span<const HeatingObservedState> preset_observed{};
  /// PRIVATE_REGISTERS: registers every poll reads after `poll_registers`, for a part the heater may not
  /// have (a night light). A miss here is not a poll failure, so a model declared on a heater without
  /// the part costs a read, not the poll.
  std::span<const HeatingFunction> extra_poll_registers{};
  // NOLINTEND(readability-redundant-member-init)
  uint8_t mp_prefix{0};     ///< High byte of a level or alias main parameter (0 for registers).
  bool fixed_range{false};  ///< TEMPERATURE_EXECUTE: the temperature range is fixed, so the YAML
                            ///< `min_temperature:` / `max_temperature:` do not apply.
  /// PRIVATE_REGISTERS: the register the HVAC modes write and the card's mode is read from.
  HeatingFunction mode_fn{HeatingFunction::SET_MODE};
  /// PRIVATE_REGISTERS with `preset_observed`: the register the card's preset is read from. The presets'
  /// own `write_fn` say what each writes.
  HeatingFunction preset_fn{HeatingFunction::SET_MODE};
  HeatingActionSource action_source{HeatingActionSource::REGULATOR};  ///< Where `features.action` reads from.
  bool experimental_writes{false};  ///< PRIVATE_REGISTERS: the mode and preset writes are unconfirmed on a device.
};
 
/// @brief What a heater's programme period resolves to, from its readings.
struct ProgrammePeriodState {
  bool active{false};       ///< The programme runs (and no timed run is on top of it).
  int8_t preset_index{-1};  ///< Index into the profile's presets of the period, or -1 when the temperature
                            ///< in force fits neither period or the readings cannot say.
  float target_c{NAN};      ///< The temperature in force; NaN until it has been read.
};
 
/// @brief Look up the heating profile for a (type, subtype, model).
/// @param type Node type.
/// @param subtype Subtype; one with no profile of its own falls back to the type's profile (subtype 0),
///        the same rule as find_device_type_info().
/// @param model Declared model. A model with a profile of its own gets it; any other falls back to the
///        (type, subtype) profile. No default: a caller that forgot the model would silently drive a
///        towel dryer as a radiator.
/// @return The profile, or nullptr when no climate entity drives this device.
const HeatingProfile *find_heating_profile(DeviceType type, uint8_t subtype, DeviceModel model);
 
/// @brief Look up the heating profile of a device record: its type, subtype and declared model.
/// @param dev The device.
/// @return The profile, or nullptr when no climate entity drives this device.
const HeatingProfile *find_heating_profile(const IoDevice &dev);
 
/// @brief Does a climate entity drive this device over the private register protocol?
/// @details The gate for every CMD_WRITE_PRIVATE frame the hub sends: a heater that takes the standard
///          EXECUTE must never be sent a register write. The control path is a fact of the
///          (type, subtype): a model's profile keeps the path of the profile above it (checked by
///          heating_profiles_test.cpp), so this and the other path predicates take no model.
/// @param type Node type.
/// @param subtype Subtype.
/// @return true when the profile's control path is HeatingControlPath::PRIVATE_REGISTERS.
bool device_uses_heating_registers(DeviceType type, uint8_t subtype);
 
/// @brief May the diagnostic register-read probes (`register_00`, `register_01`) be sent to this device?
/// @details A read of a register is the request climate support already sends to register-protocol
///          heaters, so those are allowed, and so is a water heater (device_feature::WATER_HEATER), whose
///          readings are family-0x00 registers. Every other kind -- covers, lights, switches, locks, the
///          standard-EXECUTE heaters -- is refused. This gates the probe and the register reads only; a
///          heater's register writes stay behind device_uses_heating_registers(), a water heater's
///          behind its WATER_HEATER bit.
/// @param type Node type.
/// @param subtype Subtype.
/// @return true for a register-protocol heater or a water heater.
bool device_accepts_register_probe(DeviceType type, uint8_t subtype);
 
/// @brief Does a climate entity drive this device with heating levels?
/// @param type Node type.
/// @param subtype Subtype.
/// @return true when the profile's control path is HeatingControlPath::HEATING_LEVEL.
bool device_uses_heating_levels(DeviceType type, uint8_t subtype);
 
/// @brief Does a climate entity drive this device with a temperature or an alias in the main parameter?
/// @param type Node type.
/// @param subtype Subtype.
/// @return true when the profile's control path is HeatingControlPath::TEMPERATURE_EXECUTE.
bool device_uses_heating_temperature(DeviceType type, uint8_t subtype);
 
/// @brief Encode a temperature as a main parameter over an encoding range.
/// @details `round((celsius - min) / (max - min) * HEATING_TEMPERATURE_MP_SPAN)`, clamped to the span.
/// @param celsius Temperature in degrees Celsius; must be finite.
/// @param min_c Lower end of the device's encoding range.
/// @param max_c Upper end of the device's encoding range; must exceed `min_c`.
/// @param[out] main_parameter The encoded value.
/// @return false for a non-finite temperature or an empty range; `main_parameter` is then untouched.
bool encode_temperature_main_parameter(float celsius, float min_c, float max_c, uint16_t &main_parameter);
 
/// @brief Decode a main parameter as a temperature over an encoding range (the inverse of
/// encode_temperature_main_parameter()).
/// @param main_parameter The 16-bit value from a status reply.
/// @param min_c Lower end of the device's encoding range.
/// @param max_c Upper end of the device's encoding range; must exceed `min_c`.
/// @param[out] celsius The temperature.
/// @return false when the value is above the span (an alias or a marker, not a temperature) or the
///         range is empty.
bool decode_temperature_main_parameter(uint16_t main_parameter, float min_c, float max_c, float &celsius);
 
/// @brief Main parameter of a heating level, as it travels in an EXECUTE and in a status reply.
/// @param level Level low byte (heating_level::*).
/// @return HEATING_LEVEL_MP_PREFIX in the high byte, `level` in the low byte.
constexpr uint16_t heating_level_main_parameter(uint8_t level) {
  return static_cast<uint16_t>((HEATING_LEVEL_MP_PREFIX << BITS_PER_BYTE) | level);
}
 
/// @brief Main parameter of a prefixed value (a level or an alias).
/// @param prefix High byte (HEATING_LEVEL_MP_PREFIX or HEATING_ALIAS_MP_PREFIX).
/// @param low Low byte.
/// @return The 16-bit main parameter.
constexpr uint16_t heating_prefixed_main_parameter(uint8_t prefix, uint8_t low) {
  return static_cast<uint16_t>((prefix << BITS_PER_BYTE) | low);
}
 
/// @brief Read a heating level out of a main parameter.
/// @param main_parameter The 16-bit value from a status reply.
/// @param[out] level Level low byte.
/// @return true when the value is a heating level (high byte HEATING_LEVEL_MP_PREFIX).
bool decode_heating_level(uint16_t main_parameter, uint8_t &level);
 
/// @brief Find what a device-reported wire value shows on the card.
/// @param profile The device's profile.
/// @param wire Mode register value or level low byte.
/// @return The matching entry, or nullptr when the value is not one the profile maps.
const HeatingObservedState *find_observed_state(const HeatingProfile &profile, uint8_t wire);
 
/// @brief Find what a device-reported value of the preset register (`preset_fn`) shows on the card.
/// @param profile The device's profile.
/// @param wire Value of the profile's preset register.
/// @return The matching entry, or nullptr when the profile has no preset table or does not map the value.
const HeatingObservedState *find_observed_preset(const HeatingProfile &profile, uint8_t wire);
 
/// @brief Does the heater's own programme run right now, with no timed run on top of it?
/// @details True when the profile has a programme period, its mode register reads the programme value and
///          its preset register reads the idle value. An unread register is not the programme.
/// @param profile The device's profile.
/// @param readings What the hub has read from the heater.
/// @return false for a profile without a programme period.
bool programme_period_active(const HeatingProfile &profile, const HeatingReadings &readings);
 
/// @brief Which period of its programme a heater is in, and the temperature it heats to.
/// @details Compares in whole tenths of a degree: the temperature in force equals the comfort setpoint
///          (comfort period) or the comfort setpoint minus the setback (eco period). Anything else, or a
///          register not read yet, names no period but still reports the temperature in force.
/// @param profile The device's profile.
/// @param readings What the hub has read from the heater.
/// @return `active` false when the programme does not run; otherwise the period's preset index and the
///         temperature in force.
ProgrammePeriodState resolve_programme_period(const HeatingProfile &profile, const HeatingReadings &readings);
 
/// @brief Drop the temperature in force from the readings when the programme does not run.
/// @details Keeps a value from an earlier run of the programme from being shown when the heater returns to it.
/// @param profile The device's profile.
/// @param[in,out] readings What the hub has read from the heater.
void clear_inactive_programme_reading(const HeatingProfile &profile, HeatingReadings &readings);
 
}  // namespace home_io_control
}  // namespace esphome