Heat pump controller · intent, not registers

Thermaestro

Thermaestro plans a home's heating and hot water around electricity prices, the weather and what the household wants: warm rooms, hot water by seven, cost before comfort within limits. It works out how, changes only the settings it needs, and checks the result.

  • One plan for a heat pump's climate systems, hot-water tanks and pool, with sensors and meters.
  • Goals in household terms, a ranking of what gives way, and plain reports when a goal can't be met.
  • The house and the hot-water tank used as heat storage, within limits the household sets.

Brand-neutral: devices come in through plugins, and Nibe is the first. Thermaestro is meant to replace NibePi, and is open source under the AGPL.

Operating principle

How it works

Unmarked is built and runs today; later is planned, not built. Where it stands says what is being worked on.

The household states its goals and what may give way when not all can be met. A planner turns them into a schedule; Thermaestro changes the few settings it needs, checks what happens and learns from it. The approach follows intent-based management (RFC 9315 and 9316).

Each device stays in charge of itself. A heat pump keeps its own regulation, defrosting, compressor protection and its periodic hot-water increase against legionella. Thermaestro only adjusts the settings a device offers: a heating offset, the hot-water mode, holding off or starting a hot-water charge. Setting the flow temperature directly comes later. later

One controller per setting. A device feature that changes the same setting (a maker's price function, the pump's own schedule, its room control) must be off. Otherwise Thermaestro leaves that setting alone and says why.

The loop: intents go to the planner, the planner to control, control changes the heat pump's settings, follow-up checks the result and reports back to the household. Intents what the household wants Planner makes the schedule Control changes settings, checks Follow-up goals met? learns heat pump reports go back to the household

Fail-safe

When Thermaestro stops, loses a room sensor or trips its watchdog, it puts back the settings it found, or values you chose. Behind a gateway with a dead-man, a stop leaves hot water held off, so a restart doesn't start a charge in an expensive hour; the gateway puts it back if Thermaestro stays away. A setting it can't reach is tried again until it can, and a change cut off by a crash or a power cut is checked on the next start. Missing prices only stop the moving of heat to cheaper hours. Every change is read back; a value the pump doesn't keep is reported, not retried forever, and a change someone else makes is reported, never fought.

A pump keeps its settings while Thermaestro is stopped, so Thermaestro only sets values a house can live with if they are left behind: the heating offset within three steps of the household's own, hot water held off never below 35 °C, the electric addition kept off only while the mean outdoor temperature is above −15 °C, and a pool never switched off. The documentation says how to put each back by hand.

Behind a gateway that speaks Thermaestro's protocol, with a key, there is also a dead-man: after 15 minutes of silence the gateway puts each setting back as found, unless someone changed it meanwhile, and tells Thermaestro what it did. Without one, hot water is held off three hours at most.

Functions

What it does

Two planners decide every 15 minutes what each setting should be, and say why. The rules look at the household's goals, the rooms, the tank and the prices around now. The optimizer looks two days ahead: the heat each climate system needs, the weather, the heat stored in the house and the tank, and the pump's efficiency hour by hour. The household chooses which one drives; the optimizer drives only where what it has learned has proved itself. Every setting change counts as a small cost.

Intents

Standing intents apply all the time: a comfort range per climate system on a weekly schedule, hot water by set times, a lowest hot-water temperature, cost against comfort, when the electric heater may help, the pool, a power peak limit, quiet hours.

Temporary intents always end: warmer or cooler, please; a bath by 19:30; guests until Sunday; away until the 12th, ready when back; hands off for at most 48 hours; boost now; a fire in the fireplace. The newest wins, and the one before applies again when it ends. Thermaestro also works out whether anyone is home, from a burglar alarm, presence sensors and hot water drawn; heating less while nobody is home comes later. later

Levels are the household's own: named settings such as "Comfort, 21–22 °C". The weekly schedule uses them, so changing a level changes it everywhere. A new installation starts with levels from the devices' own settings.

When intents conflict, a fixed order decides: protection, the limits on changing settings, "hands off", temporary intents, standing intents, and last the devices' own settings.

A ranking decides what gives way, most important first: protective minimum temperatures, the low edge of each comfort range, hot water marked must, then should, the high edge of each comfort range, the power peak. One slider sets cost against closeness to the target, shown as real limits ("price may move the target up to 0.75 °C either way"). The optimizer solves the ranking stage by stage and shows what each stage leaves short.

