versatile_thermostat: Open Source Internet of Things (IoT)

What is versatile_thermostat?

Versatile Thermostat is a highly configurable virtual thermostat custom component for Home Assistant that turns radiators, air conditioners, heat pumps and other heating equipment into an adaptive, centrally managed heating system.

What it is

Versatile Thermostat is a Python-based custom component for Home Assistant, distributed under the MIT licence, that creates a virtual thermostat on top of heating equipment that is already connected to Home Assistant. It transforms radiators, air conditioners, heat pumps and similar equipment into an intelligent and adaptive system, and it consolidates multiple different heating systems so they can be controlled centrally. Its behaviour is driven by TPI and auto-TPI algorithms together with learning capabilities, which adapt the thermostat to the home and its habits. The project is listed under the Home Assistant and HACS topics and has a separate UI card for dashboards.

The concrete problem it solves is the layer of complicated scripts and automations that Home Assistant users otherwise build around their heating. Typical heating events, including nobody being home, activity being detected in a room, a window being open and power load shedding, are managed natively by the thermostat. It is an upgrade and a complete rewrite of the Awesome thermostat component, with added features, so it replaces both that predecessor and much of the hand-built automation logic around it.

Key capabilities

It creates a virtual thermostat over existing heating equipment, including radiators, air conditioners and heat pumps, and consolidates multiple different heating systems for central control.
It applies TPI and auto-TPI algorithms together with learning capabilities so that heating adapts to the home and its habits.
It natively handles typical heating events such as nobody being home, activity detected in a room, an open window and power load shedding, without separate scripts and automations.
It supports presets and manual overrides, including a configurable duration after which the thermostat restores the preset that was active before a manual temperature change, resuming a timed preset until its scheduled end.
It allows central boiler command values to be calculated with a Home Assistant template, evaluated whenever the boiler is activated, deactivated or kept alive, and validated during configuration.
It provides plugin inhibition, which lets compatible plugins temporarily withdraw a VTherm from control and suspend commands to underlying devices, and it offers heating failure detection as the external vtherm_heating_failure_detection plugin with central settings and per-VTherm overrides.
It can expose current_humidity from an external humidity sensor, and over_valve thermostats support valve parameters such as opening_threshold_degree, min_opening_degrees, max_closing_degree and max_opening_degrees, plus a Sleep mode that sends a raw 100% opening request without requesting central boiler heating.

Who uses it and how

Home Assistant households with mixed heating equipment use it to place radiators, air conditioners and heat pumps under one virtual thermostat instead of separate control schemes.
Homes with occupancy, activity and window sensors use it to have those events handled by the thermostat rather than by purpose-built automations.
Installations with a central boiler and several VTherms use its boiler command templates and plugin settings to coordinate heating across rooms.
HACS users install it as a custom integration and pair it with the separate Versatile Thermostat UI Card for dashboard control.
Users of the Awesome thermostat component are the intended migration audience, because this project is described as its upgrade and complete rewrite.

Getting started

Versatile Thermostat is installed through HACS as a Home Assistant custom integration, as indicated by its hacs-custom and hacs-integration topics, with configuration and documentation available at versatile-thermostat.org.

How it compares

The only comparable tool named in the facts is the Awesome thermostat component, of which Versatile Thermostat is an upgrade and a complete rewrite with added features. It therefore fits as a replacement path within the Home Assistant custom-component ecosystem rather than as a separate platform.

When to use it — and when not to

Choose it when Home Assistant is already the centre of the heating setup and the goal is to consolidate several heating systems and remove hand-written heating automations. Do not choose it if a standalone thermostat service or a vendor-supported hardware appliance is required, because it is a custom component that depends on Home Assistant and on the heating equipment integrated there. The feature set is broad and the release notes show configuration migrations, such as disabling the legacy heating-failure sensor before enabling its plugin and watching for changed entity IDs, so self-hosters should expect to manage configuration carefully.

project readme (upstream, from github) — read inline

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) :

Card1 Card2

What's New?

Release 10.6.1

Since version 10.5.1, this release introduces the following features:

Plugin inhibition: compatible plugins can temporarily withdraw a VTherm from control. Commands to underlying devices are suspended during this period; when control resumes, the thermostat reapplies its current state.
Automatic return after a manual override: configure a duration to restore the preset that was active before a manual temperature change. If a timed preset was already running, it resumes until its scheduled end.
Templates for central boiler commands: a command value can be calculated using a Home Assistant template, evaluated each time the boiler is activated, deactivated, or kept alive. Templates are validated during configuration.

Release 10.5.0

Heating failure detection can now be used as the external vtherm_heating_failure_detection plugin. The plugin provides central settings and per-VTherm overrides; its forms pre-fill the existing core settings to make migration easier.

During the transition period, plugin settings take precedence, while values not defined by the plugin continue to use the legacy core configuration. Disable the legacy feature for a VTherm before enabling the plugin to avoid duplicate configuration.

The heating-failure binary sensor is now provided by the plugin. When this can be done without a conflict, its existing entity_id is retained so dashboards and automations keep working. Reload the plugin entry after disabling the legacy sensor; if it remains active, Home Assistant may create a new entity_id that must be used by existing consumers.

Release 10.4.0

VTherm can now expose current_humidity from an external humidity sensor for all thermostat types. The sensor can be selected in the Humidity menu or automatically detected on the room-temperature sensor device.

over_valve thermostats now have the same valve control parameters as over_climate thermostats with direct valve control regulation: opening_threshold_degree, min_opening_degrees, max_closing_degree, and max_opening_degrees. More information: valve control.

over_valve thermostats now also support Sleep mode. Sleep displays VTherm as off and sends a raw 100% opening request without requesting central boiler heating. Configured valve-control limits can cap the physical opening. More information: Sleep mode.

Release 10.3.0

Power units can now be configured. Configuration screens let you select a unit for power measurements (W by default). Calculated energy units match the configured power unit. Existing entries are migrated using the historical device power value: values above 100 are treated as W; other values as kW.

⚠️ Important change for statistics You may see a repair notification such as: The unit of “Central configuration Total power active for boiler” (sensor.total_power_active_for_boiler) was changed to “kW”, or a similar log message. This is expected because the unit was previously not specified. Select the repair action Update the unit of long-term statistics to correct the statistics.

Release 10.2.0

The Auto Fan feature is now available as an external plugin (vtherm_auto_fan_extended). The original (legacy) auto-fan version is still available in VTherm, but it must be disabled in the thermostat configuration in order to use the plugin. The full documentation is available on the plugin's GitHub repository.

Release 10.1

Auto-start/stop stop mode selection. A new select entity lets you choose the mode applied when the auto-start/stop feature detects a stop condition: Off (default), Fan only or Dry. The Fan only and Dry modes are only proposed when the underlying appliance supports them. More information here.

Self-regulation is now disabled when an over_climate VTherm is not in Heat or Cool mode: the original (non-regulated) setpoint is sent to the underlying device. More information here.

Release 10.0

Introduction of the plugin mechanism. This allows the use of external integrations as plugins for VTherm. The list of available plugins is available on the Versatile Thermostat Web site.

🍻 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:

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.

Frequently asked questions

Is versatile_thermostat free to use?

versatile_thermostat is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does versatile_thermostat do?

A full featured Thermostat for Home Assistant: presets, window, motion, presence and overpowering management

What is versatile_thermostat written in?

versatile_thermostat is primarily written in Python. Its source is publicly available at https://github.com/jmcollin78/versatile_thermostat, and it has 1,230 GitHub stars.