Versatile Thermostat

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

Versatile Thermostat is a highly configurable virtual thermostat that transforms any heating equipment (radiators, air conditioners, heat pumps, etc.) into an intelligent and adaptive system. It allows you to consolidate and centrally control multiple different heating systems, while automatically optimizing your energy consumption. Thanks to its advanced algorithms (TPI, auto-TPI) and learning capabilities, the thermostat adapts to your home 🏠 and your habits, providing you with optimal comfort and significant reduction in your heating bills 💰. 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 9.2 - stable version

1. New way of managing heating/off cycles for over_switch VTherms. The current algorithm has a time drift and the first cycles are not optimal. This disrupts the TPI and especially the auto-TPI. The new Cycle Scheduler solves these issues. This change is completely transparent for you,
2. A log collector. Your support requests often fail due to your ability to provide logs, over the right period, targeted at the faulty thermostat and at the right log level. This is especially the case for hard-to-reproduce bugs. The log collector aims to solve this difficulty. It collects logs for you in the background at the finest level and an action (formerly service) allows you to extract them into a file. You can then download them to attach to your support request. The log analyzer associated with the website - launched in 9.1 see below - adapts to be able to digest these logs. More information about the log collector here,
3. stabilization of 9.x. The major version 9 brought many changes that generated some anomalies. This version provides the latest fixes related to this version 9.

Release 9.1

1. New logo. Inspired by the work of @Krzysztonek (see here), VTherm benefits from a new feature introduced in HA 206.03 to change its logo. The whole team hopes you will like it. Enjoy!
2. A website created by @bontiv addresses one of VTherm’s major challenges: documentation. This site also allows you to analyze your logs! Provide your logs (in debug mode) and you will be able to analyze them, zoom in on a thermostat, focus on a time period, filter what interests you, and more. Discover this first version here: Versatile Thermostat Web site. A huge thank you to @bontiv for this great work.
3. Official release of the auto-TPI feature. This function calculates the optimal coefficient values for the TPI. We would like to highlight the incredible work of @KipK and @gael1980 on this topic. Do not skip the documentation if you plan to use it.
4. VTherm now relies on the state reported by underlying devices in HA. As long as all underlying devices do not have a known state in HA, the VTherm remains disabled.

Release 8.6

1. added max_opening_degrees parameter for over_climate_valve VTherms allowing to limit the maximum opening percentage of each valve to control hot water flow and optimize energy consumption or other use cases.
2. added a valve recalibration function for an VTherm over_climate_valve allowing to force a maximum opening then a maximum closing to attempt recalibration of a TRV. More information here.

Release 8.5

1. added heating failure detection for VTherms using the TPI algorithm. This feature detects two types of anomalies:
   • heating failure: the radiator is heating strongly (high on_percent) but the temperature is not increasing,
   • cooling failure: the radiator is not heating (on_percent at 0) but the temperature keeps rising.

These anomalies may indicate an open window, a faulty radiator, or an external heat source. The feature sends events that can be used to trigger automations (notifications, alerts, etc.). More information here.

More informations here.

🍻 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. Heating Failure Detection
19. Self-regulation
20. Auto TPI learning
21. Algorithms
22. Lock / Unlock
23. Temperature synchronisation
24. Timed preset
25. Reference documentation
26. Tuning examples
27. Troubleshooting
28. 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:

Some comments about the integration

⭐ Star history

Enjoy!

Contributions are welcome!

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

---