vtherm_adaptive_tpi

Language: Français | English

Adaptive TPI plugin for Versatile Thermostat, built on top of vtherm_api.

What It Does

vtherm_adaptive_tpi provides an external adaptive_tpi proportional algorithm for Versatile Thermostat.

Its goal is to learn, during normal thermostat operation:

• deadtime (nd)
• thermal losses (b)
• heating authority (a)

and to use these learned values to adjust the thermostat gains over time.

The plugin stays in the TPI family:

• it computes a requested on_percent for the next cycle
• Versatile Thermostat still commits the actual current-cycle power through its normal cycle scheduler
• learning happens only from completed real cycles

TPI is a regulation algorithm built around a proportional loop through gain_indoor plus a feed-forward term through gain_outdoor to compensate thermal losses. There is no integral correction term used to cancel steady-state errors, so the I in TPI can be misleading.

If you need a more advanced proportional-integral controller with feed-forward, see vtherm-smartpi.

The integration includes:

• Home Assistant integration scaffolding
• registration through vtherm_api
• runtime connection to Versatile Thermostat cycle callbacks
• coarse deadtime estimation
• OFF-window learning for b
• ON-window learning for a
• conservative gain projection
• persistent runtime state
• diagnostics exposed in the climate specific_states

Learning Overview

At startup, the plugin does not know the plant yet.

The normal progression is:

1. if ON and OFF deadtimes are not both identified yet, startup bootstrap may force clean OFF->ON->OFF attempts
2. ON and OFF deadtimes start to emerge
3. b starts learning from OFF windows
4. a starts only later, once deadtime is credible and b is stable

Typical early observations are:

• control_rate_per_hour still unset
• control_rate_converged = false
• drift_rate_converged = false
• gains still close to defaults
• startup_sequence_active = true during the initial forced sequence

The runtime loop is:

1. the controller computes the next requested on_percent
2. the VT scheduler commits a real cycle and its applied power
3. the plugin records the cycle context
4. at cycle end, the plugin validates the cycle for learning
5. the deadtime model is updated
6. short learning windows are reconstructed from cycle history
7. b may learn from OFF windows
8. a may learn from ON windows, once deadtime and b are ready
9. gain_indoor and gain_outdoor are projected conservatively

Startup Bootstrap

When ON and OFF deadtimes are not both identified yet, startup may temporarily override the nominal command.

For meaningful bootstrap observations, the radiator should be cold before the sequence starts.

• if already above the low threshold, stay OFF until target - 0.5°C
• if already below the low threshold, start the heating step directly
• from target - 0.5°C, heat at 100% until target + 0.3°C
• then command 0% until the room returns to the setpoint
• if both ON and OFF deadtimes are identified before the setpoint is reached, keep the final OFF return-to-target step active
• if either ON or OFF deadtime is missing at the setpoint, retry the complete bootstrap cycle
• once both deadtimes are identified and the setpoint is reached, return to normal regulation
• each bootstrap threshold crossing forces an immediate cycle restart so the scheduler does not wait for the previous cycle boundary
• b learning remains governed by the normal OFF-window rules; the final return-to-target step only forces the command to 0%

Diagnostics

The plugin exposes learning diagnostics in the climate specific_states.

The most useful fields to inspect first are:

• adaptive_phase
• actuator_mode
• current_cycle_percent
• next_cycle_percent
• valve_curve_converged
• valve_curve_observations_accepted
• valve_curve_last_reason
• startup_sequence_active
• startup_sequence_stage
• startup_sequence_attempt
• startup_sequence_completion_reason
• deadtime_cycles
• deadtime_confidence
• deadtime_on_cycles
• deadtime_on_confidence
• deadtime_on_locked
• deadtime_off_cycles
• deadtime_off_confidence
• deadtime_off_locked
• drift_rate_per_hour
• drift_rate_confidence
• drift_samples
• sample_window_size
• control_rate_per_hour
• control_rate_confidence
• control_rate_converged
• control_samples
• last_learning_result
• last_learning_family
• last_runtime_blocker

Healthy learning often looks like this:

• deadtime_cycles starts moving before it is considered reliable
• drift_rate_per_hour appears before control_rate_per_hour
• drift_samples / sample_window_size fills progressively until the rolling window is full
• last_runtime_blocker often stays related to deadtime or cooling convergence for a while
• gain_indoor and gain_outdoor stay near defaults until confidence is good enough

Main Documentation

If you want to go deeper:

• Diagnostics User-facing runtime diagnostics and how to interpret them
• Architecture Internal architecture and learning flow

Repository Layout

• custom_components/vtherm_adaptive_tpi Home Assistant integration and adaptive algorithm code
• docs Project documentation
• tests Behavioral tests for the integration
• plans Design notes, mathematical specs, implementation plans, and review reports

Development Notes

This plugin depends on:

• versatile_thermostat
• vtherm_api

Development should be done with compatible versions of both sides.