esphome-docs/components/cover/index.rst

188 lines
4.3 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-opn.png
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:
- **device_class** (*Optional*, string): The device class for the
sensor. See https://www.home-assistant.io/components/cover/ for a list of available options.
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.
- If MQTT enabled, all other options from :ref:`MQTT Component <config-mqtt-component>`.
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-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
lambda calls
2018-08-24 22:44:01 +02:00
------------
2018-06-07 15:55:31 +02:00
From :ref:`lambdas <config-lambda>`, you can call several methods on all covers to do some
advanced stuff.
2018-06-07 15:55:31 +02:00
- ``publish_state()``: Manually cause the cover to publish a new state and store it internally.
If it's different from the last internal state, it's additionally published to the frontend.
.. code-block:: yaml
2018-06-07 15:55:31 +02:00
// Within lambda, make the cover report a specific state
2019-05-12 22:44:59 +02:00
id(my_cover).publish_state(COVER_OPEN);
id(my_cover).publish_state(COVER_CLOSED);
2018-06-07 15:55:31 +02:00
- ``state``: Retrieve the current state of the cover.
.. code-block:: yaml
2018-06-07 15:55:31 +02:00
2019-05-12 22:44:59 +02:00
if (id(my_cover).state == COVER_OPEN) {
2018-06-07 15:55:31 +02:00
// Cover is open
} else {
// Cover is closed
2018-06-07 15:55:31 +02:00
}
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
*