Documentation

Configuration reference

Every field the integration asks for: what it means, what it is measured in, what it defaults to, and when it is worth changing. Nothing here is edited in YAML — the integration is configured entirely through Home Assistant's UI, and this page follows the same order the UI does.

• Initial setup — the questions asked once, when you add the integration
• Changing settings later — the 24 options pages behind two menus
• The hydronic layout catalog — which plumbing arrangements are modelled
• Services — every service and its fields

Only two answers are genuinely required: a price source — a Tibber API token by default, or a price sensor entity instead — and a weather entity. Everything else has a working default. Skipping an optional sensor costs accuracy, or leaves the one feature that needs it dormant, but it never stops the integration from planning.

#Initial setup

Settings → Devices & services → Add integration → Heat Pump Cost Optimizer.

The flow is not a straight line. After the two required screens, a menu asks how far to go now, and after the temperatures a second branch chooses how the thermal model gets its starting values:

flowchart TD
    A["1 · Basics<br/>name, price source (Tibber token or price entity),<br/>weather entity"] --> B["2 · Optional sensors<br/>temperatures, on/off switch, solar,<br/>tank probes, pump signals"]
    B --> M{"3 · Finish setup now? A menu:<br/>Quick setup (recommended) ·<br/>Continue setup · Finish setup now"}
    B -. "only if another entry turned the pre-fill<br/>offer on and a device qualifies" .-> P0["Heat pump entities<br/>read from a device<br/>(leave the pick empty to skip)"]
    P0 --> M
    M -- "Quick setup (recommended)" --> Q["Quick setup<br/>five house toggles and<br/>the building questionnaire"]
    Q --> P["Heat pump entities<br/>read from a device<br/>(leave the pick empty to skip)"]
    P -- "back to the menu,<br/>without Quick setup" --> M
    M -- "Finish setup now" --> R["Review and confirm<br/>(read-only summary)"]
    M -- "Continue setup" --> T["4 · Temperatures<br/>target, band, day and night comfort,<br/>day hours"]
    T --> C{"5 · How do you want to<br/>describe your building?"}
    C -- "Describe my building<br/>(recommended)" --> E["Questionnaire<br/>structure, era, foundation,<br/>heated area, emitters"]
    E --> F["Heat pump basics<br/>nominal COP,<br/>max power, min power"]
    C -- "Enter thermal values<br/>directly" --> G["Thermal model<br/>masses, loss coefficient,<br/>COP, power limits"]
    G --> H["Two-zone and solar<br/>per-floor masses, buffer tank,<br/>windows, orientation"]
    F --> I["6 · Hot water<br/>tank, setpoint, time frames,<br/>anti-legionella"]
    H --> I
    I --> K["7 · Weather sensitivity<br/>wind and rain"]
    K --> R
    R --> J(["Confirming creates the entry:<br/>the first plan is solved within<br/>one optimization interval"])

