Skip to content

feat(heat): plan the owner's heat zones in shadow, with heat pump zones and a named heat input - #2041

Open
hannesb90 wants to merge 8 commits into
srcfl:masterfrom
hannesb90:feat/heat-shadow-plan
Open

hannesb90 wants to merge 8 commits into
srcfl:masterfrom
hannesb90:feat/heat-shadow-plan

Conversation

@hannesb90

Copy link
Copy Markdown
Contributor

Builds on #2040. The first two commits here are #2040's. Review those there; this PR is the four commits after them, and it rebases cleanly once #2040 lands.

What

Heat zones can be planned by Core, in shadow unless the owner turns writing on (docs/adr/0012).

  1. heat config section (go/internal/config/heat.go). Each zone names its sensor, control, boundary (outdoor or a measured temperature, such as the room around a floor), source, heat output, target and hard band, plus the owner's price_comfort and peak_relief. heat.savings is the least saving a day's plans must reach together. No number has a default; a section left out changes nothing; a section that cannot be read one way is refused, naming the zone.
  2. heatrun service. Every quarter it plans each zone from its thermal twin, the stored total price and the weather forecast, applies the owner's rules, and weighs every zone's saving together against the least saving. GET /api/heat/plan shows the plan, the saving per day and what was written.
  3. Writing, off by default (heat.write). A zone's control is held at the plan's first value through the same drivercontrol.Holds the API uses. main now creates one set of holds and passes it to both, so a planned value and an operator's hold share one lock and one expiry. A zone writes only while its twin is trusted, the least saving is reached, the site meter is fresh, and no one else holds the driver; otherwise the device goes back to its own default. An operator's hold is neither overwritten nor released. A held value is renewed between plans before the hold or the device drops it (CTC resets its BMS registers five minutes after the last write).
  4. heat_input per zone for the twin. A room sensor on one device (an underfloor gateway) is heated by another (a heat pump). The twin used to take the sensor's own driver's power or the single other driver reporting one, so a site with several had none. A zone can now name "<driver>/<metric>", and the twin learns against that and nothing else. A sensor named in heat.zones is learned even if its driver declares no sensors.
  5. Heat pump zones. source: heat_pump takes the owner's efficiency and heat curve; zero fields take heatplan's starting point. A heat pump zone needs the outdoor forecast. A zone whose declared control is a curve_offset is planned through it with the owner's curve_effect until a twin learns it. heatplan.Source gains an exported Validate.

Why

This is the house that runs the planner's first version locally (a Python controller over a Wiser hub): three electric floors, and a CTC EcoZenith i255 with an EcoAir 610M feeding LK underfloor loops. Moving that control into Core needs exactly this: the owner's numbers in config, a plan visible before anything is written, writes through Core's holds, and a way to tie LK's room sensors to the CTC's heat.

Evidence

  • go build ./... and go vet are clean for the touched packages.
  • Tests pass in heatrun, heatplan, config, thermaltwin, api and drivercontrol, and in cmd/ftw for the twin zones. On the Raspberry Pi I built on, 7 cmd/ftw identity tests fail with key directory mode 0775. They pass with umask 022 and are unrelated.
  • heatrun tests cover:
    • shadow writes nothing;
    • a trusted zone is written once and held;
    • an untrusted twin, a closed gate or a stale site meter hands the device back;
    • an operator's hold is left alone;
    • turning writing off releases;
    • a 5-minute device hold is renewed between plans;
    • a heat pump needs the forecast;
    • a curve offset needs its effect.
  • A plan for a 6 kW heat pump zone under a 450 öre evening peak preheats +2 just before the peak and runs −5 through it. The house goes from 21.5 to 20.7 °C, inside its band.
  • make verify was not run.

Not in this PR

  • A floor/air constraint across two zones.
  • Joint planning of zones on a shared source.
  • Writing to the CTC, whose register 1023 has no documented scale.
  • UI.

go/cmd/ftw/main.go is also touched by #1956, #1865, #1789, #1691 and #1364. The change here is three contained blocks: the shared holds, the heat service, and the catalog/twin reload line.

The changeset is minor, a visible new capability, so it needs the owner's approval.

🤖 Generated with Claude Code

hannesb90 and others added 7 commits November 17, 2026 15:33
The optimum is found first, with no cost on changing value. Each run of one
value is then folded into a neighbour when that costs less than a share of
what one slot at full output costs for every change it removes. Without it a
price that wobbles by a couple of percent from slot to slot made the plan
change value 74 times a day on a radiator house, each one a write to the
device and a relay cycle; with it, 11, at about 0.4 % higher planned cost.

A long preheat is still weighed as a whole, because the smoothing runs on the
finished plan and not inside the search.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: hannesb90 <279736760+hannesb90@users.noreply.github.com>
Two rules the owner sets, beside PriceComfort. Both are off at zero and have
no default: what a saving or a peak is worth depends on the contract, the
house and the household.