Comfort and hot water

A comfort range per climate system, measured by room sensors from Home Assistant or MQTT. Thermaestro regulates the rooms itself, so the pump's own room control must be off. Air/air units in single rooms are still to be designed. later

No room sensor? The pump heats on its own curve, and Thermaestro may shift heat by up to a set amount toward cheaper hours. Once it has learned how the supply follows the weather and the offset, a slow system is heated ahead of the forecast, by at most three steps.

Hot water as °C at the top of the tank by a time; liters or showers once the tank model is calibrated. later Behind a gateway with the dead-man, the tank is a battery: the pump's own charges are held off and let go in the cheapest hours when the tank has room, and the comfort mode set at the pump says how full a charge makes it. Without the dead-man, charges are held off only in expensive hours. Either way the lowest hot-water temperature is kept, and charges are never held off over the pump's periodic increase.

A learned demand profile. Thermaestro sees hot water used, from how the tank cools outside its charges, and learns a typical week, the tank's heat loss, and what is drawn on days at home, away, leaving or coming back. Once these predict better than a simple guess, the planner uses them before a hot-water deadline, and the busiest hours are suggested as hot-water times, never applied without asking.

Cost, and the house as storage

Prices built from their parts: spot price, supplier surcharges, energy tax, grid fees and VAT, in 15-minute steps, checked against the supplier's own total. Grid tariffs are data: a time-of-use price, a power charge (the house is kept under the month's highest intervals so far) or a subscribed power, entered from the price list; Denmark's are read from Energi Data Service.

A reasonably insulated house is storage. Within each comfort range, price moves a room's target toward the warm edge in cheap hours and the cool edge in expensive ones, as far as the slider allows. How fast the house loses heat, how long its heating takes to show, and what its radiators or floor store are learned from the rooms, the water and the weather. The optimizer heats ahead only where the price difference pays for the extra heat lost.

Slow heating systems. Floor heating in a concrete slab can take half a day or more to respond. The planner raises comfort one response time early and says how long a request takes: "the floor heating will be 1 °C warmer in about 12 hours". The response starts from the answer given at setup, then is learned from the rooms.

The real world. Open windows, a fire in the fireplace, quiet hours and public holidays are part of the plan, and the pump's own heating stop is followed. The sun and the household's own heat are learned as part of the house; what a kWh gives in heat is learned from hot-water charges and the brine. The optimizer keeps the compressor's starts to the pace the pump kept on its own, corrects the forecasts' learned bias, and reckons each hour's COP from the brine, or the outdoor air for a pump without brine.

The ground cooling over a winter, defrosting, a margin on must goals sized from forecast misses, and cooling come later. later

Reports, wear and shadow mode

Plain reports. Asking for something gets an answer at once: when it ends, what it sets aside, and whether it will be ready in time, or how late and how warm instead. While it runs it shows whether it is on track, at risk, or giving way to something more important, and to what. An events page lists what happened, such as a room below its range or a part of Thermaestro that failed, and why. Each morning a summary says what the pump used and what it cost the day before. Each person can turn on notifications to their phone through Home Assistant, or to MQTT. Savings against a reference the household can check come later. later

Settings are changed sparingly. Some pumps store settings in memory that wears with writes. Thermaestro counts each change as a cost, never rewrites a value that is already right, and has a hard daily limit per setting.

Shadow mode. Thermaestro plans but changes nothing, and shows each decision beside what the pump showed at the time, as charts, a table and a CSV. Coming from NibePi, run it alongside, then switch one setting at a time.

Checked before it is learned from. A value a pump offers isn't always a measurement: some read 0, or never change. Each value must first have behaved like its quantity over the last week; one that hasn't is left out and shown as such. What is learned survives restarts, and the household can pin a number or start one over.

Replayed weeks. A period of an installation can be exported, without accounts, secrets, addresses or coordinates, and the learners run over it again day by day; hot-water use the household noted down is scored against the draws found.

One installation, many devices

Devices and plugins

Several devices, one plan. An installation is a tree of devices, each handled by a plugin. One planner covers a pump's climate systems, hot-water tanks and pool, each climate system with its own room sensors. Cascades of heat pumps, air/air units and other heat sources (a boiler, district heating, a wood stove) join the same plan later. later

