proto_heating.cpp

Go to the documentation of this file.

/// @file proto_heating.cpp
/// @brief Pure codec for the private register protocol of 2W heaters (CMD_WRITE_PRIVATE 0x20).
/// @ingroup hioc_protocol
 
#include "proto_heating.h"
 
#include "proto_constants.h"
#include "proto_sizes.h"
 
namespace esphome {
namespace home_io_control {
 
namespace {
 
/// Mask for the low byte of a 16-bit little-endian register value.
constexpr uint16_t LOW_BYTE_MASK = 0xFF;
 
/// Payload length of a read, and of a write that carries no value ({prefix, direction, reg-high, reg-low}).
constexpr size_t PAYLOAD_LEN_HEADER = 4;
/// Payload length for a write that carries one value byte (mode / presence / window detection).
constexpr size_t PAYLOAD_LEN_ONE_VALUE = 5;
/// Payload length for a write of a 16-bit value (the setpoint).
constexpr size_t PAYLOAD_LEN_TWO_VALUE = HEATING_PAYLOAD_MAX_SIZE;
 
/// Wire scale of the setpoint registers: round(degrees * this), little-endian 16-bit.
constexpr float DEGREES_TO_TENTHS = 10.0F;
/// Scale of the room-temperature register: signed hundredths of a degree.
constexpr float HUNDREDTHS_PER_DEGREE = 100.0F;
 
/// Highest regulator-state value the register defines (HeatingRegulatorState::HEATING).
constexpr uint8_t REGULATOR_STATE_MAX = static_cast<uint8_t>(HeatingRegulatorState::HEATING);
/// Highest towel-dryer mode value the register defines (TowelDryerMode::MANUAL).
constexpr uint8_t TOWEL_MODE_MAX = static_cast<uint8_t>(TowelDryerMode::MANUAL);
/// Highest temporary-state value (HeatingTemporaryState::DRYING).
constexpr uint8_t TEMPORARY_STATE_MAX = static_cast<uint8_t>(HeatingTemporaryState::DRYING);
/// Highest working rate: a percentage.
constexpr uint8_t WORKING_RATE_MAX = 100;
 
/// @brief How a register's value maps onto the bytes after the 4-byte header.
enum class HeatingValueKind : uint8_t {
  NONE,            ///< No typed value: logged raw, never decoded.
  TENTHS_U16,      ///< Unsigned 16-bit little-endian tenths of a degree.
  HUNDREDTHS_S16,  ///< Signed 16-bit little-endian hundredths of a degree; -1 is a sensor fault.
  BINARY,          ///< One byte, 0 or 1.
  MODE,            ///< One HeatingMode byte.
  BOUNDED_BYTE,    ///< One byte from 0 to the row's `max_value`: an enumeration (regulator state, towel-dryer
                   ///< mode, temporary state) or a percentage (working rate).
  BOUNDED_U16,     ///< Unsigned 16-bit little-endian integer from 0 to the row's `max_value` (night light brightness).
};
 
/// @brief Who may do what with a register.
enum class HeatingAccess : uint8_t {
  READ_ONLY,   ///< Reads only; a write is refused by the codec.
  READ_WRITE,  ///< Reads and writes.
  WRITE_ONLY,  ///< Writes only; the heater has no readable value for it.
};
 
/// @brief One register of the heater, the single description both directions are built from.
///
/// A request is {HEATING_PAYLOAD_PREFIX, direction, HEATING_REGISTER_HIGH_BYTE, register_low,
/// [value...]}; `direction` is HEATING_DIRECTION_GET or HEATING_DIRECTION_SET.
struct HeatingFunctionDescriptor {
  const char *name;       ///< Action-visible name.
  HeatingFunction fn;     ///< Function this row describes.
  uint8_t register_low;   ///< Payload byte 3: low byte of the 0x01xx register number.
  HeatingAccess access;   ///< Whether the register may be read, written or both.
  HeatingValueKind kind;  ///< How the value maps onto the trailing bytes.
  uint8_t max_value{0};   ///< BOUNDED_BYTE, BOUNDED_U16: highest value a reply may carry and a write may send.
};
 
constexpr HeatingFunctionDescriptor HEATING_FUNCTIONS[] = {
    {"power_on", HeatingFunction::POWER_ON, 0x2C, HeatingAccess::READ_ONLY, HeatingValueKind::NONE},
    {"set_temperature", HeatingFunction::SET_TEMPERATURE, 0x03, HeatingAccess::READ_WRITE,
     HeatingValueKind::TENTHS_U16},
    {"set_mode", HeatingFunction::SET_MODE, 0x00, HeatingAccess::READ_WRITE, HeatingValueKind::MODE},
    {"set_presence", HeatingFunction::SET_PRESENCE, 0x10, HeatingAccess::WRITE_ONLY, HeatingValueKind::BINARY},
    {"set_open_window_detection", HeatingFunction::SET_OPEN_WINDOW_DETECTION, 0x06, HeatingAccess::READ_WRITE,
     HeatingValueKind::BINARY},
    {"midnight_sync", HeatingFunction::MIDNIGHT_SYNC, 0x30, HeatingAccess::READ_ONLY, HeatingValueKind::NONE},
    {"room_temperature", HeatingFunction::ROOM_TEMPERATURE, 0x15, HeatingAccess::READ_ONLY,
     HeatingValueKind::HUNDREDTHS_S16},
    {"regulator_state", HeatingFunction::REGULATOR_STATE, 0x17, HeatingAccess::READ_ONLY,
     HeatingValueKind::BOUNDED_BYTE, REGULATOR_STATE_MAX},
    {"max_setpoint", HeatingFunction::MAX_SETPOINT, 0x02, HeatingAccess::READ_ONLY, HeatingValueKind::TENTHS_U16},
    {"window_open", HeatingFunction::WINDOW_OPEN, 0x0E, HeatingAccess::READ_ONLY, HeatingValueKind::BINARY},
    // Towel-dryer registers: read on two Atlantic Adelis units (corpus atlantic_adelis_probe_*); writing
    // 0x0136 (mode) and 0x013E (boost, drying) is confirmed against the display (issue #202).
    {"towel_mode", HeatingFunction::TOWEL_MODE, 0x36, HeatingAccess::READ_WRITE, HeatingValueKind::BOUNDED_BYTE,
     TOWEL_MODE_MAX},
    {"temporary_state", HeatingFunction::TEMPORARY_STATE, 0x3E, HeatingAccess::READ_WRITE,
     HeatingValueKind::BOUNDED_BYTE, TEMPORARY_STATE_MAX},
    {"working_rate", HeatingFunction::WORKING_RATE, 0x26, HeatingAccess::READ_ONLY, HeatingValueKind::BOUNDED_BYTE,
     WORKING_RATE_MAX},
    // Read on a towel dryer in a programme period (issue #202): the temperature in force in 0x0137 and the
    // eco setback in 0x0104.
    {"temperature_in_force", HeatingFunction::TEMPERATURE_IN_FORCE, 0x37, HeatingAccess::READ_ONLY,
     HeatingValueKind::TENTHS_U16},
    {"eco_setback", HeatingFunction::ECO_SETBACK, 0x04, HeatingAccess::READ_ONLY, HeatingValueKind::TENTHS_U16},
    // Night light registers: read on a Sauter Hekla with the light on and off (issue #222).
    {"night_light", HeatingFunction::NIGHT_LIGHT, 0x44, HeatingAccess::READ_WRITE, HeatingValueKind::BINARY},
    {"night_light_brightness", HeatingFunction::NIGHT_LIGHT_BRIGHTNESS, 0x42, HeatingAccess::READ_WRITE,
     HeatingValueKind::BOUNDED_U16, HEATING_NIGHT_LIGHT_BRIGHTNESS_MAX},
};
 
/// @brief Look up the descriptor for a function.
/// @param fn Function to resolve.
/// @return Pointer into the constexpr table, or nullptr for an out-of-range value.
const HeatingFunctionDescriptor *descriptor_for(HeatingFunction fn) {
  for (const auto &d : HEATING_FUNCTIONS) {
    if (d.fn == fn)
      return &d;
  }
  return nullptr;
}
 
/// @brief Write the 4-byte request header for a row.
void write_header(const HeatingFunctionDescriptor &d, uint8_t direction, uint8_t *out) {
  out[0] = HEATING_PAYLOAD_PREFIX;
  out[1] = direction;
  out[2] = HEATING_REGISTER_HIGH_BYTE;
  out[3] = d.register_low;
}
 
/// @brief Number of value bytes behind the header for a kind.
size_t value_length(HeatingValueKind kind) {
  switch (kind) {
    case HeatingValueKind::NONE:
      return 0;
    case HeatingValueKind::TENTHS_U16:
    case HeatingValueKind::HUNDREDTHS_S16:
    case HeatingValueKind::BOUNDED_U16:
      return 2;
    case HeatingValueKind::BINARY:
    case HeatingValueKind::MODE:
    case HeatingValueKind::BOUNDED_BYTE:
      return 1;
  }
  return 0;
}
 
/// @brief Is `value` an integer from 0 to `max_value`? NaN fails every comparison, so it is refused too.
bool is_bounded_integer(float value, uint8_t max_value) {
  return std::isfinite(value) && value >= 0.0F && value <= static_cast<float>(max_value) && value == std::floor(value);
}
 
/// @brief Write a set request for a 16-bit register: the header, then the value low byte first, the
/// order the register reads back in.
/// @return PAYLOAD_LEN_TWO_VALUE.
size_t write_u16_set(const HeatingFunctionDescriptor &d, uint16_t raw, uint8_t *out) {
  write_header(d, HEATING_DIRECTION_SET, out);
  out[4] = static_cast<uint8_t>(raw & LOW_BYTE_MASK);
  out[PAYLOAD_LEN_TWO_VALUE - 1] = static_cast<uint8_t>(raw >> BITS_PER_BYTE);
  return PAYLOAD_LEN_TWO_VALUE;
}
 
}  // namespace
 
const char *heating_function_name(HeatingFunction fn) {
  const HeatingFunctionDescriptor *d = descriptor_for(fn);
  return d != nullptr ? d->name : "unknown";
}
 
bool heating_function_is_writable(HeatingFunction fn) {
  const HeatingFunctionDescriptor *d = descriptor_for(fn);
  return d != nullptr && d->access != HeatingAccess::READ_ONLY;
}
 
bool heating_function_is_readable(HeatingFunction fn) {
  const HeatingFunctionDescriptor *d = descriptor_for(fn);
  return d != nullptr && d->access != HeatingAccess::WRITE_ONLY;
}
 
bool heating_function_register(HeatingFunction fn, uint8_t &register_low) {
  const HeatingFunctionDescriptor *d = descriptor_for(fn);
  if (d == nullptr)
    return false;
  register_low = d->register_low;
  return true;
}
 
bool heating_reply_echoes_register(const IoFrame &reply, uint8_t reg_hi, uint8_t reg_lo) {
  if (reply.cmd != CMD_WRITE_PRIVATE_ACK || reply.data_len < HEATING_REPLY_VALUE_OFFSET)
    return false;
  const uint8_t *data = reply.data;
  if (data[0] != HEATING_PAYLOAD_PREFIX || data[2] != reg_hi || data[3] != reg_lo)
    return false;
  return data[1] == HEATING_DIRECTION_GET || data[1] == HEATING_DIRECTION_SET;
}
 
size_t encode_heating_read(HeatingFunction fn, uint8_t out[HEATING_PAYLOAD_MAX_SIZE]) {
  const HeatingFunctionDescriptor *d = descriptor_for(fn);
  if (d == nullptr || d->access == HeatingAccess::WRITE_ONLY)
    return 0;
  write_header(*d, HEATING_DIRECTION_GET, out);
  return PAYLOAD_LEN_HEADER;
}
 
size_t encode_heating_register_read(uint8_t reg_hi, uint8_t reg_lo, uint8_t out[HEATING_PAYLOAD_MAX_SIZE]) {
  // The direction is the GET constant and nothing else: this is the one frame builder the register
  // probes use, so it is where "read-only" is enforced.
  out[0] = HEATING_PAYLOAD_PREFIX;
  out[1] = HEATING_DIRECTION_GET;
  out[2] = reg_hi;
  out[3] = reg_lo;
  return PAYLOAD_LEN_HEADER;
}
 
size_t encode_heating_write(HeatingFunction fn, float value, uint8_t out[HEATING_PAYLOAD_MAX_SIZE]) {
  const HeatingFunctionDescriptor *d = descriptor_for(fn);
  // A read-only register is never written, whatever the caller asks: the heater's window sensor and
  // its measurements are not settings.
  if (d == nullptr || d->access == HeatingAccess::READ_ONLY)
    return 0;
 
  switch (d->kind) {
    case HeatingValueKind::TENTHS_U16: {
      // Reject NaN / infinity and anything outside the representable range rather than emitting a
      // wrapped byte.
      if (!std::isfinite(value) || value < HEATING_TEMP_MIN_C || value > HEATING_TEMP_MAX_C)
        return 0;
      // Multiply in float (not double): the float32 product of e.g. 20.55f * 10.0f is exactly
      // 205.5f, and std::round() takes that half away from zero to 206 (0x00CE). Truncating or
      // rounding toward even would both be wrong here.
      // NB: this exactness relies on FLT_EVAL_METHOD == 0 (operands evaluated at their own single
      // precision, no hidden widening to double). That holds on x86-64 SSE and on Xtensa; the
      // proto_heating test pins 20.55 C, which is one ULP from flipping to 0xCD under any
      // excess-precision evaluation.
      return write_u16_set(*d, static_cast<uint16_t>(std::round(value * DEGREES_TO_TENTHS)), out);
    }
 
    case HeatingValueKind::MODE:
      // Exact float match against the four modes this component writes; a non-integral or unknown
      // value (the "external" mode included) is rejected, not coerced.
      if (value != static_cast<float>(HeatingMode::AUTO) && value != static_cast<float>(HeatingMode::MANUAL) &&
          value != static_cast<float>(HeatingMode::PROG) && value != static_cast<float>(HeatingMode::OFF))
        return 0;
      write_header(*d, HEATING_DIRECTION_SET, out);
      out[4] = static_cast<uint8_t>(value);
      return PAYLOAD_LEN_ONE_VALUE;
 
    case HeatingValueKind::BINARY:
      if (value != 0.0F && value != 1.0F)
        return 0;
      write_header(*d, HEATING_DIRECTION_SET, out);
      out[4] = static_cast<uint8_t>(value);
      return PAYLOAD_LEN_ONE_VALUE;
 
    case HeatingValueKind::BOUNDED_BYTE:
      // An integral value inside the register's range; anything else is refused, never truncated.
      if (!is_bounded_integer(value, d->max_value))
        return 0;
      write_header(*d, HEATING_DIRECTION_SET, out);
      out[4] = static_cast<uint8_t>(value);
      return PAYLOAD_LEN_ONE_VALUE;
 
    case HeatingValueKind::BOUNDED_U16:
      // The same rule, in the two-byte form.
      if (!is_bounded_integer(value, d->max_value))
        return 0;
      return write_u16_set(*d, static_cast<uint16_t>(value), out);
 
    case HeatingValueKind::NONE:
    case HeatingValueKind::HUNDREDTHS_S16:
      return 0;  // no writable register has this encoding
  }
  return 0;
}
 
size_t encode_heating_payload(HeatingFunction fn, float value, uint8_t out[HEATING_PAYLOAD_MAX_SIZE]) {
  const HeatingFunctionDescriptor *d = descriptor_for(fn);
  if (d == nullptr)
    return 0;
  return d->access == HeatingAccess::READ_ONLY ? encode_heating_read(fn, out) : encode_heating_write(fn, value, out);
}
 
bool decode_heating_reply(const IoFrame &reply, HeatingFunction fn, float &value) {
  const HeatingFunctionDescriptor *d = descriptor_for(fn);
  if (d == nullptr || d->kind == HeatingValueKind::NONE ||
      !heating_reply_echoes_register(reply, HEATING_REGISTER_HIGH_BYTE, d->register_low))
    return false;
  if (reply.data_len < HEATING_REPLY_VALUE_OFFSET + value_length(d->kind))
    return false;
 
  const uint8_t *v = reply.data + HEATING_REPLY_VALUE_OFFSET;
  const auto raw16 = static_cast<uint16_t>(v[0] | (v[1] << BITS_PER_BYTE));
  switch (d->kind) {
    case HeatingValueKind::TENTHS_U16:
      value = static_cast<float>(raw16) / DEGREES_TO_TENTHS;
      return true;
 
    case HeatingValueKind::HUNDREDTHS_S16: {
      const auto signed_raw = static_cast<int16_t>(raw16);
      value = signed_raw == HEATING_SENSOR_FAULT_RAW ? NAN : static_cast<float>(signed_raw) / HUNDREDTHS_PER_DEGREE;
      return true;
    }
 
    case HeatingValueKind::BINARY:
      if (v[0] > 1)
        return false;
      value = static_cast<float>(v[0]);
      return true;
 
    case HeatingValueKind::MODE:
      if (v[0] > static_cast<uint8_t>(HeatingMode::OFF))
        return false;
      value = static_cast<float>(v[0]);
      return true;
 
    case HeatingValueKind::BOUNDED_BYTE:
      if (v[0] > d->max_value)
        return false;
      value = static_cast<float>(v[0]);
      return true;
 
    case HeatingValueKind::BOUNDED_U16:
      if (raw16 > d->max_value)
        return false;
      value = static_cast<float>(raw16);
      return true;
 
    case HeatingValueKind::NONE:
      return false;
  }
  return false;
}
 
// === HeatingReadings: one table from register to field ===
 
namespace {
 
/// @brief Which field of HeatingReadings holds a register, and how its value is kept.
struct HeatingReadingField {
  HeatingFunction fn;                   ///< Register.
  float HeatingReadings::*temperature;  ///< The field of a register read in degrees (NaN until read), else nullptr.
  int16_t HeatingReadings::*
      integer;  ///< The field of a register read as a byte or a flag (-1 until read), else nullptr.
};
 
/// Every register the readings hold. POWER_ON, SET_PRESENCE and MIDNIGHT_SYNC have no row: they are logged or
/// written, never kept.
constexpr HeatingReadingField HEATING_READING_FIELDS[] = {
    {HeatingFunction::ROOM_TEMPERATURE, &HeatingReadings::room_temperature_c, nullptr},
    {HeatingFunction::SET_TEMPERATURE, &HeatingReadings::setpoint_c, nullptr},
    {HeatingFunction::MAX_SETPOINT, &HeatingReadings::max_setpoint_c, nullptr},
    {HeatingFunction::TEMPERATURE_IN_FORCE, &HeatingReadings::in_force_temperature_c, nullptr},
    {HeatingFunction::ECO_SETBACK, &HeatingReadings::eco_setback_k, nullptr},
    {HeatingFunction::SET_MODE, nullptr, &HeatingReadings::mode},
    {HeatingFunction::REGULATOR_STATE, nullptr, &HeatingReadings::regulator},
    {HeatingFunction::WINDOW_OPEN, nullptr, &HeatingReadings::window_open},
    {HeatingFunction::SET_OPEN_WINDOW_DETECTION, nullptr, &HeatingReadings::open_window_detection},
    {HeatingFunction::TOWEL_MODE, nullptr, &HeatingReadings::towel_mode},
    {HeatingFunction::TEMPORARY_STATE, nullptr, &HeatingReadings::temporary_state},
    {HeatingFunction::WORKING_RATE, nullptr, &HeatingReadings::working_rate},
    {HeatingFunction::NIGHT_LIGHT, nullptr, &HeatingReadings::night_light},
    {HeatingFunction::NIGHT_LIGHT_BRIGHTNESS, nullptr, &HeatingReadings::night_light_brightness},
};
 
/// @return The row of a register, or nullptr for one the readings do not hold.
const HeatingReadingField *reading_field_for(HeatingFunction fn) {
  for (const auto &field : HEATING_READING_FIELDS) {
    if (field.fn == fn)
      return &field;
  }
  return nullptr;
}
 
}  // namespace
 
bool HeatingReadings::store(HeatingFunction fn, float value) {
  const HeatingReadingField *field = reading_field_for(fn);
  if (field == nullptr)
    return false;
  if (field->temperature != nullptr) {
    this->*field->temperature = value;
  } else {
    this->*field->integer = static_cast<int16_t>(value);
  }
  return true;
}
 
bool HeatingReadings::clear(HeatingFunction fn) {
  const HeatingReadingField *field = reading_field_for(fn);
  if (field == nullptr)
    return false;
  if (field->temperature != nullptr) {
    this->*field->temperature = NAN;
  } else {
    this->*field->integer = -1;
  }
  return true;
}
 
bool HeatingReadings::has(HeatingFunction fn) const {
  const HeatingReadingField *field = reading_field_for(fn);
  if (field == nullptr)
    return false;
  return field->temperature != nullptr ? !std::isnan(this->*field->temperature) : this->*field->integer >= 0;
}
 
float HeatingReadings::temperature_of(HeatingFunction fn) const {
  const HeatingReadingField *field = reading_field_for(fn);
  return field != nullptr && field->temperature != nullptr ? this->*field->temperature : NAN;
}
 
int16_t HeatingReadings::value_of(HeatingFunction fn) const {
  // Temperatures and the registers the readings do not hold have no wire byte.
  const HeatingReadingField *field = reading_field_for(fn);
  return field != nullptr && field->integer != nullptr ? this->*field->integer : -1;
}
 
}  // namespace home_io_control
}  // namespace esphome