document template fan and fan triggers (#3655)

2025-02-24 03:02:12 +01:00 · 2024-03-10 15:42:14 -07:00 · 2024-03-10 15:42:14 -07:00 · b32101c04b
commit b32101c04b
parent 2af197fe09
4 changed files with 113 additions and 6 deletions
--- a/components/fan/index.rst
+++ b/components/fan/index.rst
@ -73,14 +73,20 @@ MQTT options:

 Automation triggers:

+- **on_state** (*Optional*, :ref:`Action <config-action>`): An automation to perform
+  when the fan state is changed. See :ref:`fan-on_state_trigger`.
 - **on_turn_on** (*Optional*, :ref:`Action <config-action>`): An automation to perform
  when the fan is turned on. See :ref:`fan-on_turn_on_off_trigger`.
 - **on_turn_off** (*Optional*, :ref:`Action <config-action>`): An automation to perform
  when the fan is turned off. See :ref:`fan-on_turn_on_off_trigger`.
+- **on_direction_set** (*Optional*, :ref:`Action <config-action>`): An automation to perform
+  when the fan direction is changed. See :ref:`fan-on_direction_set_trigger`.
+- **on_oscillating_set** (*Optional*, :ref:`Action <config-action>`): An automation to perform
+  when the fan oscillating state is changed. See :ref:`fan-on_oscillating_set_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`.
+  when the fan speed is 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`.
+  when the fan preset mode is changed. See :ref:`fan-on_preset_set_trigger`.

 .. _fan-toggle_action:

@ -175,6 +181,24 @@ This :ref:`condition <config-condition>` passes if the given fan is on or off.
        then:
        - script.execute: my_script

+.. _fan-on_state_trigger:
+
+``fan.on_state`` Trigger
+------------------------
+
+This trigger is activated each time the fan state is changed. It will fire when the state is either set via API e.g. in Home Assistant or locally by an automation or a lambda function.
+A pointer to the ``Fan`` is available as a variable called ``x``.
+
+.. code-block:: yaml
+
+    fan:
+      - platform: speed # or any other platform
+        # ...
+        on_state:
+        - logger.log:
+            format: "Fan State changed!  Fan Speed is %d!"
+            args: [ x->speed ]
+
 .. _fan-on_turn_on_off_trigger:

 ``fan.on_turn_on`` / ``fan.on_turn_off`` Trigger
@ -193,12 +217,49 @@ if a command to turn the fan on or off already matches the current state.
        on_turn_off:
        - logger.log: "Fan Turned Off!"

+.. _fan-on_direction_set_trigger:
+
+``fan.on_direction_set`` Trigger
+--------------------------------
+
+This trigger is activated each time the fan direction is changed. It will fire when the direction is either set via API e.g. in Home Assistant or locally by an automation or a lambda function.
+The new direction is available as a variable called ``x``.  (``0`` is FORWARD, ``1`` is REVERSE)
+
+.. code-block:: yaml
+
+    fan:
+      - platform: speed # or any other platform
+        # ...
+        on_direction_set:
+        - logger.log:
+            format: "Fan Direction was changed to %s!"
+            args: [ x == 0 ? "FORWARD" : "REVERSE" ]
+
+.. _fan-on_oscillating_set_trigger:
+
+``fan.on_oscillating_set`` Trigger
+----------------------------------
+
+This trigger is activated each time the fan oscillating state is changed. It will fire when the state is either set via API e.g. in Home Assistant or locally by an automation or a lambda function.
+The new oscillating state is available as a variable called ``x``.
+
+.. code-block:: yaml
+
+    fan:
+      - platform: speed # or any other platform
+        # ...
+        on_oscillating_set:
+        - logger.log:
+            format: "Fan Oscillating State was changed to %s!"
+            args: [ ONOFF(x) ]
+
 .. _fan-on_speed_set_trigger:

 ``fan.on_speed_set`` Trigger
 ----------------------------

 This trigger is activated each time the fan speed is changed. It will fire when the speed is either set via API e.g. in Home Assistant or locally by an automation or a lambda function.
+The new speed is available as a variable called ``x``.

 .. code-block:: yaml

@ -206,7 +267,9 @@ This trigger is activated each time the fan speed is changed. It will fire when
      - platform: speed # or any other platform
        # ...
        on_speed_set:
-        - logger.log: "Fan Speed was changed!"
+        - logger.log:
+            format: "Fan Speed was changed to %d!"
+            args: [ x ]

 .. _fan-on_preset_set_trigger:

@ -214,6 +277,7 @@ This trigger is activated each time the fan speed is changed. It will fire when
 -----------------------------

 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.
+The new mode is available as a variable called ``x``.

 .. code-block:: yaml

@ -221,7 +285,9 @@ This trigger is activated each time the fan preset mode is changed. It will fire
      - platform: speed # or any other platform
        # ...
        on_preset_set:
-          - logger.log: "Fan preset mode was changed!"
+          - logger.log:
+              format: "Fan preset mode was changed to %s!"
+              args: [ x.c_str() ]

 Lambda calls
 ------------
--- a/components/fan/speed.rst
+++ b/components/fan/speed.rst
@ -24,8 +24,7 @@ Configuration variables:
 ------------------------

 - **name** (*Optional*, string): The name for this fan.
- **output** (*Optional*, :ref:`config-id`): The id of the :ref:`float output <output>` to use for this fan.
-  (This is a temporary change until a template fan is available.)
+- **output** (**Required**, :ref:`config-id`): The id of the :ref:`float output <output>` to use for this fan.
 - **oscillation_output** (*Optional*, :ref:`config-id`): The id of the
  :ref:`output <output>` to use for the oscillation state of this fan. Default is empty.
 - **direction_output** (*Optional*, :ref:`config-id`): The id of the
--- a/components/fan/template.rst
+++ b/components/fan/template.rst
@ -0,0 +1,41 @@
+Template Fan
+============
+
+.. seo::
+    :description: Instructions for setting up template fans.
+    :image: fan.svg
+
+The ``template`` fan platform lets you create a fan interface using only triggers.
+
+.. figure:: images/fan-ui.png
+    :align: center
+    :width: 80.0%
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    fan:
+      - platform: template
+        name: "Virtual Fan"
+        on_state:
+          - do something
+        on_speed_set:
+          - do something
+
+Configuration variables:
+------------------------
+
+- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
+- **name** (*Optional*, string): The name for this fan.
+- **has_direction** (*Optional*, boolean): Indicates if there should be a control for direction.  Default is ``false``.
+- **has_oscillating** (*Optional*, boolean): Indicates if there should be a control for oscillating.  Default is ``false``.
+- **speed_count** (*Optional*, int): Set the number of supported discrete speed levels.  Default is only on/off.
+- **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
+--------
+
+- :doc:`/components/fan/index`
+- :apiref:`template/fan/template_fan.h`
+- :ghedit:`Edit`
--- a/index.rst
+++ b/index.rst
@ -647,6 +647,7 @@ Fan Components
    H-bridge Fan, components/fan/hbridge, fan.svg, dark-invert
    Speed Fan, components/fan/speed, fan.svg, dark-invert
    Tuya Fan, components/fan/tuya, tuya.png
+    Template Fan, components/fan/template, description.svg, dark-invert

 Display Components
 ------------------