esphome-docs/components/fan/index.rst

111 lines
2.7 KiB
ReStructuredText
Raw Normal View History

2018-05-13 11:37:02 +02:00
Fan Component
=============
2018-11-14 22:12:27 +01:00
.. seo::
:description: Instructions for setting up the base fan component.
:image: folder-open.png
2018-11-14 22:12:27 +01:00
2018-05-13 11:37:02 +02:00
With the ``fan`` domain you can create components that appear as fans in
the Home Assistant frontend. A fan can be switched ON or OFF, optionally
has a speed setting (``LOW``, ``MEDIUM``, ``HIGH``) and can have an
oscillate output.
2019-03-17 12:10:03 +01:00
This component restores its state on reboot/reset.
2018-06-01 18:10:00 +02:00
.. figure:: images/fan-ui.png
:align: center
:width: 70.0%
2018-05-13 11:37:02 +02:00
2018-06-01 18:10:00 +02:00
.. _config-fan:
2018-05-13 11:37:02 +02:00
Base Fan Configuration
2018-08-24 22:44:01 +02:00
----------------------
2018-05-13 11:37:02 +02:00
.. code-block:: yaml
2018-05-13 11:37:02 +02:00
fan:
- platform: ...
name: ...
Configuration variables:
2018-06-01 18:10:00 +02:00
- **name** (**Required**, string): The name of the fan.
2019-02-17 12:28:17 +01:00
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
a ``name`` will implicitly set this to true.
MQTT options:
2018-06-01 18:10:00 +02:00
- **oscillation_state_topic** (*Optional*, string): The topic to
2018-10-20 15:10:26 +02:00
publish fan oscillation state changes to.
2018-06-01 18:10:00 +02:00
- **oscillation_command_topic** (*Optional*, string): The topic to
receive oscillation commands on.
- **speed_state_topic** (*Optional*, string): The topic to publish fan
speed state changes to.
- **speed_command_topic** (*Optional*, string): The topic to receive
speed commands on.
2018-06-01 18:10:00 +02:00
- All other options from :ref:`MQTT Component <config-mqtt-component>`.
.. _fan-toggle_action:
``fan.toggle`` Action
2018-08-24 22:44:01 +02:00
---------------------
2018-06-01 18:10:00 +02:00
Toggles the ON/OFF state of the fan with the given ID when executed.
.. code-block:: yaml
2018-06-01 18:10:00 +02:00
on_...:
then:
- fan.toggle: fan_1
2018-06-01 18:10:00 +02:00
.. _fan-turn_off_action:
``fan.turn_off`` Action
2018-08-24 22:44:01 +02:00
-----------------------
2018-06-01 18:10:00 +02:00
Turns the fan with the given ID off when executed.
.. code-block:: yaml
2018-06-01 18:10:00 +02:00
on_...:
then:
- fan.turn_off: fan_1
2018-06-01 18:10:00 +02:00
.. _fan-turn_on_action:
``fan.turn_on`` Action
2018-08-24 22:44:01 +02:00
----------------------
2018-06-01 18:10:00 +02:00
Turns the fan with the given ID off when executed.
.. code-block:: yaml
2018-06-01 18:10:00 +02:00
on_...:
then:
- fan.turn_on:
2018-06-02 21:54:39 +02:00
id: fan_1
2018-11-10 14:31:27 +01:00
# Shorthand:
- fan.turn_on: fan_1
2018-06-01 18:10:00 +02:00
Configuration options:
2018-06-02 21:54:39 +02:00
- **id** (**Required**, :ref:`config-id`): The ID of the fan.
2018-06-01 18:10:00 +02:00
- **oscillating** (*Optional*, boolean, :ref:`templatable <config-templatable>`):
Set the oscillation state of the fan. Defaults to not affecting oscillation.
- **speed** (*Optional*, string, :ref:`templatable <config-templatable>`):
Set the speed setting of the fan. One of ``OFF``, ``LOW``, ``MEDIUM``, ``HIGH``.
2019-05-12 22:44:59 +02:00
If you template this value, return ``FAN_SPEED_...``, for example ``FAN_SPEED_HIGH``.
2018-06-01 18:10:00 +02:00
Full Fan Index
2018-08-24 22:44:01 +02:00
--------------
2018-06-01 18:10:00 +02:00
- :apiref:`fan/fan_state.h`
- :ghedit:`Edit`
2018-06-01 18:10:00 +02:00
.. toctree::
:maxdepth: 1
:glob:
2018-06-01 18:10:00 +02:00
*