Extend cover platform with additional usecases/devicetypes

[marcelveldt]

Intro

While working on Z-Wave and Matter devices I stumbled on the fact that we currently do not have a very good user experience for some of the window coverings, such as ones that can tilt in multiple directions. A quick talk about that with some people learned that this is actually only the tip of the iceberg and more integrations run into the fact they can not fully support the cover device or need some workarounds.

Just like with many other platforms in HA, the cover platform was originally created for a single purpose, a window covering that would open and close. Later extended with some more features such as optionally tilting and the latest addition a "tilt only" covering. The code organically grew, just like what we saw with the climate platform. It makes it hard to display the correct presentation/controls for the device in the frontend as well as the right service calls in the backend. A good example is a cover with a dynamic tilt position where halfway could be considered as open on one integration/device, while it is something else on another.

Time maybe to just stand back and see what the world of "window/door coverings" looks like in 2023 and see if we have proper support of all these device types / scenarios.

Solution proposal

My proposal is to gather specifications and information we already know and make a full list of "window cover device types and scenarios", listed below. Feel free to comment if you have another devicetype/scenario and/or you see some errors in the list.

Next step would be determining a solution(direction), for example if our current "one-platform-for-all" is still a good fit or another platform is needed. A first gut feeling is that a single cover platform is still valid but we need a way to have some sort of agreement of the devicetype and the features it supports. The deviceclass could help with that, as well as maybe a new CoverFeature Enum? Just thinking out loud here. Let's first start with listing all window covering scenarios and work from there.

Terminology and generics

• I took the liberty of using the Z-Wave specification as a starting point as it has a pretty extended list of supported features and description and I figure that other technologies have more or less the same situations.

• A window covering device may be closed or open. The term closed represents the lowest light through- put, while open represents the highest light throughput.

• In some parts of the world it is considered more intuitive to refer to a closed cover as 100% and an open cover as 0% - in contrast to current HA specification. We should consider this as a global or device specific setting perhaps ?

Device types / scenarios

Classic "roll down" cover

Description: Window/door covering (also known as roller blinds or screens) that covers the window (or door) from the top to the bottom.
Required controls: open/close (also referred to as up/down)
Optional controls: stop movement, get current open/close status, get current position, set current position
Most common controls: move open/close, stop, get/set current position
Current support status in HA:: Fully supported
Common?: Yes, very common

Classic "roll up" cover

Description: Variant of the classic covering but instead of moving from top to bottom to close, it moves from bottom to top.
Required controls: open/close (also referred to as up/down)
Optional controls: stop movement, get current open/close status, get current position, set current position
Most common controls: move open/close, stop, get/set current position
Current support status in HA:: Technically supported (like the regular top to bottom cover) but not visualized correctly (the cover would move the wrong direction in the UI).
Common?: No, exception

Roll up and down window cover

Description: A combination of the roll up and roll down cover where the "open" position would be the center of the window and closing it would roll/slide to the top and/or bottom. The most common usecase would probably be that both sides roll up and down at the same time and no individual control is possible.
Required controls: open/close
Optional controls: stop movement, get current open/close status, get current position, set current position, set roll direction?
Most common controls: open/close, stop, get/set current position
Current support status in HA:: Technically supported in theory but the frontend would probably not match reality.
Common?: No, exception - do these even exist in the wild as smart appliance?

Classic (single) curtain

Description: A classic window curtain that (slides) open by moving from left to right or from right to left.
Required controls: open/close (also referred to as up/down)
Optional controls: stop movement, get current open/close status, get current position, set current position
Most common controls: move open/close, stop, get/set current position
Current support status in HA:: Fully supported
Common?: Yes, very common
Notes: The Z-Wave specification mentions a possibility for a single curtain that can open/close in both directions, like some sort of freeform but not sure if there are actual devices that can do that ? Is it a very rare exception maybe ?

Classic (double) curtain

