Cover Component¶
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.
![../../_images/cover-ui.png](../../_images/cover-ui.png)
Base Cover Configuration¶
All cover config schemas inherit from this schema - you can set these keys for covers.
cover:
- platform: ...
device_class: garage
Configuration variables:
id (Optional, string): Manually specify the ID for code generation. At least one of id and name must be specified.
name (Optional, string): The name for the cover. At least one of id and name must be specified.
Note
If you have a friendly_name set for your device and you want the cover to use that name, you can set
name: None
.device_class (Optional, string): The device class for the sensor. See https://www.home-assistant.io/integrations/cover/#device-class for a list of available options.
icon (Optional, icon): Manually set the icon to use for the cover in the frontend.
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 aname
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). Defaults to
false
.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. Set to
""
to remove the default entity category.
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 MQTT Component.
If Webserver enabled,
web_server_sorting_weight
can be set. See Webserver Entity Sorting.
cover.open
Action¶
This action opens the cover with the given ID when executed.
on_...:
then:
- cover.open: cover_1
Note
This action can also be expressed in lambdas:
auto call = id(cover_1).make_call();
call.set_command_open();
call.perform();
cover.close
Action¶
This action closes the cover with the given ID when executed.
on_...:
then:
- cover.close: cover_1
Note
This action can also be expressed in lambdas:
auto call = id(cover_1).make_call();
call.set_command_close();
call.perform();
cover.stop
Action¶
This action stops the cover with the given ID when executed.
on_...:
then:
- cover.stop: cover_1
Note
This action can also be expressed in lambdas:
auto call = id(cover_1).make_call();
call.set_command_stop();
call.perform();
cover.toggle
Action¶
This 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.
on_...:
then:
- cover.toggle: cover_1
Note
This action can also be expressed in lambdas:
auto call = id(cover_1).make_call();
call.set_command_toggle();
call.perform();
cover.control
Action¶
This action is a more generic version of the other cover actions and allows all cover attributes to be set.
on_...:
then:
- cover.control:
id: cover_1
position: 50%
tilt: 50%
Configuration variables:
id (Required, 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
orCLOSE
.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 lambdas:
auto call = id(cover_1).make_call();
// set attributes
call.set_position(0.5);
call.perform();
Lambdas¶
From lambdas, 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).
position
: Retrieve the current position of the cover, as a value between0.0
(closed) and1.0
(open).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 }
tilt
: Retrieve the current tilt position of the cover, as a value between0.0
and1.0
.current_operation
: The operation the cover is currently performing: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 }
cover.on_open
Trigger¶
This trigger is activated each time the cover reaches a fully open state.
cover:
- platform: template # or any other platform
# ...
on_open:
- logger.log: "Cover is Open!"
cover.on_closed
Trigger¶
This trigger is activated each time the cover reaches a fully closed state.
cover:
- platform: template # or any other platform
# ...
on_closed:
- logger.log: "Cover is Closed!"