SavingsGate is the least a day's plans must save together before they are
acted on. It was taken out in srcfl#2022 on the evidence that it never opened in
the house that ran it. The log of that house shows otherwise once the plans
are summed, as the limit is: it reached 5 kr on 15 and 16 November, partly
on a room model that overstated what a preheat saves. The ADR's Open section
now says so, and decision 9 stands unchanged until it is revisited. The gate
counts a plan that leaves its band as saving nothing, scales a short horizon
up to a day, and has a keep share so a saving near the limit does not open and
close it every slot. A test holds the case that went wrong: three rooms that
each save less than the limit and together save more.

PeakRelief lets a zone's target down to the bottom of its band in the dearest
hours of a sharp price peak: at least a minimum price, at least a factor times
the lowest price of the window ahead, and at most so many hours of one peak.
On a dear but flat day nothing is a peak. It moves the target only, never the
band.

Nothing calls either yet; the planner still only proposes.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: hannesb90 <279736760+hannesb90@users.noreply.github.com>
heat.zones gives each zone its target and hard band, price comfort and peak
relief; heat.savings the least saving worth acting on; heat.write whether a
plan is sent to a device at all. A section that is left out changes nothing,
write is off unless set, and a section that cannot be read one way is
refused with the zone it names. Nothing reads it yet.

The heatplan rules gain yaml tags so the file and /api/config spell them the
same way.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: hannesb90 <279736760+hannesb90@users.noreply.github.com>
A heat service plans every zone in the heat section each quarter from its
thermal twin, the stored total price and the weather forecast, applies the
owner's price comfort and peak relief, and weighs every zone's saving
together against the owner's least saving. GET /api/heat/plan shows the plan,
what it would save a day and what was written.

Nothing is written unless heat.write is on. Then a zone's setpoint control is
held at the plan's first value through the same drivercontrol holds the API
uses, so a planned value and an operator's hold share one lock and one
expiry. A zone writes only while its twin is trusted, the least saving is
reached and the site meter is fresh; otherwise the device is handed back to
its own default. An operator's hold is neither overwritten nor released. A
held value is renewed between plans before the device or the hold drops it,
for controllers such as CTC's that reset a written register after five
minutes.

The heat section gains boundary (outdoor or a measured temperature, such as
the room around a floor), source and heat_kw, all the owner's. Only direct
electric setpoint zones are planned yet: a heat pump's efficiency and a curve
offset's learned effect have nowhere to come from in this section.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: hannesb90 <279736760+hannesb90@users.noreply.github.com>
A room sensor on an underfloor gateway is heated by a heat pump on another
device, and the twin could not tell: it takes the sensor's own driver's power
or the single other driver reporting one, and a site with more than one has
none. heat.zones[].heat_input names "<driver>/<metric>" for the zone; the twin
then learns against that and nothing else, and a silent named input is no
input rather than a fallback to a pump the owner did not name. A sensor named
in heat.zones is learned even when its driver declares no sensors.

A changed source restarts the twin, as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: hannesb90 <279736760+hannesb90@users.noreply.github.com>
…s effect

source: heat_pump takes the owner's efficiency and heat curve (zero or absent
fields take heatplan's starting point) and needs the outdoor forecast, which a
heat pump's COP and flow temperature depend on. A zone whose declared control
is a curve offset is planned through it with the owner's curve_effect, what
one unit does to the zone and the flow, until a twin learns it; the device's
own value is the control's declared default, else zero.

heatplan.Source gains an exported Validate so the config can refuse a curve or
an efficiency the planner would.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: hannesb90 <279736760+hannesb90@users.noreply.github.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: hannesb90 <279736760+hannesb90@users.noreply.github.com>

@miravoss26 miravoss26 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Builds on #2040 (first two commits are its, reviewed there). Adds the heat config section, heatrun service, GET /api/heat/plan and the write path through control holds. Shadow unless heat.write is on.

Partial review: this is ~2.9k diff lines and I read the API route, the holds writer, the config example, the changesets and heat_control.go closely. I did NOT read heatrun/service.go, thermal_twin.go or config/heat.go line by line.

  • GET /api/heat/plan is registered as Read. It exposes plan, savings and written values, no secrets. Reasonable.
  • HoldsWriter goes through the same drivercontrol.Holds as the operator endpoint, so one lock and one expiry. Good call. API and heat control share ControlHolds only when it is set, otherwise the API builds its own. Worth a test that main.go always sets it when heat is enabled, or an operator hold and a planned write could race on two locks.
  • Security screen: no secrets, no new deps, no new network hosts. The write path is the one place that touches devices. It is gated on heat.write, twin trust, the savings gate and meter freshness per the changeset.
  • CI green.

Needs a human decision before merge: this is the first path where Core writes setpoints from the planner. Someone who owns heat control should read service.go and confirm the hand-back-to-default behaviour on twin loss and meter staleness.

… of holds

main.go is read to check that drivercontrol.New is called once and that
the same holds go to heatrun.HoldsWriter and api.Deps.ControlHolds; the
API builds its own holds when given none. A second test runs both ways
over one set: each sees, and can release, the other's hold.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: hannesb90 <279736760+hannesb90@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants