Self-Adaptive PI Thermostat Control for Home Assistant
A model-based PI controller that learns your room's thermal behavior and adapts regulation automatically — beyond fixed-coefficient approaches.
Important
Like TPI, SmartPI is available only for VTherms configured over a switch, over a valve, or over a climate entity with valve control.
SmartPI is an advanced PI-based thermal control algorithm built around a first-order thermal model (1R1C) rather than a classic PID loop. It learns your room's heating capability, heat loss rate and dead time, then uses that model to compute a much more accurate heating command than fixed-time proportional controllers.
- 1R1C Thermal Model: Learns your room's heating gain, heat-loss rate, and reaction dead times from real observations — no manual tuning required
- Auto-Tuned PI Gains: Computes Kp and Ki automatically from the learned time constant and dead time using IMC and heuristic rules
- Model-Based Feed-Forward: Estimates the steady-state power needed to hold the setpoint, combined with a slow bias trim and an FF3 predictive correction enabled by default for disturbance recovery
- Analytical Setpoint Trajectory: Shapes the proportional reference and applies a model-aware landing cap in heating mode to reach the target quickly while limiting overshoot
- Safety-First Governance: A regime-based matrix freezes or unlocks learning and gain adaptation depending on the current operating context
- Auto-Calibration: Monitors model quality over time and triggers a recalibration sequence when learning stagnates
- Valve Curve Linearization: Translates SmartPI demand into a valve position adapted to the non-linear behavior of radiator TRVs
- Rich Diagnostics: Publishes detailed learning status, model state, and regulation data — viewable via a dedicated Home Assistant Markdown card or the Equinox Regulation panel
This integration extends the popular Versatile Thermostat integration by adding the SmartPI algorithm as a plugin. Versatile Thermostat already provides comprehensive thermostat management in Home Assistant, and with SmartPI, you get:
- Professional-grade temperature control algorithms
- Seamless integration with existing VT configurations
- Per-device customization options
- Global defaults for easy setup
SmartPI publishes a structured diagnostics summary that the Equinox Lovelace card can detect automatically. Once Equinox is installed and configured for your Versatile Thermostat entity, its Regulation panel gives direct access to SmartPI learning, model reliability, command breakdown, history graphs, and maintenance actions.
- Ensure you have HACS installed in your Home Assistant instance
- Click the button above or manually add this repository in HACS
- Search for "Versatile Thermostat SmartPI" in HACS
- Install the integration
- Restart Home Assistant
- Add
Vtherm_smartpiintegration from Settings / Devices & Services / Integrations - Configure the SmartPI algorithm in your Versatile Thermostat devices
- Download the latest release from the Releases page
- Extract the
vtherm_smartpi.zipfile - Copy the
custom_components/vtherm_smartpifolder to your Home Assistantcustom_componentsdirectory - Restart Home Assistant
- Configure as above
Comprehensive documentation is available in English:
Contributions are welcome! Please see the documentation for development guidelines and testing procedures.
- @gael1980 for the scientific foundation and theory behind SmartPI
- @caiusseverus for his helpful heating simulator and his support with testing SmartPI and sharing knowledge
- @jmcollin for developing Versatile Thermostat
- @bontiv for the Versatile Thermostat website
- All the people who tested SmartPI during development
If SmartPI is useful to you, you can support its development here:
This project is licensed under the Apache 2 licensing terms. See LICENSE for details.