esphome-docs/components/cover/index.rst

Cover Component
===============

.. seo::
    :description: Instructions for setting up base covers in ESPHome.
    :image: folder-opn.png

The ``cover`` component is a generic representation of covers in ESPHome.
A cover can (currently) either be *closed* or *open* and supports three types of
commands: *open*, *close* and *stop*.

.. 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>`.

.. _cover-open_action:

``cover.open`` Action
---------------------

This :ref:`action <config-action>` opens the cover with the given ID when executed.

.. code-block:: yaml

    on_...:
      then:
        - cover.open: 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_open();
        call.perform();

.. _cover-close_action:

``cover.close`` Action
----------------------

This :ref:`action <config-action>` closes the cover with the given ID when executed.

.. code-block:: yaml

    on_...:
      then:
        - cover.close: 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_close();
        call.perform();

.. _cover-stop_action:

``cover.stop`` Action
---------------------

This :ref:`action <config-action>` stops the cover with the given ID when executed.

.. code-block:: yaml

    on_...:
      then:
        - cover.stop: 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_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();

.. _cover-lambda_calls:

lambda calls
------------

From :ref:`lambdas <config-lambda>`, you can call several methods on all covers to do some
advanced stuff.

- ``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

      // Within lambda, make the cover report a specific state
      id(my_cover).publish_state(COVER_OPEN);
      id(my_cover).publish_state(COVER_CLOSED);

- ``state``: Retrieve the current state of the cover.

  .. code-block:: yaml

      if (id(my_cover).state == COVER_OPEN) {
        // Cover is open
      } else {
        // Cover is closed
      }

See Also
--------

- :apiref:`cover/cover.h`
- :ghedit:`Edit`

.. toctree::
    :maxdepth: 1
    :glob:

    *