The menu's Quick setup (recommended) answers five house toggles plus the same building questionnaire as Continue setup below, then offers to read the heat pump's own entities off a detected device (see setup.md), and returns to this same menu; Finish setup now moves straight to the review with shipped defaults for everything past the two required screens; Continue setup walks the numbered screens below. (The same pre-fill page can also appear right after the optional-sensors screen, before this menu, when the pre-fill offer is switched on in an existing entry's options (off by default) and a heat-pump device resolves — see Pre-fill from a heat pump device; a fresh install with no entry yet has it off, so this never fires on first setup.) Every route ends on the same read-only review screen, and confirming there is what actually creates the entry.

#1 · Basics — Heat Pump Optimizer Setup

Where the prices, the forecast and your own measurements come from. The token is checked against Tibber before the flow continues, and a network failure is reported as a connection problem rather than as a bad token.

#2 · Optional sensors

Every picker on this second screen is optional; skip any you do not have. Without a sensor the optimizer uses its model, or leaves the one feature that needs the sensor dormant.

The heat-curve settings (the Danfoss ECL110 MQTT topics and the offset entity) are not asked during setup. Questions only owners of such a controller can answer do not belong on everyone's first screen, so they live on their own options page, where both MQTT topics ship empty and nothing is published or subscribed until a topic is set (see ecl110.md); an install without an ECL110 never touches the topics.

#3 · The finish menu — Finish setup now?

After the optional sensors the flow asks Finish setup now? with three answers, drawn in the diagram above: Quick setup (recommended), Continue setup and Finish setup now. Quick setup and its pre-fill return to this menu; Continue setup runs the screens numbered 4 to 7 below; Finish setup now goes to the review. Nothing else on this menu has fields of its own.

#The Quick setup screen

Quick setup (recommended) asks the whole house on one page: five yes/no questions, the two wood-tank probes, and the six building questions from Describe your building. What each answer means is in setup.md.

#The Pre-fill from a heat pump device screen

After Quick setup, and on the full path when the offer is switched on, this screen reads the heat pump's own entities. The first submit names the device; the second shows what its entities suggest, as ordinary fields you can edit or clear. Nothing is written until that second submit, and leaving the device empty skips the screen. Where each suggestion comes from is listed under Pre-fill from a heat pump device.

#4 · Temperature Settings

The gap between your target and your minimum is what makes savings possible: the wider it is, the further the house may coast through an expensive hour.

The form refuses four combinations that would leave the plan permanently in violation: a minimum above the target, a maximum below it, a night temperature above the day temperature, and a day window that never opens (start at or after end). The same checks run on the options page later.

#5 · Your building — two ways to answer

#Describe your building

Describe my building (recommended) opens this screen. Six questions with answers a homeowner knows, from which the thermal masses, the heat-loss coefficient and the slab parameters are derived. These are starting values; the self-learning model corrects them from how the house actually behaves, so they need not be exact.

#Your heat pump

Then three numbers off the heat pump's nameplate:

A pump that cannot run below its min power at all, only on or off, is declared on Thermal model (expert) as Compressor runs below min power: No: on/off; otherwise the plan may book steps below the minimum as averages the pump would reach by modulating.

That is the whole questionnaire path — the two-zone and solar pages are skipped deliberately. Their fields, once written, are what switches the two-zone model on, and a fresh install should not be given a two-zone model it did not ask for. If your house does have two independently modelled floors, turn it on afterwards on Advanced settings → Thermal model (expert).

#Thermal Model & Optimization

Enter thermal values directly opens this screen. It is for someone holding a real energy declaration, and asks the model's own numbers:

#Two-Zone & Solar Configuration

The direct path continues on the two-zone and solar screen:

The tick box at the top decides the two-zone model; the zone fields only apply while it is on. The questionnaire path skips this screen, so a fresh install is single-zone until you turn two-zone on.

#6 · Hot water — Domestic Hot Water (DHW) Configuration

Tell the optimizer when you actually need hot water. It then guarantees a usable tank temperature during those periods and heats in the cheapest hours beforehand. Outside them the tank is meant to cool — that is where much of the saving comes from.

Per-weekday windows are an options-page feature (see Hot water under Changing settings later); the setup wizard's single field takes the same grammar, including day selectors such as weekdays 06:00-08:30, weekend 08:00-09:30.

#7 · Weather Sensitivity Parameters

Saving this page moves to the review screen.

#The review screen — Your system, as configured

Every route ends here: a read-only picture of what you described, the zones, the tanks and every sensor slot with what is assigned to it. Confirming it is what creates the entry. All 82 entities appear at once and the first plan is solved within one optimization interval.

#Reauthenticate Tibber

When Tibber refuses the stored token, Home Assistant asks you to re-authenticate the integration under Settings → Devices & services, which opens this screen. Enter a valid token and price updates resume.

#Changing settings later

Settings → Devices & services → Heat Pump Optimizer → Configure.

There are 24 pages: eight on the first menu, and sixteen more behind Advanced settings. One of the eight — Your system, as configured — is read-only, and the last advanced page, Reset to factory defaults, is an action behind a confirmation rather than settings. Each page saves on its own, so changing one setting never touches another page's values. Every page also ends with one shared navigation control, described once here rather than twenty-three times below:

#Your system, as configured

No fields. It renders what the optimizer believes your system is: the zones, the tanks, the valve, and every sensor slot with what is assigned to it. Empty slots are shown as empty on purpose — the point is to reveal what is missing.

#Comfort and temperatures

The seven weekday fields are those of the Temperature Settings screen, with the same defaults, ranges and cross-checks. The weekend and holiday schedules live here too, and each of their fields starts as a copy of the weekday value it mirrors; leave every one at that default and weekends and holidays simply follow the weekday plan.

Four mold-guard fields complete the page:

#Hot water

The first-menu page is the schedule and the temperatures the tank is held to. Tank size, inlet water and the circulation pumps live on their own advanced pages.

Per-weekday windows, and how the layers stack. One schedule rarely fits a week with early workdays, a late Saturday and a Sunday that starts at noon. You can already type day selectors into the ordinary field (weekdays 06:00-08:30, weekend 08:00-09:30); Customize by weekday is the form version — switch it on, save, reopen the page, and seven fields appear, each holding one weekday's times in the same comma-separated format (12:00-24:00 for "nothing until noon"). An empty field does not mean "no hot water that day"; it means inherit.

The page as the flow renders it, two weekdays answered and the rest inheriting. A generated render of the integration's own form definitions and English texts — the same kind of picture setup.md uses, of this options page.

The layers resolve in a fixed order, per day:

1. A weekday field that has times wins for its weekday — including over the holiday windows. If you say Sundays are always the same, a Sunday that happens to be a public holiday keeps your Sunday schedule.
2. Otherwise, on a day the holiday calendar is on, the holiday windows apply.
3. Otherwise the ordinary windows — flat, or with their own day selectors — apply.

Switching Customize by weekday off suspends the weekday fields without erasing them: the holiday/ordinary schedule runs, and switching it back on restores what you had typed. Each field takes plain times only — day selectors belong in the ordinary field, and the form refuses one here because the field already names its day.

The dashboard card follows the same resolution. Its plan tab's hot-water band is drawn from the schedule the plan actually resolved against — with weekday fields in force, from their folded result — while the what-if editor still edits the ordinary windows: editing those is editing the default layer, and a weekday field set for that day keeps winning over an edit made in the card.

The temperatures the schedule holds the tank to:

#Savings vs comfort

The trade-off between a cheap bill and a rock-steady temperature. If the house feels cool during price peaks, raise How strictly to hold the temperature or raise your minimum temperature; both work, and both trade savings for warmth.

#Grid peak tariff

The monthly capacity charge. Many grid companies bill on your highest hours, which means stacking hot water and space heating into the same cheap hour can cost more than it saves. Transfer fees, the main fuse and the live peak guard are on their own advanced pages.

#Away and holiday mode

This page has four fields. The Away switch and the Away Expected Return datetime are their own entities, not options — they are on the integration's device page and on the card, not here.

#Quick setup

The one-page house questions of the Quick setup screen, pre-filled with this entry's own recorded answers. Change an answer and submit, and the thermal model is re-derived from the questionnaire; submit without changing anything and nothing is written. The device pre-fill is not offered here: an existing entry's sensor slots are already answered, and that read stays on Pre-fill from a heat pump device.

#Pre-fill from a heat pump device

The pump keeps several of the answers the other pages ask for, and this page reads them. Two sources reach them: the pump's own device — any integration that publishes a heat pump device, with tuya_heat_pump the reference — and, for a Rotenso Windmi or another GCHV-built heat pump, that project's Modbus package (docs/modbus/rotenso_windmi_gchv.yaml in the tuya_heat_pump repository, generated by its tools/gen_gchv_package.py; neither file lives in this repository).

It takes two submits. The first says where to read the pump from — either its own device, or the Modbus package's entity prefix; the second shows what that source suggests, as ordinary fields you can edit or clear, and saves what you keep. Nothing is written until that second submit, a field you clear is left as it was, and if nothing is found, nothing is written at all.

Both routes stay because they answer different installs. A Modbus YAML package gives its sensors a unique id and no device, so only the prefix reaches them. A pump integrated through tuya_heat_pump has a device and no package.

What the second form can suggest, and where each value comes from:

A register that is missing or unreadable suggests nothing, a value equal to the one already in force is not suggested, and a value outside its field's own range is left out rather than offered. The raw register sensors are found under either spelling an install may hold, sensor.hp_gchv_r404_0194h or sensor.hp_gchv_r404. The form also shows how many of the package's entities were read, and the backup heater type register: any value but 7 means the pump has electric heat of its own, which the heater slots on Heat pump telemetry are there to watch. The same refusals as on the pages these settings live on apply to what you save — a hot water minimum too close to its setpoint, a time frame shorter than a planning step, a maximum power below the minimum.

Nothing about the house, its emitters or its thermal model can be read this way; those stay yours to describe.

The same page is offered during setup, when the pre-fill offer is switched on and a heat-pump device added to the install resolves through one of those sources: the wizard asks which device to read and shows the same suggestions, and what you keep lands in the new entry's own configuration. Leave the device empty to skip it.

#Sensors and entities

Price, weather, room and tank sensors, and the on/off switch. Clearing a field genuinely clears it. Meters, solar irradiance and compressor frequency are on Power and solar sensors; mode / defrost / online / fault are on Heat pump telemetry.

#Power and solar sensors

#Heat pump telemetry

The return slot is the pump loop's return, not necessarily the floor's. If the pump feeds your floor loops directly, with no buffer tank and no mixing valve in between, the two are the same water and the same sensor may go in both this field and Floor heating return temperature sensor on the sensors page. Behind a buffer tank or a mixing valve they are different water: the pump's return comes back from the tank, the floor's from the slab, and they can differ by ten degrees or more. Floor heating return temperature sensor is what the optimizer estimates your slab temperature from, so filling it with the pump's return on such a system tells it the slab is far hotter or colder than it is, and it will under- or over-heat the lower floor accordingly.

#Pump duty control

A pump left on its own serves whichever demand its two thermostats see, so a step the plan meant for hot water only can turn into space heating in a house that is already warm. With Pump duty control at Control the optimizer writes, at every 15-minute plan step:

• For a Flow temperature entity (and a Return temperature one, below) the heating value follows the planned power. At full power it is 55 °C (the flow_heat_c option, when set), or the entity's maximum if that is lower. A lower planned level moves the target toward the return-water temperature, or toward 35 °C when no return sensor is configured, so the pump's own water thermostat can deliver that level. A fixed 55 °C never cycles, and a slot the plan priced below the pump's minimum then runs at that minimum. The supply only gets as hot as your radiators or floor can take the pump's output, so in mild weather it stays below the ceiling. The space gate is the entity's minimum, never below 25 °C. The hold value, for when the plan is not in charge, is 35 °C (the flow the pump's rated COP assumes), or the model's weather curve where that is higher. The curve is never written above the heating ceiling; the bare 35 °C is, if you set the ceiling below it. The model's weather curve is a pricing curve, not a set-point: written as one, it held the pump at 25 °C and underheated the house. The lift at the lowest level is 5 K over the inlet (flow_min_lift_k) and the ceiling 55 °C (flow_heat_c); both are on Sensors and entities, once the unit is Flow or Return temperature (the two fields appear once that unit is saved). Those defaults suit a controller that holds its supply at the set-point.
• For a Return temperature entity — a controller that takes the number as its return-water target, as a Luxtronik (alpha innotec, Novelan) through its Smart Home Interface is assumed to — everything above applies, with these differences:
  • The values derived from a supply temperature — the 35 °C hold, the weather curve and the 25 °C gate — are written 5 K lower (the rated supply-over-return spread, an assumption from the W35 rating point), and so is the 35 °C floor used when no inlet sensor reads. The hold is always capped at the heating ceiling. The gate a step that does not heat writes is therefore 20 °C (or the entity's minimum, if higher): a 25 °C return target sits above a floor return cooled overnight, and a controller that modulates on target minus return would heat on a step meant to be off. The lift at the lowest level is taken from the measured return or this 20 °C gate, whichever is higher.
  • The lift is taken only from the heat pump's return, the buffer tank or the floor return, never from the valve outlet, which is house-side supply. With none of them reading, the floor is the 30 °C hold. Map the heat pump's return sensor.
  • A ceiling write counts as "the pump may draw its maximum" for the learned power range and the ceiling probe only while the measured return sits at least 5 K below the ceiling. Closer than that, the pump is assumed to modulate down, so those draws do not teach the range a lower top.
  • The lift and the ceiling are written as you set them, and their defaults stay 5 K and 55 °C. Those are assumed to be too high for such a controller: on the install this was written for, a 5 K lift ran the compressor near full speed at the plan's lowest level, and a 55 °C return target would overheat the system water. Choose the lift small enough that the compressor runs near its minimum at the plan's lowest level; check it against the measured frequency and power. Choose the ceiling above the highest return you see in normal heating plus the lift (otherwise a heating step writes a target below the return, and such a controller presumably stops), and no higher than the controller accepts: a Luxtronik clamps the target to its own minimum return target and return limit, so a ceiling above the limit is written but not followed. A controller that starts heating only once the target sits its hysteresis above the return is not started by a smaller lift; it only keeps a running compressor near its minimum. That hysteresis is a setting of the controller, not a fixed 2 K: a Luxtronik accepts 0.5 K at the least, and the start threshold in effect (the return target less the hysteresis) is input 10107 of its Smart Home Interface, which ha-luxtronik-shi publishes as its Demand border sensor (the contributor's answers). This integration does not read it. On the install this was written for, a 0.5 K lift held 26–31 Hz once running, 1–1.5 K ramped to 73–81 Hz. For a low-temperature floor heating, 0.5–2 K and 30–40 °C may be a starting point; check them against the compressor's frequency and power.
  • The integration that exposes the controller must poll it at least every 10 minutes and restore its heating mode after a controller restart: a Luxtronik Smart Home Interface drops every value set through it after 600 s without access and after each restart. Any access re-arms those 600 s, a read as much as a write, so polling alone keeps a written value; ha-luxtronik-shi polls every 30 s by default and offers 10–300 s, and restores what it wrote after a controller restart only where its restore-after-device-reset option is on (the contributor's answers). A reverted set-point is noticed and written again; a reverted heating mode is not visible to this integration. No second tool may write the same registers: a Luxtronik then silently discards writes (error 816).
  • Downgrading: a version before this option reads Return temperature as Indoor temperature and writes the planned room temperature to the entity. Switch the unit back to Flow temperature before downgrading.
• Power feedback (Flow or Return temperature, with a heat-pump power sensor). A controller that integrates on target minus inlet keeps speeding up for as long as the target sits above the water, and the inlet-plus-lift value above rises with the inlet, so the planned level is never reached: on the install that reported it, a planned 0.53 kW drew 1.1–1.6 kW. With Follow the planned power on the measured draw on (the default), a space-only step below full power writes the inlet-plus-lift value for the first 5 minutes of a run (the controller's start programme), then nudges the heating value 0.2 K per minute down while the draw, averaged over 3 minutes, is above the planned level and up while it is below, and holds it while the two are within 10 % of the planned level (of the pump's minimum power, where the plan asks less). It goes no lower than 0.3 K below the inlet, no higher than the ceiling, and never to the gate. Hot water, both duties, a boost, a defrost, the system-identification experiment and full power write the value above unchanged and start the loop over. Where the controller cuts a written value to its own limits, that cut is taken as the run's limit and no repair is raised. Preconditions on the controller:
  • its heating hysteresis is at most the lift (Luxtronik: 0.5 K, its minimum), or the first write of a run does not start a stopped compressor — the same limitation as without the loop;
  • its minimum return target sits below the return during the heating season, or the loop cannot wind the compressor down past it. A Luxtronik cuts the set-point to its minimum return target (input 10104 of its Smart Home Interface, parameter 979) and its return limit (input 10103, parameter 87), both of which ha-luxtronik-shi publishes as sensors (the contributor's answers). Name them as the two optional limit sensors on Sensors and entities (space_setpoint_low_limit_entity, space_setpoint_high_limit_entity) and the loop stays inside them, so no write is cut. A limit sensor is read whatever its age, since a setting reports only when it changes; one that is unavailable, not a number or outside −20 to 100 °C is left out, and so are both when the lower is not below the upper. An upper limit below the lowest heating value (the gate plus one step of the set-point entity) is left out too: the gate is the value that means off, and no heating step writes it. They bound the loop alone: the first write of a run is the inlet plus the lift either way. Without them the two limits are taken from the value the controller reports back after a write.
• For an Indoor temperature entity each of the three is the step's planned room temperature, clamped to the entity's range (5 °C as the gate where the mode offers no hot-water-only option). An entity whose own minimum is above the planned room temperature cannot be an indoor set-point, so it is not written at all and a warning is logged: set its unit to Flow temperature.
• Space heating steps are heating only. The cheapest hours to heat the house need not be the ones that keep the tank ready for its next hot water window, so the pump's own tank thermostat is kept out of them. The exception: while the optimizer holds your disinfection switch on, a space step is Heating + DHW, so the planned anti-legionella cycle can run. A heating-only mode the optimizer wrote does not stop the next plan from making hot water, and the "set-point below the disinfection temperature" notice does not fire on the optimizer's own hot water gate (see below).
• Idle steps leave the mode alone. The mode on the pump served the duty that just finished, whose thermostat the plan has just satisfied, so it is the least likely to start anything; Heating + DHW would arm both.
• Tuya or Modbus, the same logic. The entities decide. The tuya_heat_pump mode select offers DHW (Hot Water) and Heating, so the mode is the gate. The GCHV Modbus package's HP Setting mode (register 44) offers only Off / Cool + DHW / Heat + DHW — no single-duty heating mode either way — so the other duty's set-point is the gate: the space set-point (for example HP Occupied heating water setpoint, register 401) is lowered to the entity's minimum (never below 25 °C) on hot-water-only steps, and the DHW set-point (HP DHW normal setpoint, register 404) to its minimum (never below 30 °C) on space-only steps.
• A step the plan gives both duties is split, so the optimizer rather than the pump's two thermostats decides which runs: hot water first, for the step's hot-water power over its total power, times 15 minutes, then heating for the rest. A share under 5 minutes goes to the other duty for the whole step. On a pump with no single-duty mode, each part is *Heating
  • DHW* with the other duty's set-point lowered to its gate. A boost or a disinfection cycle keeps Heating + DHW for the whole step.
• Rails. A hot-water-only stretch lasts at most 90 minutes (30 below -10 °C outdoors), idle steps after it included, then Heating + DHW returns — unless the room is already at or above the step's planned room temperature, when a warm house needs no space heat. A stale plan, comfort mode, a system-identification experiment and unloading the integration all get the fallback row, the space set-point apart (see below). A boost switch adds its own duty to the plan's step: Boost Space Heating alone writes Heating, DHW Boost alone writes DHW (Hot Water), and a step that also wants the other duty writes Heating + DHW. Boost mode writes Heating + DHW with the heating-flow ceiling (55 °C, or flow_heat_c) rather than the fallback's.
• While Optimizer active is on, the optimizer holds what it wrote. A reading of those three entities that differs from what the optimizer wrote — a change made on the pump, in an app, by a schedule, or the pump's own reset — is written back at once. To change the pump by hand, turn Optimizer active off first: from then on nothing is written to the pump, not even the fallback row, until you turn it back on — except the space set-point, restored once as described next. Readings in the first 20 seconds after a write are not counted: the tuya_heat_pump integration shows the value it sent for about 8 seconds whatever the pump reports.
• Turning it off restores your space set-point. Before its first write to the space-heating set-point entity, the optimizer reads the value there and keeps it, across restarts too. Turning Optimizer active off, and every unload (a reload after an options change, a disable, Home Assistant stopping), writes that value back. A value you set on the pump while the optimizer is on becomes the one restored, though the optimizer still writes over it until you turn it off (outside the entity's own minimum and maximum, the nearest value it takes); a value set while it is off is read again when it next writes. A reading equal to the optimizer's own last write is never taken as yours: after an upgrade from a version without this, the set-point is not written until it reads anything else, so set it on the pump once. The mode and the hot-water set-point are not restored.
• A write the pump does not hold is retried. If the value written back still does not hold, a warning repair notice is raised and the value is sent again every 5 minutes; the notice clears on the first write that holds, or when Control is left. An unavailable mode entity is no reading at all.
• A pump switched off is left alone. While the heat pump power switch reads off, nothing is compared or written: switched off, a pump can report set-points of its own (a Tuya pump reads 25 °C). Once it is on, a reset that is still there is written back like any other difference.
• A disinfection cycle writes its own temperature. While the plan's step runs the anti-legionella cycle, or the integration holds the pump's disinfection switch on, the hot water set-point written is the disinfection temperature, or the everyday set-point where that is higher, on the entity's step rounded up and never above the entity's maximum. Because the optimizer writes the cycle's temperature itself, the "set-point below the disinfection temperature" notice does not fire on any hot water set-point the optimizer wrote; it still fires on a value set by anybody else, and, with Control off, on the pump's own set-point.
• Its own mode is not a pump limit. A mode the optimizer wrote does not stop the next plan from heating the house or making hot water, even when the pump has not shown it yet or after a restart; one set by anybody else does.

Observe writes nothing. In Observe and Control the optimizer keeps a ledger of the last 24 hours: per 15-minute step, the duty the plan wanted against what the pump did, and a verdict — delivered, space-instead, dhw-instead, idle-instead, unknown or baseline (no plan duty). What the pump did is read from what the integration already reads: the power entity (running or not), the operating mode (DHW (Hot Water)) and the tank temperature (a rise of 0.5 °C over the step counts as hot water). Without a power entity only hot water can be seen, and other steps are unknown; a Heating + DHW run reads as hot water, and a large draw can hide a tank rise. The counts and the steps are in the diagnostics download under pump_duty → ledger, and start empty after a restart. Their use is to decide whether Control is worth turning on: the share of delivered steps is how often the pump already does what the plan wanted. Off (the default) does neither.

#Heating system and heat storage

Everything between the heat sources and the emitters. Leave the valve at No mixing valve if you do not have one — the model is already correct for that case. A throttling valve is any mode other than No mixing valve — Set by hand, Read from a sensor or Commanded by the optimizer — where a real valve exists and limits delivery to the emitters, which is what the hydronic layout catalog below keys off.

The four fuel-price fields and the external-heat detection group render only while Wood furnace is on. The Wood Cheaper Than Heat Pump sensor stays unavailable until the furnace is on, a wood-tank probe is set, external-heat detection or the DHW wood coil is on, type and packing are set, the billed price is greater than 0, and efficiency is between 10 and 95. A usable wood tank alone is not enough. While it is available it also carries today's cheaper windows — each run of planned heat-pump steps whose heat costs more than wood's, as start and end in the cheaper_windows attribute — and the recommended lighting window ahead of the first of them in lighting_start and lighting_end. Both are empty on a day with no cheaper window. The wood notification blueprint sends them to a phone.

#Building type and emitters

The same six questions as the setup questionnaire, plus the structural properties the preset does not derive — so a hand-set window area survives turning the preset on.

#Thermal model (expert)

The raw single-zone numbers, otherwise only asked at setup. A field left empty keeps its current value and is never saved. Buffer tank size lives on Heating system and heat storage; window area and the glazing coefficient live on Building type and emitters; the two-zone switch and the per-floor numbers live on Two-zone model.

Changing a derived value turns the derivation off. These fields are what Building type and emitters works out from the questionnaire. If that switch stayed on, the next save of that page would take your edit back — so changing any of them to a different value switches it off instead, and the page says so while it is still armed. Only a real change counts: pressing Submit without touching anything, re-typing a value that was already there, or editing a field the questionnaire does not own all leave it on.

A stored value outside a field's normal range widens that field rather than blocking the page. The ranges cover the physics of a 40–400 m² building; a 20 m² cabin or a 1000 m² block can derive something outside them. The one field holding such a value stretches to show it and is flagged with a warning; every other field keeps its normal limits.

#Two-zone model

#Hot water tank and inlet

Tank size, daily draw, inlet water and the disinfection extras. The first-menu Hot water page is the schedule and the hold temperatures.

#Hot water circulation

The DHW loop pump. The heating-circuit circulation pump lives on Heating system and heat storage.

#Solar panels

If you have solar, heating hot water or the buffer from surplus beats exporting it at the compensation rate. Told about the array, the plan prices each hour at what consuming actually costs you.

#Self-learning and diagnostics

The sensor watchdog is on by default and protects everything else. The three core learners are off until you turn them on. External-heat detection lives on Heating system and heat storage with the wood group. The remaining opt-in learners are on Advanced learning features.

#Advanced learning features

#Fuse and peak guards

#Transfer fees and contract

Fee amounts are in the same currency as your electricity prices; where a label reads SEK, that is a label, not a constraint.

#Heat curve control

For Danfoss ECL110 controllers driven over MQTT, or any controller whose heat-curve offset Home Assistant exposes as a number. The topics have no shipped default: each is exactly what you store, an empty or absent topic leaves that arm off, and nothing is published or subscribed until a topic is set — an install without an ECL110 never touches these topics. See ecl110.md for the full picture.

#Reset to factory defaults

Returns the entry to the state of a fresh installation. Pick the scope and tick the confirmation; submitted unticked, the menu comes back and nothing changes, and closing the dialog cancels.

• Settings: every setting on these pages returns to its default. Kept, so the optimizer stays connected to the house: every assigned entity, the zone and emitter topology (the two-zone switch is written as the settings in force imply it), the hot-water tank, valve and wood-furnace layout, the price and solar-forecast sources and the Tibber token, the plant diagram, the ECL110 MQTT wiring, the pre-fill device and the main fuse.
• Learned values: every learner starts again from the settings: the heat loss scale and lower-floor ratio, the comfort weight, COP, buffer and hot water cooling, the hot water profile and draws, defrost, the heat curve, the price shape, the plant learners and the prediction accuracy history. The billed peaks, the energy ledger, the operating mode, the frequency watchdog's stand-down and any manual plan or override are kept.
• Both.

A snapshot of every learned store and of the settings the reset drops is taken first. Until the next weekly snapshot, about a week, restore_learned_snapshot undoes the reset, with the sensors as they are now, and puts the two-zone, hot-water and wood-furnace switches back as they were stored. The entry then reloads and plans again straight away. If Home Assistant refuses to unload the entry, the dialog says the reset was not applied, and nothing is changed.

#The hydronic layout catalog

The optimizer models a named arrangement of pipes, not a free-form drawing. A layout is only ever stored as a catalog key, and only when your configuration can actually honour it — so the picture on the card's setup tab, the physics in the model and the settings on the pages above can never drift apart.

Most people never touch this. The layout is derived from what you configured:

• no throttling mixing valve → No mixing valve;
• a throttling valve, two zones and a wood tank top sensor → Two tanks, one 4-way valve;
• any other throttling valve → One tank behind a valve.

The layout editor on the card's Setup tab is where you override that, and Valve on the radiators, slab fed direct is only reachable that way — nothing derives it. If the configuration later stops supporting your stored choice — the valve mode changed, the probe was removed — the derived default quietly takes over again rather than erroring.

flowchart TB
    subgraph L1["No mixing valve (no_valve)"]
        direction LR
        hp1["Heat pump"] --> t1["Buffer tank<br/>(pass-through)"] --> z1["Emitters"]
    end
    subgraph L2["One tank behind a valve (single_tank_valve)"]
        direction LR
        hp2["Heat pump"] --> t2["Buffer tank"] --> v2["Mixing valve"] --> z2["All circuits"]
    end
    subgraph L3["Two tanks, one 4-way valve (two_tank_4way)"]
        direction LR
        hp3["Heat pump"] --> t3["Heat pump tank"]
        w3["Wood tank<br/>(drawn wood-first)"] --> v3["4-way valve"]
        t3 --> v3
        v3 --> u3["Upper floor"]
        v3 --> lo3["Lower floor"]
    end
    subgraph L4["Valve on the radiators, slab fed direct (valve_upper_direct_slab)"]
        direction LR
        hp4["Heat pump"] --> t4["Buffer tank"]
        t4 --> v4["Mixing valve"] --> r4["Radiators"]
        t4 --> s4["Slab<br/>(raw tank water)"]
    end

On every layout the heat pump also feeds the hot water tank directly whenever hot water is modelled; that pipe is left out above to keep the sketches readable. On a single-tank layout a wood tank, if you have one, is drawn feeding the buffer tank — its heat is folded in rather than stored separately.

#Services

15 services are registered under the heatpump_optimizer domain. The ten that act on a specific config entry also accept an entry_id: optional on nine, where omitting it applies the call to every loaded entry, which is what a single-heat-pump install wants, and required on factory_reset. Of those ten, assign_entity, apply_topology, apply_schedule, debug_collect and factory_reset write configuration back into the entry — debug_collect's start turns the collection option on, which reloads the entry — and the other five act on the running coordinator. run_optimization, set_away, set_mode, set_thermal_parameters and simulate_plan always act on every loaded entry.

The services are registered when the integration loads and stay registered while every entry is unloaded, so an automation that names one still validates. A call that finds no loaded entry — or names an entry_id that does not exist or is not loaded — fails with a validation error rather than doing nothing.

run_optimization fetches prices and weather and re-solves the 24-hour plan immediately. The Optimize Now button does the same thing. A run that cannot happen fails with an error — too few price steps available, or the solve itself failed — instead of acknowledging the call while the old plan stands.

set_away writes the Plan-page away override. At least one field is required. active turns the override on or off; omit it to leave on/off unchanged. Turning it off also clears the return time. return_time is an ISO datetime, or empty to clear; omit it to leave the stored time. Setting a time while the override is off stores it without turning away on. The Away switch and the Away Expected Return datetime call this service; they are not a second store.

set_mode takes mode: auto (full optimization), comfort (hold the comfort temperature and ignore prices), economy (allow up to 1.5 °C below your comfort floor to ride out expensive hours, never below 15 °C), boost (maximum heating power) or off.

set_thermal_parameters writes model parameters at runtime. All 31 fields are optional and anything omitted is left alone. Unparseable dhw_windows frames are rejected — the call refuses rather than silently keeping the old windows. The three quiet-window fields (quiet_silent_windows, quiet_off_windows, silent_mode_power_fraction) are configuration rather than physics: they are stored and take effect on the next solve, with the same overlap refusals apply_schedule applies. The ranges below are the physics bounds rather than the UI's convenience sliders, so several are wider than the options pages allow — an automation calling with a zero thermal mass would otherwise divide by zero inside the model:

• House and slab: house_thermal_mass and slab_thermal_mass (each 0.01–200), house_heat_loss_coefficient (0.01–10), slab_heat_transfer (0.01–50).
• Heat pump: heat_pump_cop_nominal (1.0–8.0).
• Two zones: upper_floor_thermal_mass, lower_floor_thermal_mass (0.01–200), inter_zone_heat_transfer (0.01–50), radiator_power_fraction (0–1).
• Solar: window_area (0.01–500), solar_heat_gain_coefficient (0–1).
• Hot water: dhw_tank_volume (0.01–2000), dhw_setpoint (30–75), dhw_min_temperature (10–70), dhw_daily_consumption (0.01–2000), dhw_cooling_rate (0.01–5), buffer_cooling_rate (0.01–50), dhw_schedule_enabled, dhw_windows, dhw_idle_min_temperature (5–60), dhw_legionella_enabled, dhw_legionella_temperature (55–75), dhw_legionella_interval_days (0.01–60).
• Weather: wind_sensitivity_factor (0–1), rain_heat_loss_multiplier (1–2).
• ECL110: ecl110_pid_time_constant_hours (0.01–24), ecl110_displace_min (−30–0), ecl110_displace_max (0–30).

simulate_plan prices a hypothetical comfort choice against the current forecast without disturbing operation, and returns the answer directly. Fields, all optional: target_temp, min_temp, max_temp, comfort_weight, comfort_temp_day, comfort_temp_night, dhw_setpoint, dhw_min_temperature, day_start_hour (0–23), day_end_hour (0–24), dhw_windows, quiet_silent_windows, quiet_off_windows, silent_mode_power_fraction (0–1), wood_type, wood_packing, wood_price_sek_m3, wood_furnace_efficiency, wood_slots. An empty dhw_windows string is meaningful: it simulates having no guaranteed hot water periods at all. The underlying solve is rate-limited, so dragging a slider cannot trigger one solve per pixel — this is what the card's what-if panel calls. A what-if that cannot run fails with an error rather than returning an error entry inside the response: there is nothing to compare against before the first plan exists, and not enough price data is the same failure the live solve would report.

apply_schedule is the save counterpart: it writes day_start_hour, day_end_hour, comfort_temp_day, target_temperature, dhw_setpoint, dhw_min_temperature, dhw_windows, quiet_silent_windows, quiet_off_windows and silent_mode_power_fraction into your configuration and reloads the entry, so the next plan uses them. The windows are parsed and canonicalised before storing, and a day window that would never open is rejected — checked against the values that would be stored, not only against the ones in the call.

assign_entity assigns or clears one optional sensor slot: key is one of the 21 assignable configuration keys (outdoor_temp_entity, solar_radiation_entity, pv_production_entity, indoor_temp_entity, lower_floor_temp_entity, floor_return_temp_entity, heat_pump_switch_entity, heat_pump_power_entity, heat_pump_energy_entity, house_power_entity, heat_pump_mode_entity, heat_pump_defrost_entity, heat_pump_online_entity, heat_pump_fault_entity, buffer_tank_temp_entity, mixing_valve_target_entity, dhw_temp_entity, external_heat_entity, wood_tank_top_entity, wood_tank_bottom_entity, valve_outlet_temp_entity) and entity_id is the entity to put there — an empty string clears the slot. manual_setpoint is an optional number, 0–30, stored as the valve's indoor target when the slot is mixing_valve_target_entity and ignored on any other slot. The entity must exist and its domain must be one the slot accepts. This is what clicking a sensor on the card's Setup tab calls; it writes exactly what the options pages write.

apply_topology stores the hydronic layout the setup editor snapped to: layout is one of the four selectable catalog keys above, and positions is an optional {place: [x, y]} map of cosmetic box coordinates. dhw and wood are optional booleans that set the hot-water and wood-furnace toggles alongside the layout. Free-form edge sets are never stored — the editor matches a drawing against the catalog and saves only the key.

apply_manual_plan pins exact run slots. space_slots and dhw_slots are lists of {start, end} ISO datetimes; an empty list means forced off for that channel, and omitting one leaves it automatic. expires_at defaults to 20 hours from now and must be in the future. Slots are validated in full before any coordinator is touched, so a rejected call leaves an existing pin untouched. Safety still wins: a forced-off slot is released if the house or the tank would breach a hard floor, and the legionella clock is never skipped.

clear_manual_plan drops the pins immediately. restore_learned_snapshot rolls every learner back to the last healthy weekly snapshot — the manual counterpart of the drift watchdog. When no snapshot qualifies (healthy inputs and in-band accuracy at capture time are required) the call fails with an error instead of answering with an empty restore. Until the next weekly snapshot after a factory reset, it undoes that reset instead: every learned store and the dropped settings come back. reset_heat_loss_learners returns the learned house heat loss scale and the learned lower floor loss ratio to 1.0, so the plan uses the heat loss values in the settings as they stand, and the learners start collecting evidence again from there; the plan is recalculated straight away. learners names which: house_heat_loss_scale, lower_floor_loss_ratio, or both when left empty. The comfort weight and the hot-water, COP and defrost learners are left alone. The Learning Reset Heat Loss button resets both. Changing the indoor or the lower-floor temperature sensor resets the learner fitted on it the same way, because evidence fitted against one sensor says nothing about another. factory_reset returns one entry's scope — settings, learners or both — to its defaults, exactly as Reset to factory defaults does, and answers with the entry and the scope; if Home Assistant refuses to unload the entry, the call fails and nothing is changed. Within a week of it, restore_learned_snapshot undoes it. diagnose_interval attributes the last interval's temperature error input by input and publishes the result on the Prediction Accuracy sensor. debug_collect takes action: start, stop or status. Collect a week of debug data is the learning page's option that turns the collection on. start turns the learning page's debug-collection option on, which reloads the entry and begins the week (or clears a collection that has already finished and begins again). stop ends it now, which is what the Finalize Debug Collection button does. status reports how many cycles it holds and how large it is, and that report is the service response. The collection also stops itself after seven days. However it ends, five self-tests then run once in the background, read only and within 15 minutes together: the stored documents against their declared domains, the accuracy monitor re-derived from its store, one what-if solve with no change, the inputs' missing and unchanged readings, and the price and forecast feeds across the week — with the longest gap between published payloads (a price feed that is failing publishes nothing, so the gap is the only record of it) and the outage streak the collection ended in. Turning the option off deletes what was collected. Download diagnostics on the entry carries the week and those results; a week over 8 MiB is carried as its summary and the name of the store file under .storage/ that holds the rows.

#Where else to look

• ../README.md — what the integration does, the entity list, and the first 30 minutes
• ../README.md#removal — removing the integration: what deleting the entry does, and what it leaves behind
• how-it-works.md — the mechanisms behind these settings
• dashboard-card.md — the card, its own configuration keys, and the Setup tab
• ecl110.md — the heat-curve path in full: the Danfoss ECL110 over MQTT, and an offset number entity

Rendered from docs/configuration.md, which is the source of truth; this page changes only when that file does.