Add support for fan preset modes (#5694)

Co-authored-by: J. Nick Koston <nick@koston.org>

esphome/components/fan/__init__.py

@@ -18,6 +18,7 @@ from esphome.const import (
     CONF_ON_SPEED_SET,
     CONF_ON_TURN_OFF,
     CONF_ON_TURN_ON,
+    CONF_ON_PRESET_SET,
     CONF_TRIGGER_ID,
     CONF_DIRECTION,
     CONF_RESTORE_MODE,
@@ -57,6 +58,9 @@ CycleSpeedAction = fan_ns.class_("CycleSpeedAction", automation.Action)
 FanTurnOnTrigger = fan_ns.class_("FanTurnOnTrigger", automation.Trigger.template())
 FanTurnOffTrigger = fan_ns.class_("FanTurnOffTrigger", automation.Trigger.template())
 FanSpeedSetTrigger = fan_ns.class_("FanSpeedSetTrigger", automation.Trigger.template())
+FanPresetSetTrigger = fan_ns.class_(
+    "FanPresetSetTrigger", automation.Trigger.template()
+)
 
 FanIsOnCondition = fan_ns.class_("FanIsOnCondition", automation.Condition.template())
 FanIsOffCondition = fan_ns.class_("FanIsOffCondition", automation.Condition.template())
@@ -101,9 +105,46 @@ FAN_SCHEMA = cv.ENTITY_BASE_SCHEMA.extend(cv.MQTT_COMMAND_COMPONENT_SCHEMA).exte
                 cv.GenerateID(CONF_TRIGGER_ID): cv.declare_id(FanSpeedSetTrigger),
             }
         ),
+        cv.Optional(CONF_ON_PRESET_SET): automation.validate_automation(
+            {
+                cv.GenerateID(CONF_TRIGGER_ID): cv.declare_id(FanPresetSetTrigger),
+            }
+        ),
     }
 )
 
+_PRESET_MODES_SCHEMA = cv.All(
+    cv.ensure_list(cv.string_strict),
+    cv.Length(min=1),
+)
+
+
+def validate_preset_modes(value):
+    # Check against defined schema
+    value = _PRESET_MODES_SCHEMA(value)
+
+    # Ensure preset names are unique
+    errors = []
+    presets = set()
+    for i, preset in enumerate(value):
+        # If name does not exist yet add it
+        if preset not in presets:
+            presets.add(preset)
+            continue
+
+        # Otherwise it's an error
+        errors.append(
+            cv.Invalid(
+                f"Found duplicate preset name '{preset}'. Presets must have unique names.",
+                [i],
+            )
+        )
+
+    if errors:
+        raise cv.MultipleInvalid(errors)
+
+    return value
+
 
 async def setup_fan_core_(var, config):
     await setup_entity(var, config)
@@ -154,6 +195,9 @@ async def setup_fan_core_(var, config):
     for conf in config.get(CONF_ON_SPEED_SET, []):
         trigger = cg.new_Pvariable(conf[CONF_TRIGGER_ID], var)
         await automation.build_automation(trigger, [], conf)
+    for conf in config.get(CONF_ON_PRESET_SET, []):
+        trigger = cg.new_Pvariable(conf[CONF_TRIGGER_ID], var)
+        await automation.build_automation(trigger, [], conf)
 
 
 async def register_fan(var, config):

esphome/components/fan/automation.h

@@ -165,5 +165,23 @@ class FanSpeedSetTrigger : public Trigger<> {
   int last_speed_;
 };
 
+class FanPresetSetTrigger : public Trigger<> {
+ public:
+  FanPresetSetTrigger(Fan *state) {
+    state->add_on_state_callback([this, state]() {
+      auto preset_mode = state->preset_mode;
+      auto should_trigger = preset_mode != this->last_preset_mode_;
+      this->last_preset_mode_ = preset_mode;
+      if (should_trigger) {
+        this->trigger();
+      }
+    });
+    this->last_preset_mode_ = state->preset_mode;
+  }
+
+ protected:
+  std::string last_preset_mode_;
+};
+
 }  // namespace fan
 }  // namespace esphome

esphome/components/fan/fan.cpp

@@ -32,9 +32,12 @@ void FanCall::perform() {
   if (this->direction_.has_value()) {
     ESP_LOGD(TAG, "  Direction: %s", LOG_STR_ARG(fan_direction_to_string(*this->direction_)));
   }
-
+  if (!this->preset_mode_.empty()) {
+    ESP_LOGD(TAG, "  Preset Mode: %s", this->preset_mode_.c_str());
+  }
   this->parent_.control(*this);
 }
