Add optional speed parameter to cover movement actions

homeassistant/components/cover/__init__.py

@@ -23,6 +23,7 @@
     SERVICE_TOGGLE_COVER_TILT,
 )
 from homeassistant.core import HomeAssistant
+from homeassistant.exceptions import ServiceValidationError
 from homeassistant.helpers import config_validation as cv
 from homeassistant.helpers.entity import Entity, EntityDescription
 from homeassistant.helpers.entity_component import EntityComponent
@@ -35,11 +36,13 @@
     ATTR_CURRENT_TILT_POSITION,
     ATTR_IS_CLOSED,
     ATTR_POSITION,
+    ATTR_SPEED,
     ATTR_TILT_POSITION,
     DOMAIN,
     INTENT_CLOSE_COVER,
     INTENT_OPEN_COVER,
     CoverDeviceClass,
+    CoverEntityCapabilityAttribute,
     CoverEntityFeature,
     CoverEntityStateAttribute,
     CoverState,
@@ -65,6 +68,7 @@
     "ATTR_CURRENT_TILT_POSITION",
     "ATTR_IS_CLOSED",
     "ATTR_POSITION",
+    "ATTR_SPEED",
     "ATTR_TILT_POSITION",
     "DEVICE_CLASSES",
     "DEVICE_CLASSES_SCHEMA",
@@ -75,6 +79,7 @@
     "PLATFORM_SCHEMA_BASE",
     "CoverDeviceClass",
     "CoverEntity",
+    "CoverEntityCapabilityAttribute",
     "CoverEntityDescription",
     "CoverEntityFeature",
     "CoverEntityStateAttribute",
@@ -100,21 +105,28 @@ async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
     await component.async_setup(config)
 
     component.async_register_entity_service(
-        SERVICE_OPEN_COVER, None, "async_open_cover", [CoverEntityFeature.OPEN]
+        SERVICE_OPEN_COVER,
+        {vol.Optional(ATTR_SPEED): cv.string},
+        "async_handle_open_cover",
+        [CoverEntityFeature.OPEN],
     )
 
     component.async_register_entity_service(
-        SERVICE_CLOSE_COVER, None, "async_close_cover", [CoverEntityFeature.CLOSE]
+        SERVICE_CLOSE_COVER,
+        {vol.Optional(ATTR_SPEED): cv.string},
+        "async_handle_close_cover",
+        [CoverEntityFeature.CLOSE],
     )
 
     component.async_register_entity_service(
         SERVICE_SET_COVER_POSITION,
         {
             vol.Required(ATTR_POSITION): vol.All(
                 vol.Coerce(int), vol.Range(min=0, max=100)
-            )
+            ),
+            vol.Optional(ATTR_SPEED): cv.string,
         },
-        "async_set_cover_position",
+        "async_handle_set_cover_position",
         [CoverEntityFeature.SET_POSITION],
     )
 
@@ -194,6 +206,7 @@ class CoverEntityDescription(EntityDescription, frozen_or_thawed=True):
     "is_opening",
     "is_closing",
     "is_closed",
+    "supported_speeds",
 }
 
 
@@ -209,9 +222,16 @@ class CoverEntity(Entity, cached_properties=CACHED_PROPERTIES_WITH_ATTR_):
     _attr_is_opening: bool | None = None
     _attr_state: None = None
     _attr_supported_features: CoverEntityFeature | None
+    _attr_supported_speeds: list[str] | None = None
 
     _cover_is_last_toggle_direction_open = True
 
