Versatile Thermostat: a full feature thermostat (energy, door/window, presence, motion, preset, ... management)

See full readme here: GitHub - jmcollin78/versatile_thermostat: A full featured Thermostat for Home Assistant: presets, window, motion, presence and overpowering management


Tip This thermostat integration aims to drastically simplify your automations around climate management. Because all classical events in climate are natively handled by the thermostat (nobody at home ?, activity detected in a room ?, window open ?, power shedding ?), you don’t have to build over complicated scripts and automations to manage your climates ;-).

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

New News

  • Release 3.1: added detection of open windows/doors by temperature drop. This new function makes it possible to automatically stop a radiator when the temperature drops suddenly. See Auto mode
  • Major release 3.0: addition of thermostat equipment and associated sensors (binary and non-binary). Much closer to the Home Assistant philosophy, you now have direct access to the energy consumed by the radiator controlled by the thermostat and many other sensors that will be useful in your automations and dashboard.
  • release 2.3: addition of the power and energy measurement of the radiator controlled by the thermostat.
  • release 2.2: addition of a safety function allowing a radiator not to be left heating forever in the event of a thermometer failure
  • major release 2.0: addition of the “over climate” thermostat allowing you to transform any thermostat into a Versatile Thermostat and add all the functions of the latter.

When to use / not use

This thermostat can control 2 types of equipment:

  1. a heater that only works in on/off mode (named thermostat_over_switch). The minimum configuration required to use this type of thermostat is:
    has. equipment such as a radiator (a switch or equivalent),
    b. a temperature probe for the room (or an input_number),
    vs. an external temperature sensor (think about weather integration if you don’t have one)
  2. another thermostat that has its own operating modes (named thermostat_over_climate). For this type of thermostat, the minimum configuration requires:
    has. equipment such as air conditioning which is controlled by its own climate type entity,
    b. a temperature probe for the room (or an input_number),
    vs. an external temperature sensor (think about weather integration if you don’t have one)

The thermostat_over_climate type allows you to add all the functionality provided by VersatileThermostat to your existing equipment. The climate VersatileThermostat entity will control your climate entity, turning it off if the windows are open, switching it to Eco mode if no one is present, etc. See here. For this type of thermostat, any heating cycles are controlled by the underlying climate entity and not by the Versatile Thermostat itself.

Why another thermostat implementation ?

This component named Versatile thermostat manage the following use cases :

  • Configuration through standard integration GUI (using Config Entry flow),
  • Full uses of presets mode,
  • Unset the preset mode when the temperature is manually defined on a thermostat,
  • Turn off/on a thermostat when a door or windows is opened/closed after a certain delay,
  • Change preset when an activity is detected or not in a room for a defined time,
  • Use a TPI (Time Proportional Interval) algorithm thank’s to [Argonaute] algorithm ,
  • Add power shedding management or regulation to avoid exceeding a defined total power. When max power is exceeded, a hidden ‘power’ preset is set on the climate entity. When power goes below the max, the previous preset is restored.
  • Add home presence management. This feature allows you to dynamically change the temperature of preset considering a occupancy sensor of your home.
  • Add services to interact with the thermostat from others integration: you can force the presence / un-presence using a service, and you can dynamically change the temperature of the presets and change dynamically the security parameters.
  • Add sensors to see the internal states of the thermostat


Note: no configuration in configuration.yaml is needed because all configuration is done through the standard GUI when adding the integration.

Click on Add integration button in the integration page

The configuration can be change through the same interface. Simply select the thermostat to change, hit “Configure” and you will be able to change some parameters or configuration.

Then follow the configurations steps as follow:

Minimal configuration update

Give the main mandatory attributes:

  1. a name (will be the name of the integration and also the name of the climate entity)
  2. the type of thermostat thermostat_over_switch to control a radiator controlled by a switch or thermostat_over_climate to control another thermostat. Cf. above
  3. a temperature sensor entity identifier which gives the temperature of the room in which the radiator is installed,
  4. a temperature sensor entity giving the outside temperature. If you don’t have an external sensor, you can use local weather integration
  5. a cycle duration in minutes. On each cycle, the heater will cycle on and then off for a calculated time to reach the target temperature (see preset below),
  6. minimum and maximum thermostat temperatures,
  7. the power of the l’équipement which will activate the power and energy sensors of the device,
  8. the list of features that will be used for this thermostat. Depending on your choices, the following configuration screens will appear or not.

Tip Notes
1. With the thermostat_over_switch type, calculation are done at each cycle. So in case of conditions change, you will have to wait for the next cycle to see a change. For this reason, the cycle should not be too long. 5 min is a good value,
2. if the cycle is too short, the heater could never reach the target temperature indeed for heater with accumulation features and it will be unnecessary solicited