+
 void FanCall::validate_() {
   auto traits = this->parent_.get_traits();
 
@@ -62,6 +65,15 @@ void FanCall::validate_() {
     ESP_LOGW(TAG, "'%s' - This fan does not support directions!", this->parent_.get_name().c_str());
     this->direction_.reset();
   }
+
+  if (!this->preset_mode_.empty()) {
+    const auto &preset_modes = traits.supported_preset_modes();
+    if (preset_modes.find(this->preset_mode_) == preset_modes.end()) {
+      ESP_LOGW(TAG, "'%s' - This fan does not support preset mode '%s'!", this->parent_.get_name().c_str(),
+               this->preset_mode_.c_str());
+      this->preset_mode_.clear();
+    }
+  }
 }
 
 FanCall FanRestoreState::to_call(Fan &fan) {
@@ -70,6 +82,14 @@ FanCall FanRestoreState::to_call(Fan &fan) {
   call.set_oscillating(this->oscillating);
   call.set_speed(this->speed);
   call.set_direction(this->direction);
+
+  if (fan.get_traits().supports_preset_modes()) {
+    // Use stored preset index to get preset name
+    const auto &preset_modes = fan.get_traits().supported_preset_modes();
+    if (this->preset_mode < preset_modes.size()) {
+      call.set_preset_mode(*std::next(preset_modes.begin(), this->preset_mode));
+    }
+  }
   return call;
 }
 void FanRestoreState::apply(Fan &fan) {
@@ -77,6 +97,14 @@ void FanRestoreState::apply(Fan &fan) {
   fan.oscillating = this->oscillating;
   fan.speed = this->speed;
   fan.direction = this->direction;
+
+  if (fan.get_traits().supports_preset_modes()) {
+    // Use stored preset index to get preset name
+    const auto &preset_modes = fan.get_traits().supported_preset_modes();
+    if (this->preset_mode < preset_modes.size()) {
+      fan.preset_mode = *std::next(preset_modes.begin(), this->preset_mode);
+    }
+  }
   fan.publish_state();
 }
 
@@ -100,7 +128,9 @@ void Fan::publish_state() {
   if (traits.supports_direction()) {
     ESP_LOGD(TAG, "  Direction: %s", LOG_STR_ARG(fan_direction_to_string(this->direction)));
   }
-
+  if (traits.supports_preset_modes() && !this->preset_mode.empty()) {
+    ESP_LOGD(TAG, "  Preset Mode: %s", this->preset_mode.c_str());
+  }
   this->state_callback_.call();
   this->save_state_();
 }
@@ -143,20 +173,36 @@ void Fan::save_state_() {
   state.oscillating = this->oscillating;
   state.speed = this->speed;
   state.direction = this->direction;
+
+  if (this->get_traits().supports_preset_modes() && !this->preset_mode.empty()) {
+    const auto &preset_modes = this->get_traits().supported_preset_modes();
+    // Store index of current preset mode
+    auto preset_iterator = preset_modes.find(this->preset_mode);
+    if (preset_iterator != preset_modes.end())
+      state.preset_mode = std::distance(preset_modes.begin(), preset_iterator);
+  }
+
   this->rtc_.save(&state);
 }
 
 void Fan::dump_traits_(const char *tag, const char *prefix) {
-  if (this->get_traits().supports_speed()) {
+  auto traits = this->get_traits();
+
+  if (traits.supports_speed()) {
     ESP_LOGCONFIG(tag, "%s  Speed: YES", prefix);
-    ESP_LOGCONFIG(tag, "%s  Speed count: %d", prefix, this->get_traits().supported_speed_count());
+    ESP_LOGCONFIG(tag, "%s  Speed count: %d", prefix, traits.supported_speed_count());
   }
-  if (this->get_traits().supports_oscillation()) {
+  if (traits.supports_oscillation()) {
     ESP_LOGCONFIG(tag, "%s  Oscillation: YES", prefix);
   }
-  if (this->get_traits().supports_direction()) {
+  if (traits.supports_direction()) {
     ESP_LOGCONFIG(tag, "%s  Direction: YES", prefix);
   }
+  if (traits.supports_preset_modes()) {
+    ESP_LOGCONFIG(tag, "%s  Supported presets:", prefix);
+    for (const std::string &s : traits.supported_preset_modes())
+      ESP_LOGCONFIG(tag, "%s    - %s", prefix, s.c_str());
+  }
 }
 
 }  // namespace fan

esphome/components/fan/fan.h

@@ -72,6 +72,11 @@ class FanCall {
     return *this;
   }
   optional<FanDirection> get_direction() const { return this->direction_; }
+  FanCall &set_preset_mode(const std::string &preset_mode) {
+    this->preset_mode_ = preset_mode;
+    return *this;
+  }
+  std::string get_preset_mode() const { return this->preset_mode_; }
 
   void perform();
 
@@ -83,6 +88,7 @@ class FanCall {
   optional<bool> oscillating_;
   optional<int> speed_;
   optional<FanDirection> direction_{};
+  std::string preset_mode_{};
 };
 
 struct FanRestoreState {
@@ -90,6 +96,7 @@ struct FanRestoreState {
   int speed;
   bool oscillating;
   FanDirection direction;
+  uint8_t preset_mode;
 
   /// Convert this struct to a fan call that can be performed.
   FanCall to_call(Fan &fan);
@@ -107,6 +114,8 @@ class Fan : public EntityBase {
   int speed{0};
   /// The current direction of the fan
   FanDirection direction{FanDirection::FORWARD};
+  // The current preset mode of the fan
+  std::string preset_mode{};
 
   FanCall turn_on();
   FanCall turn_off();

esphome/components/fan/fan_traits.h

@@ -1,3 +1,6 @@
+#include <set>
+#include <utility>
+
 #pragma once
 
 namespace esphome {
@@ -25,12 +28,19 @@ class FanTraits {
   bool supports_direction() const { return this->direction_; }
   /// Set whether this fan supports changing direction
   void set_direction(bool direction) { this->direction_ = direction; }
+  /// Return the preset modes supported by the fan.
+  std::set<std::string> supported_preset_modes() const { return this->preset_modes_; }
+  /// Set the preset modes supported by the fan.
+  void set_supported_preset_modes(const std::set<std::string> &preset_modes) { this->preset_modes_ = preset_modes; }
+  /// Return if preset modes are supported
+  bool supports_preset_modes() const { return !this->preset_modes_.empty(); }
 
  protected:
   bool oscillation_{false};
   bool speed_{false};
   bool direction_{false};
   int speed_count_{};
+  std::set<std::string> preset_modes_{};
 };
 
 }  // namespace fan