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

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

  • If Webserver enabled and version 3 is selected, All other options from Webserver Component.. See Webserver Version 3.

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.

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 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 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 between 0.0 (closed) and 1.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 between 0.0 and 1.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!"

See Also