Description: A classic double window curtain setup which opens from the middle to the sides. The left curtain would move from left to right to close, the right curtain would move from right to left to close.
Required controls: open/close (also referred to as up/down)
Optional controls: stop movement, get current open/close status, get current position, set current position
Most common controls: move open/close, stop, get/set current position
Current support status in HA:: Fully supported
Common?: Yes, very common
Notes: The curtains will always be controlled as a set and the position would be the result of the average/calibrated position where calibration/dividing of individual curtains happens outside the scope of Home Assistant.

Horizontal Window blinds

Description: Window covering (also known as blinds) that covers the window fully or partially and is semi-transparent by default. Closing happend by tilting the blinds up and/or down. Usually the middle tilt position is considered open. Optionally these window blinds can also be moved up/down.
Required controls: open/close (which will tilt in one direction)
Optional controls: stop movement, get current open/close status, get current position, set current position, tilt direction, up/down control, up/down position
Most common controls: open/close, stop, get/set current (tilt) position
Current support status in HA:: Partially supported
Common?:Yes, becoming more common.

Vertical Window blinds

Description: Window covering (also known as blinds) that covers the window fully or partially and is semi-transparent by default. Closing happens by tilting the blinds left and/or right. Usually the middle tilt position is considered open. Optionally these window blinds can also be moved to the left/right.
Required controls: open/close (which will tilt in one direction)
Optional controls: stop movement, get current open/close status, get current position, set current position, tilt direction, left/right control, left/right position
Most common controls: open/close, stop, get/set current (tilt) position
Current support status in HA:: Unknown
Common?:Unknown

Awnings (over patios)

Description: Rolled up next to the wall, the rolls out to cover a a patio. Inverted logic in a sense. Closed would be fully retracted, 0% retracted. See retracted awning on: https://en.wikipedia.org/wiki/Awning
Required controls: open/close (where closed means fully retracted)
Optional controls: stop movement, get current open/close status, get current position, set current position
Most common controls: open/close, stop, get/set current position
Current support status in HA:: Technically supported, not sure about the visualization in the frontend
Common?:Yes, very common
Notes: The most common awning is the large patio one which covers a large horizontal area (patio) where you can also have the window awnings which are smaller and meant for covering the window (feature wise the same as the traditional roller cover but optical not the same)

[elupus]

Awnings over patios. Inverted logic in a sense. Closed would be fully retracted, 0% retracted.

[marcelveldt]

Added to the text, please check if I'm complete, thanks!

[elupus]

I would add a image to the larger style of patio awnings too. The one that covers a full floor, rather than a window. The window awning are closer to other window covers.

[marcelveldt]

done and added a comment about window awning vs patio awning

[mback2k]

I created the new wmspro integration with patio awnings in mind and implemented it like described above, e.g. closed = retracted = 0%. But of course this results in a weird representation in HA, especially once not only horizontal awnings are handled, but also vertical awnings like described here: home-assistant/home-assistant.io#35116

Here you would think based on the draggable bar that the awning is not retracted and open, but of course it is closed/retracted instead:

Are there any suggestions how to handle this situation until a new architecture has been implemented?

[mback2k]

WMS cover state has been inverted in the mean time to align with current implementation state and limitations of HA:
home-assistant/core#128079

[EnochPrime]

There are also "top-down bottom-up" shades which are the classic single curtain, but a vertical orientation.

[marcelveldt]

Like this ?

[EnochPrime]

Correct

[marcelveldt]

Added to the text, please check if I'm complete, thanks!

[starkillerOG]

Actually the motion blinds integration supports smart Top Down Bottom Up covers that can individually control the top and bottom bars, see motion blinds docs.

These have 2 motors inside, so you can basically cover ever area you want with these (only top half, only bottom half, or middel section).

[EnochPrime]

Are the door-type "covers" out of scope of this discussion?

[marcelveldt]

No, I should extend the text for that, valid point

[BradleyFord]

