platform_cover.h

Go to the documentation of this file.

#pragma once
 
/// @file platform_cover.h
/// @brief ESPHome cover entity for IO‑Homecontrol devices.
/// @ingroup hioc_platforms
///
/// Maps IO‑Homecontrol devices (shutters, awnings, blinds) to Home Assistant cover entities
/// with position control and real‑time feedback.
///
/// Position mapping between Home Assistant and IO‑Homecontrol:
///   HA:  1.0 = fully open,  0.0 = fully closed
///   IO:  0   = fully open,  100  = fully closed
/// The conversion is: ha_position = 1.0 - (io_position / 100.0)
///
/// @warning Some device types (e.g., horizontal awnings) have inverted position mapping
///          by default (device_feature::INVERTED). The invert
///          flag flips the HA↔IO conversion accordingly. Ensure the device's actual
///          behavior matches the mapping, or set invert_position accordingly.
 
#include "esphome/core/component.h"
#include "esphome/components/cover/cover.h"
#include "platform_entity_base.h"
 
namespace esphome {
namespace home_io_control {
 
/// @brief Cover entity representing an IO‑Homecontrol shutter/awning/blind.
/// @ingroup hioc_platforms
///
/// The device-binding setters, setup() registration ritual and poll-interval dump line come
/// from DeviceBoundEntity; the richer position/tilt/movement mapping and the invert option
/// stay here.
class IOHomeCover : public cover::Cover, public Component, public DeviceBoundEntity {
 public:
  IOHomeCover() = default;
  /// @brief Initialize the cover entity (register device, subscribe to updates, schedule initial status poll).
  void setup() override;
  /// @brief Dump configuration to log.
  void dump_config() override;
  /// @brief Get setup priority (DATA so we have device registry available).
  /// @return setup_priority::DATA.
  [[nodiscard]] float get_setup_priority() const override { return setup_priority::DATA; }
 
  /// @brief Return the traits object describing this cover's capabilities.
  /// @return CoverTraits configured for position (with intermediate positions only), stop, optional
  ///         tilt, and assumed state for a cover that is only open or closed.
  cover::CoverTraits get_traits() override;
 
  /// @brief Enable or disable position inversion.
  /// Some devices (e.g., horizontal awnings) report reversed open/close semantics.
  /// @param invert True to invert the mapping (HA 1.0 → IO 0, HA 0.0 → IO 100).
  void set_invert_position(bool invert) {
    this->invert_ = invert;
    this->invert_explicit_ = true;
  }
  /// @brief Opt this cover into the periodic rain sensor poll (from YAML `rain_sensor_poll_interval`).
  /// @param interval_ms Poll interval in milliseconds; zero (the default) means no poll.
  void set_rain_sensor_poll_interval(uint32_t interval_ms) { this->rain_sensor_poll_interval_ms_ = interval_ms; }
  /// @brief Opt this cover into the periodic sun level poll (from YAML `sun_level_poll_interval`).
  /// @param interval_ms Poll interval in milliseconds; 0 = not opted in.
  void set_sun_level_poll_interval(uint32_t interval_ms) { this->sun_level_poll_interval_ms_ = interval_ms; }
  /// @brief Opt this cover into the periodic battery level poll (from YAML `battery_level_poll_interval`).
  /// @param interval_ms Poll interval in milliseconds; 0 = not opted in.
  void set_battery_level_poll_interval(uint32_t interval_ms) { this->battery_level_poll_interval_ms_ = interval_ms; }
  /// @brief Opt this cover into the status refresh at rest (from YAML `status_refresh_interval`).
  /// @param interval_ms Refresh interval in milliseconds; zero (the default) means no refresh.
  void set_status_refresh_interval(uint32_t interval_ms) { this->status_refresh_interval_ms_ = interval_ms; }
  /// @brief Query whether this device takes intermediate positions (a slider) or only open / close / stop.
  /// @return true if the device has device_feature::LEVELS.
  [[nodiscard]] bool supports_intermediate_positions() const;
  /// @brief Query whether this device supports tilt (slat angle) control.
  /// @return true if the device has device_feature::TILT.
  [[nodiscard]] bool supports_tilt() const;
 
 protected:
  /// @brief Handle cover commands from Home Assistant (open/close/stop/set_position).
  /// @param call CoverCall containing the requested operation.
  void control(const cover::CoverCall &call) override;
  /// @brief Callback invoked when the underlying device state changes.
  /// @param id Device ID that updated.
  /// @param dev Updated IoDevice state.
  void on_device_update_(const std::string &id, const IoDevice &dev);
  /// @brief Resolve the current inversion mode.
  /// @return Explicit YAML override when set, otherwise the runtime device profile.
  [[nodiscard]] bool effective_invert_() const;
  /// @brief Infer HA movement direction from successive IO positions when the protocol target is unknown.
  /// @param invert Effective inversion mode for this device.
  /// @param current_io_position Latest reported IO position (0=open, 100=closed).
  /// @return OPENING, CLOSING, or IDLE when no direction can be inferred yet.
  [[nodiscard]] cover::CoverOperation infer_operation_from_position_delta_(bool invert,
                                                                           float current_io_position) const;
 
  bool invert_{false};
  bool invert_explicit_{false};
  float last_io_position_{UNKNOWN_POSITION};
  uint32_t rain_sensor_poll_interval_ms_{0};    ///< 0 = not opted in; no rain poll is scheduled.
  uint32_t sun_level_poll_interval_ms_{0};      ///< 0 = not opted in; no sun level poll is scheduled.
  uint32_t battery_level_poll_interval_ms_{0};  ///< 0 = not opted in; no battery level poll is scheduled.
  uint32_t status_refresh_interval_ms_{0};      ///< 0 = not opted in; no status refresh is scheduled.
};
 
}  // namespace home_io_control
}  // namespace esphome