Model-predictive heating control for Home Assistant. It plans your heat pump and your hot water 24 hours ahead against hourly electricity prices, the weather forecast, and a thermal model of your own house that it keeps correcting from your own sensors.
An illustrative day drawn by a toy planner on this page. It is not a recording of the integration, and no number is read off it.
Solve: minimize cost + comfort penalty subject to comfort floor, tank limits, legionella clock, fuse and peak caps
A 24-hour model-predictive plan is re-solved on every interval against the full forecast trajectory, not against the weather right now.
Space heating and hot water share one compressor, so they are planned against each other rather than one after the other.
Hot water is guaranteed inside demand time frames rather than kept permanently hot, which is where most of the saving comes from.
Publish plan sensors, switch the heat pump, ECL110 displace / frequency advice
The plan is re-solved once per optimization interval — 30 minutes by default — and holds until the next solve.
Afterwards: compare prediction against reality, nudge the learned parameters
Every learner is snapshotted weekly (the last eight are kept), and a drift watchdog can roll them back to the last healthy snapshot.
The full theory: how it works
Each series has a legend chip that toggles it, hovering a slot shows why it was planned, and the stretch of the horizon whose prices are estimated rather than published is shaded. Click the card to enlarge it: the plan becomes two editable lanes you can drag, stretch, add to and remove from, with a running total and an Apply this plan button that pins your arrangement.
The integration serves and registers the card automatically. Add it with:
type: custom:heatpump-optimizer-card
Options and interactions: the dashboard card documentation
A 24-hour model-predictive plan is re-solved on every interval against the full forecast trajectory, not against the weather right now. Space heating and hot water share one compressor, so they are planned against each other rather than one after the other.
The heat-loss scale, tank cooling rates, the COP curve and its defrost derate, the solar aperture, internal gains, how the loss splits between floors, your hot-water draw statistics, your revealed comfort preference, and a cool-only heat-curve correction are all estimated from your own house. Every learner is snapshotted weekly (the last eight are kept), and a drift watchdog can roll them back to the last healthy snapshot.
Tibber spot prices, time-of-use grid transfer fees, the monthly capacity (effekt) tariff and its billing clock, PV self-consumption priced at what consuming actually costs you, and a learned diurnal price prior for the part of the horizon that has not been published yet. A live peak guard and a main-fuse headroom advisor act inside the metering window the plan never saw, and a contract comparison settles the month three ways so you can see what your tariff choice is worth.
A mixing valve is what lets a buffer tank store anything, so it is modelled explicitly. A wood furnace tank is a store of its own, drawn wood-first while it is usable, with an optional hot-water inlet coil. Your hydronic layout is picked from a catalog of drawn arrangements rather than described in prose, and circulation pumps — the hot-water loop and the space pump — are scheduled instead of left running.
Hot water is guaranteed inside demand time frames rather than kept permanently hot, which is where most of the saving comes from. Draw statistics are learned per window, with a heavy-day (90th percentile) target so the second shower is not the one that runs cold.
The plan is published as sentences grouped by reason, and graded 0–100 across envelope, machine and operation. Energy and cost accumulate into the Energy dashboard split by hot water versus space heating.
The card's editor pins exact run slots for up to 20 hours and the optimizer plans around them; a what-if simulator prices a comfort change before you commit to it; a climate entity and a switch give you the ordinary Home Assistant controls. Compressor frequency control is deliberately two-stage: it observes and advises until you explicitly turn writing on.
A staleness watchdog treats a sensor that stopped updating as missing and pauses learning rather than training on a flatline. Away and holiday mode sets back deeply and buys the recovery heat in the cheapest hours before you get home.
Entity names are translated (English, Swedish and German) and follow your Home Assistant language, without touching entity ids or history. Monetary units follow your instance currency.
A Tibber account with an API token (developer.tibber.com), or a price entity — a Home Assistant price sensor such as Nord Pool exposing raw_today / raw_tomorrow
A weather integration with hourly forecasts (Met.no or similar)
Everything else — indoor and outdoor thermometers, tank probes, a power meter — is optional. The optimizer runs without them and gets steadily better with each one you add.
a switch that turns the heat pump on and off
may turn it off during expensive hours
a Danfoss ECL110-compatible weather-compensated controller, reachable over MQTT
a heat-pump on/off decision and an integer parallel shift (displace) onto the controller's own heat curve
the compressor frequency exposed as a number entity (typically from Modbus or ESPHome)
the recommended frequency via number.set_value — but only once you switch the mode to Control
Each path is optional, the three are independent of each other, and with none of them configured “the plan is published on sensors for your own automations to act on”
Before 2026.11 the same four steps run in HACS.
Every screen, in order: setting up the integration
The first plan is solved within one optimization interval (30 minutes by default). Add the dashboard card and you can see what it intends to do.
If you want the commissioning step test, first switch on Allow a one-off measurement experiment under Advanced settings → Self-learning and diagnostics
The heat-loss scale, tank cooling rates and the COP curve start correcting themselves as soon as there is data to correct them with.
Hot-water draw quantiles and the heavy-day demand sensor need weeks of observation before they mean anything, and stay unavailable until they do.
There is no cooling mode and no cooling plan.
This is a planner, not a real-time controller.
There is no built-in way to feed prices from any other source.
Other markets' tariff structures are not modelled.
You add the integration yourself and pick every entity it reads.
The default Observe mode “learns and recommends but never writes”
Every cost, saving and percentage this integration reports is the output of a model, computed against forecast prices and forecast weather. Treat the numbers as a guide to relative decisions, not as an accounting record.
The characteristic failure mode is not bad code — it is confident wrong claims about code.
Nearly every one caught here was caught by re-measuring rather than by re-reading.
This is not a claim that the code is correct — it is a claim that assertions about it are recomputable, and that a wrong one is more likely to be caught than believed.
Every sentence of fact on this page is quoted from the documentation, and a test refuses one the documentation no longer makes.
Each document is a page of this site, built from its source in the repository, and changes only when that file does. The README holds the entity and service reference.