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.

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:

• mqtt_json_state_payload (Optional, boolean): When set to true, state changes will be published only to the state_topic as a single JSON object per state change. Example:

  { "state": "open", "position": 100, "tilt": 50 }

  When false, individual values are published to the state_topic, position_state_topic, and tilt_state_topic separately. Defaults to false.

• position_state_topic (Optional, string): The topic to publish cover position changes to. Not valid if mqtt_json_state_payload is set to true.

• 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. Not valid if mqtt_json_state_payload is set to true.

• tilt_command_topic (Optional, string): The topic to receive cover tilt commands on.

• All other options from MQTT Component.

Actions

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();

Conditions

cover.is_open Condition

This condition checks if the cover with the given ID is fully open.

on_...:
  if:
    condition:
      cover.is_open: cover_1
    then:
      - logger.log: "Cover is open!"

Configuration variables:

• id (Required, ID): The cover to check.

cover.is_closed Condition

This condition checks if the cover with the given ID is fully closed.

on_...:
  if:
    condition:
      cover.is_closed: cover_1
    then:
      - logger.log: "Cover is closed!"

Configuration variables:

• id (Required, ID): The cover to check.

Triggers

cover.on_opened Trigger

This trigger is activated each time the cover reaches a fully open state.

cover:
  - platform: template  # or any other platform
    # ...
    on_opened:
      - logger.log: "Cover is fully 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 fully closed!"

cover.on_opening Trigger

This trigger is activated each time the cover starts opening.

cover:
  - platform: template  # or any other platform
    # ...
    on_opening:
      - logger.log: "Cover started opening"

cover.on_closing Trigger

This trigger is activated each time the cover starts closing.

cover:
  - platform: template  # or any other platform
    # ...
    on_closing:
      - logger.log: "Cover started closing"

cover.on_idle Trigger

This trigger is activated each time the cover stops moving and becomes idle.

cover:
  - platform: template  # or any other platform
    # ...
    on_idle:
      - logger.log: "Cover stopped moving"

NOTE

The on_open trigger is deprecated and will be removed in a future release. Please use on_opened instead.

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
        }

See Also

• API Reference: Cover
• API Reference: cover.h