Add feature flags ClimateEntityFeature.TURN_OFF + ClimateEntityFeature.TURN_ON

[emontnemery]

Background

Core PR home-assistant/core#25026 added services climate.turn_off + climate.turn_on, but without corresponding feature flags. Core PR home-assistant/core#100418 adds service climate.toggle which relies on climate.turn_off + climate.turn_on. However, the default implementations of climate.turn_off and climate.turn_on only work if the climate entity supports certain HVAC modes:

• The default implementation of climate.turn_off only works if the climate entity supports HVAC mode HVACMode.OFF
• The default implementation of climate.turn_on only works if the climate entity supports at least one of HVAC modes HVACMode.HEAT_COOL, HVACMode.HEAT, HVACMode.COOL

Problem

Calling climate.turn_off, climate.turn_on or climate.toggle does nothing, or doesn't work as expected in case of toggle, if the climate device does not override climate.turn_on and climate.turn_off and also does not support the required HVAC modes.

Proposal

Add feature flags ClimateEntityFeature.TURN_OFF + ClimateEntityFeature.TURN_ON.
During a deprecation period of 12 months, ClimateEntityFeature.TURN_OFF + ClimateEntityFeature.TURN_ON will be automatically set by the base component if either of the following is true:

• The derived class overrides the default implementation of climate.turn_on or climate.turn_off
• The required HVAC modes are supported

[arturpragacz]

During a deprecation period of 12 months, ClimateEntityFeature.TURN_OFF + ClimateEntityFeature.TURN_ON will be automatically set by the base component

Is there any reason to deprecate setting those flags automatically? I mean the conditions for the base implementation seem pretty sensible - if the climate entity has HVACMode.OFF then it obviously supports turning off.
By forcing all integrations to be explicit about it, all that we are gonna achieve is that some of them inevitably will not update and users will lose functionality for no good reason.

[emontnemery]

Is there any reason to deprecate setting those flags automatically? I mean the conditions for the base implementation seem pretty sensible - if the climate entity has HVACMode.OFF then it obviously supports turning off.

It's mostly that we don't do this kind of auto detection for any other feature flag, we leave it to the integration to explicitly signal that there's support.

By forcing all integrations to be explicit about it, all that we are gonna achieve is that some of them inevitably will not update

During the deprecation period, we should log messages and/or create issues telling users to ask their custom component author's to update their integration.

[arturpragacz]

Makes sense - if we don't do this for any other feature, then keeping that consistent is a valid consideration.

In that case I think we should add something like is_turn_{on,off}_supported_by_base() to the base class, so that subclasses that don't provide their own overrides can easily call that and set the flag based on the result.

[gjohansson-ST]

In this case it likely make sense to "calculate" to add the features automatically if overrides exists.
Not sure what's being proposed here but developers should not need to do anything else than overriding the functions and set the feature flags accordingly (during the deprecation period).

[arturpragacz]

As far as I understand the proposal is:

1. Make support for turn_on, turn_off, toggle services conditional on the adequate flags.
2. During the deprecation period set the flags automatically if either:
   • the overrides exist
   • the HVAC modes required by the base implementation are present
3. After the deprecation period the integrations need to set flags themselves. They do so if:
   • they provide their own overrides
   • if they want to opt in to using the base implementation instead, they check whether the necessary conditions for it are met; to do that they simply call is_turn_{on,off}_supported_by_base() and set the flags based on the result

The last dot is my addition. Everything prior to that was already in the OP.

[gjohansson-ST]

I suggest we leave it with ClimateEntityFeature.TURN_OFF as that implies we also can turn if on and toggle.
It also matches and HVACmode which exist but there is not mode for on
Thinking a bit more I think probably we need both.

[arturpragacz]

Thinking a bit more I think probably we need both.

Yes, we do. If anything it is actually the opposite - it is the ClimateEntityFeature.TURN_OFF that can be reasonably guessed based on whether the device has HVACMode.OFF in its supported modes. It is much harder to know about TURN_ON.