Also there are blinds (Shangri-la) that I have. Essentially they operate as normal roller blinds and are partially transparent; but when you go from 95% to 100% closed they will become much more transparent by tilting. https://www.alibaba.com/product-detail/Deyi-Smart-interior-decoration-light-filtering_1600625135476.html?spm=a2700.shop_plgr.41413.3.af9618ddTq81Ic We could potentially solve this by supporting a configurable "Favorite" position; so then I can set the favorite to 95%. Then people can choose to click on close or favorite.

[marcelveldt]

isn't that just a up/down window cover with additional tilt ?

[BradleyFord]

The challenge is the tilt is based on how far down the blind goes.
95%: If I bring the blind down to 95% then is it fully at the bottom of the window, but the tilt is open
100%: Between 95 to 100, the tilt then changes so that it is not see through.

So I am thinking we could solve by adding a "Favorite" position so then it can be used for other purposes as well; in that case I could set "Favorite" to be the fully down but not tilted.

[farmio]

I just want to point out that there are parts of the world where it is considered more intuitive to refer to a closed cover as 100% and an open cover as 0% - in contrast to current HA specification.

It would for sure be widely appreciated if this would be user / integration configurable.

See https://community.home-assistant.io/t/why-the-heck-cant-we-freely-configure-a-cover-to-interpret-its-percentage-value-as-percentage-open-or-percentage-closed/225453

[marcelveldt]

valid point, I actually ran into this myself too where we do the opposite of various specs, HA does it the other way around and we have to invert many cover state values. Added it to the main text

[piitaya]

Most smart home platforms are using the same convention as HA (Google, Apple, Somfy). If you ask for any voice assistant to open or close the blind to 40%, it will always be 40% open.

[jlpouffier]

A window covering device may be closed or open. The term closed represents the lowest light through- put, while open represents the highest light throughput.

Just note that for some device type. Closed/Open will be the result of a combination of two more technical components.

For Venetian blind.

If the blind is all the way down, then tilting the blades will "open it" based on your definition. From 0% to 100%

If the blind is half way down. Then tilting the blades will change its "opening position" from 50% to 100%. We will never reach 0% since only half of the window is covered in the first place.

And finally if the blind is fully up, then tilting is pointless and does not change its "opening".

What I want to say is that if we want to offer a "opening position" and a service to "set" the opening position, it many be complex for Venetian blind because an large number of configuration leads to the same result.

Or to put differently:
If you show me a Venetian blind, then I can tell you its "opening position" from 0% to 100%.
But if you tell me to put a Venetian blind at 76% open, then I cannot give you a single answer. I can give tou dozens and dozens of answers that will satisfy "76% open"

[jlpouffier]

We're missing a type of awning. Unfortunately I only know the name in French (Pergola Bioclimatique à lames orientables)
But let's say "Tilting blade awning"

It looks like this
https://youtu.be/X3qzygRtRG0

[jlpouffier]

I am not sure it's important but coming back to the fact that we want to represent the "light throughput" as "opening position"

I have some blinds with interlocking blades.
When the blinds reaches the "bottom" of the window, the light is still able to enter the room through small holes in between the blades.
If I close it even more, it becomes fully opaque

Like that:
https://youtube.com/shorts/7_CPmr7qplo

That results in a non linear light throughput based on the cover position.

[starkillerOG]

Smart motorized double roller blinds also exist: https://motionblinds.com/en/products/double-roller-blinds/

These are a sort of cross bread between a venetian and roller blind.

[pawlizio]

Velux has a list of device (actuator) types which are supported by io-homecontrol protocol (also used by Somfy). So in order to fill your list you should take a look at page 104 and 105 of the linked document: https://github.com/pawlizio/pyvlx/blob/master/spec/technical%20specification%20for%20klf%20200%20api-ver3-18.pdf

Moreover here also the logic of 100% and 0% open/close is inverted, in io-homecontrol 100% is fully closed.

Below is a list of Somfy device types

[emontnemery]

It's mentioned about tilt that:

"Usually the middle tilt position is considered open"

It has been discussed before to have the neutral tilt as 0, and then tilt in two directions, either +/- degrees or +/- 100

[piitaya]