Select the driven entity

Depending on your choice on the type of thermostat, you will have to choose a switch type entity or a climate type entity. Only compatible entities are shown.

For a thermostat_over_switch thermostat:
The algorithm to be used today is limited to TPI is available. See algorithm

For a thermostat_over_climate thermostat:

Configure the TPI algorithm coefficients

Click on ‘Validate’ on the previous page and you will get there:

For more informations on the TPI algorithm and tuned please refer to algorithm.

Configure the preset temperature

Click on ‘Validate’ on the previous page and you will get there:

The preset mode allows you to pre-configurate targeted temperature. Used in conjonction with Scheduler (see scheduler you will have a powerfull and simple way to optimize the temperature vs electrical consumption of your hous. Preset handled are the following :

  • Eco : device is running an energy-saving mode
  • Comfort : device is in comfort mode
  • Boost : device turn all valve full up

None is always added in the list of modes, as it is a way to not use the presets modes but a manual temperature instead.

Tip Notes
1. Changing manually the target temperature, set the preset to None (no preset). This way you can always set a target temperature even if no preset are available.
2. standard Away preset is a hidden preset which is not directly selectable. Versatile Thermostat uses the presence management or movement management to set automatically and dynamically the target temperature depending on a presence in the home or an activity in the room. See presence management.
3. if you uses the power shedding management, you will see a hidden preset named power. The heater preset is set to power when overpowering conditions are encountered and shedding is active for this heater. See power management.
4. if you uses the advanced configuration you will see the preset set to security if the temperature could not be retrieved after a certain delay
5. ff you don’t want to use the preseet, give 0 as temperature. The preset will then been ignored and will not displayed in the front component

Configure the doors/windows turning on/off the thermostats

You must have chosen the With opening detection feature on the first page to arrive on this page.
The detection of openings can be done in 2 ways:

  1. either with a sensor placed on the opening (sensor mode),
  2. either by detecting a sudden drop in temperature (auto mode)

The sensor mode

In sensor mode, you must fill in the following information:

  1. an entity ID of a window/door sensor. It should be a binary_sensor or an input_boolean. The state of the entity must be ‘on’ when the window is open or ‘off’ when it is closed
  2. a delay in seconds before any change. This allows a window to be opened quickly without stopping the heating.

Auto mode

In auto mode, the configuration is as follows:

  1. a detection threshold in degrees per minute. When the temperature drops below this threshold, the thermostat will turn off. The lower this value, the faster the detection will be (in return for a risk of false positives),
  2. an end of detection threshold in degrees per minute. When the temperature drop goes above this value, the thermostat will go back to the previous mode (mode and preset),
  3. maximum detection time. Beyond this time, the thermostat will return to its previous mode and preset even if the temperature continues to drop.

To set the thresholds it is advisable to start with the reference values ​​and adjust the detection thresholds. A few tries gave me the following values ​​(for a desktop):

  • detection threshold: 0.05°C/min
  • non-detection threshold: 0 °C/min
  • maximum duration: 60 min.

A new “slope” sensor has been added for all thermostats. It gives the slope of the temperature curve in °C/min (or °K/min). This slope is smoothed and filtered to avoid aberrant values ​​from the thermometers which would interfere with the measurement.

To properly adjust it is advisable to display on the same historical graph the temperature curve and the slope of the curve (the “slope”):

And that’s all ! your thermostat will turn off when the windows are open and turn back on when closed.

Tip Notes
1. If you want to use multiple door/window sensors to automate your thermostat, just create a group with the usual behavior (Group - Home Assistant)
2. If you don’t have a window/door sensor in your room, just leave the sensor entity id blank,
3. Only one mode is allowed. You cannot configure a thermostat with a sensor and automatic detection. The 2 modes may contradict each other, it is not possible to have the 2 modes at the same time,
4. It is not recommended to use the automatic mode for equipment subject to frequent and normal temperature variations (corridors, open areas, …)

Configure the activity mode or motion detection

If you choose the Motion management feature, lick on ‘Validate’ on the previous page and you will get there:

We will now see how to configure the new Activity mode.
What we need:

  • a motion sensor. The entity id of a motion sensor. Motion sensor states should be ‘on’ (motion detected) or ‘off’ (no motion detected)
  • a motion delay (in seconds) duration defining how long we wait for motion confirmation before considering the motion
  • a target “motion” preset. We will used the temperature of this preset when an activity is detected.
  • a target “no motion” preset. We will used the temperature of this second preset when no activity is detected.

… see more on github readme here: GitHub - jmcollin78/versatile_thermostat: A full featured Thermostat for Home Assistant: presets, window, motion, presence and overpowering management


Hello, I tested your thermostat. I noticed that no group can be used in the presence. Is that right? The heating should only be turned down in a room when everyone is absent. How do I do that?

You can create a template binary sensor.

Group in configuration.yaml are not usable because they are not seen as ‘binary sensor’ nor ‘person’.

A template is good solution as proposed by @Skeletorjus

EDIT: an example (to be adapted, it is for multiple window sensors):

- binary_sensor:
# Template pour Temporisation ouverture/fermeture des fenêtres
    - name: Fenêtres Bureau  (temporisation)
        seconds: 1
        seconds: 270
      state: >
        {{ is_state('binary_sensor.fenetre_bureau_contact', 'on')
          or is_state('binary_sensor.fenetre_bureau_escalier_contact', 'on')
      device_class: window

I like very much this work because it is very much near perfection for my needs.
I want to contribute but I cannot find Contribution guidelines page on github.
How can I help ?
I’m an Home Assistant newbie and I’m not a coder, so, at first, I can translate Versatile in Italian but I don’t know where to send the file.
I also have in my house a quite complex hvac system (heating / cooling) plus controlled mechanical ventilation, if You want to test new functions for Versatile…

Hello @CBergoglio ,

Glad to here you. The last release 3.2.0 is now stable but if you want to contribute you are welcome. You have a contribution link at the of the Readme.

In general you fork the repo, made contributions and then do Pull Request to have your work merged. I will be happy to review your work.

Translations to italien are very welcomed !

Ok, I will try.
And, also, my daughter will help me (She is studying how to code in Python).

I understood that this thermostat can manage only heating, am I right ?
We are thinking to modify Versatile also for cooling… but we are newbie, so can You explain us where to work ?..


VTherm can also control AC device through the thermostat over climate feature.
If you already have a climate for your AC device, you can add the VTherm feature (presence, windows, …) with this feature.

Have a look at the documentation for this feature and let me know if it is clear for you.


this saturday I will translate in Italian.

At the same time I will test a solution for my home heating / cooling system.
I have some questions about Versatile for cooling system :

  1. I will set Versatile thermostat_over_climate to control the generic_thermostat from HA settled to ac_mode true; is it a good idea ?
  2. how must I set configuration variables in the generic_thermostat to work with Versatile ?
  3. I think that I must set temperatures presets with opposite logic, for example eco 29°C - comfort 28°C - boost 27°C, am I right ?
  4. what about the TPI algorithm ? How I must set it for cooling ?


Hello @CBergoglio ,

this saturday I will translate in Italian.

Very nice ! Glad to see this.

  1. I will set Versatile thermostat_over_climate to control the generic_thermostat from HA settled to ac_mode true; is it a good idea ?

Yes. But with with your HVAC device, don’t you already have a dedicated “climate” entity ? If yes, you should use this climate entity and not a generic one. But it should work also.

  1. how must I set configuration variables in the generic_thermostat to work with Versatile ?

You just have to expose hvac_mode, set temperature, current_temperature and if you want min_temperature and max_temperature. It should be enough to start

  1. I think that I must set temperatures presets with opposite logic, for example eco 29°C - comfort 28°C - boost 27°C, am I right ?


  1. what about the TPI algorithm ? How I must set it for cooling ?

TPI algorithm is NOT for the thermostat_over_climate. In thermostat_over_climate, the regulation is done by the device itself or by the underlying thermostat but not by the Versatile Thermostat. So there is no way to use TPI algorithm with thermostat_over_climate

I will expose my case:
I have an Airton reversible HVAC which have a Wifi module which is controlable via Smart Home (Tuya) application. This HVAC is regulating itself consider the target temperature you give it. The integration in Home Assistant is done by a Tuya climate entity which is connected to the device. Versatile Thermostat in thermostat_over_climate mode is just changing hvac_mode (cool, heat, off, dry, …) and target temperature of the Tuya climate entity. That is why I said, you certainly have an existing climate which is controling your device. And because regulation is done by the device itself, there is no need to TPI algorithm.

I hope it is more clear

Ok, I made the Italian translation (I’m sorry for my delay).
Must I work also on the file ?

I made an it.json file and Github allowed me only to fork Your repo then put in my repo the file it.json

Hello, I have seen your file. I will have a check and then merge quickly. I intend to do a release today, so your update will be embedded if ok.

Must I work also on the file ?

It would be a valuable work. As you want


today my daughter helped me and She wrote some code for automation.yaml and script.yaml (I’m not a coder).

At first my hardware set :

  • in every room I have one fancoil Aermec FCZ P (a simple fancoil with one radiator, 3 speed fan and without electronics) that can heat or cool

  • every fancoil has a valve kit (Aermec VCZ1X4L) composed of two valves (one for cool pipes, one for heat pipes) that manage cool water or hot water inside the radiator

  • I control the 3 speed fan through a Shelly Pro4pm and the valves through a Shelly Pro2pm

  • I also control the on/off heating of the condensing boiler through another Shelly Pro2pm

My idea is to control heating with 1 Scheduler Component + 1 Versatile Thermostat in thermostat_over_a_switch mode, then in the first heater I will choose a virtual switch that will start the hot valve, the fan and the condensing boiler.

My daughter wrote this afternoon this script to switch on (She will write the switch off next days) :

            - if:
                - condition: state
                  entity_id: switch.valvola_freddo_bagno_nonna
                  state: 'on'          
                - service: switch.turn_off
                    - if:
                      - condition: state
                        entity_id: switch.valvola_caldo_bagno_nonna
                        state: 'off'
                        - service: switch.turn_on
                 - service: switch.turn_on
                   entity_id: switch.valvola_caldo_bagno_nonna
            - service: switch.turn_on
                entity_id: ##switch.caldaia
            - service: switch.turn_off
                  - switch.velocita_1_clima_bagno_nonna
                  - switch.velocita_2_clima_bagno_nonna
                  - switch.velocita_3_clima_bagno_nonna
            - delay:
                seconds: 10
            - variables:
                t_ril: "{{ states('sensor.bagno_nonna_temperatura') }}"
                    entity_id: ###termostato
                    value_template: "{{ states('input_number.temperature') | int }}"
            - if:
                - condition: template
                    - sensor.vel1_clima_bagno_nonna_power
                    - sensor.vel2_clima_bagno_nonna_power
                    - sensor.vel3_clima_bagno_nonna_power
                  value_template: 0
                - choose:
                      - conditions:
                                - condition: template
                                  value_template: "{{ t_tar - t_ril < 0,2 }}"
                                - service: switch.turn_on
                                  entity_id: switch.velocita_1_clima_bagno_nonna
                      - conditions:
                                - condition: template
                                  value_template: "{{ t_tar - t_ril >= 0,2 and t_tar - t_ril < 0,5 }}"
                                - service: switch.turn_on
                                  entity_id: switch.velocita_2_clima_bagno_nonna
                      - conditions:
                                - condition: template
                                  value_template: "{{ t_tar - t_ril >= 0,5 }}"
                                - service: switch.turn_on
                                  entity_id: switch.velocita_3_clima_bagno_nonna
                - service: notify.notify
                    message: "Errore clima bagno nonna"

But we are newbie of Home Assistant and we don’t know how to obtain the target temperature value from Versatile :
t_tar > target temperature from Versatile
t_ril > real temperature in the room
in lines

- variables:
                t_ril: "{{ states('sensor.bagno_nonna_temperatura') }}"
                    entity_id: ###termostato
                    value_template: "{{ states('input_number.temperature') | int }}"


Current room temperature and target temperature can be obtained by requesting the attributes current_temperature and temperature of the thermostat entity.

In template you do that with such code:

"{{ state_attr('sensor.bagno_nonna_temperatura','current_temperature') }}"
"{{ state_attr('sensor.bagno_nonna_temperatura','temperature') }}"

How can I add custom preset like a Wind Free on my Samsung A/C? I’m using this custom addon GitHub - veista/smartthings: A fork of the Home Assistant SmartThings Integration. This adds better support for Samsung OCF Devices.

Hello @dimmuboy , with Versatile Thermostat you cannot add a preset. You have to use the existing one: Eco, Comfort, Boost, Activity

Ok, after one month and some days I found 2 problems :

  1. I created and settled 4 Versatile thermostats (over 4 standard Home Assistant thermostats) and I don’t know why one of them (always the same) it switches off by itself, the others never.
  2. Three of these thermostats use detection of presence relying on one person (person.renata) and Versatile always think “no presence” (Out of house). It happens with every (me, my wife and my daughter). The fourth Versatile relies on a binary_sensor that I made in configuration.yaml
  - binary_sensor:
      - name: "Siamo a casa"
        state: "{{ is_state('group.gruppo_bergoglio_p1','home') }}"

and the presence in Versatile works in the right way.

1 Like

Hi, my daughter is trying to develop on the code of Versatile, but she has a lot of problems to understand guidelines and she needs to be more in contact with You and other developers. How can she contact You ?

Hello @CBergoglio, she can contact me on Discord jmc#4854

Hi, just started to try out this one.

One question, I realized that I need different preset temperatures depending on if cooling or heating. How would I do that with least effort?

For example, during the summer I want to cool but have Eco/Comfort/Boost set to 23/21/19, but during the winter I want to use the something like 17/19/21 instead. I would like this to be controlled by selecting Cool or Heat HVAC mode rather than scheduling a date period.

Edit: Sorry, should have read the manual first :slight_smile:
Using an automation that triggers when state changes to cool or heat and then modifies the presets.