esphome-docs/components/cover/index.rst

277 lines
7.2 KiB
ReStructuredText
Raw Normal View History

2018-06-01 18:10:00 +02:00
Cover Component
===============
2018-11-14 22:12:27 +01:00
.. seo::
2019-02-16 23:25:23 +01:00
:description: Instructions for setting up base covers in ESPHome.
:image: folder-open.svg
2018-11-14 22:12:27 +01:00
2019-02-16 23:25:23 +01:00
The ``cover`` component is a generic representation of covers in ESPHome.
2018-06-01 18:10:00 +02:00
A cover can (currently) either be *closed* or *open* and supports three types of
commands: *open*, *close* and *stop*.
2019-05-12 22:44:59 +02:00
.. figure:: images/cover-ui.png
:align: center
:width: 75.0%
.. _config-cover:
Base Cover Configuration
------------------------
All cover config schemas inherit from this schema - you can set these keys for covers.
.. code-block:: yaml
cover:
- platform: ...
device_class: garage
Configuration variables:
- **name** (**Required**, string): The name for the cover.
.. note::
If you have a :ref:`friendly_name <esphome-configuration_variables>` set for your device and
you want the cover to use that name, you can set ``name: None``.
2019-05-12 22:44:59 +02:00
- **device_class** (*Optional*, string): The device class for the
sensor. See https://www.home-assistant.io/components/cover/ for a list of available options.
- **icon** (*Optional*, icon): Manually set the icon to use for the cover in the frontend.
2019-05-12 22:44:59 +02:00
Advanced options:
- **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.
- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
2021-11-07 19:24:55 +01:00
- **entity_category** (*Optional*, string): The category of the entity.
See https://developers.home-assistant.io/docs/core/entity/#generic-properties
for a list of available options. Requires Home Assistant 2021.11 or newer.
Set to ``""`` to remove the default entity category.
2021-10-10 17:54:39 +02:00
MQTT options:
- **position_state_topic** (*Optional*, string): The topic to publish
cover position changes to.
- **position_command_topic** (*Optional*, string): The topic to receive
cover position commands on.
- **tilt_state_topic** (*Optional*, string): The topic to publish cover
cover tilt state changes to.
- **tilt_command_topic** (*Optional*, string): The topic to receive
cover tilt commands on.
- All other options from :ref:`MQTT Component <config-mqtt-component>`.
2019-05-12 22:44:59 +02:00
2018-06-01 18:10:00 +02:00
.. _cover-open_action:
``cover.open`` Action
2018-08-24 22:44:01 +02:00
---------------------
2018-06-01 18:10:00 +02:00
2019-05-12 22:44:59 +02:00
This :ref:`action <config-action>` opens the cover with the given ID when executed.
2018-06-01 18:10:00 +02:00
.. code-block:: yaml
2018-06-01 18:10:00 +02:00
on_...:
then:
- cover.open: cover_1
.. note::
This action can also be expressed in :ref:`lambdas <config-lambda>`:
.. code-block:: cpp
2019-05-12 22:44:59 +02:00
auto call = id(cover_1).make_call();
call.set_command_open();
call.perform();
2018-06-01 18:10:00 +02:00
.. _cover-close_action:
``cover.close`` Action
2018-08-24 22:44:01 +02:00
----------------------
2018-06-01 18:10:00 +02:00
2019-05-12 22:44:59 +02:00
This :ref:`action <config-action>` closes the cover with the given ID when executed.
2018-06-01 18:10:00 +02:00
.. code-block:: yaml
2018-06-01 18:10:00 +02:00
on_...:
then:
- cover.close: cover_1
.. note::
This action can also be expressed in :ref:`lambdas <config-lambda>`:
.. code-block:: cpp
2019-05-12 22:44:59 +02:00
auto call = id(cover_1).make_call();
call.set_command_close();
call.perform();
2018-06-01 18:10:00 +02:00
.. _cover-stop_action:
``cover.stop`` Action
2018-08-24 22:44:01 +02:00
---------------------
2018-06-01 18:10:00 +02:00
2019-05-12 22:44:59 +02:00
This :ref:`action <config-action>` stops the cover with the given ID when executed.
2018-06-01 18:10:00 +02:00
.. code-block:: yaml
2018-06-01 18:10:00 +02:00
on_...:
then:
- cover.stop: cover_1
.. note::
This action can also be expressed in :ref:`lambdas <config-lambda>`:
.. code-block:: cpp
2019-05-12 22:44:59 +02:00
auto call = id(cover_1).make_call();
call.set_command_stop();
call.perform();
.. _cover-toggle_action:
``cover.toggle`` Action
-----------------------
This :ref:`action <config-action>` toggles the cover with the given ID when executed,
cycling through the states close/stop/open/stop... This allows the cover to be controlled
by a single push button.
.. code-block:: yaml
on_...:
then:
- cover.toggle: cover_1
.. note::
This action can also be expressed in :ref:`lambdas <config-lambda>`:
.. code-block:: cpp
auto call = id(cover_1).make_call();
call.set_command_toggle();
call.perform();
2019-05-12 22:44:59 +02:00
.. _cover-control_action:
``cover.control`` Action
------------------------
This :ref:`action <config-action>` is a more generic version of the other cover actions and
allows all cover attributes to be set.
.. code-block:: yaml
on_...:
then:
- cover.control:
id: cover_1
position: 50%
tilt: 50%
Configuration variables:
- **id** (**Required**, :ref:`config-id`): The cover to control.
- **stop** (*Optional*, boolean): Whether to stop the cover.
- **state** (*Optional*, string): The state to set the cover to - one of ``OPEN`` or ``CLOSE``.
- **position** (*Optional*, float): The cover position to set.
- ``0.0`` = ``0%`` = ``CLOSED``
- ``1.0`` = ``100%`` = ``OPEN``
- **tilt** (*Optional*, float): The tilt position to set. In range 0% - 100%.
.. note::
This action can also be expressed in :ref:`lambdas <config-lambda>`:
.. code-block:: cpp
auto call = id(cover_1).make_call();
// set attributes
call.set_position(0.5);
call.perform();
2018-06-01 18:10:00 +02:00
.. _cover-lambda_calls:
2018-06-07 15:55:31 +02:00
2021-09-16 02:46:32 +02:00
Lambdas
-------
2018-06-07 15:55:31 +02:00
2021-09-16 02:46:32 +02:00
From :ref:`lambdas <config-lambda>`, you can access the current state of the cover (note that these
fields are read-only, if you want to act on the cover, use the ``make_call()`` method as shown above).
2018-06-07 15:55:31 +02:00
2022-09-22 06:26:36 +02:00
- ``position``: Retrieve the current position of the cover, as a value between ``0.0`` (closed) and ``1.0`` (open).
2018-06-07 15:55:31 +02:00
2021-09-16 02:46:32 +02:00
.. code-block:: cpp
2018-06-07 15:55:31 +02:00
2021-09-16 02:46:32 +02:00
if (id(my_cover).position == COVER_OPEN) {
// Cover is open
} else if (id(my_cover).position == COVER_CLOSED) {
// Cover is closed
} else {
// Cover is in-between open and closed
}
2021-10-10 17:54:39 +02:00
2021-09-16 02:46:32 +02:00
- ``tilt``: Retrieve the current tilt position of the cover, as a value between ``0.0`` and ``1.0``.
2018-06-07 15:55:31 +02:00
2021-09-16 02:46:32 +02:00
- ``current_operation``: The operation the cover is currently performing:
2018-06-07 15:55:31 +02:00
2021-09-16 02:46:32 +02:00
.. code-block:: cpp
2018-06-07 15:55:31 +02:00
2021-09-16 02:46:32 +02:00
if (id(my_cover).current_operation == CoverOperation::COVER_OPERATION_IDLE) {
// Cover is idle
} else if (id(my_cover).current_operation == CoverOperation::COVER_OPERATION_OPENING) {
// Cover is currently opening
} else if (id(my_cover).current_operation == CoverOperation::COVER_OPERATION_CLOSING) {
// Cover is currently closing
}
2018-06-07 15:55:31 +02:00
.. _cover-on_open_trigger:
``cover.on_open`` Trigger
*************************
This trigger is activated each time the cover reaches a fully open state.
.. code-block:: yaml
cover:
- platform: template # or any other platform
# ...
on_open:
- logger.log: "Cover is Open!"
.. _cover-on_closed_trigger:
``cover.on_closed`` Trigger
***************************
This trigger is activated each time the cover reaches a fully closed state.
.. code-block:: yaml
cover:
- platform: template # or any other platform
# ...
on_closed:
- logger.log: "Cover is Closed!"
2018-06-03 12:50:44 +02:00
See Also
2018-08-24 22:44:01 +02:00
--------
2018-06-01 18:10:00 +02:00
- :apiref:`cover/cover.h`
- :ghedit:`Edit`
2018-06-01 18:10:00 +02:00
.. toctree::
:maxdepth: 1
:glob:
2018-06-01 18:10:00 +02:00
*