Add support for fan preset modes (esphome#5694)

Co-authored-by: J. Nick Koston <[email protected]>

esphome/components/api/api.proto

@@ -365,6 +365,7 @@ message ListEntitiesFanResponse {
   bool disabled_by_default = 9;
   string icon = 10;
   EntityCategory entity_category = 11;
+  repeated string supported_preset_modes = 12;
 }
 enum FanSpeed {
   FAN_SPEED_LOW = 0;
@@ -387,6 +388,7 @@ message FanStateResponse {
   FanSpeed speed = 4 [deprecated = true];
   FanDirection direction = 5;
   int32 speed_level = 6;
+  string preset_mode = 7;
 }
 message FanCommandRequest {
   option (id) = 31;
@@ -405,6 +407,8 @@ message FanCommandRequest {
   FanDirection direction = 9;
   bool has_speed_level = 10;
   int32 speed_level = 11;
+  bool has_preset_mode = 12;
+  string preset_mode = 13;
 }
 
 // ==================== LIGHT ====================

esphome/components/api/api_connection.cpp

@@ -293,6 +293,8 @@ bool APIConnection::send_fan_state(fan::Fan *fan) {
   }
   if (traits.supports_direction())
     resp.direction = static_cast<enums::FanDirection>(fan->direction);
+  if (traits.supports_preset_modes())
+    resp.preset_mode = fan->preset_mode;
   return this->send_fan_state_response(resp);
 }
 bool APIConnection::send_fan_info(fan::Fan *fan) {
@@ -307,6 +309,8 @@ bool APIConnection::send_fan_info(fan::Fan *fan) {
   msg.supports_speed = traits.supports_speed();
   msg.supports_direction = traits.supports_direction();
   msg.supported_speed_count = traits.supported_speed_count();
+  for (auto const &preset : traits.supported_preset_modes())
+    msg.supported_preset_modes.push_back(preset);
   msg.disabled_by_default = fan->is_disabled_by_default();
   msg.icon = fan->get_icon();
   msg.entity_category = static_cast<enums::EntityCategory>(fan->get_entity_category());
@@ -328,6 +332,8 @@ void APIConnection::fan_command(const FanCommandRequest &msg) {
   }
   if (msg.has_direction)
     call.set_direction(static_cast<fan::FanDirection>(msg.direction));
+  if (msg.has_preset_mode)
+    call.set_preset_mode(msg.preset_mode);
   call.perform();
 }
 #endif

esphome/components/api/api_pb2.cpp

@@ -1375,6 +1375,10 @@ bool ListEntitiesFanResponse::decode_length(uint32_t field_id, ProtoLengthDelimi
       this->icon = value.as_string();
       return true;
     }
+    case 12: {
+      this->supported_preset_modes.push_back(value.as_string());
+      return true;
+    }
     default:
       return false;
   }
@@ -1401,6 +1405,9 @@ void ListEntitiesFanResponse::encode(ProtoWriteBuffer buffer) const {
   buffer.encode_bool(9, this->disabled_by_default);
   buffer.encode_string(10, this->icon);
   buffer.encode_enum<enums::EntityCategory>(11, this->entity_category);
+  for (auto &it : this->supported_preset_modes) {
+    buffer.encode_string(12, it, true);
+  }
 }
 #ifdef HAS_PROTO_MESSAGE_DUMP
 void ListEntitiesFanResponse::dump_to(std::string &out) const {
@@ -1451,6 +1458,12 @@ void ListEntitiesFanResponse::dump_to(std::string &out) const {
   out.append("  entity_category: ");
   out.append(proto_enum_to_string<enums::EntityCategory>(this->entity_category));
   out.append("\n");
+
+  for (const auto &it : this->supported_preset_modes) {
+    out.append("  supported_preset_modes: ");
+    out.append("'").append(it).append("'");
+    out.append("\n");
+  }
   out.append("}");
 }
 #endif
@@ -1480,6 +1493,16 @@ bool FanStateResponse::decode_varint(uint32_t field_id, ProtoVarInt value) {
       return false;
   }
 }
+bool FanStateResponse::decode_length(uint32_t field_id, ProtoLengthDelimited value) {
+  switch (field_id) {
+    case 7: {
+      this->preset_mode = value.as_string();
+      return true;
+    }
+    default:
+      return false;
+  }
+}
 bool FanStateResponse::decode_32bit(uint32_t field_id, Proto32Bit value) {
   switch (field_id) {
     case 1: {
@@ -1497,6 +1520,7 @@ void FanStateResponse::encode(ProtoWriteBuffer buffer) const {
   buffer.encode_enum<enums::FanSpeed>(4, this->speed);
   buffer.encode_enum<enums::FanDirection>(5, this->direction);
   buffer.encode_int32(6, this->speed_level);
+  buffer.encode_string(7, this->preset_mode);
 }
 #ifdef HAS_PROTO_MESSAGE_DUMP
 void FanStateResponse::dump_to(std::string &out) const {
@@ -1527,6 +1551,10 @@ void FanStateResponse::dump_to(std::string &out) const {
   sprintf(buffer, "%" PRId32, this->speed_level);
   out.append(buffer);
   out.append("\n");
+
+  out.append("  preset_mode: ");
+  out.append("'").append(this->preset_mode).append("'");
+  out.append("\n");
   out.append("}");
 }
 #endif
@@ -1572,6 +1600,20 @@ bool FanCommandRequest::decode_varint(uint32_t field_id, ProtoVarInt value) {
       this->speed_level = value.as_int32();
       return true;
     }
+    case 12: {
+      this->has_preset_mode = value.as_bool();
+      return true;
+    }
+    default:
+      return false;
+  }
+}
+bool FanCommandRequest::decode_length(uint32_t field_id, ProtoLengthDelimited value) {
+  switch (field_id) {
+    case 13: {
+      this->preset_mode = value.as_string();
+      return true;
+    }
     default:
       return false;
   }
@@ -1598,6 +1640,8 @@ void FanCommandRequest::encode(ProtoWriteBuffer buffer) const {
   buffer.encode_enum<enums::FanDirection>(9, this->direction);
   buffer.encode_bool(10, this->has_speed_level);
   buffer.encode_int32(11, this->speed_level);
+  buffer.encode_bool(12, this->has_preset_mode);
+  buffer.encode_string(13, this->preset_mode);
 }
 #ifdef HAS_PROTO_MESSAGE_DUMP
 void FanCommandRequest::dump_to(std::string &out) const {
@@ -1648,6 +1692,14 @@ void FanCommandRequest::dump_to(std::string &out) const {
   sprintf(buffer, "%" PRId32, this->speed_level);
   out.append(buffer);
   out.append("\n");
+
+  out.append("  has_preset_mode: ");
+  out.append(YESNO(this->has_preset_mode));
+  out.append("\n");
+
+  out.append("  preset_mode: ");
+  out.append("'").append(this->preset_mode).append("'");
+  out.append("\n");
   out.append("}");
 }
 #endif

esphome/components/api/api_pb2.h

@@ -472,6 +472,7 @@ class ListEntitiesFanResponse : public ProtoMessage {
   bool disabled_by_default{false};
   std::string icon{};
   enums::EntityCategory entity_category{};
+  std::vector<std::string> supported_preset_modes{};
   void encode(ProtoWriteBuffer buffer) const override;
 #ifdef HAS_PROTO_MESSAGE_DUMP
   void dump_to(std::string &out) const override;
@@ -490,13 +491,15 @@ class FanStateResponse : public ProtoMessage {
   enums::FanSpeed speed{};
   enums::FanDirection direction{};
   int32_t speed_level{0};
+  std::string preset_mode{};
   void encode(ProtoWriteBuffer buffer) const override;
 #ifdef HAS_PROTO_MESSAGE_DUMP
   void dump_to(std::string &out) const override;
 #endif
 
  protected:
   bool decode_32bit(uint32_t field_id, Proto32Bit value) override;
+  bool decode_length(uint32_t field_id, ProtoLengthDelimited value) override;
   bool decode_varint(uint32_t field_id, ProtoVarInt value) override;
 };
 class FanCommandRequest : public ProtoMessage {
@@ -512,13 +515,16 @@ class FanCommandRequest : public ProtoMessage {
   enums::FanDirection direction{};
   bool has_speed_level{false};
   int32_t speed_level{0};
+  bool has_preset_mode{false};
+  std::string preset_mode{};
   void encode(ProtoWriteBuffer buffer) const override;
 #ifdef HAS_PROTO_MESSAGE_DUMP
   void dump_to(std::string &out) const override;
 #endif
 
  protected:
   bool decode_32bit(uint32_t field_id, Proto32Bit value) override;
+  bool decode_length(uint32_t field_id, ProtoLengthDelimited value) override;
   bool decode_varint(uint32_t field_id, ProtoVarInt value) override;
 };
 class ListEntitiesLightResponse : public ProtoMessage {

esphome/components/copy/fan/copy_fan.cpp

@@ -12,13 +12,15 @@ void CopyFan::setup() {
     this->oscillating = source_->oscillating;
     this->speed = source_->speed;
     this->direction = source_->direction;
+    this->preset_mode = source_->preset_mode;
     this->publish_state();
   });
 
   this->state = source_->state;
   this->oscillating = source_->oscillating;
   this->speed = source_->speed;
   this->direction = source_->direction;
+  this->preset_mode = source_->preset_mode;
   this->publish_state();
 }
 
@@ -33,6 +35,7 @@ fan::FanTraits CopyFan::get_traits() {
   traits.set_speed(base.supports_speed());
   traits.set_supported_speed_count(base.supported_speed_count());
   traits.set_direction(base.supports_direction());
+  traits.set_supported_preset_modes(base.supported_preset_modes());
   return traits;
 }
 
@@ -46,6 +49,8 @@ void CopyFan::control(const fan::FanCall &call) {
     call2.set_speed(*call.get_speed());
   if (call.get_direction().has_value())
     call2.set_direction(*call.get_direction());
+  if (!call.get_preset_mode().empty())
+    call2.set_preset_mode(call.get_preset_mode());
   call2.perform();
 }
 

esphome/components/fan/__init__.py

@@ -18,6 +18,7 @@
     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 @@
 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 @@
                 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