Turn your heating into a Predictive Smart System.
This integration acts as a Stand-Alone Pilot for your heating. It learns the thermal physics of your room to calculate heating signals for any thermostat (actual control is done via a Blueprint or automation), without needing complex dependencies.
- Goal: Reach your target temperature exactly when you arrive/wake up.
- Goal: Stop heating before you leave ("Optimal Stop").
Detailed documentation is available in the docs/ folder:
- Installation Guide (HACS & Manual)
- Configuration Reference (All parameters explained)
- How it Works (The Math) (Physics & Optimal Stop theory)
- Troubleshooting & FAQ (Common issues and solutions)
Important: This integration calculates the optimal time. You need an automation or Blueprint to actually control your thermostat!
Use the official Smart Setpoint Controller Blueprint. It connects this integration with your thermostats (TRVs) in seconds:
- View Discussion: Smart Setpoint Blueprint (Community)
- What it does: Automatically switches between Comfort/Eco based on the
preheatandoptimal_stopsignals.
- Self-Learning Physics: Automatically calculates
Thermal Mass,Thermal Loss, andDeadtime. Supports Euler Simulation for complex scenarios. - The Observer: Learns your habits to predict when you leave (Shadow Mode), providing "Next Departure" insights.
- Calendar Intelligence: Auto-detects holidays and shifts via Calendar integration to skip preheating intelligently.
- 🚀 Retroactive Bootstrap: On first install, the system automatically scans your Home Assistant history to learn your habits instantly. No more "cold start" week!
- Global Homecoming Prediction: A dedicated, automatically created "Preheat System" configuration entry manages a shared House Arrival Hub (device "Preheat House"). It aggregates occupancy data across all zones (or an optional global presence entity) to learn the typical homecoming patterns for the entire house once, robustly. Individual zone config entries reference this shared hub, and the System entry is created automatically (no manual step).
- Global Entities:
sensor.<...>_next_arrival— Predicted next house arrival time (Timestamp).sensor.<...>_arrival_confidence— Statistical confidence of the arrival pattern (%).sensor.<...>_arrival_window— Expected arrival time window (e.g.17:30-19:00).binary_sensor.<...>_incoming— The "someone is coming home" preheat signal (ON within maximum preheat lead time before expected arrival).
- Frost Protection: Heating is automatically forced ON if the temperature drops below 5°C, even if the system is disabled.
- ⚡ Reactive Setpoints: The system re-calculates immediately when you change the target temperature (0 latency).
- Physics Safety Net: The thermal model uses a physics-based model with stability protection (clamping, 20% jump limitation).
- Optimal Stop (Coast-to-Vacancy): Turns off the heating early if the room stays warm enough until the schedule ends (opt-in).
- Schedule-Free Operation: Works with Learned Patterns alone, without requiring a Schedule Helper, once arrival patterns are mature.
- Adaptive Polling: Sleeps (5 min updates) when idle, sprints (1 min) when active—80% less system load.
- Stand-Alone: Works with any thermostat entity. No external "Scheduler Component" required.
- Weather Forecast Integration: Looks ahead at the weather forecast to adjust heating power for incoming cold fronts.
- Outdoor Sensor Precedence: Supports dedicated outdoor temperature sensors that take precedence over regional weather entities for local microclimate accuracy.
- 🪟 Window Detection: Pauses operation if a rapid temperature drop is detected.
- 🔥 Heat Demand Sensor:
binary_sensor.<zone>_heat_demandsignals when a zone needs active heat supply.
- 15+ Repair Issues: Built-in health checks alert you to stale sensors, misconfigurations, or learning problems.
- Decision Trace: Provides detailed Diagnostics, Confidence scores, and "Reason" attributes so you know why it acted.
- UI Integration: Status sensor exposes
climate_entity,operative_sensor, andintegration_versionas attributes for UI Auto-Discovery by the Smart Setpoint Card. - 🌎 Localized: Available in English and German.
- Install via HACS (Custom Repository).
- Add Integration in Home Assistant settings.
- Config: Select your Heating Profile, Climate Entity (Thermostat), and Occupancy Sensor.
- Done: The system auto-scans your history and starts learning immediately!
This version is a stable release with the following feature maturity:
- Preheating Start: Fully active, supports both Schedule Helper entities and Schedule-Free Autonomous Start (gated by arrival pattern maturity).
- Optimal Stop / Coast-to-Vacancy: Available (opt-in via
enable_optimal_stopoption). - Schedule-Free Operation: Available (House Arrival Hub, opt-in).
- Shadow Savings Metrics: Fully active and accumulated over time.
- Autonomous Engine Cockpit Card: The original forum card is incompatible. An updated card is available as a diagnostic-only tool at docs/diagnostics/preheat_diagnostics_card.yaml (see docs/troubleshooting.md for details).
License: MIT