Nevertheless, although it wasn't mentioned, it is however worth pointing out that we do NOT need flag for TOGGLE. Support for TOGGLE should be equivalent to having support for both TURN_ON and TURN_OFF.

[Noltari]

@emontnemery there's another discussion related to this topic, which suggests adding a new HVAC_MODE_ON mode (or at least broadening the scope of HVAC_MODE_AUTO).
Maybe it would also make sense to add TURN_ON and TURN_OFF by default only if HVAC_MODE_OFF and HVAC_MODE_ON modes are supported.

Context: some climate entities only support being switched on and off (slave thermostats depending on their corresponding master thermostats) and, in order to support them, integration developers (advantage_air, airzone, airzone_cloud...) are forced to do weird stuff like replicating the modes of the master thermostat or misusing the HVAC_MODE_AUTO mode.

[gjohansson-ST]

I don't think the other discussion makes sense but we should anyway not consider it for this one.

[Noltari]

Well, it makes sense to me because in Home Assistant climate entities can't be really switched on and off. We're faking it by having an OFF mode and by considering that any HVAC mode != OFF is ON.
For me ON and OFF should be completely independent from the HVAC mode and most of the air conditioners have this behaviour: you can switch them on and off without changing its HVAC mode.

[Noltari]

So maybe what I should do is open a new discussion which suggests separating the ON/OFF status from the HVAC modes on the climate entities...

[frenck]

As per discussion in a video call on October 12, 2023; this proposal has been approved. ✅

[frenck]

Implemented in home-assistant/core#101673

[frawau]

Sorry to be late on this... but, as I wrote somewhere else...

I really thing that having a TURN_OFF feature for a HVAC entity is a terrible idea.

Any HVAC device will either cool, heat, fan, dry, humidify, ... or none of the above, which essentially means off. So OFF, is never a feature, it is a mode. If an entity implements the turn_off method, it simply should be considered as a convenient shortcut for switching to the "off" mode, possibly saving the current mode, and can easily be handled through introspection.

The TURN_ON feature is a bit more subtle. A fan device will not be "ON" it will simply be in "FAN" mode or "OFF" mode, A/C can be more complex. In that context, turn on may simply mean that we restore the state that existed prior switching to the "OFF" mode. But the semantic should be clear.

This does not change the fact that TURN_OFF should never be a feature. Even in the unlikely case a device cannot be turned off, it simply means that device does not support the "off" mode. No need for a feature.

A toggle feature might be a better option for those entities with only 2 states, like a fan ( fan, off) or a heater (heat, off)...

[Noltari]

I totally disagree with your point, since there are some HVAC devices in which the temperature can be adjusted, but the mode can't be changed.
This happens with zonified HVAC installations in which there's one (master) thermostat in which the mode can be changed, and there are N (slave) thermostats in which the desired temperature can be adjusted, and the thermostat can only be turned on or off, but no HVAC mode can be configured.
For reference see #998

If we apply your reasoning to light entities then you're saying that a light can't be turned on, it will just be OFF or in WARM_COLOR_MODE, but never on, which makes no sense at all.

For me, one thing is the HVAC mode, and another different thing is the switch status, which can be either ON or OFF. And in this case I wouldn't even provide an OFF mode for climate devices, since this should go on a separate kind of switch attribute.

[frenck]

. So OFF, is never a feature, it is a mode.

I don't agree with that. For example, electric heaters (like those little radiator things).

But the good news is: This is feature flag. So each integration can adjust it to the situation that best fits it.

../Frenck

[frawau]

If I may.

@frenck Sorry, but those electric heater are IMO in either "Heat" or "Off" mode. One advantage is that it makes very clear what the device actually does.

@Noltari I see your point as long as the slave devices can be used whilst the master is "off". At the same time, I think that "Off" feature should only apply to the master device, slave would then have 2 modes, Off and the (dynamically set) mode selected by the master. Again this makes vary clear what the slave can do.

Cheers,
François