Many brands, many connections. Plugins reach devices however they allow: today a bus gateway, Modbus TCP, Home Assistant and MQTT, and the interface leaves room for a REST gateway, a cloud API, infrared or relay contacts such as SG Ready. Planning never sees registers, only what a device reports and which settings it offers.

Nibe first: F-series and related models through a small gateway on the pump's accessory bus, S-series over their built-in Modbus TCP. Other brands follow as plugins. later

Gateways for Nibe's bus. Thermaestro's fork of esphome-nibe runs on an ESP32 with RS485, and thermaestro-gateway on Linux with an RS485 adapter. Both speak plain NibeGW and the Thermaestro gateway protocol, which adds a report for every request, bus timing, health statistics, optional authentication and, with a key, the dead-man. Plain NibeGW gateways work too, with less information.

Home Assistant and MQTT

To Home Assistant, Thermaestro is a device like any other, found through MQTT discovery. It takes room sensors and other values from Home Assistant or MQTT. It is not a Home Assistant add-on.

Users and security

Everyone logs in, on the home network too. Rights are per kind of action, so a household member can ask for more warmth without changing minimum temperatures. HTTPS by default, with the installation's own certificate. Secrets live in their own file and are never shown back. There is no cloud service.

Coming from NibePi

Upload NibePi's config.json: the gateway, MQTT broker, sensors, rooms, location, prices and secrets come over once you confirm. Run Thermaestro in shadow beside NibePi before switching. Once NibePi is stopped, the pump settings it changed are listed beside their factory values and their values before NibePi, to keep or set back one at a time. NibePi's learned hot-water profile can start the tank's week.

NibePi's control settings as draft intents. later

Installation

Running it

Today: a Docker Compose file builds Thermaestro from its source on GitHub. See running it in Docker.

At release: Docker images for amd64 and arm64, and .deb packages for Raspberry Pi OS, 32-bit and 64-bit, from the project's own apt repository. thermaestro-gateway is its own small package, so it can run on a Pi next to the pump with the core elsewhere.

Setup adds each device through its plugin, detects its model, firmware, climate systems, tanks and pool, asks what heats each climate system, and takes the sensors, the location and the price source, suggested from the bidding zone. Starting levels come from the pump, so on day one it behaves like the pump on its own.

Technical data

In short

Software
CorePython 3.13
LicenseAGPL-3.0-or-later (test vectors also MIT)
Web interfaceServer-rendered; every action has an API counterpart; a command line
LanguagesEnglish, Swedish, German
Plugin interfaceJSON lines with a JSON Schema, in the core or over a Unix socket
Planner
Time step15 minutes
MethodRules, from the prices 12 hours either side; beside them, linear programming (HiGHS) over 48 hours, goals solved by rank
GoalsGive way in the household's order; only device limits and protections are absolute
Setting changesAbout 50 per device and day planned; a hard stop at 200 per setting and day; both configurable
Data sources
Prices, no accountEnergy-Charts, Beneficial Apps' Nordic price sites, OMIE (Spain, Portugal)
Prices, own tokenTibber, ENTSO-E (every European zone)
Grid tariffsEntered by hand; Energi Data Service (Denmark), no account
Great BritainOctopus Agile
WeatherMET Norway, SMHI, Open-Meteo, each scored against the house's own outdoor sensor; Home Assistant as a fallback
Hosts and devices
DockerA Compose file that builds from source today; amd64 and arm64 images at release
Raspberry Pi OS32-bit and 64-bit packages at release
Heat pumpsNibe F-series and related models; Nibe S-series over Modbus TCP; other brands by plugin later
Other heat sourcesIn the same plan where a plugin reaches them later
Sensors and metersHome Assistant and MQTT, indoors and outdoors
Smallest host for everythingTo be measured later

Where it stands

On its first pump

Thermaestro runs in Docker beside NibePi on its first test pump, a Nibe F1245. It has run there in shadow since October, deciding and showing what it would change, and each setting it uses was tried on that pump first. Control is handed over one setting at a time, hot water first. There is no release yet.

Now

  • Hot water into control on the test pump: a week with the tank used as a battery, its cost per kWh compared with each day's average price.
  • Learning by watching: the tank, the house, the pump's curve and what electricity gives in heat.

Next

  • The heating offset in control, decided by cost within the comfort ranges.

Later

  • Release images, Raspberry Pi OS packages and a beta channel.
  • Testers on other pump models, once it runs reliably on the first.
  • Other brands and heat sources, by plugin.