Implement a keep-alive feature for directly controlled heater switches

[pdcastro]

The heater switch keep-alive feature consists of regularly refreshing the state of directly controlled switches at a configurable interval (regularly turning the switch ‘on’ or ‘off’ again, even if it is already turned ‘on’ or ‘off’), just like the keep_alive setting of Home Assistant’s Generic Thermostat integration:

HASS Generic Thermostat https://www.home-assistant.io/integrations/generic_thermostat/
keep_alive integer (optional)
Set a keep-alive interval. If set, the switch specified in the heater option will be triggered every time the interval elapses. Use with heaters and A/C units that shut off if they don’t receive a signal from their remote for a while. Use also with switches that might lose state.

[pdcastro]

@jmcollin78, this PR proposes the implementation of a keep-alive feature as described. If you agree to having such a feature added as proposed in this PR generally, I can then work further on it, especially adding documentation and translations.

When rebased on tag 5.3.3.beta3, all tests pass in the VSCode dev container. I have also tested “the real thing” with an appliance of mine and Home Assistant version 2024.1.3. The code was linted with black.

[jmcollin78]

Oooh I will see that. Thank you for this PR !

For over_switch, because of the cycle which constantly turns on and off, I guess there is no need of keep_alive (that is why I don't implement it initialy). And don't know for over_climate if this make sens, because the underlying climate may do it alone and may be for over_valve ?

I'm not sure this is useful finaly. In what case do you need this feature ?

[pdcastro]

Oooh I will see that. Thank you for this PR !

For over_switch, because of the cycle which constantly turns on and off, I guess there is no need of keep_alive (that is why I don't implement it initialy). And don't know for over_climate if this make sens, because the underlying climate may do it alone and may be for over_valve ?

I'm not sure this is useful finaly. In what case do you need this feature ?

Thanks for the feedback. 👍 The keep-alive feature is intended for “over_switch” operation — directly controlled switch entities. When a TPI cycle is delivering high power, say 100% (when the target temperature is well above the current temperature and the “on_percent” variable is near 1 = 100%), I understand that the switch is turned ‘on’ at the beginning of the cycle, and no further action (switch on/off) is taken on the switch until the end of the cycle. Does this match your understanding as well? In this case, if the appliance requires a keep-alive interval that is shorter than the TPI cycle, then the appliance will switch off (failsafe mode) before the end of the TPI cycle, delivering less power than intended.

I have definitely observed this behaviour with a small electric heater that requires a short keep-alive interval of 20 seconds, with a TPI cycle of 1 minute and intended 100% power. Without the keep-alive feature implemented in this PR, the appliance would switch off about 20 seconds into the TPI cycle, thus delivering 33% power (20 seconds ‘on’, 40 seconds ‘off’) even when the intended TPI power was 100% (60 seconds 'on', 0 seconds 'off').

Reducing the TPI cycle duration to match the required keep-alive interval may work in some cases, but not all cases. A larger heating system based on oil or natural gas (currently over three quarters of homes here in the UK, for example) may require longer TPI cycles such as 10 or 20 minutes,* while switch keep-alive intervals might be 1 or 5 minutes (or any other value, depending on the system design).

* Example: My central heating system takes up to a minute between heat demand being presented and the boiler igniting the flame, so a TPI cycle of 1 minute would just not work. When heat demand is presented to the system, a mechanical water valve slowly opens and some 20 seconds later, a water pump turns on and heat demand is presented to a natural gas boiler. The boiler then turns on a fan and takes another 20 to 40 seconds to ignite the main flame. I find that 20 minutes is a reasonable TPI cycle for this system.

[jmcollin78]

When a TPI cycle is delivering high power, say 100% (when the target temperature is well above the current temperature and the “on_percent” variable is near 1 = 100%), I understand that the switch is turned ‘on’ at the beginning of the cycle, and no further action (switch on/off) is taken on the switch until the end of the cycle

Yes, you are totally right. When 100% or 0% the switch is not switched but only at start of the first cycle. THe use case is now clear for me. I will have a look before going further to the development of the release (based on beta already pubished).

[jmcollin78]

Great improvement @pdcastro !

I will take this PR with pleasure. The comments are easy to fix, I guess.

[pdcastro]

Thanks for you review. 👍 I am adding new commits that address the points that were raised, to make it easier for you to see what has changed. Before merging the PR though, I could squash the commits to make the history tidier.
I also still need to add documentation and translations (Google Translate...). I can add those to this same PR, or I can create a separate PR. Let me know if you have a preference.

[pdcastro]

New commits added to address the review comments. To confirm:

• All tests pass (pytest in the VS Code dev container).
• Code formatted with black.
• Code checked with pylint and pylance.

[jmcollin78]

Thanks for you review. 👍 I am adding new commits that address the points that were raised, to make it easier for you to see what has changed. Before merging the PR though, I could squash the commits to make the history tidier. I also still need to add documentation and translations (Google Translate...). I can add those to this same PR, or I can create a separate PR. Let me know if you have a preference.

I prefer to have all in the same PR.

[pdcastro]

PR status: I have added the documentation and translations for review, with some comments. Other than that, I think the PR is ready for merging. I have squashed two of the commits too (tidier history). I have not marked any conversations as “resolved” — I leave that to you as the reviewer. If you think I have missed any conversation, please point it out to me. Thanks!

[jmcollin78]

We are almost done. And you have now a conflict in readme since your PR in images. Sorry for this but it should be easy to fix.

This is really a great job you have done 😍

[pdcastro]

I think it’s all done! 🎉

[jmcollin78]

Nice work !

[jmcollin78]

Merged !

If you want to give it a try in your environment, you can install the main branch from HACS.