Agree, but min_tilt and max_tilt doesn't have to be symmetric.

Here's an example at home :
-/+90* is closed, 0° is open, -/+60° is almost closed (but we can considered it closed) 😅

IMG_2577.2.mp4

If we have 2 closed position, what we will the closed position when you will call the close service?

[piitaya]

In some parts of the world it is considered more intuitive to refer to a closed cover as 100% and an open cover as 0% - in contrast to current HA specification. We should consider this as a global or device specific setting perhaps ?

I don't agree, even it can be counter intuitive, it's a pretty common use-case in the smart home environnement to use open percentage instead of closed percentage.

Google smart home is using openPercent : https://developers.home.google.com/cloud-to-cloud/traits/openclose
Homekit is also using the same : https://developer.apple.com/documentation/homekit/hmcharacteristictypecurrentposition

About tilting, Homekit is using degree instead of percentage (https://developer.apple.com/documentation/homekit/hmcharacteristictypecurrenttilt). IMO, it makes sense. 0° is fully open and -90°/90° fully closed.

[gaaf]

As the platform is named "cover" and not "window cover", I'd like to add the pool cover as option. I now have the cover modeled as a shutter as that gives the most appropriate icon. Because the cover is laid out horizontally, the up/down arrows on the buttons for open/close are highly confusing. I can not deduce from the icons which one does which action.

[gaaf]

I think the overview of the cover types in the OP should get an additional bullet item: "Supported feedback" besides the "Required/optional controls". This would indicate whether the cover can supply open/closed/opening/closing/idle/etc... states. For correct representation of controls in the frontend this information is necessary. See home-assistant/frontend#18889 for an example.

[wernerhp]

Covers can also behave differently after being stopped. See home-assistant/frontend#17945 for a longer description.

[rrooggiieerr]

I would like to add my cover types:

Projector screen, projector lift and tv lift.

In all these cases open is in a pulled out state and closed a retracted state, opposite to the default cover behaviour.

[BradleyFord]

Same for me, I have projector lift and screen in which the states are actually opposite to normal.

[rrooggiieerr]

Which projector screen you're using and how you're controlling it? I'm currently working on updating my integration for XY Screens which is an OEM brand and being sold by many other brands:
https://github.com/rrooggiieerr/homeassistant-xyscreens

[pp81381]

I didn't have a lot of luck with my proposal here: #578

Much the same as the author of this discussion, I believe that projector screens should be a new device class. Would something along those lines be what you are looking for?

[wernerhp]

Another cover type rhat would be useful is Desk. For standing desks.

[jvmahon]

Not a device type, but a property addition:
It would be nice to be able to implement the target position as an attribute that could be triggered on and used in automations.

For example, in Matter, this would be the TargetPositionLiftPercent100ths attribute. The TargetPositionLiftPercent100ths usually changes several seconds before the CurrentPositionLiftPercent100ths attribute. If you are using the position of Slide 1 to set slides 2, 3, 4, if you could trigger an automation once the target position changes, and could then use the target to set slides 2, 3, 4, then using one shade as the "lead" device which controls the others would be much more responsive.

[tommyjlong]

Would it be helpful to have different device classes?
In one of my cases I have tilt-only blinds, so perhaps a device class of blinds_tilt_only

[farmio]

This is currently covered by CoverEntityFeature flags.
Cover already has device classes like "awning", "curtain", "blind", "garage" etc.

[tommyjlong]

I think I understand what you are saying:

class CoverEntityFeature(IntFlag):
    """Supported features of the cover entity."""

    OPEN = 1
    CLOSE = 2
    SET_POSITION = 4
    STOP = 8
    OPEN_TILT = 16
    CLOSE_TILT = 32
    STOP_TILT = 64
    SET_TILT_POSITION = 128

For my tilt-only blinds it does indeed shows that it only supports the last 4 features (supported_features: 240 =>xF0).
So why do tilt-only blinds always have "unknown" state? For tilt-only blinds it can be easily determined from the tilt position that the state is either open or closed.