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:

  • device_class (Optional, string): The device class for the sensor. See https://www.home-assistant.io/components/cover/ 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). Requires Home Assistant 2021.9 or newer. 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. Requires Home Assistant 2021.11 or newer. 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.

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