Versatile Thermostat Documentation

Versatile Thermostat (VTherm) is a Home Assistant integration that turns your heat pump, air conditioner or any HVAC system controlled by a climate entity into a smart thermostat: presets, window detection, presence, automatic start/stop and self-regulation to reach the target temperature.

VTherm also controls electric radiators and thermostatic radiator valves. All features are configured from the Home Assistant interface, without scripts or complex automations: nobody home, a window open, a room that does not reach its setpoint? The thermostat handles it natively.

• Versatile Thermostat Documentation
  • Installation Example
  • Supported Equipment
  • Prerequisites
  • Devices
  • Documentation Contents
    • Getting Started
    • VTherm Types
    • Features
    • Regulation
    • Help and Reference
    • Going Further
  • Next Step

Installation Example

For heat pumps and air conditioners:

1. Create a VTherm of type over_climate on top of the existing climate entity of your heat pump or air conditioner. The device keeps its own regulation and VTherm adds its features on top of it.
2. The heat pump quick start of the website details the configuration step by step.
3. If the device does not reach the target temperature, enable self-regulation: VTherm then adjusts the setpoint sent to the device.
4. Add the useful features: automatic start/stop to stop the device when it is not needed, window detection, presence management, and the auto-fan to speed up the fan when the temperature gap is large.

Supported Equipment

VTherm controls the heating and cooling equipment available in Home Assistant:

• Heat pumps, air conditioners and HVAC systems exposed by a climate entity: heat pump guide,
• Water radiators fitted with thermostatic radiator valves (TRV), with or without direct valve control: TRV guide,
• Electric radiators, controlled by a switch or by a pilot wire module: pilot wire guide,
• Valves controlled by a number entity, without an associated thermostat,
• Pellet stoves, with the VTherm Pellet stove plugin: pellet stove guide,
• Central boiler: VTherm turns it on as soon as a room needs heating (see Controlling a Central Boiler).

The VTherm type to create for each piece of equipment is explained in Choosing a VTherm.

Prerequisites

• Home Assistant and the Versatile Thermostat integration installed from HACS (see Installation),
• the equipment to control, available in Home Assistant,
• a room temperature sensor: any sensor available in Home Assistant can be used, or an input_number,
• an outdoor temperature sensor: the Home Assistant weather integration is enough.

Devices

The heat pumps, air conditioners and other devices exposed by a climate entity that have been tested with VTherm are listed in the device catalog of the website, with their support level and configuration advice. The catalog also lists thermometers, thermostatic valves and electric heating devices.

This catalog is not exhaustive: a device that is not listed is not necessarily incompatible. The incompatible devices and the partially supported devices are described there with their known limitations.

Documentation Contents

Getting Started

• Installation: install the integration with HACS.
• Quick Start: a working VTherm in a few steps, depending on your equipment.
• Choosing a VTherm: centralized configuration or not, choice of the VTherm type.
• Choosing Basic Attributes: name, temperature sensors and features to enable.

VTherm Types

• over_climate Type Thermostat: heat pumps, air conditioners and thermostatic valves exposed by a climate entity.
• over_switch Type Thermostat: electric radiators controlled by a switch or a pilot wire.
• over_valve Type Thermostat: valves controlled by a number entity.

Features

• Comfort and savings
  • Presets: preset temperatures (Comfort, Eco, Frost protection...).
  • Timed Preset: apply a preset for a given duration.
  • Presence Management: lower the setpoint when nobody is home.
  • Motion Detection: change the preset depending on the activity in the room.
  • Door/Window Open Detection: react when a door or a window is opened.
  • External Humidity Sensor: display the humidity measured by an external sensor.
• Controlling the installation
  • Auto-start / Auto-stop: stop an over_climate when it is not needed.
  • Power Management (Load Shedding): do not exceed the available power.
  • Centralized Control: control all the VTherm at once.
  • Central Boiler: turn the boiler on when a VTherm needs heating.
  • Lock Feature: prevent changes from the interface or from automations.
• Safety
  • Advanced Configuration and Safety Mode: sensor that stops responding, incorrect equipment state.
  • Heating Failure Detection: the temperature does not follow the command.

Regulation

• Self-regulation: adjust the setpoint sent to an over_climate, or control the valve directly.
• Internal Device Temperature Synchronization: align the internal thermometer of the device with the room temperature.
• The Different Algorithms Used: TPI, SmartPI and other algorithms available as plugins.
• Auto TPI: automatic learning of the TPI coefficients.
  • Auto TPI: In-Depth Technical Guide
• Valve Recalibration: the recalibrate_valves service.
• Tuning Examples: commented settings for different types of installation.

Help and Reference

• Troubleshooting: common problems and their solutions.
• Download Past Logs: collect targeted logs, then open them in the log analyzer of the website.
• Reference Documentation: parameters, sensors, actions, events and attributes.
• Release Notes

Going Further

• Some Essential Add-Ons: UI card, scheduler, curves, notifications.
• Plugins catalog: algorithms, cards and device helpers.
• Device catalog: tested devices and their support level.

Next Step

Installation: install Versatile Thermostat in Home Assistant.

For common equipment, the quick start sums up the whole configuration on a single page.