esphome-docs/components/cover/template.rst
Otto Winter 6053f490b5
Update svg2png and seo.py (#1380)
Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
2021-11-16 15:19:33 +13:00

132 lines
5.2 KiB
ReStructuredText

Template Cover
==============
.. seo::
:description: Instructions for setting up template covers in ESPHome.
:image: description.svg
The ``template`` cover platform allows you to create simple covers out of just a few
actions and a value lambda. Once defined, it will automatically appear in Home Assistant
as a cover and can be controlled through the frontend.
.. figure:: images/cover-ui.png
:align: center
:width: 75.0%
.. code-block:: yaml
# Example configuration entry
cover:
- platform: template
name: "Template Cover"
lambda: |-
if (id(top_end_stop).state) {
return COVER_OPEN;
} else {
return COVER_CLOSED;
}
open_action:
- switch.turn_on: open_cover_switch
close_action:
- switch.turn_on: close_cover_switch
stop_action:
- switch.turn_on: stop_cover_switch
optimistic: true
Possible return values for the optional lambda:
- ``return COVER_OPEN;`` if the cover should be reported as OPEN.
- ``return COVER_CLOSED;`` if the cover should be reported as CLOSED.
- ``return {};`` if the last state should be repeated.
Configuration variables:
------------------------
- **name** (**Required**, string): The name of the cover.
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`):
Lambda to be evaluated repeatedly to get the current state of the cover.
- **open_action** (*Optional*, :ref:`Action <config-action>`): The action that should
be performed when the remote (like Home Assistant's frontend) requests the cover to be opened.
- **close_action** (*Optional*, :ref:`Action <config-action>`): The action that should
be performed when the remote requests the cover to be closed.
- **stop_action** (*Optional*, :ref:`Action <config-action>`): The action that should
be performed when the remote requests the cover to be stopped.
- **optimistic** (*Optional*, boolean): Whether to operate in optimistic mode - when in this mode,
any command sent to the template cover will immediately update the reported state and no lambda
needs to be used. Defaults to ``false``.
- **assumed_state** (*Optional*, boolean): Whether the true state of the cover is not known.
This will make the Home Assistant frontend show buttons for both OPEN and CLOSE actions, instead
of hiding one of them. Defaults to ``false``.
- **has_position** (*Optional*, boolean): Whether this cover will publish its position as a floating point number.
By default (``false``), the cover only publishes OPEN/CLOSED position.
Parameter useless if you set the POSITION_ACTION (is set to TRUE).
- **tilt_action** (*Optional*, :ref:`Action <config-action>`): The action that should
be performed when the remote (like Home Assistant's frontend) requests the cover be set to a specific
tilt position. The desired tilt is available in the lambda in the ``tilt`` variable.
- **tilt_lambda** (*Optional*, :ref:`lambda <config-lambda>`):
Lambda to be evaluated repeatedly to get the current tilt position of the cover.
- **position_action** (*Optional*, :ref:`Action <config-action>`): The action that should
be performed when the remote (like Home Assistant's frontend) requests the cover be set to a specific
position. The desired position is available in the lambda in the ``pos`` variable.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- All other options from :ref:`Cover <config-cover>`.
.. _cover-template-publish_action:
``cover.template.publish`` Action
---------------------------------
You can also publish a state to a template cover from elsewhere in your YAML file
with the ``cover.template.publish`` action.
.. code-block:: yaml
# Example configuration entry
cover:
- platform: template
name: "Template Cover"
id: template_cov
# in some trigger
on_...:
- cover.template.publish:
id: template_cov
state: OPEN
# Templated
- cover.template.publish:
id: template_cov
state: !lambda 'return COVER_OPEN;'
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the template cover.
- **state** (*Optional*, :ref:`templatable <config-templatable>`):
The state to publish. One of ``OPEN``, ``CLOSED``. If using a lambda, use ``COVER_OPEN`` or ``COVER_CLOSED``.
- **position** (*Optional*, :ref:`templatable <config-templatable>`, float):
The position to publish, from 0 (CLOSED) to 1.0 (OPEN)
- **tilt** (*Optional*, :ref:`templatable <config-templatable>`, float):
The tilt position to publish, from 0 (CLOSED) to 1.0 (OPEN)
- **current_operation** (*Optional*, :ref:`templatable <config-templatable>`, string):
The current operation mode to publish. One of ``IDLE``, ``OPENING`` and ``CLOSING``. If using a lambda, use ``COVER_OPERATION_IDLE``, ``COVER_OPERATION_OPENING``, and ``COVER_OPERATION_CLOSING``.
.. note::
This action can also be written in lambdas:
.. code-block:: cpp
id(template_cov).position = COVER_OPEN;
id(template_cov).tilt = 0.5;
id(template_cov).publish_state();
See Also
--------
- :doc:`/components/cover/index`
- :ref:`automation`
- :doc:`/cookbook/garage-door`
- :apiref:`template/cover/template_cover.h`
- :ghedit:`Edit`