Add "timed open" to the valve entity

[puddly]

Problem

If a simple automation opens a valve and uses a delay to close it, Home Assistant restarting, crashing, losing wireless connectivity, etc. will cause the valve to stay open. For lights this is at most an annoyance but irrigation valves failing in an "open" state are much more of a danger.

Background

Many protocols already have a "timed open" concept for most things that can be turned on: Zigbee On With Timed Off, Matter ValveConfigurationAndControl.Open(openDuration, targetLevel), Z-Wave Irrigation Valve Run. Integrations currently use custom actions (hydrawise.start_watering, rainbird.start_irrigation, rachio.start_watering) or config entities (Matter DefaultOpenDuration, Gardena Bluetooth manual_watering_time) to represent this.

This is a valve-only version of #615 (but I think this concept really should be extended to anything that supports it, lights and switches included).

Proposal

1. Add ValveEntityFeature.OPEN_TIMED.
2. Add ValveEntity.async_open_valve_for(duration: timedelta) and ValveEntity.async_set_valve_position_for(position: int, duration: timedelta).
3. Add an optional duration field to valve.open_valve and valve.set_valve_position, filtered on OPEN_TIMED. As today, valve.open_valve on a valve with SET_POSITION calls async_set_valve_position_for(100, duration).
4. (Maybe) add an auto_close_at state attribute: the time at which the valve closes by itself, or None.

Integrations

• Matter
• Gardena Bluetooth
• Hydrawise
• ZHA (the valve platform is a WIP but we have a few devices that expose this functionality already)
• Rain Bird and Rachio, which use switch today
• Z-Wave (once zwave_js has a valve platform, the specification supports it)

[puddly]

At least for Zigbee, support for async_set_valve_position_for with a duration is not provided by the specification (though some manufacturers I think support it with proprietary commands). We might need to add ValveEntityFeature.SET_POSITION_TIMED as well.

[edenhaus]

We discussed this in the architecture meeting and there was general support for the idea. Having the device itself handle the auto-off/close is a valuable safety mechanism, since it keeps working when Home Assistant restarts, crashes, or loses connectivity. That matters for valves especially, but applies to probably all toggle entities.

The consensus was to consider this more broadly than valves: ideally the same concept should apply to toggle entities (switch, light, …), which also ties back to #615. Defining it consistently across entity types now is better than adding a valve-only version and retrofitting it later.

During the discussion we came up with the idea to keep the state as it is and add a state attribute holding the time at which the device will automatically revert (e.g. when the valve will close). In addition, the open/close (turn on/off) actions would get an optional duration parameter, gated by an EntityFeature.

@puddly could you put together an analysis of the timed-off/timed-open support across the different integrations?

• which entity types/device classes support it (valves, switches, lights, …)
• whether positional/level + duration is supported, or only open/on + duration
• whether the device reports back the remaining time or the scheduled off/close time
• duration limits/resolution and how cancellation works
• whether there are devices that support only "timed open" (open for X, then close) but not "timed close" (close for X, then reopen), or vice versa

@nielsrowinbik can you please look into this topic from the product/UX side, e.g. how the duration is exposed in the UI and in actions, and how the auto-off time is shown to users?

Once we have both, we can come back with a concrete proposal covering valves and toggle entities.

[AlCalzone]

To answer the question here for the Z-Wave perspective: The Z-Wave standard knows no timed on/off commands. Some devices implement auto-on and auto-off through non-standardized config parameters, but that is a per device setting and not per command.

[AlCalzone]

...except for some locks which can be unlocked for a given amount of time.

[AlCalzone]

There is exactly one Z-Wave irrigation system on the market. The Irrigation Command Class lets a controller turn a specific valve on for a certain amount of time, or multiple valves where each has a configured runtime.
Z-Wave valves have no position support, only off or on with runtime.
The command class has a bunch of support for configuring valves, their runtimes, and system properties though.