Device Class for retractable projector screen/semantics of Covers

[pp81381]

Hi,

I am hoping to submit a frontend PR for a new device class to support in-ceiling or on-ceiling retractable projector screens. I asked about this on Discord and there was some challenge so it was suggested that I bring it up here.

The link to my proposed change is here

I have built my back end integration to comply with my understanding of the requirements of a Cover. E.g. that a position of 0 is closed and a position of 100 is fully open. However, the question is - what do open and closed mean in the context of a retractable screen?

At the moment I've built the integration in the way that I think is most intuitive:

• a screen is closed when it is retracted and the image area is not visible
• a screen is open when it is extended or partially extended so that the image area is visible
• a screen is "active" (i.e. should be yellow in the front end) when it is "open" and the image area is visible. My particular screen (in conjunction with a mask) supports multiple aspect ratios so doesn't need to be fully extended to be "open".

However, this logic is the reverse of say a blind which is closed when it is fully extended/covering the window and open/active when it is fully or partially retracted and not covering or partially covering the window.

Further, for most classes of cover in the front end, "open" means "up" and "closed" means "down". The front end cards reflect this which means that the default buttons and icons are in the opposite direction to what is expected. Hence my proposed change.

A comment was made on Discord that it might be the case that "HA calls it Closed when the cover is 'covering'.". While this is definitely true in most cases, my suggestion would be that the definition of "open" and "closed" should be device-class specific and intuitive to the user. While I was thinking about this I drew a table below of my personal perspective which may or may not be useful. As long as the back end correctly flags the device class then the front end can show the user an intuitive interface. Plus the user can override the device class too.

Do people think that my thinking around the semantics of open/closed in the context of a retractable screen make sense (is it even a Cover at all?) and is my PR acceptable?

A secondary question would be what would the best name for this device class? Currently I've called it "screen". I was wondering about "projector_screen", "retractable_screen" or "in_ceiling_screen" but I note that all of the existing device classes are concise single word names.

Regards,

Phil

P.S. Here is the table I mentioned. I had a look at all of the other Cover device classes and while most are consistent with blinds I'd argue that "awning" is very similar semantically to a screen:

device_class	object of cover	meaning of open	meaning of closed	meaning of opening	meaning of closing
awning	area below	the area below is partially or fully covered	the area below is not covered	covering (usually extending)	uncovering (usually retracting)
blind	window	window not covered or partially covered	window fully covered	uncovering (usually going up)	covering (usually going down)
curtain	opening, window, door	the opening is not covered or partially covered	the opening is fully covered	uncovering (usually going left/right)	covering (usually going left/right)
damper	airflow, sound, light	the object is partially or fully uncovered	the object is fully covered ("damped")	uncovering (usually retracting)	covering (usually extending)
door	area behind	the area behind is not covered or partially covered	the area behind is fully covered	uncovering	covering
garage	garage	garage entrance not covered or partially covered	garage entrance fully covered	uncovering (could be going up/down or side to side)	covering
gate	area behind	the area behind is not covered or partially covered	the area behind is fully covered	uncovering	covering
screen (proposed!)	image area	not retracted or partially retracted (image area visible or partially visible)	fully retracted (image area not visible)	extending (usually going down)	retracting (usually going up)
shade	opening, window	the opening is not covered or partially covered	the opening is fully covered	uncovering (usually going up)	covering (usually going down)
shutter	opening	the opening is not covered or partially covered	the opening is fully covered	uncovering (usually going up)	covering (usually going down)
window	area behind	the area behind is not covered or partially covered	the area behind is fully covered	uncovering	covering

[pp81381]

A quick update on the above.

I have submitted related PRs for Core, Front end and the Docs.

An example of a Cover implementation that works with these PRs is here.

Hopefully the PRs will be accepted.

[frenck]

Sorry! I've closed them, as this architectural discussion wasn't approved yet.

[frenck]

Some parts missing in this proposal:

• Which integrations can use this today (besides MQTT/Templates)? We only want to add things to our base entity components if there is a wider use possible from the start.
• How would the frontend be represented?

Please note, that the lack of activity on a proposal also indicates the general demand for it.

../Frenck

[BradleyFord]

I'm not yet sure what this adds that the other types don't offer?

I have a motorized ceiling projector and screen, both via MQTT. What will this add?

[pp81381]

Hi

Thanks for taking the time to review the proposal. Apologies for the delay in responding - I ran out of time last weekend.

What is the proposal trying to achieve?

The purpose of this proposal is to fully align the semantics and behaviours of projector screens implemented as Covers with the built-in Home Assistant front end cards.

• The default icons will represent a projector screen
• References to the terms "Up", "Down", "Opening", "Open", "Closing", "Closed" will be semantically correct
• Buttons will point in the right direction and will have the correct tooltips
• The correct button will be disabled when fully up or down
• The "More Info" dialog slider will show the correct position
• The percentage position will reflect the percentage "open" as expected
• The "active" and "inactive" states and icon coloring will be correct
• The Open/Close services will have the expected behaviour

Unfortunately, custom cards would not support this device class out of the box but if they are gradually updated to leverage the logic encapsulated in src/data/cover.ts (assuming they are implemented in TypeScript) then they would easily do so. For example, I intend to submit a PR to Mushroom Cards if this proposal is accepted.

Implementation notes

It's worth noting that I've simplified the proposed changes to the frontend since the PR above. I realised that the original PR wasn't respecting the HA standard that position 0 is fully closed and position 100 is fully open. The change now only comprises:

• Add the new device class itself
• Infer the cover icon from the state
• Compute the correct button open and close icons from the state
• Invert the more info slider

The relationship of the states "opening", "closing" and "closed" to "down", "up" and "fully up" needs to be defined in the integration itself. In my case:

        self._attr_is_opening = self._tt6_cover.cover.is_going_down
        self._attr_is_closing = self._tt6_cover.cover.is_going_up
        self._attr_is_closed = self._tt6_cover.cover.is_fully_up
        self._attr_current_cover_position = cover_position_to_percent_open(self._tt6_cover.cover.pos)

Similarly, the "open" and "close" commands have to map to "move down" and "move up":

    async def async_open_cover(self, **kwargs) -> None:
        await self.async_send_simple_command("move_down")

    async def async_close_cover(self, **kwargs) -> None:
        await self.async_send_simple_command("move_up")

Which integrations can use this?

Any integration that could be used to control a tubular motor used by a Projector Screen manufacturer. E.g. MQTT, ZHA, deCONZ, KNX, Somfy, Cover Templates etc. The point isn't to support my specific device/integration, but the class of devices - by leveraging an existing architectural capability that was designed for exactly that. I would add that the implementation of a custom integration is dramatically more intuitive if the device semantics match.

How would the Frontend be represented?

Here are some screen shots (apologies - not sure how to resize these:

Screen closed, state is inactive, close button greyed out, open button tooltip visible:

Screen opening:

Screen 75% open (e.g. for widescreen), state is active, both buttons active:

Screen Fully Open, open button greyed out, close button tooltip visible:

Screen closing:

More info slider - screen 75% open:

More info buttons:

Please let me know if you have any questions.