Versatile Thermostat (VTherm)

Versatile Thermostat (VTherm) is a highly configurable virtual thermostat for Home Assistant. It transforms various heating equipment—such as radiators, air conditioners, heat pumps, and switches—into intelligent, adaptive systems.

Key capabilities include:

• Centralized Control: Consolidate and manage multiple different heating systems from a single interface.
• Energy Optimization: Uses advanced algorithms like TPI (Time Proportional Integral) and auto-TPI to adapt to your home's thermal characteristics and your habits.
• Native Event Management: Automatically handles typical heating events like presence detection (nobody home?), room activity, window opening, and power load shedding, reducing the need for complex manual automations.
• Plugin Mechanism: (Available in v10.0+) Allows the use of external integrations as plugins.

VTherm is a highly configurable virtual thermostat for Home Assistant that transforms any heating device (radiators, air conditioners, heat pumps, etc.) into an intelligent, adaptive system. It centralizes control of multiple heating systems and optimizes energy consumption using advanced algorithms like TPI and auto-TPI.

Key benefits include:

• Simplified Automation: Native handling of heating-related events like presence detection, room activity, open windows, and power loss, reducing the need for complex custom scripts.
• Adaptive Learning: The thermostat learns your home's thermal characteristics and your habits to provide optimal comfort and reduce heating bills.
• Device Consolidation: Allows managing diverse heating hardware through a unified interface.

Versatile Thermostat (VTherm) is a highly configurable virtual thermostat for Home Assistant. It transforms any heating or cooling device (radiators, air conditioning, heat pumps, etc.) into an intelligent, adaptive system.

Key capabilities include:

• Centralized Control: Consolidate and manage multiple different heating systems centrally.
• Energy Optimization: Uses advanced algorithms like TPI (Time Proportional Integral) and auto-TPI to optimize energy consumption.
• Adaptive Learning: The thermostat learns your home's thermal characteristics and your habits.
• Native Event Management: Automatically handles common heating events such as presence detection (is anyone home?), activity detection, open windows, and energy consumption limits, reducing the need for complex manual automations.

Self-regulation is a feature available for VTherms of type over_climate. It allows the thermostat to automatically adjust its control strategy to ensure the room temperature reaches the desired setpoint.

There are two primary modes of operation depending on your hardware:

1. Direct Valve Control: Used if your underlying device is a TRV (Thermostatic Radiator Valve) and the valve is directly controllable in Home Assistant (e.g., Sonoff TRVZB). In this mode, the VTherm directly manipulates the valve opening using a TPI (Time Proportional Integral) algorithm.
2. Setpoint Adjustment: Used for other devices. Instead of controlling a valve, Versatile Thermostat adjusts the temperature setpoint sent to the underlying climate device to compensate for temperature deviations.

Auto TPI (Automatic Learning) is a feature that allows the thermostat to automatically learn the thermal characteristics of a room by adjusting two key coefficients:

• Kint (Internal Inertia): Controls heating responsiveness. It is adjusted during temperature rise when the deviation from the setpoint is significant (> 0.05°C) and heating is not at 100% power.
• Kext (External Insulation): Compensates for heat loss. It is adjusted during stabilization around the setpoint when the deviation is small (< 1°C).

Target Hardware: This feature is primarily designed for Switch (On/Off) heating systems (e.g., electric radiators, boilers, underfloor heating, or pellet stoves). It is not recommended for thermostatic radiator valves (TRV) due to their non-linearity.

When deciding which VTherm type to implement, follow this priority order based on your equipment:

1. Priority 1 (Best Regulation): If you have a controllable TRV exposed via a number entity (e.g., Shelly TRV), use over_valve.
2. Priority 2: If you have an electric radiator controlled via a switch entity, use over_switch. Regulation is managed by VTherm based on your local thermometer.
3. Priority 3 (Fallback): For all other cases (like HVAC systems), use over_climate. You retain your original climate entity, and VTherm manages its target temperature and on/off state.

Regulation Strategy Tip:

• If the equipment has reliable built-in regulation (e.g., standard HVAC), use over_climate.
• For TRVs with a controllable valve in Home Assistant, use over_climate with Direct Valve Control self-regulation for the best results.

To prevent feedback loops when the thermostat updates an entity, compare the new state received from Home Assistant against the last value sent by the thermostat. If the values match, the change was likely triggered by the thermostat itself and should be ignored. If they differ, the change originated from an external source (e.g., a user or an automation) and should be processed.

# In UnderlyingClimate._underlying_changed()
new_target_temp = new_state.attributes.get("temperature")

# Compare with last sent temperature to detect if change came from thermostat
if new_target_temp == self._last_sent_temperature:
    # Change was from thermostat, ignore
    return

# Otherwise it's from external source (user interaction, automation, etc.)

Continuous Kext Learning allows the thermostat to adapt to long-term climate changes and insulation variations in the background without manual sessions.

• Mechanism: It monitors $K_{ext}$ precision and applies micro-corrections using an Exponential Moving Average (EWMA) when systematic deviations are detected.
• Safety: Only active when power is not saturated and the system is stable.
• Configuration: You can adjust the Alpha factor (default 0.04). Higher values increase adaptation speed but increase sensitivity to noise.
• Requirement: Requires at least one successful outdoor learning cycle from a standard session to have been performed first.