+    _entity_component_unrecorded_attributes = frozenset(
+        {
+            CoverEntityCapabilityAttribute.SUPPORTED_SPEEDS,
+        }
+    )
+
     @cached_property
     def current_cover_position(self) -> int | None:
         """Return current position of cover.
@@ -283,6 +303,9 @@ def supported_features(self) -> CoverEntityFeature:
             CoverEntityFeature.OPEN | CoverEntityFeature.CLOSE | CoverEntityFeature.STOP
         )
 
+        if self.supported_speeds:
+            supported_features |= CoverEntityFeature.SPEED
+
         if self.current_cover_position is not None:
             supported_features |= CoverEntityFeature.SET_POSITION
 
@@ -311,6 +334,73 @@ def is_closed(self) -> bool | None:
         """Return if the cover is closed or not."""
         return self._attr_is_closed
 
+    @cached_property
+    def supported_speeds(self) -> list[str] | None:
+        """Return the list of speeds supported for open/close/set_position operations.
+
+        None or an empty list means speed selection is not supported.
+        """
+        return self._attr_supported_speeds
+
+    @property
+    @override
+    def capability_attributes(self) -> dict[str, Any] | None:
+        """Return capability attributes."""
+
+        if speeds := self.supported_speeds:
+            return {CoverEntityCapabilityAttribute.SUPPORTED_SPEEDS: speeds}
+        return None
+
+    @final
+    def _valid_speed_or_raise(self, speed: str, supported: list[str]) -> None:
+        """Raise ServiceValidationError if speed is not in the supported list."""
+        if speed not in supported:
+            supported_str = ", ".join(supported)
+            raise ServiceValidationError(
+                translation_key="not_valid_speed",
+                translation_domain=DOMAIN,
+                translation_placeholders={
+                    "speed": speed,
+                    "supported_speeds": supported_str,
+                },
+            )
+
+    @final
+    async def async_handle_open_cover(self, **kwargs: Any) -> None:
+        """Validate speed and open the cover."""
+        call_kwargs = kwargs
+        if (speed := kwargs.get(ATTR_SPEED)) is not None:
+            if speeds := self.supported_speeds:
+                self._valid_speed_or_raise(speed, speeds)
+            else:
+                call_kwargs = dict(kwargs)
+                call_kwargs.pop(ATTR_SPEED)
+        await self.async_open_cover(**call_kwargs)
+
+    @final
+    async def async_handle_close_cover(self, **kwargs: Any) -> None:
+        """Validate speed and close the cover."""
+        call_kwargs = kwargs
+        if (speed := kwargs.get(ATTR_SPEED)) is not None:
+            if speeds := self.supported_speeds:
+                self._valid_speed_or_raise(speed, speeds)
+            else:
+                call_kwargs = dict(kwargs)
+                call_kwargs.pop(ATTR_SPEED)
+        await self.async_close_cover(**call_kwargs)
+
+    @final
+    async def async_handle_set_cover_position(self, **kwargs: Any) -> None:
+        """Validate speed and move the cover to a specific position."""
+        call_kwargs = kwargs
+        if (speed := kwargs.get(ATTR_SPEED)) is not None:
+            if speeds := self.supported_speeds:
+                self._valid_speed_or_raise(speed, speeds)
+            else:
+                call_kwargs = dict(kwargs)
+                call_kwargs.pop(ATTR_SPEED)
+        await self.async_set_cover_position(**call_kwargs)
+
     def open_cover(self, **kwargs: Any) -> None:
         """Open the cover."""
         raise NotImplementedError

homeassistant/components/cover/const.py

@@ -8,9 +8,16 @@
 ATTR_CURRENT_TILT_POSITION = "current_tilt_position"
 ATTR_IS_CLOSED = "is_closed"
 ATTR_POSITION = "position"
+ATTR_SPEED = "speed"
 ATTR_TILT_POSITION = "tilt_position"
 
 
+class CoverEntityCapabilityAttribute(StrEnum):
+    """Capability attributes for cover entities."""
+
+    SUPPORTED_SPEEDS = "supported_speeds"
+
+
 class CoverEntityStateAttribute(StrEnum):
     """State attributes for cover entities."""
 
@@ -34,6 +41,7 @@ class CoverEntityFeature(IntFlag):
     CLOSE_TILT = 32
     STOP_TILT = 64
     SET_TILT_POSITION = 128
+    SPEED = 256
 
 
 class CoverState(StrEnum):

homeassistant/components/cover/services.yaml

@@ -6,13 +6,31 @@ open_cover:
       domain: cover
       supported_features:
         - cover.CoverEntityFeature.OPEN
+  fields:
+    speed:
+      example: "fast"
+      filter:
+        supported_features:
+          - cover.CoverEntityFeature.SPEED
+      selector:
+        state:
+          attribute: speed
 
 close_cover:
   target:
     entity:
       domain: cover
       supported_features:
         - cover.CoverEntityFeature.CLOSE
+  fields:
+    speed:
+      example: "fast"
+      filter:
+        supported_features:
+          - cover.CoverEntityFeature.SPEED
+      selector:
+        state:
+          attribute: speed
 
 toggle:
   target:
@@ -36,6 +54,14 @@ set_cover_position:
           min: 0
           max: 100
           unit_of_measurement: "%"
+    speed:
+      filter:
+        supported_features:
+          - cover.CoverEntityFeature.SPEED
+      example: "fast"
+      selector:
+        state:
+          attribute: speed
 
 stop_cover:
   target:

homeassistant/components/cover/strings.json

@@ -2,6 +2,7 @@
   "common": {
     "condition_behavior_name": "Condition passes if",
     "condition_for_name": "For at least",
+    "field_speed_name": "Speed",
     "trigger_behavior_name": "Trigger when",
     "trigger_for_name": "For at least"
   },
@@ -210,9 +211,20 @@
       "name": "Window"
     }
   },
+  "exceptions": {
+    "not_valid_speed": {
+      "message": "Speed {speed} is not valid. Valid speeds are: {supported_speeds}."
+    }
+  },
   "services": {
     "close_cover": {
       "description": "Closes a cover.",
+      "fields": {
+        "speed": {
+          "description": "Speed at which to close the cover.",
+          "name": "[%key:component::cover::common::field_speed_name%]"
+        }
+      },
       "name": "Close cover"
     },
     "close_cover_tilt": {
@@ -221,6 +233,12 @@
     },
     "open_cover": {
       "description": "Opens a cover.",
+      "fields": {
+        "speed": {
+          "description": "Speed at which to open the cover.",
+          "name": "[%key:component::cover::common::field_speed_name%]"
+        }
+      },
       "name": "Open cover"
     },
     "open_cover_tilt": {
@@ -233,6 +251,10 @@
         "position": {
           "description": "Target position.",
           "name": "Position"
+        },
+        "speed": {
+          "description": "Speed at which to move the cover.",
+          "name": "[%key:component::cover::common::field_speed_name%]"
         }
       },
       "name": "Set cover position"

homeassistant/components/demo/cover.py

@@ -29,7 +29,15 @@ async def async_setup_entry(
         [
             DemoCover(hass, "cover_1", "Kitchen Window"),
             DemoCover(hass, "cover_2", "Hall Window", 10),
-            DemoCover(hass, "cover_3", "Living Room Window", 70, 50),
+            DemoCover(
+                hass,
+                "cover_3",
+                "Living Room Window",
+                70,
+                50,
+                supported_speeds=["slow", "default"],
+                translation_key="living_room_window",
+            ),
             DemoCover(
                 hass,
                 "cover_4",
@@ -69,13 +77,17 @@ def __init__(
         tilt_position: int | None = None,
         device_class: CoverDeviceClass | None = None,
         supported_features: CoverEntityFeature | None = None,
+        supported_speeds: list[str] | None = None,
+        translation_key: str | None = None,
     ) -> None:
         """Initialize the cover."""
         self.hass = hass
         self._unique_id = unique_id
         self._position = position
         self._attr_device_class = device_class
         self._attr_supported_features = supported_features
+        self._attr_supported_speeds = supported_speeds
+        self._attr_translation_key = translation_key
         self._set_position: int | None = None
         self._set_tilt_position: int | None = None
         self._tilt_position = tilt_position

homeassistant/components/demo/strings.json

@@ -30,6 +30,18 @@
         }
       }
     },
+    "cover": {
+      "living_room_window": {
+        "state_attributes": {
+          "speed": {
+            "state": {
+              "default": "Default",
+              "slow": "Slow"
+            }
+          }
+        }
+      }
+    },
     "event": {
       "push": {
         "state_attributes": {