Update speed fan with configuration options for preset modes (#3362)

Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>

components/fan/hbridge.rst

@@ -56,6 +56,7 @@ Configuration variables:
   will allow 1% increments in the output. Defaults to ``100``.
 - **name** (**Required**, string): The name for this fan.
 - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
+- **preset_modes** (*Optional*): A list of preset modes for this fan. Preset modes can be used in automations (i.e. `on_preset_set`).
 - All other options from :ref:`Fan Component <config-fan>`.
 
 .. _fan-hbridge_brake_action:

components/fan/index.rst

@@ -79,6 +79,8 @@ Automation triggers:
   when the fan is turned off. See :ref:`fan-on_turn_on_off_trigger`.
 - **on_speed_set** (*Optional*, :ref:`Action <config-action>`): An automation to perform
   when the fan speed is set/changed. See :ref:`fan-on_speed_set_trigger`.
+- **on_preset_set** (*Optional*, :ref:`Action <config-action>`): An automation to perform
+  when the fan preset mode is set/changed. See :ref:`fan-on_preset_set_trigger`.
 
 .. _fan-toggle_action:
 
@@ -206,6 +208,21 @@ This trigger is activated each time the fan speed is changed. It will fire when
         on_speed_set:
         - logger.log: "Fan Speed was changed!"
 
+.. _fan-on_preset_set_trigger:
+
+``fan.on_preset_set`` Trigger
+-----------------------------
+
+This trigger is activated each time the fan preset mode is changed. It will fire when the preset mode is either set via API e.g. in Home Assistant or locally by an automation or a lambda function.
+
+.. code-block:: yaml
+
+    fan:
+      - platform: speed # or any other platform
+        # ...
+        on_preset_set:
+          - logger.log: "Fan preset mode was changed!"
+
 Lambda calls
 ------------
 
@@ -256,6 +273,17 @@ advanced stuff (see the full API Reference for more info).
         // Fan direction is reverse, do something else here
       }
 
+- ``preset_mode``: Retrieve the current preset mode of the fan.
+
+  .. code-block:: yaml
+
+      // Within lambda, get the fan preset mode and conditionally do something
+      if (id(my_fan).preset_mode == "auto") {
+        // Fan preset mode is "auto", do something here
+      } else {
+        // Fan preset mode is not "auto", do something else here
+      }
+
 - ``turn_off()``/``turn_on()``/``toggle()``: Manually turn the fan ON/OFF from code.
   Similar to the ``fan.turn_on``, ``fan.turn_off``, and ``fan.toggle`` actions,
   but can be used in complex lambda expressions.
@@ -273,6 +301,11 @@ advanced stuff (see the full API Reference for more info).
       call.set_direction(FanDirection::REVERSE);
       call.perform();
 
+      // Set a preset mode
+      auto call = id(my_fan).turn_on();
+      call.set_preset_mode("auto");
+      call.perform();
+
       // Toggle the fan on/off
       auto call = id(my_fan).toggle();
       call.perform();

components/fan/speed.rst

@@ -34,6 +34,7 @@ Configuration variables:
   to calculate the percentages for each speed. E.g. ``2`` means that you have 50% and 100% while ``100``
   will allow 1% increments in the output. Defaults to ``100``.
 - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
+- **preset_modes** (*Optional*): A list of preset modes for this fan. Preset modes can be used in automations (i.e. `on_preset_set`).
 - All other options from :ref:`Fan Component <config-fan>`.
 
 See Also