platform_cover.cpp

Go to the documentation of this file.

/// @file platform_cover.cpp
/// @brief ESPHome cover entity for IO-Homecontrol devices.
/// @ingroup hioc_platforms
 
#include "platform_cover.h"
#include "entity_helpers.h"
#include "esphome/core/log.h"
 
namespace esphome {
namespace home_io_control {
 
static const char *const TAG = "home_io_control.cover";
 
namespace {
 
/// IO position of a fully closed (non-inverted) device and of a fully open one.
constexpr float IO_POSITION_CLOSED = 100.0F;
constexpr float IO_POSITION_OPEN = 0.0F;
 
/// Movement direction implied by travelling from one IO position toward another.
///
/// One rule for every direction question this entity asks, so the inversion handling and the
/// "no information" case cannot drift between call sites. Equal endpoints, or either end unknown,
/// mean the direction is not known — never a direction picked by whichever way a comparison
/// happens to fall. Pure position arithmetic, so it lives here rather than on the entity.
/// @param invert Whether this device's open/close mapping is inverted.
/// @param from_io_position Starting IO position, or UNKNOWN_POSITION.
/// @param to_io_position Destination IO position, or UNKNOWN_POSITION.
cover::CoverOperation operation_toward(bool invert, float from_io_position, float to_io_position) {
  if (from_io_position == UNKNOWN_POSITION || to_io_position == UNKNOWN_POSITION ||
      from_io_position == to_io_position) {
    return cover::COVER_OPERATION_IDLE;
  }
  const bool opening = invert ? (to_io_position > from_io_position) : (to_io_position < from_io_position);
  return opening ? cover::COVER_OPERATION_OPENING : cover::COVER_OPERATION_CLOSING;
}
 
/// The direction toward an end position, or IDLE for an intermediate or unknown target.
/// @param invert True when the cover's IO scale runs the other way (0 = closed).
/// @param to_io_position Target on the IO scale (0-100).
cover::CoverOperation operation_toward_end(bool invert, float to_io_position) {
  const float closed_position = invert ? IO_POSITION_OPEN : IO_POSITION_CLOSED;
  const float open_position = invert ? IO_POSITION_CLOSED : IO_POSITION_OPEN;
  if (to_io_position == closed_position)
    return cover::COVER_OPERATION_CLOSING;
  if (to_io_position == open_position)
    return cover::COVER_OPERATION_OPENING;
  return cover::COVER_OPERATION_IDLE;
}
 
/// Direction of a device that is moving with its live position withheld, from the last position
/// seen to the target.
///
/// The last seen position says nothing when it equals the target: a door that opened from closed
/// reports no position on the way, so a Close sent mid-travel compares 100 with 100 (issue #163). An
/// end-position target still names the direction, but a device can also report its pre-command
/// target while starting the other way, so it is trusted only when it is the hub's own command or the
/// direction already shown. With no position seen at all there is no start point, and the direction
/// stays unknown.
/// @param invert True when the cover's IO scale runs the other way (0 = closed).
/// @param previous_io_position Last position the device reported, or UNKNOWN_POSITION.
/// @param target Effective target (prediction or observation).
/// @param own_command True while the target is the hub's own prediction.
/// @param shown Direction the entity showed before this report.
cover::CoverOperation operation_with_withheld_position(bool invert, float previous_io_position, float target,
                                                       bool own_command, cover::CoverOperation shown) {
  if (previous_io_position != target)
    return operation_toward(invert, previous_io_position, target);
  const cover::CoverOperation toward_end = operation_toward_end(invert, target);
  return own_command || toward_end == shown ? toward_end : cover::COVER_OPERATION_IDLE;
}
 
}  // namespace
 
void IOHomeCover::setup() {
  // A cover passes its explicit YAML inversion; without one the kind's default applies. The rest of
  // the registration ritual is shared with the other entity types.
  this->register_device_binding_(
      this, DeviceCapabilityClass::COVER, this->invert_explicit_ ? std::optional<bool>(this->invert_) : std::nullopt,
      [this](const std::string &id, const IoDevice &dev) { this->on_device_update_(id, dev); });
  // After the registration above: the hub only schedules a poll for a registered device.
  if (this->rain_sensor_poll_interval_ms_ != 0)
    this->parent_->set_device_rain_poll_interval(this->device_id_, this->rain_sensor_poll_interval_ms_);
  if (this->sun_level_poll_interval_ms_ != 0)
    this->parent_->set_device_sun_poll_interval(this->device_id_, this->sun_level_poll_interval_ms_);
  if (this->battery_level_poll_interval_ms_ != 0)
    this->parent_->set_device_battery_level_poll_interval(this->device_id_, this->battery_level_poll_interval_ms_);
  if (this->status_refresh_interval_ms_ != 0)
    this->parent_->set_device_status_refresh_interval(this->device_id_, this->status_refresh_interval_ms_);
}
 
cover::CoverTraits IOHomeCover::get_traits() {
  auto traits = cover::CoverTraits();
  // A device without intermediate positions (a garage opener of subtype 58, say) gets open / close /
  // stop and no slider. It also gets assumed state: Home Assistant disables Open on a position-less
  // cover that shows open and Close on one that shows closed, and this cover shows open for every
  // position that is not fully closed, so a door stopped half-way would otherwise offer no Open.
  const bool levels = this->supports_intermediate_positions();
  traits.set_supports_position(levels);  // Slider in HA UI
  traits.set_supports_stop(true);        // Stop button in HA UI
  traits.set_supports_tilt(this->supports_tilt());
  traits.set_is_assumed_state(!levels);  // A discrete cover is open or closed; anything between is a guess
  return traits;
}
 
bool IOHomeCover::supports_intermediate_positions() const {
  return has_feature(this->device_features_(DeviceCapabilityClass::COVER), device_feature::LEVELS);
}
 
bool IOHomeCover::supports_tilt() const {
  return has_feature(this->device_features_(DeviceCapabilityClass::COVER), device_feature::TILT);
}
 
bool IOHomeCover::effective_invert_() const {
  if (this->invert_explicit_)
    return this->invert_;
  if (this->parent_ == nullptr)
    return false;
  const auto *dev = this->parent_->get_device(this->device_id_);
  return dev != nullptr && dev->inverted;
}
 
cover::CoverOperation IOHomeCover::infer_operation_from_position_delta_(bool invert, float current_io_position) const {
  return operation_toward(invert, this->last_io_position_, current_io_position);
}
 
void IOHomeCover::control(const cover::CoverCall &call) {
  // Optimistic state gives immediate HA UI feedback for the queue-dispatch + TX/response gap;
  // the queued command's own response (update_device_status_()) supersedes the prediction, and a
  // failed command withdraws it (DeviceRegistry::rollback_optimistic()). No-op when this device
  // has optimistic_state=false (see
  // DeviceRegistry::apply_optimistic_target()/apply_optimistic_stop()).
  if (call.get_stop()) {
    this->parent_->apply_optimistic_stop(this->device_id_);
    this->parent_->queue_device_command(this->device_id_, CoverCommand::STOP);
    return;
  }
 
  const auto &tilt_opt = call.get_tilt();
  const auto &position_opt = call.get_position();
 
  // Combined position+tilt in one atomic command when both are present.
  /// @todo Monitor https://github.com/home-assistant/core/issues/174533 — if HA adds a combined
  ///       cover.set_cover_position_and_tilt action, this branch would be exercised directly from
  ///       a single CoverCall. The queue coalescing in queue_set_device_position/tilt remains a
  ///       useful optimization for the two-separate-calls path regardless.
  // Position/tilt fraction -> IO percent uses detail::round_percent() (entity_helpers.h) — rounds
  // rather than truncates, since HA quantizes call values to 0-255 before they reach us (its
  // "50%" is 128/255=0.502, not exactly 0.5) and a truncating cast would compound that into a
  // consistent ~1% bias (caught on hardware; see PlatformCover.ControlRoundsQuantizedPosition-
  // InsteadOfTruncating).
  if (position_opt.has_value() && tilt_opt.has_value() && this->supports_tilt()) {
    float const ha_pos = *position_opt;
    const bool invert = this->effective_invert_();
    uint8_t const io_pos = invert ? detail::round_percent(ha_pos) : detail::round_percent(1.0F - ha_pos);
    auto const tilt = detail::round_percent(*tilt_opt);
    this->parent_->apply_optimistic_target(this->device_id_, io_pos);
    this->parent_->apply_optimistic_tilt(this->device_id_, tilt);
    this->parent_->queue_set_device_position_and_tilt(this->device_id_, io_pos, tilt);
    return;
  }
 
  if (tilt_opt.has_value()) {
    auto const tilt = detail::round_percent(*tilt_opt);
    // Position commands get their optimistic feedback from apply_optimistic_target() above; tilt
    // needs its own because a tilt command's reply carries no usable slat angle, so without this
    // the slider snaps back to the pre-command angle until the next status poll.
    this->parent_->apply_optimistic_tilt(this->device_id_, tilt);
    this->parent_->queue_set_device_tilt(this->device_id_, tilt);
    return;
  }
 
  if (position_opt.has_value()) {
    float const ha_pos = *position_opt;  // HA: 1.0 = fully open, 0.0 = fully closed
    const bool invert = this->effective_invert_();
 
    // Convert HA position (0.0-1.0) to IO position (0-100)
    // Standard: HA 1.0 (open) → IO 0 (open), HA 0.0 (closed) → IO 100 (closed)
    // Inverted: HA 1.0 (open) → IO 100, HA 0.0 (closed) → IO 0
    // (used for devices like horizontal awnings where the IO convention is reversed)
    const uint8_t io_pos = invert ? detail::round_percent(ha_pos) : detail::round_percent(1.0F - ha_pos);
 
    this->parent_->apply_optimistic_target(this->device_id_, io_pos);
    this->parent_->queue_set_device_position(this->device_id_, io_pos);
  }
}
 
void IOHomeCover::on_device_update_(const std::string &id, const IoDevice &dev) {
  if (id != this->device_id_)
    return;
 
  const bool invert = this->effective_invert_();
  const float previous_io_position = this->last_io_position_;
  const cover::CoverOperation previous_operation = this->current_operation;
 
  // Predictions win over the last observation, per axis (see OptimisticState). `position` is
  // observed-only — the hub never guesses a live position — so it is read directly.
  const float eff_tilt = effective_tilt(dev);
  const bool eff_stopped = effective_is_stopped(dev);
  const float eff_target = effective_target(dev);
 
  if (!this->supports_intermediate_positions()) {
    // Open or closed, nothing between: closed only when the device reports fully closed (IO 100,
    // or IO 0 when inverted); every other report, an unknown one included, shows open. A door
    // stopped mid-travel reports an unknown position (issue #163) and is not closed. Written for
    // every report, because an unknown one must not leave the last state standing.
    const float closed_position = invert ? IO_POSITION_OPEN : IO_POSITION_CLOSED;
    this->position = dev.position == closed_position ? cover::COVER_CLOSED : cover::COVER_OPEN;
  } else if (dev.position != UNKNOWN_POSITION) {
    // Convert IO position (0-100) back to HA position (0.0-1.0)
    float ha_pos;
    if (invert) {
      ha_pos = detail::whole_percent(dev.position) / 100.0F;
    } else {
      ha_pos = 1.0F - (detail::whole_percent(dev.position) / 100.0F);
    }
 
    this->position = ha_pos;
  }
 
  if (this->supports_tilt() && eff_tilt != UNKNOWN_POSITION) {
    this->tilt = detail::whole_percent(eff_tilt) / 100.0F;
  }
 
  // Determine movement direction for the HA UI animation
  if (eff_stopped) {
    this->current_operation = cover::COVER_OPERATION_IDLE;
  } else if (eff_target != UNKNOWN_POSITION && dev.position != UNKNOWN_POSITION && eff_target != dev.position) {
    // Travelling toward a target we can see, from a position we can see.
    this->current_operation = operation_toward(invert, dev.position, eff_target);
  } else if (eff_target != UNKNOWN_POSITION && dev.position == UNKNOWN_POSITION) {
    // Moving, target known, live position withheld. Not every actuator publishes intermediate
    // positions: some report current = POS_UNKNOWN (0xD4) on every poll mid-travel (flagging
    // themselves "moving" vs. "at rest" instead), and only report a real value once they settle.
    // The last position we *did* see is enough to say which way the device is going, and
    // `this->position` keeps displaying that value meanwhile rather than blanking, because the
    // assignment above is skipped for an unknown reading.
    this->current_operation = operation_with_withheld_position(
        invert, previous_io_position, eff_target, dev.optimistic.target != UNKNOWN_POSITION, previous_operation);
  } else if (dev.position != UNKNOWN_POSITION) {
    // Either no target at all, or a target equal to the current position while the device says it
    // is moving. The second case is not a standstill: a device flags itself moving while still
    // reporting its *pre-command* target for roughly the first second, so equal endpoints here mean
    // "no information yet", not "closing". Fall through to the delta inference, which reports IDLE
    // until an actual position change reveals the direction.
    this->current_operation = this->infer_operation_from_position_delta_(invert, dev.position);
  }
 
  if (dev.position != UNKNOWN_POSITION) {
    this->last_io_position_ = dev.position;
  } else {
    this->last_io_position_ = previous_io_position;
  }
 
  this->publish_state();
}
 
void IOHomeCover::dump_config() {
  LOG_COVER("", "IO-Homecontrol Cover", this);
  ESP_LOGCONFIG(TAG, "  Device ID: %s", this->device_id_.c_str());
  ESP_LOGCONFIG(TAG, "  Invert Position Override: %s", this->invert_explicit_ ? YESNO(this->invert_) : "AUTO");
  this->log_poll_interval_config_(TAG);
  if (this->rain_sensor_poll_interval_ms_ != 0)
    ESP_LOGCONFIG(TAG, "  Rain Sensor Poll Interval: %" PRIu32 " ms", this->rain_sensor_poll_interval_ms_);
  if (this->sun_level_poll_interval_ms_ != 0)
    ESP_LOGCONFIG(TAG, "  Sun Level Poll Interval: %" PRIu32 " ms", this->sun_level_poll_interval_ms_);
  if (this->battery_level_poll_interval_ms_ != 0)
    ESP_LOGCONFIG(TAG, "  Battery Level Poll Interval: %" PRIu32 " ms", this->battery_level_poll_interval_ms_);
  if (this->status_refresh_interval_ms_ != 0)
    ESP_LOGCONFIG(TAG, "  Status Refresh Interval: %" PRIu32 " ms", this->status_refresh_interval_ms_);
  ESP_LOGCONFIG(TAG, "  Supports Tilt: %s", YESNO(this->supports_tilt()));
}
 
}  // namespace home_io_control
}  // namespace esphome