Versatile Thermostat

This README file is available in languages : English | Français | Deutsch | Čeština | Polski

This thermostat integration aims to greatly simplify your heating management automations. Since all typical heating events (nobody home?, activity detected in a room?, window open?, power load shedding?), are natively managed by the thermostat, you don’t need to deal with complicated scripts and automations to manage your thermostats. ;-).

This custom component for Home Assistant is an upgrade and a complete rewrite of the "Awesome thermostat" component (see Github) with added features.

Screenshots

Versatile Thermostat UI Card (Available on Github) :

What's New?

Release 8.0

This is a major release. It rewrites a significant part of the internal mechanisms of Versatile Thermostat by introducing several new features:

1. requested state / current state: VTherm now has 2 states. The requested state is the state requested by the user (or Scheduler). The current state is the state currently applied to the VTherm. The latter depends on the different VTherm functions. For example, the user can request (requested state) to have heating on with Comfort preset but since the window has been detected open, the VTherm is actually off. This dual management always preserves the user's request and applies the result of the different functions on this user request to get the current state. This better handles cases where multiple functions want to act on the VTherm state (window opening and power shedding for example). It also ensures a return to the user's initial request when no detection is in progress anymore,
2. time filtering: the time filtering operation has been revised. Time filtering prevents sending too many commands to a controlled equipment to avoid consuming too much battery (battery-powered TRV for example), changing setpoints too frequently (heat pump, pellet stove, underfloor heating, ...). The new operation is now as follows: explicit user (or Scheduler) requests are always immediately taken into account. They are not filtered. Only changes related to external conditions (room temperature for example) are potentially filtered. Filtering consists of resending the desired command later and not ignoring the command as was previously the case. The auto_regulation_dtemp parameter allows adjusting the delay,
3. hvac_action improvement: the hvac_action reflects the current activation state of the controlled equipment. For an over_switch type it reflects the switch activation state, for an over_valve or valve regulation, it is active when the valve opening is greater than the minimum valve opening (or 0 if not configured), for an over_climate it reflects the underlying climate's hvac_action if available or a simulation otherwise.
4. custom attributes: the organization of custom attributes accessible in Developer Tools / States has been reorganized into sections depending on the VTherm type and each activated function. More information here.
5. power shedding: the power shedding algorithm now takes into account equipment shutdown between two measurements of home power consumption. Suppose you have power consumption feedback every 5 minutes. If a radiator is turned off between 2 measurements then turning on a new one may be authorized. Before, only turn-ons were taken into account between 2 measurements. As before, the next power consumption feedback will possibly shed more or less.
6. auto-start/stop: auto-start/stop is only useful for over_climate type VTherm without direct valve control. The option has been removed for other VTherm types.
7. VTherm UI Card: all these modifications allowed a major evolution of the VTherm UI Card to integrate messages explaining the current state (why does my VTherm have this target temperature?) and if time filtering is in progress - so the underlying state update has been delayed.
8. log improvements: logs have been improved to simplify debugging. Logs in the form --------------------> NEW EVENT: VersatileThermostat-Inversed ... inform of an event impacting the VTherm state.

⚠️ Warning

This major release includes breaking changes from the previous version:

• versatile_thermostat_security_event has been renamed to versatile_thermostat_safety_event. If your automations use this event, you must update them,
• custom attributes have been reorganized. You must update your automations or Jinja templates that use them,
• the VTherm UI Card must be updated to at least V2.0 to be compatible,

Despite the 342 automated tests of this integration and the care taken with this major release, I cannot guarantee that its installation will not disrupt your VTherms' states. For each VTherm you must check the preset, hvac_mode and possibly the VTherm setpoint temperature after installation.

🍻 Thanks for the beers 🍻

A big thank you to all my beer sponsors for their donations and encouragements. It means a lot to me and motivates me to keep going! If this integration has saved you money, buy me a beer in return; I would greatly appreciate it!

Glossary

VTherm: Versatile Thermostat as referred to in this document

TRV: Thermostatic Radiator Valve equipped with a valve. The valve opens or closes to allow hot water to pass.

AC: Air Conditioning. An AC device cools instead of heats. Temperatures are reversed: Eco is warmer than Comfort, which is warmer than Boost. The algorithms take this information into account.

EMA: Exponential Moving Average. Used to smooth sensor temperature measurements. It represents a moving average of the room's temperature and is used to calculate the slope of the temperature curve, which would be too unstable on the raw data.

slope: The slope of the temperature curve, measured in ° (C or K)/h. It is positive when the temperature increases and negative when it decreases. This slope is calculated based on the EMA.

PAC: Heat pump

HA: Home Assistant

underlying: the device controlled by VTherm

Documentation

The documentation is now divided into several pages for easier reading and searching:

1. Introduction
2. Installation
3. Quick start
4. Choosing a VTherm type
5. Basic attributes
6. Configuring a VTherm on a switch
7. Configuring a VTherm on a climate
8. Configuring a VTherm on a valve
9. Presets
10. Window management
11. Presence management
12. Motion management
13. Power management
14. Auto start and stop
15. Centralized control of all VTherms
16. Central heating control
17. Advanced aspects, security mode
18. Self-regulation
19. Tuning examples
20. Algorithms
21. Reference documentation
22. Tuning examples
23. Troubleshooting
24. Release notes

Some results

Temperature stability around the target configured by preset:

On/off cycles calculated by the integration over_climate:

Regulation with an over_switch:

Strong regulation in over_climate:

Regulation with direct valve control in over_climate:

Enjoy!

Contributions are welcome!

If you wish to contribute, please read the contribution guidelines.

---