From 35c3541dd948472d5626894e36a4d9609a03c490 Mon Sep 17 00:00:00 2001 From: hannesb90 <279736760+hannesb90@users.noreply.github.com> Date: Tue, 17 Nov 2026 15:33:15 +0100 Subject: [PATCH 1/8] feat(heatplan): do not stop and start for a sliver of price 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 Signed-off-by: hannesb90 <279736760+hannesb90@users.noreply.github.com> --- go/internal/heatplan/plan.go | 106 +++++++++++++++++++++++++++++- go/internal/heatplan/plan_test.go | 35 ++++++++++ 2 files changed, 139 insertions(+), 2 deletions(-) diff --git a/go/internal/heatplan/plan.go b/go/internal/heatplan/plan.go index c7abb0d3c..e3fdb5da7 100644 --- a/go/internal/heatplan/plan.go +++ b/go/internal/heatplan/plan.go @@ -67,6 +67,11 @@ const ( // offers few values: a sliver over the limit can buy a whole slot of // heat, and must still lose. limitWeightFactor = 1e3 + // A change of value must gain at least this share of what one slot at + // full output costs. Without it the plan stops for a single slot to + // win a sliver on a small price step, and every such stop is a write + // to the device and a relay cycle. + switchShare = 0.1 ) // Zone is one heated thing as its twin describes it, in thermal terms. @@ -343,6 +348,7 @@ type solver struct { bandPerKh float64 limitPerKWh float64 chatter float64 + switchCost float64 lo, step float64 points int @@ -409,6 +415,7 @@ func newSolver(r Request) *solver { s.comfortPerKh = z.ComfortWeight * holdPerKh s.bandPerKh = bandWeightFactor * (heatPrice*z.CapacityKWhPerK + holdPerKh + 1e-9) s.chatter = chatterShare * holdPerKh * r.SlotH + s.switchCost = switchShare * heatPrice * a.MaxHeatKW * r.SlotH // The site's import limit outranks the band. A kWh held back costs the // zone at most 1/C kelvin outside its band for the rest of the horizon; // a kWh over the limit must cost more than that. @@ -675,7 +682,7 @@ func (s *solver) run(baseline bool) Plan { } } - plan := Plan{Slots: make([]Slot, 0, s.n)} + idx := make([]int, s.n) temp, rs := s.r.Zone.StartC, s.startState() for k := 0; k < s.n; k++ { var next [][]float64 @@ -683,11 +690,34 @@ func (s *solver) run(baseline bool) Plan { next = values[k+1] } j, st, nrs := pick(k, rs, temp, next) + idx[k], temp, rs = j, st.next, nrs + } + if !baseline { + s.smooth(idx) + } + return s.follow(idx) +} + +// act is the action for an index; below zero is a device with only start +// and stop left on its own thermostat, which holds the target. +func (s *solver) act(i int) action { + if i < 0 { + return action{setpoint: func(k int) float64 { return s.r.Zone.TargetC[k] }} + } + return s.acts[i] +} + +// follow predicts the zone under a sequence of actions. +func (s *solver) follow(idx []int) Plan { + plan := Plan{Slots: make([]Slot, 0, s.n)} + temp := s.r.Zone.StartC + for k, j := range idx { + st := s.advance(k, temp, s.act(j)) value := s.r.Zone.TargetC[k] if j >= 0 { value = s.acts[j].value } - temp, rs = st.next, nrs + temp = st.next plan.Slots = append(plan.Slots, Slot{Value: value, TempC: temp, HeatKWh: st.heatKWh, ElecKWh: st.elecKWh, Cost: st.cost}) plan.Cost += st.cost plan.BandExcursionKh += s.excursion(k, temp) * s.r.SlotH @@ -696,3 +726,75 @@ func (s *solver) run(baseline bool) Plan { plan.Cost += s.terminal(temp) return plan } + +// objective is what the plan minimises for a sequence of actions, or +Inf +// when the sequence breaks a minimum run. +func (s *solver) objective(idx []int) float64 { + temp, rs, total := s.r.Zone.StartC, s.startState(), 0.0 + for k, j := range idx { + next, ok := s.allowed(rs, s.acts[j]) + if !ok { + return math.Inf(1) + } + st := s.advance(k, temp, s.acts[j]) + total += st.cost + st.penalty + if j != s.neutral(k) { + total += s.chatter + } + temp, rs = st.next, next + } + return total + s.terminal(temp) +} + +// smooth removes the changes of value that do not pay for themselves. The +// optimum is found first and without a cost on changing, so that a long +// preheat is weighed as a whole; then each run of one value is folded into +// a neighbour when that costs less than switchCost for every change it +// removes. What is left is the plan's shape without the single slots it +// stopped or started for a sliver. +func (s *solver) smooth(idx []int) { + total := s.objective(idx) + run := make([]int, 0, s.n) + for a := 0; a < s.n; { + b := a + for b < s.n && idx[b] == idx[a] { + b++ + } + if a == 0 && b == s.n { + return + } + run = append(run[:0], idx[a:b]...) + removed := 1 + if a > 0 && b < s.n && idx[a-1] == idx[b] { + removed = 2 + } + best, bestTotal := -1, total+s.switchCost*float64(removed) + try := func(v int) { + for k := a; k < b; k++ { + idx[k] = v + } + if t := s.objective(idx); t < bestTotal { + best, bestTotal = v, t + } + copy(idx[a:b], run) + } + if a > 0 { + try(idx[a-1]) + } + if b < s.n && (a == 0 || idx[b] != idx[a-1]) { + try(idx[b]) + } + if best < 0 { + a = b + continue + } + for k := a; k < b; k++ { + idx[k] = best + } + total = bestTotal + // The run has joined a neighbour: weigh the joined run again. + for a > 0 && idx[a-1] == idx[a] { + a-- + } + } +} diff --git a/go/internal/heatplan/plan_test.go b/go/internal/heatplan/plan_test.go index 126229bad..f5959e15b 100644 --- a/go/internal/heatplan/plan_test.go +++ b/go/internal/heatplan/plan_test.go @@ -831,3 +831,38 @@ func TestBatteryMakesAPeakCheaperToHeatThrough(t *testing.T) { } } } + +func valueChanges(p Plan) int { + n := 0 + for i := 1; i < len(p.Slots); i++ { + if p.Slots[i].Value != p.Slots[i-1].Value { + n++ + } + } + return n +} + +// A price that wobbles by a couple of percent from slot to slot is worth +// nothing to chase: every change of value is a write to the device. The plan +// keeps the shape the real peak gives it and ignores the wobble. +func TestAWobbleInThePriceIsNotChased(t *testing.T) { + price := eveningPeak(day, 100, 200) + for i := range price { + price[i] += 2 * float64(i%2) + } + for name, c := range map[string]struct { + r Request + max int + }{ + "slab": {slabHouse(day, price, flat(day, 0)), 6}, + "radiators": {radiatorHouse(day, price), 16}, + } { + p := propose(t, c.r) + if got := valueChanges(p); got > c.max { + t.Errorf("%s: %d changes of value for a wobble, want at most %d", name, got, c.max) + } + if p.Cost >= p.BaselineCost { + t.Errorf("%s: cost %.0f, no better than %.0f left alone", name, p.Cost, p.BaselineCost) + } + } +} From bf7d28cc5bedf587a569f5f9b7e53c80589d6c0c Mon Sep 17 00:00:00 2001 From: hannesb90 <279736760+hannesb90@users.noreply.github.com> Date: Tue, 17 Nov 2026 15:35:44 +0100 Subject: [PATCH 2/8] feat(heatplan): the owner's least saving and a peak to sit out 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 #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 Signed-off-by: hannesb90 <279736760+hannesb90@users.noreply.github.com> --- .changeset/heatplan-owner-rules.md | 12 ++ docs/adr/0012-heat-control.md | 23 +++ go/internal/heatplan/comfort.go | 183 ++++++++++++++++++- go/internal/heatplan/comfort_test.go | 254 +++++++++++++++++++++++++++ 4 files changed, 469 insertions(+), 3 deletions(-) create mode 100644 .changeset/heatplan-owner-rules.md diff --git a/.changeset/heatplan-owner-rules.md b/.changeset/heatplan-owner-rules.md new file mode 100644 index 000000000..c6739e1db --- /dev/null +++ b/.changeset/heatplan-owner-rules.md @@ -0,0 +1,12 @@ +--- +"ftw": patch +--- + +The heat planner no longer stops and starts for a sliver of price: a change +of value must earn a share of what one slot at full output costs, so a price +that wobbles by a couple of percent gives 11 changes a day instead of 74 at +about 0.4 % higher planned cost. Two rules the owner sets are added to the +planner, both off at zero and with no default: a least saving a day's plans +must reach together before they are acted on, and a short price peak a zone +may sit through at the bottom of its band. Nothing calls them yet; the +planner still only proposes. diff --git a/docs/adr/0012-heat-control.md b/docs/adr/0012-heat-control.md index f98704f94..9bcc667d8 100644 --- a/docs/adr/0012-heat-control.md +++ b/docs/adr/0012-heat-control.md @@ -424,6 +424,29 @@ Fredrik answered on comfort that follows the day's price on 15 November 2026: the day's mean against the owner's fixed levels. Whether a longer reference, such as the month, serves better is open until it has run in more than one house. +- **A least saving, as the owner's own number.** Decision 9 did not take + one, on the evidence that in the one house that ran it the plans saved + 0.1–4.9 kr a day against a limit of 5 kr and the limit never opened. That + figure was one room's saving read against a limit that is the household's. + Summed over the three rooms, as the limit is, the same house's log reached + 5 kr on 15 and 16 November and held it open for 84 % and 41 % of the + time. Part of that was a room model that overstated what a preheat saves; + with the model corrected the sum is 2–4 kr a day and the limit is mostly + closed, which is the effect decision 9 describes. The question left is what + the limit is for. Proposed: not a switch that turns the planner off, but the + owner's own answer to "what must a day's saving be worth to me before I + accept a change of comfort or a write to my devices". It is off at zero, + has no default, and the shadow run's saving per day is what the owner sets + it against. `heatplan.SavingsGate` carries the rule so the owner's number + has somewhere to go if the decision is revisited; nothing calls it yet. +- **Sitting out a short price peak.** The same house keeps a second rule of + its own: a slot is a peak when it costs at least 200 öre and three times + the lowest price of the next 12 hours, and a zone may sit at the bottom of + its band for at most 3 hours of one. On a dear but flat day nothing is a + peak and the rule does nothing, which is why it cannot replace the + planner. `heatplan.PeakRelief` carries it as the owner's numbers, with no + default, applied to a zone's target after `PriceComfort`; the band is not + moved. - **Holding off a reheat needs a control.** Many heat pumps start a hot-water charge by themselves at their own start temperature. The planner can only delay a reheat on a device whose driver declares a control that diff --git a/go/internal/heatplan/comfort.go b/go/internal/heatplan/comfort.go index 035087c5a..751a3409f 100644 --- a/go/internal/heatplan/comfort.go +++ b/go/internal/heatplan/comfort.go @@ -3,6 +3,7 @@ package heatplan import ( "errors" "math" + "sort" ) // This file holds the owner's rule for what heat is worth, beside the plan @@ -16,9 +17,15 @@ import ( // on the comfort that day is worth. It needs no model of the zone and holds // from the first day. // -// There is no least saving before a plan may act. What a plan saves is shown -// to the owner from the shadow run, and the owner decides with that number -// in view (ADR 0012, decision 9). +// Two more rules are the owner's own number for when a saving is worth a +// change of comfort or a write to a device. Both are off at zero. +// +// - SavingsGate: the least a day's plans must save together before they are +// acted on. Below it every zone stays on its target. What a plan saves is +// also shown to the owner from the shadow run; the gate is the owner's way +// to say what a saving has to be worth to them. +// - PeakRelief: a short, sharp price peak the owner will sit through at the +// bottom of the band, with how sharp and how long as the owner's numbers. // PriceComfort moves a zone's target with the day's mean price. All prices // are in the unit of Request.Price. @@ -148,3 +155,173 @@ func (p Plan) Saving() float64 { } return math.Max(0, p.BaselineCost-p.Cost) } + +// SavingsGate is the owner's least saving for planned heat to be acted on. +// It is a choice about what a saving is worth to this household, so it has +// no default: zero opens the gate always. +type SavingsGate struct { + // MinPerDay is what the plans must save together in a day, in the unit + // of Request.Price times kWh. Zero or less opens the gate always. + MinPerDay float64 `json:"min_per_day"` + // KeepShare is the share of MinPerDay below which an open gate closes + // again, so that a saving near the limit does not open and close it + // every slot. From above 0 to 1; zero means 1, no hysteresis. + KeepShare float64 `json:"keep_share,omitempty"` +} + +// Validate refuses a gate that cannot be read one way. +func (g SavingsGate) Validate() error { + if !finite(g.MinPerDay, g.KeepShare) || g.KeepShare < 0 || g.KeepShare > 1 { + return errors.New("heatplan: the savings gate keeps a share of 0 to 1 of a finite limit") + } + return nil +} + +// Open reports whether the plans together save enough to act on, and what +// they save scaled to a day. horizonH is the horizon the plans cover; a +// horizon longer than a day is scaled down and a shorter one up, since a +// morning with half a day of prices would otherwise never reach a daily +// limit. wasOpen is the gate's last answer. +// +// The plans passed in are the plans of every zone the gate covers, each +// counted once: a limit is the household's, and a limit compared with one +// room's saving would read as never reached. +// +// A closed gate means every zone is left on its target, which with +// PriceComfort is the target that day is worth. An invalid gate, or a +// horizon that is not a length of time, is closed: the devices then run +// themselves, which is always safe. +func (g SavingsGate) Open(plans []Plan, horizonH float64, wasOpen bool) (open bool, perDay float64) { + if g.Validate() != nil || !(horizonH > 0) || !finite(horizonH) { + return false, 0 + } + var saved float64 + for _, p := range plans { + saved += p.Saving() + } + perDay = saved * 24 / horizonH + if g.MinPerDay <= 0 { + return true, perDay + } + limit := g.MinPerDay + if wasOpen && g.KeepShare > 0 { + limit *= g.KeepShare + } + return perDay >= limit, perDay +} + +// PeakRelief lets a zone sit at the bottom of its band through a short price +// peak. A slot is in a peak when its price is at least MinPrice and at least +// Factor times the lowest price in the WindowH hours from it, itself +// included. Of every unbroken stretch of such slots only the dearest +// MaxHours are relieved, so a long dear period is not one peak: its +// beginning is left to the plan. With a price that is zero or negative +// somewhere in the window, the ratio holds for any slot at or above MinPrice. +// +// It is the owner's rule and has no default: MaxHours zero turns it off. +type PeakRelief struct { + // MinPrice is the price below which no slot is a peak, in the unit of + // Request.Price. + MinPrice float64 `json:"min_price"` + // Factor is how many times the window's lowest price a peak costs. Above 1. + Factor float64 `json:"factor"` + // WindowH is how far ahead the lowest price is looked for, in hours. + WindowH float64 `json:"window_h"` + // MaxHours is the longest relief in one peak. + MaxHours float64 `json:"max_hours"` +} + +// Enabled reports whether the rule relieves anything. +func (r PeakRelief) Enabled() bool { return r.MaxHours > 0 } + +// Validate refuses a rule that cannot be read one way. A rule that is off +// needs no other number. +func (r PeakRelief) Validate() error { + if !finite(r.MinPrice, r.Factor, r.WindowH, r.MaxHours) || r.MaxHours < 0 { + return errors.New("heatplan: peak relief must be finite, and its longest relief not negative") + } + if r.MaxHours == 0 { + return nil + } + if r.MaxHours > 24 || !(r.Factor > 1) || !(r.WindowH > 0) || r.WindowH > 48 { + return errors.New("heatplan: peak relief needs a factor above 1, a window of up to 48 hours and a longest relief of up to 24 hours") + } + return nil +} + +// Slots marks the slots of price that the rule relieves. An invalid or +// disabled rule, or a price that is not finite, marks none. +func (r PeakRelief) Slots(price []float64, slotH float64) []bool { + out := make([]bool, len(price)) + if !r.Enabled() || r.Validate() != nil || !(slotH > 0) || !finite(slotH) { + return out + } + for _, p := range price { + if !finite(p) { + return out + } + } + window := int(math.Ceil(r.WindowH/slotH - 1e-9)) + keep := int(math.Floor(r.MaxHours/slotH + 1e-9)) + if window < 1 || keep < 1 { + return out + } + n := len(price) + peak := make([]bool, n) + for k, p := range price { + if p < r.MinPrice { + continue + } + end := min(n, k+window) + low := price[k] + for _, q := range price[k:end] { + low = math.Min(low, q) + } + peak[k] = low <= 0 || p >= r.Factor*low + } + for k := 0; k < n; { + if !peak[k] { + k++ + continue + } + j := k + for j < n && peak[j] { + j++ + } + // The dearest slots of the stretch; the earlier one wins a tie. + idx := make([]int, 0, j-k) + for i := k; i < j; i++ { + idx = append(idx, i) + } + sort.SliceStable(idx, func(a, b int) bool { return price[idx[a]] > price[idx[b]] }) + for rank, i := range idx { + if rank < keep { + out[i] = true + } + } + k = j + } + return out +} + +// Apply returns the zone with its target let down to the bottom of its band +// in the relieved slots. The band is the owner's hard limit and stays where +// it is. Apply it after PriceComfort, which moves the target for the day. +// The zone passed in is not changed. +func (r PeakRelief) Apply(z Zone, price []float64, slotH float64) Zone { + relieved := r.Slots(price, slotH) + changed := false + target := make([]float64, len(z.TargetC)) + copy(target, z.TargetC) + for i := range target { + if i < len(relieved) && relieved[i] && i < len(z.MinC) && z.MinC[i] < target[i] { + target[i] = z.MinC[i] + changed = true + } + } + if !changed { + return z + } + z.TargetC = target + return z +} diff --git a/go/internal/heatplan/comfort_test.go b/go/internal/heatplan/comfort_test.go index 11b40e991..020618725 100644 --- a/go/internal/heatplan/comfort_test.go +++ b/go/internal/heatplan/comfort_test.go @@ -171,3 +171,257 @@ func TestPriceComfortStepNeverPassesTheOwnersLimit(t *testing.T) { } } } + +// Five kronor a day, in öre, as a household set it. +func TestSavingsGateWeighsEveryPlanTogether(t *testing.T) { + gate := SavingsGate{MinPerDay: 500, KeepShare: 0.8} + if open, perDay := gate.Open([]Plan{saves(200), saves(250)}, 24, false); open || perDay != 450 { + t.Errorf("450 a day: open %v, per day %v", open, perDay) + } + if open, perDay := gate.Open([]Plan{saves(200), saves(250), saves(60)}, 24, false); !open || perDay != 510 { + t.Errorf("510 a day: open %v, per day %v", open, perDay) + } + // No room reaches the limit alone, and together they do. A limit read + // against one room at a time would look as if it were never reached. + for _, one := range []float64{200, 190, 180} { + if open, _ := gate.Open([]Plan{saves(one)}, 24, false); open { + t.Errorf("%v from one room opened the gate", one) + } + } + if open, perDay := gate.Open([]Plan{saves(200), saves(190), saves(180)}, 24, false); !open || perDay != 570 { + t.Errorf("three rooms: open %v, per day %v", open, perDay) + } + // Half a day of prices: the same plans are worth twice as much a day. + if open, perDay := gate.Open([]Plan{saves(260)}, 12, false); !open || perDay != 520 { + t.Errorf("260 in 12 hours: open %v, per day %v", open, perDay) + } + // Two days of horizon are not two days of saving in one. + if open, perDay := gate.Open([]Plan{saves(900)}, 48, false); open || perDay != 450 { + t.Errorf("900 in 48 hours: open %v, per day %v", open, perDay) + } +} + +func TestSavingsGateDoesNotFlapAtTheLimit(t *testing.T) { + gate := SavingsGate{MinPerDay: 500, KeepShare: 0.8} + open := false + var got []bool + for _, v := range []float64{480, 510, 480, 410, 390, 480, 500} { + open, _ = gate.Open([]Plan{saves(v)}, 24, open) + got = append(got, open) + } + want := []bool{false, true, true, true, false, false, true} + for i := range want { + if got[i] != want[i] { + t.Fatalf("gate over time = %v, want %v", got, want) + } + } + if open, _ := (SavingsGate{MinPerDay: 500}).Open([]Plan{saves(480)}, 24, true); open { + t.Error("without a keep share an open gate stayed open below the limit") + } +} + +// A plan that leaves its band, or costs more than leaving the device alone, +// adds nothing to what the gate weighs. +func TestSavingsGateCountsOnlyFeasiblePlans(t *testing.T) { + out := saves(900) + out.BandExcursionKh = 0.5 + worse := Plan{Cost: 1100, BaselineCost: 1000} + gate := SavingsGate{MinPerDay: 500} + if open, perDay := gate.Open([]Plan{out, worse, saves(300)}, 24, false); open || perDay != 300 { + t.Errorf("open %v, per day %v; want closed at 300", open, perDay) + } +} + +// No limit set is no gate. A gate that cannot be read is closed, because +// leaving the devices to themselves is the safe answer. +func TestSavingsGateWithoutALimitIsOpenAndABrokenOneIsClosed(t *testing.T) { + if open, _ := (SavingsGate{}).Open(nil, 24, false); !open { + t.Error("the zero value closed the gate") + } + for name, g := range map[string]SavingsGate{ + "keep share above 1": {MinPerDay: 500, KeepShare: 1.5}, + "negative keep": {MinPerDay: 500, KeepShare: -0.1}, + "not a number": {MinPerDay: math.NaN()}, + } { + if g.Validate() == nil { + t.Errorf("%s: Validate accepted it", name) + } + if open, _ := g.Open([]Plan{saves(9000)}, 24, true); open { + t.Errorf("%s: gate open", name) + } + } + for _, h := range []float64{0, -3, math.NaN(), math.Inf(1)} { + if open, _ := (SavingsGate{MinPerDay: 500}).Open([]Plan{saves(9000)}, h, true); open { + t.Errorf("horizon %v: gate open", h) + } + } +} + +// The owner's rule from the house that built it: a peak is at least 200 and +// three times the lowest price of the next 12 hours, and the zone may sit at +// the bottom of its band for at most 3 hours of one. +var houseRule = PeakRelief{MinPrice: 200, Factor: 3, WindowH: 12, MaxHours: 3} + +func relievedHours(r PeakRelief, price []float64) float64 { + var n float64 + for _, v := range r.Slots(price, slotH) { + if v { + n += slotH + } + } + return n +} + +func TestPeakReliefNeedsASharpPeakNotAHighDay(t *testing.T) { + // A flat price, even a dear one, has nothing to wait for. + if got := relievedHours(houseRule, flat(day, 450)); got != 0 { + t.Errorf("a flat dear day relieved %v h", got) + } + // A dear plateau: the dearest hour is 1.4 times the cheapest, not 3. + plateau := hours(day, func(h float64) float64 { return 300 + 100*math.Sin(h/24*2*math.Pi) }) + if got := relievedHours(houseRule, plateau); got != 0 { + t.Errorf("a plateau relieved %v h", got) + } + // A real peak: 100 at night, 450 for five evening hours. + peak := eveningPeak(day, 100, 450) + got := relievedHours(houseRule, peak) + if got != 3 { + t.Errorf("a 3-hour limit relieved %v h of a 3-hour peak", got) + } +} + +func TestPeakReliefLimitsALongPeakToItsDearestHours(t *testing.T) { + price := hours(day, func(h float64) float64 { + switch { + case between(h, 17, 22): + return 400 + 10*(h-17) // five hours, rising + default: + return 100 + } + }) + rule := PeakRelief{MinPrice: 200, Factor: 3, WindowH: 12, MaxHours: 2} + got := rule.Slots(price, slotH) + var n float64 + for i, v := range got { + if v { + n += slotH + if h := math.Mod(float64(i)*slotH, 24); h < 20 { + t.Errorf("relieved slot at %v h, before the dearest two hours of a rising peak", h) + } + } + } + if n != 2 { + t.Errorf("relieved %v h, want 2", n) + } +} + +func TestPeakReliefBelowItsMinimumPriceIsNoPeak(t *testing.T) { + // A tenfold step, but at prices an owner calls small. + price := hours(day, func(h float64) float64 { + if between(h, 17, 20) { + return 50 + } + return 5 + }) + if got := relievedHours(houseRule, price); got != 0 { + t.Errorf("relieved %v h below the minimum price", got) + } +} + +func TestPeakReliefLetsTheTargetDownToTheBandOnly(t *testing.T) { + price := eveningPeak(day, 100, 450) + z := radiatorHouse(day, price).Zone + before := append([]float64(nil), z.TargetC...) + out := houseRule.Apply(z, price, slotH) + if len(out.TargetC) != len(before) { + t.Fatalf("target length %d, want %d", len(out.TargetC), len(before)) + } + var lowered int + for i := range before { + switch { + case out.TargetC[i] == before[i]: + case out.TargetC[i] == z.MinC[i]: + lowered++ + default: + t.Fatalf("slot %d target %v: neither untouched nor the bottom of the band %v", i, out.TargetC[i], z.MinC[i]) + } + if out.MinC[i] != z.MinC[i] || out.MaxC[i] != z.MaxC[i] { + t.Fatalf("slot %d: the band moved", i) + } + } + if lowered == 0 { + t.Fatal("no slot was let down") + } + for i, v := range before { + if z.TargetC[i] != v { + t.Fatal("Apply changed the zone it was given") + } + } +} + +func TestPeakReliefOffOrBrokenChangesNothing(t *testing.T) { + price := eveningPeak(day, 100, 450) + z := radiatorHouse(day, price).Zone + for name, r := range map[string]PeakRelief{ + "zero value": {}, + "no longest relief": {MinPrice: 200, Factor: 3, WindowH: 12}, + "factor not above 1": {MinPrice: 200, Factor: 1, WindowH: 12, MaxHours: 3}, + "no window": {MinPrice: 200, Factor: 3, MaxHours: 3}, + "not a number": {MinPrice: math.NaN(), Factor: 3, WindowH: 12, MaxHours: 3}, + "longer than a day": {MinPrice: 200, Factor: 3, WindowH: 12, MaxHours: 30}, + "negative longest": {MinPrice: 200, Factor: 3, WindowH: 12, MaxHours: -1}, + } { + if relievedHours(r, price) != 0 { + t.Errorf("%s relieved something", name) + } + out := r.Apply(z, price, slotH) + for i := range z.TargetC { + if out.TargetC[i] != z.TargetC[i] { + t.Errorf("%s moved the target in slot %d", name, i) + break + } + } + } + if (PeakRelief{}).Validate() != nil { + t.Error("the zero value is not a valid, switched-off rule") + } + if houseRule.Validate() != nil { + t.Errorf("the house rule was refused: %v", houseRule.Validate()) + } + if (PeakRelief{MinPrice: 200, Factor: 1, WindowH: 12, MaxHours: 3}).Validate() == nil { + t.Error("a factor of 1 was accepted") + } + // A price that is not a number relieves nothing. + bad := append([]float64(nil), price...) + bad[10] = math.NaN() + if relievedHours(houseRule, bad) != 0 { + t.Error("a price series with a NaN relieved something") + } +} + +// Through the plan: the zone is let down further inside a relieved peak, and +// what it stored is worth more than the heat it would have held for comfort, +// so the heat bought comes out cheaper. The plan already buys nothing inside +// a peak this sharp, so the difference is where the zone sits, not how much +// is bought. +func TestPeakReliefLetsThePlanSitLowerThroughAPeak(t *testing.T) { + price := eveningPeak(day, 100, 450) + r := radiatorHouse(day, price) + plain := propose(t, r) + r.Zone = houseRule.Apply(r.Zone, price, slotH) + relieved := propose(t, r) + if got := heat(relieved, 17, 20); got > heat(plain, 17, 20)+1e-9 { + t.Errorf("bought %.2f kWh in the relieved peak, more than %.2f without the rule", got, heat(plain, 17, 20)) + } + loPlain, _ := tempRange(plain, 17, 20) + loRelieved, _ := tempRange(relieved, 17, 20) + if !(loRelieved < loPlain-0.05) { + t.Errorf("coldest in the peak %.2f with the rule, %.2f without: it did not sit lower", loRelieved, loPlain) + } + if loRelieved < r.Zone.MinC[0]-1e-6 { + t.Errorf("the zone left its band: %.2f below %.2f", loRelieved, r.Zone.MinC[0]) + } + if !(relieved.Cost < plain.Cost) { + t.Errorf("heat cost %.0f with the rule, %.0f without: nothing was saved", relieved.Cost, plain.Cost) + } +} From 334cf486cde12086aa3a3fade460e0c53bc32437 Mon Sep 17 00:00:00 2001 From: hannesb90 <279736760+hannesb90@users.noreply.github.com> Date: Tue, 17 Nov 2026 16:12:24 +0100 Subject: [PATCH 3/8] feat(config): the owner's heat section, with no default for any number 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 Signed-off-by: hannesb90 <279736760+hannesb90@users.noreply.github.com> --- go/internal/config/config.go | 4 ++ go/internal/config/heat.go | 109 ++++++++++++++++++++++++++++++++ go/internal/config/heat_test.go | 76 ++++++++++++++++++++++ go/internal/heatplan/comfort.go | 24 +++---- 4 files changed, 201 insertions(+), 12 deletions(-) create mode 100644 go/internal/config/heat.go create mode 100644 go/internal/config/heat_test.go diff --git a/go/internal/config/config.go b/go/internal/config/config.go index 0b8e473f0..d3c7375bc 100644 --- a/go/internal/config/config.go +++ b/go/internal/config/config.go @@ -33,6 +33,7 @@ type Config struct { Price *Price `yaml:"price,omitempty" json:"price,omitempty"` Weather *Weather `yaml:"weather,omitempty" json:"weather,omitempty"` Planner *Planner `yaml:"planner,omitempty" json:"planner,omitempty"` + Heat *Heat `yaml:"heat,omitempty" json:"heat,omitempty"` Batteries map[string]Battery `yaml:"batteries,omitempty" json:"batteries,omitempty"` EVCharger *EVCharger `yaml:"ev_charger,omitempty" json:"ev_charger,omitempty"` Loadpoints []Loadpoint `yaml:"loadpoints,omitempty" json:"loadpoints,omitempty"` @@ -1972,6 +1973,9 @@ func (c *Config) Validate() error { if err := c.FleetPing.Validate(); err != nil { return err } + if err := c.Heat.Validate(); err != nil { + return err + } if err := c.validateModbusProxy(); err != nil { return err } diff --git a/go/internal/config/heat.go b/go/internal/config/heat.go new file mode 100644 index 000000000..02713b705 --- /dev/null +++ b/go/internal/config/heat.go @@ -0,0 +1,109 @@ +package config + +import ( + "fmt" + "math" + "regexp" + + "github.com/srcfl/ftw/go/internal/heatplan" +) + +// Heat is the owner's heat control (docs/adr/0012). Everything in it is the +// owner's own number: the band a zone may move in, what a cheap or dear day +// is worth, the least saving worth acting on, the peak worth sitting out. +// There is no default for any of them, and a section that is left out +// changes nothing. Plans are proposals; they are only written to a device +// when Write is true. +type Heat struct { + // Write lets Core send a plan's values to the zones' controls. False, the + // default, runs the planner in shadow: the plan and what it would save + // are shown and nothing is written. + Write bool `yaml:"write,omitempty" json:"write,omitempty"` + // Savings is the least saving a day's plans must reach together, over + // every zone, before they are acted on. Nil means no limit. + Savings *heatplan.SavingsGate `yaml:"savings,omitempty" json:"savings,omitempty"` + Zones []HeatZone `yaml:"zones,omitempty" json:"zones,omitempty"` +} + +// HeatZone is one heated thing: a room's air, a floor. +type HeatZone struct { + // Name is the zone's own name, used in plans and logs. + Name string `yaml:"name" json:"name"` + // Sensor is the thermal twin's key for this zone, "/". + Sensor string `yaml:"sensor" json:"sensor"` + // Control is the declared control the plan moves, "/". + // Empty means the zone is planned in shadow only. + Control string `yaml:"control,omitempty" json:"control,omitempty"` + // TargetC is what the owner asks for; MinC and MaxC the hard band + // around it. The band is never widened. + TargetC float64 `yaml:"target_c" json:"target_c"` + MinC float64 `yaml:"min_c" json:"min_c"` + MaxC float64 `yaml:"max_c" json:"max_c"` + // ComfortWeight prices distance from the target; see heatplan.Zone. + ComfortWeight float64 `yaml:"comfort_weight,omitempty" json:"comfort_weight,omitempty"` + // PriceComfort moves the target with the day's mean price. + PriceComfort *heatplan.PriceComfort `yaml:"price_comfort,omitempty" json:"price_comfort,omitempty"` + // PeakRelief lets the zone sit at the bottom of its band through a peak. + PeakRelief *heatplan.PeakRelief `yaml:"peak_relief,omitempty" json:"peak_relief,omitempty"` +} + +var heatKey = regexp.MustCompile(`^[^/\s]+/[^/\s]+$`) + +// Validate refuses a heat section that cannot be read one way. +func (h *Heat) Validate() error { + if h == nil { + return nil + } + if h.Savings != nil { + if err := h.Savings.Validate(); err != nil { + return fmt.Errorf("heat.savings: %w", err) + } + } + seen := map[string]bool{} + for i, z := range h.Zones { + at := fmt.Sprintf("heat.zones[%d]", i) + if z.Name == "" { + return fmt.Errorf("%s: name is required", at) + } + if seen[z.Name] { + return fmt.Errorf("%s: zone %q is listed twice", at, z.Name) + } + seen[z.Name] = true + if !heatKey.MatchString(z.Sensor) { + return fmt.Errorf("%s (%s): sensor must be \"/\"", at, z.Name) + } + if z.Control != "" && !heatKey.MatchString(z.Control) { + return fmt.Errorf("%s (%s): control must be \"/\"", at, z.Name) + } + for _, v := range []float64{z.TargetC, z.MinC, z.MaxC, z.ComfortWeight} { + if math.IsNaN(v) || math.IsInf(v, 0) { + return fmt.Errorf("%s (%s): temperatures must be finite", at, z.Name) + } + } + if !(z.MinC <= z.TargetC && z.TargetC <= z.MaxC) || z.MinC == z.MaxC { + return fmt.Errorf("%s (%s): need min_c <= target_c <= max_c with a band wider than zero", at, z.Name) + } + if z.ComfortWeight < 0 { + return fmt.Errorf("%s (%s): comfort_weight must not be negative", at, z.Name) + } + if z.PriceComfort != nil { + if err := z.PriceComfort.Validate(); err != nil { + return fmt.Errorf("%s (%s): price_comfort: %w", at, z.Name, err) + } + } + if z.PeakRelief != nil { + if err := z.PeakRelief.Validate(); err != nil { + return fmt.Errorf("%s (%s): peak_relief: %w", at, z.Name, err) + } + } + } + if h.Write { + for _, z := range h.Zones { + if z.Control != "" { + return nil + } + } + return fmt.Errorf("heat.write is on but no zone has a control to write to") + } + return nil +} diff --git a/go/internal/config/heat_test.go b/go/internal/config/heat_test.go new file mode 100644 index 000000000..565ce4bdb --- /dev/null +++ b/go/internal/config/heat_test.go @@ -0,0 +1,76 @@ +package config + +import ( + "strings" + "testing" + + "gopkg.in/yaml.v3" + + "github.com/srcfl/ftw/go/internal/heatplan" +) + +// The numbers the house that built the planner runs, as its owner would write +// them. Every one of them is the owner's, and none has a default. +const houseHeatYAML = ` +write: false +savings: { min_per_day: 500, keep_share: 0.8 } +zones: + - name: badrum + sensor: wiser_7/floor_temp_c + control: wiser_7/set_setpoint + target_c: 24.5 + min_c: 20 + max_c: 27 + price_comfort: { cheap_price: 150, normal_price: 260, dear_price: 400, raise_k: 1, lower_k: 1, step_k: 0.5 } + peak_relief: { min_price: 200, factor: 3, window_h: 12, max_hours: 3 } +` + +func TestHeatSectionReadsTheOwnersNumbers(t *testing.T) { + var h Heat + if err := yaml.Unmarshal([]byte(houseHeatYAML), &h); err != nil { + t.Fatal(err) + } + if err := h.Validate(); err != nil { + t.Fatal(err) + } + z := h.Zones[0] + if h.Write || h.Savings.MinPerDay != 500 || h.Savings.KeepShare != 0.8 || + z.MaxC != 27 || z.PriceComfort.DearPrice != 400 || z.PeakRelief.MaxHours != 3 { + t.Fatalf("numbers were not read: %+v %+v", h, z) + } + var _ heatplan.PeakRelief = *z.PeakRelief +} + +func TestHeatSectionLeftOutOrEmptyChangesNothing(t *testing.T) { + if (*Heat)(nil).Validate() != nil || (&Heat{}).Validate() != nil { + t.Fatal("an absent or empty heat section was refused") + } +} + +func TestHeatSectionRefusesWhatCannotBeReadOneWay(t *testing.T) { + ok := HeatZone{Name: "a", Sensor: "d/m", TargetC: 22, MinC: 20, MaxC: 24} + for name, tc := range map[string]struct { + h Heat + want string + }{ + "no name": {Heat{Zones: []HeatZone{{Sensor: "d/m", TargetC: 22, MinC: 20, MaxC: 24}}}, "name"}, + "twice": {Heat{Zones: []HeatZone{ok, ok}}, "twice"}, + "bad sensor": {Heat{Zones: []HeatZone{{Name: "a", Sensor: "dm", TargetC: 22, MinC: 20, MaxC: 24}}}, "sensor"}, + "bad control": {Heat{Zones: []HeatZone{{Name: "a", Sensor: "d/m", Control: "x", TargetC: 22, MinC: 20, MaxC: 24}}}, "control"}, + "target outside": {Heat{Zones: []HeatZone{{Name: "a", Sensor: "d/m", TargetC: 25, MinC: 20, MaxC: 24}}}, "min_c"}, + "no band": {Heat{Zones: []HeatZone{{Name: "a", Sensor: "d/m", TargetC: 22, MinC: 22, MaxC: 22}}}, "band"}, + "bad gate": {Heat{Savings: &heatplan.SavingsGate{MinPerDay: 5, KeepShare: 2}, Zones: []HeatZone{ok}}, "savings"}, + "bad relief": {Heat{Zones: []HeatZone{{Name: "a", Sensor: "d/m", TargetC: 22, MinC: 20, MaxC: 24, PeakRelief: &heatplan.PeakRelief{MaxHours: 3, Factor: 1, WindowH: 12}}}}, "peak_relief"}, + "write no control": {Heat{Write: true, Zones: []HeatZone{ok}}, "control"}, + } { + err := tc.h.Validate() + if err == nil || !strings.Contains(err.Error(), tc.want) { + t.Errorf("%s: error %v, want one mentioning %q", name, err, tc.want) + } + } + w := ok + w.Control = "d/set_setpoint" + if err := (&Heat{Write: true, Zones: []HeatZone{w}}).Validate(); err != nil { + t.Errorf("a zone with a control and write on was refused: %v", err) + } +} diff --git a/go/internal/heatplan/comfort.go b/go/internal/heatplan/comfort.go index 751a3409f..365fa6147 100644 --- a/go/internal/heatplan/comfort.go +++ b/go/internal/heatplan/comfort.go @@ -34,17 +34,17 @@ type PriceComfort struct { // raised by all of RaiseK. NormalPrice is where the target is the // owner's own, and DearPrice the mean at or above which it is lowered by // all of LowerK. Between them the shift is linear, never a step. - CheapPrice float64 `json:"cheap_price"` - NormalPrice float64 `json:"normal_price"` - DearPrice float64 `json:"dear_price"` + CheapPrice float64 `yaml:"cheap_price" json:"cheap_price"` + NormalPrice float64 `yaml:"normal_price" json:"normal_price"` + DearPrice float64 `yaml:"dear_price" json:"dear_price"` // RaiseK and LowerK are how far the target moves, in kelvin. Zero turns // that direction off: a floor may follow cheap days up while the room // air only follows dear days down. - RaiseK float64 `json:"raise_k"` - LowerK float64 `json:"lower_k"` + RaiseK float64 `yaml:"raise_k" json:"raise_k"` + LowerK float64 `yaml:"lower_k" json:"lower_k"` // StepK rounds the shift to the control's step, halves away from zero. // Zero leaves it unrounded. - StepK float64 `json:"step_k,omitempty"` + StepK float64 `yaml:"step_k,omitempty" json:"step_k,omitempty"` } // Enabled reports whether the rule moves anything. @@ -162,11 +162,11 @@ func (p Plan) Saving() float64 { type SavingsGate struct { // MinPerDay is what the plans must save together in a day, in the unit // of Request.Price times kWh. Zero or less opens the gate always. - MinPerDay float64 `json:"min_per_day"` + MinPerDay float64 `yaml:"min_per_day" json:"min_per_day"` // KeepShare is the share of MinPerDay below which an open gate closes // again, so that a saving near the limit does not open and close it // every slot. From above 0 to 1; zero means 1, no hysteresis. - KeepShare float64 `json:"keep_share,omitempty"` + KeepShare float64 `yaml:"keep_share,omitempty" json:"keep_share,omitempty"` } // Validate refuses a gate that cannot be read one way. @@ -222,13 +222,13 @@ func (g SavingsGate) Open(plans []Plan, horizonH float64, wasOpen bool) (open bo type PeakRelief struct { // MinPrice is the price below which no slot is a peak, in the unit of // Request.Price. - MinPrice float64 `json:"min_price"` + MinPrice float64 `yaml:"min_price" json:"min_price"` // Factor is how many times the window's lowest price a peak costs. Above 1. - Factor float64 `json:"factor"` + Factor float64 `yaml:"factor" json:"factor"` // WindowH is how far ahead the lowest price is looked for, in hours. - WindowH float64 `json:"window_h"` + WindowH float64 `yaml:"window_h" json:"window_h"` // MaxHours is the longest relief in one peak. - MaxHours float64 `json:"max_hours"` + MaxHours float64 `yaml:"max_hours" json:"max_hours"` } // Enabled reports whether the rule relieves anything. From 947b671bd97c7f9abea16c2d5a98fea92048ab3b Mon Sep 17 00:00:00 2001 From: hannesb90 <279736760+hannesb90@users.noreply.github.com> Date: Tue, 17 Nov 2026 16:32:00 +0100 Subject: [PATCH 4/8] feat(heat): plan the owner's heat zones, shadow unless heat.write is on 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 Signed-off-by: hannesb90 <279736760+hannesb90@users.noreply.github.com> --- .changeset/heat-shadow-plan.md | 15 + config.example.yaml | 21 + go/cmd/ftw/heat_control.go | 111 +++++ go/cmd/ftw/main.go | 47 ++ go/internal/api/api.go | 16 +- go/internal/api/api_agent_catalog.go | 3 +- go/internal/api/api_heat_plan.go | 14 + go/internal/config/heat.go | 27 ++ go/internal/config/heat_test.go | 13 +- go/internal/heatrun/holds.go | 48 ++ go/internal/heatrun/service.go | 663 +++++++++++++++++++++++++++ go/internal/heatrun/service_test.go | 341 ++++++++++++++ 12 files changed, 1312 insertions(+), 7 deletions(-) create mode 100644 .changeset/heat-shadow-plan.md create mode 100644 go/cmd/ftw/heat_control.go create mode 100644 go/internal/api/api_heat_plan.go create mode 100644 go/internal/heatrun/holds.go create mode 100644 go/internal/heatrun/service.go create mode 100644 go/internal/heatrun/service_test.go diff --git a/.changeset/heat-shadow-plan.md b/.changeset/heat-shadow-plan.md new file mode 100644 index 000000000..a87644a03 --- /dev/null +++ b/.changeset/heat-shadow-plan.md @@ -0,0 +1,15 @@ +--- +"ftw": minor +--- + +Heat zones can now be planned. A new `heat` section names each zone's +sensor, control, boundary, heat output, target and hard band, and the owner's +own rules: price comfort, peak relief and a least saving per day for all +zones together. No number has a default. Core plans every quarter from the +thermal twins, the stored prices and the weather forecast, and shows the plan +and what it would save at `GET /api/heat/plan`. Nothing is written unless +`heat.write` is on; then a zone's setpoint is held through the same control +holds as an operator's request, only while its twin is trusted, the least +saving is reached and the site meter is fresh, and the device is handed back +to its own default otherwise. A device that drops a written value by itself is +written again before it does. diff --git a/config.example.yaml b/config.example.yaml index c9073eea6..6a70713d4 100644 --- a/config.example.yaml +++ b/config.example.yaml @@ -280,6 +280,27 @@ fleet_ping: # soc_min: 0.10 # soc_max: 0.95 +# Heat control (docs/adr/0012). Every number is the owner's and none has a +# default. Without write: true the plan is shadow: GET /api/heat/plan shows +# it and what it would save, and nothing is written. Prices are the stored +# total price (öre/kWh); min_per_day is in öre for all zones together. +# heat: +# write: false +# savings: { min_per_day: 500, keep_share: 0.8 } +# zones: +# - name: bathroom_floor +# sensor: wiser_7/floor_temp_c # the twin that judges this zone +# control: wiser_7/set_setpoint # a declared setpoint control +# boundary: wiser_7/room_temp_c # or "outdoor" +# source: direct_electric +# heat_kw: 0.6 +# target_c: 24.5 +# min_c: 20 +# max_c: 27 +# comfort_weight: 2 +# price_comfort: { cheap_price: 150, normal_price: 260, dear_price: 400, raise_k: 1, lower_k: 0 } +# peak_relief: { min_price: 200, factor: 3, window_h: 12, max_hours: 3 } + # Peak-power tariff (weekday 06–20 local time). Same minor units as # grid_tariff_ore_kwh, per kW, excluding VAT. 0 disables it. # price: diff --git a/go/cmd/ftw/heat_control.go b/go/cmd/ftw/heat_control.go new file mode 100644 index 000000000..dbf33b367 --- /dev/null +++ b/go/cmd/ftw/heat_control.go @@ -0,0 +1,111 @@ +package main + +import ( + "sync" + "time" + + "github.com/srcfl/ftw/go/internal/config" + "github.com/srcfl/ftw/go/internal/drivers" + "github.com/srcfl/ftw/go/internal/heatrun" + "github.com/srcfl/ftw/go/internal/state" +) + +// heatCatalog is the driver catalog as the heat control reads it. The +// reload path replaces it; the heat tick reads it from another goroutine. +type heatCatalog struct { + mu sync.Mutex + drivers []config.Driver + catalog []drivers.CatalogEntry +} + +func (h *heatCatalog) set(cfgDrivers []config.Driver, catalog []drivers.CatalogEntry) { + h.mu.Lock() + defer h.mu.Unlock() + h.drivers = append([]config.Driver(nil), cfgDrivers...) + h.catalog = catalog +} + +// control is the declared control behind a driver instance's name. A driver +// that is disabled, observe-only or unknown has none. +func (h *heatCatalog) control(driver, control string) (drivers.CatalogControl, bool) { + h.mu.Lock() + defer h.mu.Unlock() + for _, d := range h.drivers { + if d.Name != driver || d.Disabled || d.ObserveOnly { + continue + } + entry := drivers.EntryForDriver(h.catalog, d.Lua) + if entry == nil { + return drivers.CatalogControl{}, false + } + for _, c := range entry.Controls { + if c.ID == control { + return c, true + } + } + } + return drivers.CatalogControl{}, false +} + +// heatPrices reads the stored total price, the one the owner's limits are +// written in. +func heatPrices(st *state.Store, zone func() string) func(from, to time.Time) []heatrun.Price { + return func(from, to time.Time) []heatrun.Price { + z := zone() + if st == nil || z == "" { + return nil + } + rows, err := st.LoadPrices(z, from.Add(-time.Hour).UnixMilli(), to.UnixMilli()) + if err != nil { + return nil + } + out := make([]heatrun.Price, 0, len(rows)) + for _, r := range rows { + if r.SlotLenMin <= 0 { + continue + } + out = append(out, heatrun.Price{ + Start: time.UnixMilli(r.SlotTsMs), + Len: time.Duration(r.SlotLenMin) * time.Minute, + Value: r.TotalOreKwh, + }) + } + return out + } +} + +// heatOutdoor is the outdoor forecast for n quarters from start, from rows +// fetched within the last 12 hours, or false when any quarter is missing. +func heatOutdoor(st *state.Store, since func() int64) func(start time.Time, n int) ([]float64, bool) { + return func(start time.Time, n int) ([]float64, bool) { + if st == nil || n <= 0 { + return nil, false + } + end := start.Add(time.Duration(n) * 15 * time.Minute) + rows, err := st.LoadForecasts(start.Add(-2*time.Hour).UnixMilli(), end.UnixMilli()) + if err != nil { + return nil, false + } + now := time.Now() + out := make([]float64, n) + for k := 0; k < n; k++ { + t := start.Add(time.Duration(k)*15*time.Minute + 7*time.Minute).UnixMilli() + found := false + for _, r := range rows { + slotLen := r.SlotLenMin + if slotLen <= 0 { + slotLen = 60 + } + if t >= r.SlotTsMs && t < r.SlotTsMs+int64(slotLen)*60*1000 && r.TempC != nil && + usableTrainingWeather(r, now) && r.FetchedAtMs >= since() { + out[k], found = *r.TempC, true + break + } + } + if !found { + return nil, false + } + } + return out, true + } +} diff --git a/go/cmd/ftw/main.go b/go/cmd/ftw/main.go index eb6c4c2d4..b2b0dfd19 100644 --- a/go/cmd/ftw/main.go +++ b/go/cmd/ftw/main.go @@ -49,6 +49,7 @@ import ( "github.com/srcfl/ftw/go/internal/control" "github.com/srcfl/ftw/go/internal/currency" "github.com/srcfl/ftw/go/internal/devtools" + "github.com/srcfl/ftw/go/internal/drivercontrol" "github.com/srcfl/ftw/go/internal/driverinventory" "github.com/srcfl/ftw/go/internal/driverrepo" "github.com/srcfl/ftw/go/internal/drivers" @@ -58,6 +59,7 @@ import ( "github.com/srcfl/ftw/go/internal/ftwcli" "github.com/srcfl/ftw/go/internal/gatewayidentity" "github.com/srcfl/ftw/go/internal/ha" + "github.com/srcfl/ftw/go/internal/heatrun" "github.com/srcfl/ftw/go/internal/journal" "github.com/srcfl/ftw/go/internal/loadmodel" "github.com/srcfl/ftw/go/internal/loadpoint" @@ -1068,6 +1070,11 @@ func main() { // Likewise constructed further down; the applier hands it the zones a // changed configuration or driver catalog declares. var thermalTwins *thermaltwin.Service + heatCat := &heatCatalog{} + var heatSvc *heatrun.Service + // One set of control holds for the API and the heat control, so a + // planned value and an operator's hold share a lock and an expiry. + controlHolds := drivercontrol.New(func() drivercontrol.Registry { return reg }) // Caller holds forecastConfigMu for a live transition. Keep persisted state // intact during a short unconfirmed startup; only confirmed live bindings @@ -1200,6 +1207,7 @@ func main() { if thermalTwins != nil { thermalTwins.SetZones(thermalTwinZones(newCfg.Drivers, reloadCatalog)) } + heatCat.set(newCfg.Drivers, reloadCatalog) warnIfEVHasBatteryCapacity(newCfg.Drivers, newCfg.Loadpoints, reloadCatalog) // Swap inverter-group tags (#143) and per-driver power @@ -1495,6 +1503,43 @@ func main() { thermalTwins.Start(ctx) defer thermalTwins.Stop() + // ---- Heat control (docs/adr/0012) ---- + // Plans the owner's heat.zones every quarter. It writes nothing unless + // heat.write is on, and then only through the shared control holds. + heatCat.set(twinDrivers(), driverCatalog) + heatSvc = heatrun.New(heatrun.Inputs{ + Config: func() *config.Heat { + cfgMu.RLock() + defer cfgMu.RUnlock() + return cfg.Heat + }, + Twins: thermalTwins.Snapshot, + Latest: tel.LatestMetric, + Prices: heatPrices(st, func() string { + cfgMu.RLock() + defer cfgMu.RUnlock() + if cfg.Price == nil { + return "" + } + return cfg.Price.Zone + }), + Outdoor: heatOutdoor(st, func() int64 { return forecastSettings.Snapshot().WeatherSinceMS }), + Control: heatCat.control, + Writer: heatrun.HoldsWriter{Holds: controlHolds}, + SiteFresh: func() bool { + cfgMu.RLock() + meter := cfg.SiteMeterDriver() + watchdog := time.Duration(cfg.Site.WatchdogTimeoutS) * time.Second + cfgMu.RUnlock() + if watchdog <= 0 { + watchdog = 60 * time.Second + } + return meter != "" && !tel.IsStale(meter, telemetry.DerMeter, watchdog) + }, + }) + heatSvc.Start(ctx) + defer heatSvc.Stop() + // ---- Start OCPP 1.6J Central System (optional) ---- // Chargers dial us, so there is nothing to add to cfg.Drivers and no Lua // driver involved. A charge point whose identity (the last segment of the @@ -2636,6 +2681,8 @@ func main() { PVModel: pvSvc, LoadModel: loadSvc, ThermalTwin: thermalTwins, + HeatPlan: heatSvc, + ControlHolds: controlHolds, ForecastLearning: forecastTrackerSvc, Loadpoints: lpMgr, Cars: carsRT, diff --git a/go/internal/api/api.go b/go/internal/api/api.go index 1f3b3a227..b74d42c83 100644 --- a/go/internal/api/api.go +++ b/go/internal/api/api.go @@ -48,6 +48,7 @@ import ( "github.com/srcfl/ftw/go/internal/fleetping" "github.com/srcfl/ftw/go/internal/forecast" "github.com/srcfl/ftw/go/internal/ha" + "github.com/srcfl/ftw/go/internal/heatrun" "github.com/srcfl/ftw/go/internal/loadmodel" "github.com/srcfl/ftw/go/internal/loadpoint" "github.com/srcfl/ftw/go/internal/localzone" @@ -178,7 +179,13 @@ type Deps struct { // Optional: load digital-twin self-learner. LoadModel *loadmodel.Service // Optional: shadow thermal twins of declared room sensors. - ThermalTwin *thermaltwin.Service + ThermalTwin *thermaltwin.Service + // HeatPlan is the heat zones' plan; nil when Core runs none. + HeatPlan *heatrun.Service + // ControlHolds, when set, is shared with Core's heat control so planned + // values and an operator's hold go through one lock. Nil gives the API + // holds of its own. + ControlHolds *drivercontrol.Holds ForecastLearning ForecastLearning // Optional: EV loadpoint state consumed by the API and MPC. @@ -341,7 +348,11 @@ func New(deps *Deps) *Server { drafts: newDriverDrafts(), marks: make(map[string]routeMark), } - s.controlHolds = drivercontrol.New(s.controlRegistry) + if deps.ControlHolds != nil { + s.controlHolds = deps.ControlHolds + } else { + s.controlHolds = drivercontrol.New(s.controlRegistry) + } s.setup = onboarding.NewWithSecrets(deps.State, s.preserveSetupSecrets, filepath.Dir(deps.ConfigPath)) if deps.SaveConfigWithValues == nil && deps.State != nil { deps.SaveConfigWithValues = func(path string, cfg *config.Config, values map[string]string, reviewedJSON []byte, beforeSave func() error) error { @@ -540,6 +551,7 @@ func (s *Server) routes() { s.handle("POST /api/pvmodel/reset", Configure, s.handlePVModelReset) s.handle("GET /api/loadmodel", Read, s.handleLoadModel) s.handle("GET /api/thermal/twins", Read, s.handleThermalTwins) + s.handle("GET /api/heat/plan", Read, s.handleHeatPlan) s.handle("POST /api/loadmodel/profile", Configure, s.handleLoadModelProfile) s.handle("POST /api/loadmodel/reset", Configure, s.handleLoadModelReset) s.handle("GET /api/research/load/dump", Read, s.handleLoadResearchDump) diff --git a/go/internal/api/api_agent_catalog.go b/go/internal/api/api_agent_catalog.go index 42a75d3ed..f951e1799 100644 --- a/go/internal/api/api_agent_catalog.go +++ b/go/internal/api/api_agent_catalog.go @@ -25,7 +25,8 @@ var agentAPIHints = []protocol.AgentAPIRoute{ {Path: "/api/data-sources", Description: "Available data sources and freshness"}, {Path: "/api/battery_models", Description: "Learned battery model and efficiency"}, {Path: "/api/loadmodel", Description: "Load forecast model and learning"}, - {Path: "/api/thermal/twins", Description: "Learned thermal twins of room sensors; shadow only, nothing controls from them"}, + {Path: "/api/thermal/twins", Description: "Learned thermal twins of room sensors; heat control writes from them only when heat.write is on"}, + {Path: "/api/heat/plan", Description: "Heat zones' plan per quarter, the day's saving against the owner's least saving, and what was written; shadow unless heat.write is on"}, {Path: "/api/pvmodel", Description: "Solar forecast model and learning"}, {Path: "/api/forecast", Description: "Load and solar forecasts", Query: map[string]string{"range": "Time ahead, such as 24h"}}, {Path: "/api/prices", Description: "Stored import and export prices", Query: map[string]string{"range": "Time ahead, such as 24h", "since_ms": "Unix milliseconds", "until_ms": "Unix milliseconds"}}, diff --git a/go/internal/api/api_heat_plan.go b/go/internal/api/api_heat_plan.go new file mode 100644 index 000000000..7ff73d5b3 --- /dev/null +++ b/go/internal/api/api_heat_plan.go @@ -0,0 +1,14 @@ +package api + +import "net/http" + +// GET /api/heat/plan — each heat zone's plan from the last slot, what the +// zones together would save a day against the owner's least saving, and what +// was written. `write: false` means the plan is shadow and nothing was sent. +func (s *Server) handleHeatPlan(w http.ResponseWriter, r *http.Request) { + if s.deps.HeatPlan == nil { + writeJSON(w, http.StatusOK, map[string]any{"enabled": false, "write": false}) + return + } + writeJSON(w, http.StatusOK, s.deps.HeatPlan.Snapshot()) +} diff --git a/go/internal/config/heat.go b/go/internal/config/heat.go index 02713b705..bcd7a8994 100644 --- a/go/internal/config/heat.go +++ b/go/internal/config/heat.go @@ -34,6 +34,18 @@ type HeatZone struct { // Control is the declared control the plan moves, "/". // Empty means the zone is planned in shadow only. Control string `yaml:"control,omitempty" json:"control,omitempty"` + // Boundary is what the zone loses heat to: "outdoor" for the weather + // forecast, or "/" for a measured temperature, such as + // the room air around a floor. Required: a floor that loses heat to + // outdoors is planned as a different thing. + Boundary string `yaml:"boundary" json:"boundary"` + // Source is what makes the heat. Only "direct_electric" is planned yet; + // a heat pump needs its efficiency declared, which this section does not + // carry. + Source string `yaml:"source" json:"source"` + // HeatKW is the heat at full output, the owner's figure: a floor's area + // times its rating, a radiator's plate. + HeatKW float64 `yaml:"heat_kw" json:"heat_kw"` // TargetC is what the owner asks for; MinC and MaxC the hard band // around it. The band is never widened. TargetC float64 `yaml:"target_c" json:"target_c"` @@ -47,6 +59,12 @@ type HeatZone struct { PeakRelief *heatplan.PeakRelief `yaml:"peak_relief,omitempty" json:"peak_relief,omitempty"` } +// The words a heat zone's boundary and source may take besides a sensor key. +const ( + HeatBoundaryOutdoor = "outdoor" + HeatSourceDirectElectric = "direct_electric" +) + var heatKey = regexp.MustCompile(`^[^/\s]+/[^/\s]+$`) // Validate refuses a heat section that cannot be read one way. @@ -75,6 +93,15 @@ func (h *Heat) Validate() error { if z.Control != "" && !heatKey.MatchString(z.Control) { return fmt.Errorf("%s (%s): control must be \"/\"", at, z.Name) } + if z.Boundary != HeatBoundaryOutdoor && !heatKey.MatchString(z.Boundary) { + return fmt.Errorf("%s (%s): boundary must be \"outdoor\" or \"/\"", at, z.Name) + } + if z.Source != HeatSourceDirectElectric { + return fmt.Errorf("%s (%s): source must be %q; a heat pump is not planned from this section yet", at, z.Name, HeatSourceDirectElectric) + } + if !(z.HeatKW > 0) || z.HeatKW > 500 { + return fmt.Errorf("%s (%s): heat_kw must be above 0 and at most 500", at, z.Name) + } for _, v := range []float64{z.TargetC, z.MinC, z.MaxC, z.ComfortWeight} { if math.IsNaN(v) || math.IsInf(v, 0) { return fmt.Errorf("%s (%s): temperatures must be finite", at, z.Name) diff --git a/go/internal/config/heat_test.go b/go/internal/config/heat_test.go index 565ce4bdb..b4553c4ac 100644 --- a/go/internal/config/heat_test.go +++ b/go/internal/config/heat_test.go @@ -18,6 +18,9 @@ zones: - name: badrum sensor: wiser_7/floor_temp_c control: wiser_7/set_setpoint + boundary: wiser_7/room_temp_c + source: direct_electric + heat_kw: 0.6 target_c: 24.5 min_c: 20 max_c: 27 @@ -48,7 +51,7 @@ func TestHeatSectionLeftOutOrEmptyChangesNothing(t *testing.T) { } func TestHeatSectionRefusesWhatCannotBeReadOneWay(t *testing.T) { - ok := HeatZone{Name: "a", Sensor: "d/m", TargetC: 22, MinC: 20, MaxC: 24} + ok := HeatZone{Name: "a", Sensor: "d/m", Boundary: "outdoor", Source: "direct_electric", HeatKW: 1, TargetC: 22, MinC: 20, MaxC: 24} for name, tc := range map[string]struct { h Heat want string @@ -57,10 +60,10 @@ func TestHeatSectionRefusesWhatCannotBeReadOneWay(t *testing.T) { "twice": {Heat{Zones: []HeatZone{ok, ok}}, "twice"}, "bad sensor": {Heat{Zones: []HeatZone{{Name: "a", Sensor: "dm", TargetC: 22, MinC: 20, MaxC: 24}}}, "sensor"}, "bad control": {Heat{Zones: []HeatZone{{Name: "a", Sensor: "d/m", Control: "x", TargetC: 22, MinC: 20, MaxC: 24}}}, "control"}, - "target outside": {Heat{Zones: []HeatZone{{Name: "a", Sensor: "d/m", TargetC: 25, MinC: 20, MaxC: 24}}}, "min_c"}, - "no band": {Heat{Zones: []HeatZone{{Name: "a", Sensor: "d/m", TargetC: 22, MinC: 22, MaxC: 22}}}, "band"}, + "target outside": {Heat{Zones: []HeatZone{with(ok, func(z *HeatZone) { z.TargetC = 25 })}}, "min_c"}, + "no band": {Heat{Zones: []HeatZone{with(ok, func(z *HeatZone) { z.MinC, z.TargetC, z.MaxC = 22, 22, 22 })}}, "band"}, "bad gate": {Heat{Savings: &heatplan.SavingsGate{MinPerDay: 5, KeepShare: 2}, Zones: []HeatZone{ok}}, "savings"}, - "bad relief": {Heat{Zones: []HeatZone{{Name: "a", Sensor: "d/m", TargetC: 22, MinC: 20, MaxC: 24, PeakRelief: &heatplan.PeakRelief{MaxHours: 3, Factor: 1, WindowH: 12}}}}, "peak_relief"}, + "bad relief": {Heat{Zones: []HeatZone{with(ok, func(z *HeatZone) { z.PeakRelief = &heatplan.PeakRelief{MaxHours: 3, Factor: 1, WindowH: 12} })}}, "peak_relief"}, "write no control": {Heat{Write: true, Zones: []HeatZone{ok}}, "control"}, } { err := tc.h.Validate() @@ -74,3 +77,5 @@ func TestHeatSectionRefusesWhatCannotBeReadOneWay(t *testing.T) { t.Errorf("a zone with a control and write on was refused: %v", err) } } + +func with(z HeatZone, f func(*HeatZone)) HeatZone { f(&z); return z } diff --git a/go/internal/heatrun/holds.go b/go/internal/heatrun/holds.go new file mode 100644 index 000000000..309846c5b --- /dev/null +++ b/go/internal/heatrun/holds.go @@ -0,0 +1,48 @@ +package heatrun + +import ( + "context" + "encoding/json" + "errors" + "time" + + "github.com/srcfl/ftw/go/internal/drivercontrol" +) + +// HoldsWriter writes through the same holds an operator's control request +// uses, so the two share one lock and one expiry and neither can expire into +// a default that undoes the other. +type HoldsWriter struct{ Holds *drivercontrol.Holds } + +// Hold sends the value the way POST /api/drivers/{name}/control does. +func (w HoldsWriter) Hold(ctx context.Context, driver, control string, value float64, d time.Duration) (int64, error) { + body, err := json.Marshal(map[string]any{"action": control, "value": value, "offset": value}) + if err != nil { + return 0, err + } + var ( + exp int64 + sent error + ) + w.Holds.Send(ctx, driver, control, value, body, d, func(h drivercontrol.Hold, err error) { + exp, sent = h.ExpiresAt, err + }) + if sent == nil && exp == 0 { + return 0, errors.New("the hold was not armed") + } + return exp, sent +} + +// Active is the driver's hold now, if any. +func (w HoldsWriter) Active(driver string) (string, int64, bool) { + h := w.Holds.Active(driver) + if h == nil { + return "", 0, false + } + return h.Control, h.ExpiresAt, true +} + +// Release ends the hold and sends the driver's own default. +func (w HoldsWriter) Release(ctx context.Context, driver string) error { + return w.Holds.SendDefault(ctx, driver) +} diff --git a/go/internal/heatrun/service.go b/go/internal/heatrun/service.go new file mode 100644 index 000000000..1714db85f --- /dev/null +++ b/go/internal/heatrun/service.go @@ -0,0 +1,663 @@ +// Package heatrun plans the owner's heat zones with heatplan and, when the +// owner has turned writing on, holds each zone's control at the plan's value +// through drivercontrol (docs/adr/0012). +// +// It is shadow first. With heat.write off, the default, it plans every slot, +// shows the plan and what it would save, and writes nothing. With it on, a +// zone is written only when all of these hold: its twin is trusted, its +// control is declared as a setpoint, the plans of every zone together pass +// the owner's least saving, and no one else holds the driver. Anything else +// hands the device back to its own default, so a fault ends in the device +// running itself. +package heatrun + +import ( + "context" + "errors" + "fmt" + "log/slog" + "math" + "sync" + "time" + + "github.com/srcfl/ftw/go/internal/config" + "github.com/srcfl/ftw/go/internal/drivers" + "github.com/srcfl/ftw/go/internal/heatplan" + "github.com/srcfl/ftw/go/internal/thermal" + "github.com/srcfl/ftw/go/internal/thermaltwin" +) + +const ( + // SlotH is the planning slot. Prices come in quarters. + SlotH = 0.25 + slot = 15 * time.Minute + // A horizon shorter than this is not worth planning; one longer is cut. + minSlots = 8 + maxSlots = 36 * 4 + // A reading older than this is not the zone now. + maxReadingAge = 15 * time.Minute + // A day's mean price needs this much of the day known. + dayMinHours = 22 + // From this local hour the comfort is for tomorrow when its prices are + // known, as the evening already heats for it. + tomorrowFromHour = 20 + // How long a written value is held when the driver declares no limit. + // Each tick writes again, so a value outlives a dead Core by at most + // this long. + defaultHold = 30 * time.Minute +) + +// Price is one price slot, in the unit the owner's limits are written in +// (öre/kWh including grid fee and tax, as the price service stores it). +type Price struct { + Start time.Time + Len time.Duration + Value float64 +} + +// Writer is the part of drivercontrol.Holds the service writes through, so +// planned values and an operator's hold share one lock and one expiry. +type Writer interface { + // Hold sends value to the control and holds it for d. It returns when + // the hold expires. + Hold(ctx context.Context, driver, control string, value float64, d time.Duration) (expiresAtMs int64, err error) + // Active is the hold on the driver now: its control and expiry, and + // whether there is one. + Active(driver string) (control string, expiresAtMs int64, ok bool) + // Release clears the hold and sends the driver's own default. + Release(ctx context.Context, driver string) error +} + +// Inputs is everything the service reads. Each is read at each tick. +type Inputs struct { + Config func() *config.Heat + Twins func() []thermaltwin.ZoneStatus + Latest func(driver, metric string) (float64, time.Time, bool) + Prices func(from, to time.Time) []Price + Outdoor func(from time.Time, n int) ([]float64, bool) + // Control is the declared control behind "/". + Control func(driver, control string) (drivers.CatalogControl, bool) + // Writer is nil when nothing may be written, whatever the config says. + Writer Writer + // SiteFresh reports whether the site meter is current. Stale site-meter + // data stops dispatch (AGENTS.md); nil means no meter is known, which + // also stops it. + SiteFresh func() bool + // Now is time.Now unless a test sets it. + Now func() time.Time +} + +// Gate is the owner's least saving as the last tick weighed it. +type Gate struct { + Set bool `json:"set"` + Limit float64 `json:"min_per_day,omitempty"` + PerDay float64 `json:"per_day"` + Open bool `json:"open"` + HorizonH float64 `json:"horizon_h"` +} + +// ZonePlan is one zone's plan and what was done with it. +type ZonePlan struct { + Name string `json:"name"` + Sensor string `json:"sensor"` + Control string `json:"control,omitempty"` + // Planned is false when the zone could not be planned; Reason says why. + Planned bool `json:"planned"` + Reason string `json:"reason,omitempty"` + Twin string `json:"twin_status,omitempty"` + // StartC is the zone now; TargetC the owner's target and DayTargetC the + // target the day's price moved it to. + StartC float64 `json:"start_c,omitempty"` + TargetC float64 `json:"target_c"` + DayTargetC float64 `json:"day_target_c"` + DayMean float64 `json:"day_mean_price,omitempty"` + PeakSlots int `json:"peak_relief_slots,omitempty"` + Value *float64 `json:"value,omitempty"` + Neutral *float64 `json:"neutral_value,omitempty"` + Saving float64 `json:"saving"` + Cost float64 `json:"cost"` + Baseline float64 `json:"baseline_cost"` + ExcursionKh float64 `json:"band_excursion_kh"` + // Write is what was done with the control this tick. + Write string `json:"write"` + Slots []heatplan.Slot `json:"slots,omitempty"` +} + +// Snapshot is the last tick. +type Snapshot struct { + At time.Time `json:"at"` + Enabled bool `json:"enabled"` + Write bool `json:"write"` + Gate Gate `json:"gate"` + Zones []ZonePlan `json:"zones"` + // Prices is the horizon's price per slot, from At. + Prices []float64 `json:"prices,omitempty"` +} + +type held struct { + control string + value float64 + expiresMs int64 + changedAt time.Time + hold time.Duration +} + +// refreshEvery is how often held values are checked between plans. A device +// that drops a written value by itself (CTC resets its control registers +// five minutes after the last write) is written again before its hold ends. +const refreshEvery = 30 * time.Second + +// Service runs the plan every slot. +type Service struct { + in Inputs + + mu sync.Mutex + last Snapshot + gateOpen bool + held map[string]held // by driver: what this service holds + + cancel context.CancelFunc + done chan struct{} +} + +// New returns a service that has not started. +func New(in Inputs) *Service { + if in.Now == nil { + in.Now = time.Now + } + return &Service{in: in, held: map[string]held{}} +} + +// Start ticks at every slot boundary until Stop. +func (s *Service) Start(ctx context.Context) { + ctx, s.cancel = context.WithCancel(ctx) + s.done = make(chan struct{}) + go func() { + defer close(s.done) + // Let telemetry and the twins fill before the first plan. + next := s.in.Now().Add(time.Minute) + ticker := time.NewTicker(refreshEvery) + defer ticker.Stop() + for { + select { + case <-ctx.Done(): + return + case <-ticker.C: + } + if now := s.in.Now(); !now.Before(next) { + s.Tick(ctx) + next = now.Truncate(slot).Add(slot) + } else { + s.Refresh(ctx) + } + } + }() +} + +// Refresh writes a held value again when its hold would end before the next +// check, and hands the device back if the site meter went stale since the +// plan. It decides nothing new: values change only at Tick. +func (s *Service) Refresh(ctx context.Context) { + s.mu.Lock() + defer s.mu.Unlock() + if s.in.Writer == nil { + return + } + now := s.in.Now() + for driver, h := range s.held { + if s.in.SiteFresh == nil || !s.in.SiteFresh() { + s.releaseLocked(ctx, driver) + continue + } + if time.UnixMilli(h.expiresMs).Sub(now) > 3*refreshEvery { + continue + } + if c, exp, ok := s.in.Writer.Active(driver); !ok || c != h.control || exp != h.expiresMs { + // Expired, or someone else holds it now: not ours to renew. + delete(s.held, driver) + continue + } + exp, err := s.in.Writer.Hold(ctx, driver, h.control, h.value, h.hold) + if err != nil { + delete(s.held, driver) + slog.Warn("heat: renewing a hold failed", "driver", driver, "err", err) + continue + } + h.expiresMs = exp + s.held[driver] = h + } +} + +// Stop ends the ticks and hands back every driver this service holds. +func (s *Service) Stop() { + if s.cancel == nil { + return + } + s.cancel() + <-s.done + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + s.mu.Lock() + defer s.mu.Unlock() + for driver := range s.held { + s.releaseLocked(ctx, driver) + } +} + +// Snapshot returns the last tick. +func (s *Service) Snapshot() Snapshot { + s.mu.Lock() + defer s.mu.Unlock() + out := s.last + out.Zones = append([]ZonePlan(nil), s.last.Zones...) + return out +} + +// Tick plans every zone once and writes what may be written. +func (s *Service) Tick(ctx context.Context) { + s.mu.Lock() + defer s.mu.Unlock() + now := s.in.Now() + var cfg *config.Heat + if s.in.Config != nil { + cfg = s.in.Config() + } + snap := Snapshot{At: now} + if cfg == nil || len(cfg.Zones) == 0 || cfg.Validate() != nil { + s.last = snap + s.releaseAllLocked(ctx) + return + } + snap.Enabled = true + snap.Write = cfg.Write && s.in.Writer != nil + + start := now.Truncate(slot) + price := s.horizon(start) + snap.Prices = price + twins := map[string]thermaltwin.ZoneStatus{} + if s.in.Twins != nil { + for _, t := range s.in.Twins() { + twins[t.Key] = t + } + } + + zones := make([]ZonePlan, len(cfg.Zones)) + plans := make([]heatplan.Plan, 0, len(cfg.Zones)) + reqs := make([]*heatplan.Request, len(cfg.Zones)) + for i, zc := range cfg.Zones { + zp := ZonePlan{Name: zc.Name, Sensor: zc.Sensor, Control: zc.Control, TargetC: zc.TargetC, DayTargetC: zc.TargetC} + req, err := s.request(zc, twins, price, start, now, &zp) + if err != nil { + zp.Reason = err.Error() + zones[i] = zp + continue + } + plan, err := heatplan.Propose(*req) + if err != nil { + zp.Reason = err.Error() + zones[i] = zp + continue + } + reqs[i] = req + zp.Planned = true + zp.Saving, zp.Cost, zp.Baseline, zp.ExcursionKh = plan.Saving(), plan.Cost, plan.BaselineCost, plan.BandExcursionKh + zp.Slots = plan.Slots + if len(plan.Slots) > 0 { + v := plan.Slots[0].Value + zp.Value = &v + } + plans = append(plans, plan) + zones[i] = zp + } + + gate := heatplan.SavingsGate{} + if cfg.Savings != nil { + gate = *cfg.Savings + } + horizonH := float64(len(price)) * SlotH + open, perDay := gate.Open(plans, horizonH, s.gateOpen) + if len(plans) == 0 { + open, perDay = false, 0 + } + s.gateOpen = open + snap.Gate = Gate{Set: gate.MinPerDay > 0, Limit: gate.MinPerDay, PerDay: perDay, Open: open, HorizonH: horizonH} + + wanted := map[string]bool{} + for i, zc := range cfg.Zones { + zones[i].Write = s.write(ctx, cfg, zc, &zones[i], reqs[i], twins, open, snap.Write, now, wanted) + } + // A driver this service holds that no zone wants any more goes back. + for driver := range s.held { + if !wanted[driver] { + s.releaseLocked(ctx, driver) + } + } + snap.Zones = zones + s.last = snap +} + +// horizon is the price per slot from start, as far as prices run unbroken. +func (s *Service) horizon(start time.Time) []float64 { + if s.in.Prices == nil { + return nil + } + rows := s.in.Prices(start, start.Add(maxSlots*slot)) + var out []float64 + for k := 0; k < maxSlots; k++ { + t := start.Add(time.Duration(k) * slot) + v, ok := priceAt(rows, t) + if !ok { + break + } + out = append(out, v) + } + return out +} + +func priceAt(rows []Price, t time.Time) (float64, bool) { + for _, r := range rows { + if !t.Before(r.Start) && t.Before(r.Start.Add(r.Len)) && !math.IsNaN(r.Value) && !math.IsInf(r.Value, 0) { + return r.Value, true + } + } + return 0, false +} + +// dayMean is the mean price of the day the comfort is for: today, or from +// the evening tomorrow when tomorrow is known. +func (s *Service) dayMean(now time.Time) (float64, bool) { + if s.in.Prices == nil { + return 0, false + } + day := time.Date(now.Year(), now.Month(), now.Day(), 0, 0, 0, 0, now.Location()) + mean := func(d time.Time) (float64, bool) { + end := d.AddDate(0, 0, 1) + rows := s.in.Prices(d, end) + var series []float64 + for t := d; t.Before(end); t = t.Add(slot) { + if v, ok := priceAt(rows, t); ok { + series = append(series, v) + } + } + return heatplan.DayMean(series, SlotH, dayMinHours) + } + if now.Hour() >= tomorrowFromHour { + if m, ok := mean(day.AddDate(0, 0, 1)); ok { + return m, true + } + } + return mean(day) +} + +func splitKey(key string) (string, string) { + for i := 0; i < len(key); i++ { + if key[i] == '/' { + return key[:i], key[i+1:] + } + } + return key, "" +} + +func (s *Service) reading(key string, now time.Time) (float64, error) { + if s.in.Latest == nil { + return 0, errors.New("no telemetry") + } + driver, metric := splitKey(key) + v, at, ok := s.in.Latest(driver, metric) + if !ok { + return 0, fmt.Errorf("%s has no reading", key) + } + if now.Sub(at) > maxReadingAge { + return 0, fmt.Errorf("%s was last read %s ago", key, now.Sub(at).Round(time.Minute)) + } + return v, nil +} + +func constant(n int, v float64) []float64 { + out := make([]float64, n) + for i := range out { + out[i] = v + } + return out +} + +// request builds one zone's request, or says why it cannot. +func (s *Service) request(zc config.HeatZone, twins map[string]thermaltwin.ZoneStatus, price []float64, start, now time.Time, zp *ZonePlan) (*heatplan.Request, error) { + n := len(price) + if n < minSlots { + return nil, fmt.Errorf("only %d quarters of prices are known", n) + } + twin, ok := twins[zc.Sensor] + if !ok { + return nil, errors.New("no thermal twin learns this sensor") + } + zp.Twin = string(twin.Status) + p := twin.Params + if p.TauH == nil || p.CapacityKWhPerK == nil { + return nil, errors.New("the twin has no physical model yet") + } + startC, err := s.reading(zc.Sensor, now) + if err != nil { + return nil, err + } + zp.StartC = startC + + var outdoor []float64 + if s.in.Outdoor != nil { + if o, ok := s.in.Outdoor(start, n); ok && len(o) == n { + outdoor = o + } + } + var boundary []float64 + if zc.Boundary == config.HeatBoundaryOutdoor { + if outdoor == nil { + return nil, errors.New("no outdoor forecast for the horizon") + } + boundary = outdoor + } else { + b, err := s.reading(zc.Boundary, now) + if err != nil { + return nil, fmt.Errorf("boundary: %w", err) + } + boundary = constant(n, b) + } + if outdoor == nil { + // Direct electric heat does not depend on the weather; the + // planner still wants a series. + outdoor = boundary + } + + z := heatplan.Zone{ + TauH: *p.TauH, + CapacityKWhPerK: *p.CapacityKWhPerK, + OtherGainKPerH: p.OtherGainKPerH, + StartC: startC, + BoundaryC: boundary, + TargetC: constant(n, zc.TargetC), + MinC: constant(n, zc.MinC), + MaxC: constant(n, zc.MaxC), + ComfortWeight: zc.ComfortWeight, + } + if zc.PriceComfort != nil && zc.PriceComfort.Enabled() { + if mean, ok := s.dayMean(now); ok { + zp.DayMean = mean + z = zc.PriceComfort.Apply(z, mean) + zp.DayTargetC = z.TargetC[0] + } + } + if zc.PeakRelief != nil && zc.PeakRelief.Enabled() { + for _, v := range zc.PeakRelief.Slots(price, SlotH) { + if v { + zp.PeakSlots++ + } + } + z = zc.PeakRelief.Apply(z, price, SlotH) + } + + act, neutral, err := s.actuator(zc) + if err != nil { + return nil, err + } + if neutral != nil { + zp.Neutral = neutral + } + return &heatplan.Request{SlotH: SlotH, Price: price, OutdoorC: outdoor, Zone: z, Actuator: act}, nil +} + +// actuator is the zone's control as the plan sees it. A zone with no +// control is planned as if a thermostat could be set anywhere in its band +// in half-degree steps, so the owner sees what a control would do. +func (s *Service) actuator(zc config.HeatZone) (heatplan.Actuator, *float64, error) { + lo, hi, step := zc.MinC, zc.MaxC, 0.5 + if zc.Control != "" { + if s.in.Control == nil { + return heatplan.Actuator{}, nil, errors.New("the control's declaration is not known") + } + c, ok := s.in.Control(splitKey(zc.Control)) + if !ok { + return heatplan.Actuator{}, nil, fmt.Errorf("%s is not a declared control", zc.Control) + } + if c.Thermal == nil || c.Thermal.Strategy != thermal.InfluenceSetpoint { + return heatplan.Actuator{}, nil, fmt.Errorf("%s is not declared as a setpoint; only setpoints are planned yet", zc.Control) + } + in := c.Input + if in.Min == nil || in.Max == nil { + return heatplan.Actuator{}, nil, fmt.Errorf("%s declares no range", zc.Control) + } + lo, hi = math.Max(lo, *in.Min), math.Min(hi, *in.Max) + if in.Step != nil && *in.Step > 0 { + step = *in.Step + } + } + values := candidates(lo, hi, step) + if len(values) == 0 { + return heatplan.Actuator{}, nil, errors.New("the control can reach nothing inside the band") + } + neutral := values[0] + for _, v := range values { + if math.Abs(v-zc.TargetC) < math.Abs(neutral-zc.TargetC) { + neutral = v + } + } + return heatplan.Actuator{ + Strategy: thermal.InfluenceSetpoint, + Values: values, + MaxHeatKW: zc.HeatKW, + Source: heatplan.Source{Kind: heatplan.SourceDirectElectric}, + }, &neutral, nil +} + +// candidates are the control's steps from lo to hi, at most 16; a fine step +// over a wide band is coarsened by whole multiples so lo and hi stay in. +func candidates(lo, hi, step float64) []float64 { + if !(step > 0) || hi < lo { + return nil + } + first := math.Ceil(lo/step-1e-9) * step + count := int(math.Floor((hi-first)/step+1e-9)) + 1 + if count < 1 { + return nil + } + mult := 1 + for (count-1)/mult+1 > 16 { + mult++ + } + var out []float64 + for i := 0; i < count; i += mult { + out = append(out, math.Round((first+float64(i)*step)*1000)/1000) + } + return out +} + +// write does what may be done with one zone's control and says what it did. +func (s *Service) write(ctx context.Context, cfg *config.Heat, zc config.HeatZone, zp *ZonePlan, req *heatplan.Request, twins map[string]thermaltwin.ZoneStatus, gateOpen, writeOn bool, now time.Time, wanted map[string]bool) string { + if zc.Control == "" { + return "shadow: no control" + } + if !writeOn { + return "shadow: writing is off" + } + driver, control := splitKey(zc.Control) + // The zone may claim the driver only while it would write to it. + switch { + case !zp.Planned || zp.Value == nil: + return s.giveBack(ctx, driver, "not planned") + case twins[zc.Sensor].Status != thermaltwin.StatusTrusted: + return s.giveBack(ctx, driver, "twin not trusted") + case !gateOpen: + return s.giveBack(ctx, driver, "below the least saving") + case s.in.SiteFresh == nil || !s.in.SiteFresh(): + return s.giveBack(ctx, driver, "site meter is stale") + } + if wanted[driver] { + return "skipped: another zone writes to this driver" + } + value := *zp.Value + if zp.Neutral != nil && value == *zp.Neutral { + return s.giveBack(ctx, driver, "plan asks for the device's own") + } + ours, mine := s.held[driver] + if c, exp, ok := s.in.Writer.Active(driver); ok && (!mine || c != ours.control || exp != ours.expiresMs) { + return "skipped: held by someone else" + } + wanted[driver] = true + + hold := defaultHold + minInterval := time.Duration(0) + if c, ok := s.in.Control(driver, control); ok && c.Thermal != nil { + if c.Thermal.DeviceHoldMaxS != nil && *c.Thermal.DeviceHoldMaxS > 0 { + hold = min(hold, time.Duration(*c.Thermal.DeviceHoldMaxS)*time.Second) + } + if c.Thermal.MinIntervalS != nil { + minInterval = time.Duration(*c.Thermal.MinIntervalS) * time.Second + } + } + if mine && ours.value != value && now.Sub(ours.changedAt) < minInterval { + return fmt.Sprintf("held %.1f: the control may change again in %s", ours.value, (minInterval - now.Sub(ours.changedAt)).Round(time.Minute)) + } + if mine && ours.value == value && time.UnixMilli(ours.expiresMs).Sub(now) > 3*refreshEvery { + return fmt.Sprintf("holding %.1f", value) + } + exp, err := s.in.Writer.Hold(ctx, driver, control, value, hold) + if err != nil { + delete(s.held, driver) + slog.Warn("heat: write failed", "zone", zc.Name, "control", zc.Control, "err", err) + return "write failed: " + err.Error() + } + changed := now + if mine && ours.value == value { + changed = ours.changedAt + } + s.held[driver] = held{control: control, value: value, expiresMs: exp, changedAt: changed, hold: hold} + return fmt.Sprintf("wrote %.1f", value) +} + +func (s *Service) giveBack(ctx context.Context, driver, why string) string { + if _, mine := s.held[driver]; !mine { + return "device runs itself: " + why + } + s.releaseLocked(ctx, driver) + return "released: " + why +} + +func (s *Service) releaseAllLocked(ctx context.Context) { + for driver := range s.held { + s.releaseLocked(ctx, driver) + } +} + +// releaseLocked hands the driver back only while the hold is still this +// service's: an operator's newer hold is not undone. +func (s *Service) releaseLocked(ctx context.Context, driver string) { + ours := s.held[driver] + delete(s.held, driver) + if s.in.Writer == nil { + return + } + if c, exp, ok := s.in.Writer.Active(driver); ok && (c != ours.control || exp != ours.expiresMs) { + return + } + if err := s.in.Writer.Release(ctx, driver); err != nil { + slog.Warn("heat: release failed", "driver", driver, "err", err) + } +} diff --git a/go/internal/heatrun/service_test.go b/go/internal/heatrun/service_test.go new file mode 100644 index 000000000..44dcf395f --- /dev/null +++ b/go/internal/heatrun/service_test.go @@ -0,0 +1,341 @@ +package heatrun + +import ( + "context" + "strings" + "testing" + "time" + + "github.com/srcfl/ftw/go/internal/config" + "github.com/srcfl/ftw/go/internal/drivers" + "github.com/srcfl/ftw/go/internal/heatplan" + "github.com/srcfl/ftw/go/internal/thermal" + "github.com/srcfl/ftw/go/internal/thermaltwin" +) + +func fp(v float64) *float64 { return &v } +func ip(v int) *int { return &v } + +type fakeWriter struct { + holds map[string]struct { + control string + exp int64 + } + sent []float64 + released []string + now func() time.Time +} + +func newWriter(now func() time.Time) *fakeWriter { + return &fakeWriter{holds: map[string]struct { + control string + exp int64 + }{}, now: now} +} + +func (w *fakeWriter) Hold(_ context.Context, driver, control string, v float64, d time.Duration) (int64, error) { + exp := w.now().Add(d).UnixMilli() + w.holds[driver] = struct { + control string + exp int64 + }{control, exp} + w.sent = append(w.sent, v) + return exp, nil +} + +func (w *fakeWriter) Active(driver string) (string, int64, bool) { + h, ok := w.holds[driver] + if !ok || h.exp <= w.now().UnixMilli() { + return "", 0, false + } + return h.control, h.exp, true +} + +func (w *fakeWriter) Release(_ context.Context, driver string) error { + delete(w.holds, driver) + w.released = append(w.released, driver) + return nil +} + +type house struct { + now time.Time + cfg *config.Heat + status thermaltwin.Status + price func(h float64) float64 + floor float64 + w *fakeWriter + + meterStale bool +} + +// A bathroom floor the size of the one that built this: 0.6 kW, coasting +// some ten hours, regulated on its floor sensor by an air thermostat. +func newHouse() *house { + h := &house{ + now: time.Date(2026, 11, 17, 12, 0, 0, 0, time.Local), + status: thermaltwin.StatusTrusted, + floor: 23, + price: func(hr float64) float64 { + if hr >= 17 && hr < 20 { + return 450 + } + return 100 + }, + } + h.cfg = &config.Heat{Write: true, Zones: []config.HeatZone{{ + Name: "badrum", Sensor: "wiser_7/floor_temp_c", Control: "wiser_7/set_setpoint", + Boundary: "wiser_7/room_temp_c", Source: "direct_electric", HeatKW: 0.6, + TargetC: 24.5, MinC: 20, MaxC: 27, ComfortWeight: 2, + }}} + h.w = newWriter(func() time.Time { return h.now }) + return h +} + +func (h *house) service() *Service { + return New(Inputs{ + Config: func() *config.Heat { return h.cfg }, + Twins: func() []thermaltwin.ZoneStatus { + return []thermaltwin.ZoneStatus{{ + Zone: thermaltwin.Zone{Key: "wiser_7/floor_temp_c"}, + Status: h.status, + Params: thermaltwin.Params{TauH: fp(10), CapacityKWhPerK: fp(0.4)}, + }} + }, + Latest: func(driver, metric string) (float64, time.Time, bool) { + switch metric { + case "floor_temp_c": + return h.floor, h.now, true + case "room_temp_c": + return 21, h.now, true + } + return 0, time.Time{}, false + }, + Prices: func(from, to time.Time) []Price { + var out []Price + for t := from.Truncate(time.Hour); t.Before(to); t = t.Add(time.Hour) { + out = append(out, Price{Start: t, Len: time.Hour, Value: h.price(float64(t.Hour()))}) + } + // Prices known until midnight tomorrow. + end := time.Date(2026, 11, 19, 0, 0, 0, 0, time.Local) + var cut []Price + for _, p := range out { + if p.Start.Before(end) { + cut = append(cut, p) + } + } + return cut + }, + Control: func(driver, control string) (drivers.CatalogControl, bool) { + if driver != "wiser_7" || control != "set_setpoint" { + return drivers.CatalogControl{}, false + } + return drivers.CatalogControl{ID: control, + Input: drivers.CatalogControlInput{Type: "number", Min: fp(5), Max: fp(30), Step: fp(0.5)}, + Thermal: &drivers.CatalogThermalControl{Asset: thermal.AssetSpaceHeat, Strategy: thermal.InfluenceSetpoint, MinIntervalS: ip(300), DeviceHoldMaxS: ip(1800)}, + }, true + }, + Writer: h.w, + SiteFresh: func() bool { return !h.meterStale }, + Now: func() time.Time { return h.now }, + }) +} + +func TestShadowPlansAndWritesNothing(t *testing.T) { + h := newHouse() + h.cfg.Write = false + s := h.service() + s.Tick(context.Background()) + snap := s.Snapshot() + if !snap.Enabled || snap.Write { + t.Fatalf("enabled %v write %v", snap.Enabled, snap.Write) + } + z := snap.Zones[0] + if !z.Planned || z.Value == nil || len(z.Slots) == 0 { + t.Fatalf("zone not planned: %+v", z) + } + if !strings.HasPrefix(z.Write, "shadow") || len(h.w.sent) != 0 { + t.Fatalf("write %q, sent %v", z.Write, h.w.sent) + } +} + +// Before a peak the plan stores heat in the floor: it asks for more than the +// device's own setpoint, and with writing on and the twin trusted it is held. +func TestTrustedZoneIsWrittenAndHeldOnce(t *testing.T) { + h := newHouse() + h.now = time.Date(2026, 11, 17, 15, 0, 0, 0, time.Local) + h.floor = 22 + s := h.service() + s.Tick(context.Background()) + z := s.Snapshot().Zones[0] + if len(h.w.sent) != 1 || !strings.HasPrefix(z.Write, "wrote") { + t.Fatalf("write %q, sent %v, value %v neutral %v", z.Write, h.w.sent, deref(z.Value), deref(z.Neutral)) + } + // The next quarter with the same value does not write again while the + // hold has time left. + h.now = h.now.Add(slot) + s.Tick(context.Background()) + if z := s.Snapshot().Zones[0]; len(h.w.sent) != 1 && !strings.HasPrefix(z.Write, "wrote") { + t.Fatalf("second tick: %q, sent %v", z.Write, h.w.sent) + } + s.Stop() +} + +func deref(p *float64) any { + if p == nil { + return nil + } + return *p +} + +func TestUntrustedTwinOrClosedGateWritesNothingAndHandsBack(t *testing.T) { + h := newHouse() + h.now = time.Date(2026, 11, 17, 15, 0, 0, 0, time.Local) + h.floor = 22 + s := h.service() + s.Tick(context.Background()) + if len(h.w.sent) != 1 { + t.Fatalf("setup: sent %v (%q)", h.w.sent, s.Snapshot().Zones[0].Write) + } + + h.status = thermaltwin.StatusLearning + h.now = h.now.Add(slot) + s.Tick(context.Background()) + z := s.Snapshot().Zones[0] + if !strings.HasPrefix(z.Write, "released") || len(h.w.released) != 1 { + t.Fatalf("untrusted: %q, released %v", z.Write, h.w.released) + } + + h.status = thermaltwin.StatusTrusted + h.cfg.Savings = &heatplan.SavingsGate{MinPerDay: 1e6} + h.now = h.now.Add(slot) + s.Tick(context.Background()) + snap := s.Snapshot() + if snap.Gate.Open || !strings.Contains(snap.Zones[0].Write, "least saving") || len(h.w.sent) != 1 { + t.Fatalf("closed gate: %+v, %q, sent %v", snap.Gate, snap.Zones[0].Write, h.w.sent) + } +} + +// An operator's hold on the driver is not overwritten and not released. +func TestAnOperatorsHoldIsLeftAlone(t *testing.T) { + h := newHouse() + h.now = time.Date(2026, 11, 17, 15, 0, 0, 0, time.Local) + h.floor = 22 + h.w.holds["wiser_7"] = struct { + control string + exp int64 + }{"set_setpoint", h.now.Add(time.Hour).UnixMilli()} + s := h.service() + s.Tick(context.Background()) + z := s.Snapshot().Zones[0] + if !strings.Contains(z.Write, "someone else") || len(h.w.sent) != 0 { + t.Fatalf("%q, sent %v", z.Write, h.w.sent) + } + h.cfg.Write = false + s.Tick(context.Background()) + if len(h.w.released) != 0 { + t.Fatalf("released an operator's hold: %v", h.w.released) + } +} + +// Writing off after writing hands the device back at once. +func TestTurningWritingOffHandsTheDeviceBack(t *testing.T) { + h := newHouse() + h.now = time.Date(2026, 11, 17, 15, 0, 0, 0, time.Local) + h.floor = 22 + s := h.service() + s.Tick(context.Background()) + h.cfg.Write = false + h.now = h.now.Add(slot) + s.Tick(context.Background()) + if len(h.w.released) != 1 { + t.Fatalf("released %v after writing was turned off", h.w.released) + } +} + +func TestZoneThatCannotBePlannedSaysWhy(t *testing.T) { + for name, tc := range map[string]struct { + mod func(h *house) + want string + }{ + "stale sensor": {func(h *house) { h.floor = 22; h.now = h.now.Add(0) }, ""}, + "no model": {func(h *house) { h.cfg.Zones[0].Sensor = "wiser_8/floor_temp_c" }, "no thermal twin"}, + "undeclared control": {func(h *house) { h.cfg.Zones[0].Control = "wiser_7/other" }, "not a declared control"}, + } { + if tc.want == "" { + continue + } + h := newHouse() + tc.mod(h) + s := h.service() + s.Tick(context.Background()) + z := s.Snapshot().Zones[0] + if z.Planned || !strings.Contains(z.Reason, tc.want) { + t.Errorf("%s: planned %v reason %q", name, z.Planned, z.Reason) + } + } +} + +func TestCandidatesStayWithinSixteenAndKeepTheEnds(t *testing.T) { + got := candidates(20, 27, 0.5) + if len(got) > 16 || got[0] != 20 || got[len(got)-1] > 27 { + t.Fatalf("candidates %v", got) + } + if got := candidates(20, 22, 0.5); len(got) != 5 { + t.Fatalf("candidates %v", got) + } + if candidates(22, 20, 0.5) != nil { + t.Fatal("an empty range gave candidates") + } +} + +// Stale site-meter data stops dispatch: the device goes back to itself. +func TestStaleSiteMeterStopsWriting(t *testing.T) { + h := newHouse() + h.now = time.Date(2026, 11, 17, 15, 0, 0, 0, time.Local) + h.floor = 22 + s := h.service() + s.Tick(context.Background()) + if len(h.w.sent) != 1 { + t.Fatalf("setup: sent %v", h.w.sent) + } + h.meterStale = true + h.now = h.now.Add(slot) + s.Tick(context.Background()) + if z := s.Snapshot().Zones[0]; !strings.Contains(z.Write, "site meter") || len(h.w.released) != 1 { + t.Fatalf("%q, released %v", z.Write, h.w.released) + } +} + +// A device that drops a written value after five minutes is written again +// between plans, and stops being written when the meter goes stale. +func TestShortDeviceHoldIsRenewedBetweenPlans(t *testing.T) { + h := newHouse() + h.now = time.Date(2026, 11, 17, 15, 0, 0, 0, time.Local) + h.floor = 22 + s := h.service() + s.in.Control = func(driver, control string) (drivers.CatalogControl, bool) { + return drivers.CatalogControl{ID: control, + Input: drivers.CatalogControlInput{Type: "number", Min: fp(5), Max: fp(30), Step: fp(0.5)}, + Thermal: &drivers.CatalogThermalControl{Asset: thermal.AssetSpaceHeat, Strategy: thermal.InfluenceSetpoint, DeviceHoldMaxS: ip(300)}, + }, true + } + s.Tick(context.Background()) + if len(h.w.sent) != 1 { + t.Fatalf("setup: sent %v (%q)", h.w.sent, s.Snapshot().Zones[0].Write) + } + for i := 0; i < 28; i++ { // 14 minutes in 30 s steps + h.now = h.now.Add(refreshEvery) + s.Refresh(context.Background()) + if _, _, ok := h.w.Active("wiser_7"); !ok { + t.Fatalf("the hold lapsed after %v", time.Duration(i+1)*refreshEvery) + } + } + if len(h.w.sent) < 3 || len(h.w.sent) > 6 { + t.Fatalf("renewed %d times in 14 minutes of a 5-minute hold", len(h.w.sent)-1) + } + h.meterStale = true + s.Refresh(context.Background()) + if len(h.w.released) != 1 { + t.Fatalf("a stale meter did not hand the device back: %v", h.w.released) + } +} From e2972c91a914f0bbfd0d1659048aee680580b7f7 Mon Sep 17 00:00:00 2001 From: hannesb90 <279736760+hannesb90@users.noreply.github.com> Date: Tue, 17 Nov 2026 16:44:46 +0100 Subject: [PATCH 5/8] feat(thermaltwin): learn a zone against the heat input the owner names 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 "/" 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 Signed-off-by: hannesb90 <279736760+hannesb90@users.noreply.github.com> --- .changeset/heat-shadow-plan.md | 5 ++++ config.example.yaml | 1 + go/cmd/ftw/main.go | 4 ++-- go/cmd/ftw/thermal_twin.go | 31 ++++++++++++++++++++++++- go/cmd/ftw/thermal_twin_test.go | 23 +++++++++++++++--- go/internal/config/heat.go | 9 +++++++ go/internal/thermaltwin/service.go | 25 +++++++++++++++++++- go/internal/thermaltwin/service_test.go | 31 +++++++++++++++++++++++++ 8 files changed, 122 insertions(+), 7 deletions(-) diff --git a/.changeset/heat-shadow-plan.md b/.changeset/heat-shadow-plan.md index a87644a03..163d0e324 100644 --- a/.changeset/heat-shadow-plan.md +++ b/.changeset/heat-shadow-plan.md @@ -13,3 +13,8 @@ holds as an operator's request, only while its twin is trusted, the least saving is reached and the site meter is fresh, and the device is handed back to its own default otherwise. A device that drops a written value by itself is written again before it does. + +A zone can name its heat input (`heat_input: "/"`), so a room +sensor on one device, such as an underfloor gateway, learns against the heat +of another, such as a heat pump's estimated space heat. A sensor named in +`heat.zones` is learned even when its driver does not declare it. diff --git a/config.example.yaml b/config.example.yaml index 6a70713d4..54d66bf9d 100644 --- a/config.example.yaml +++ b/config.example.yaml @@ -291,6 +291,7 @@ fleet_ping: # - name: bathroom_floor # sensor: wiser_7/floor_temp_c # the twin that judges this zone # control: wiser_7/set_setpoint # a declared setpoint control +# # heat_input: ctc/space_heat_w # when the heat comes from another device # boundary: wiser_7/room_temp_c # or "outdoor" # source: direct_electric # heat_kw: 0.6 diff --git a/go/cmd/ftw/main.go b/go/cmd/ftw/main.go index b2b0dfd19..19afa87f9 100644 --- a/go/cmd/ftw/main.go +++ b/go/cmd/ftw/main.go @@ -1205,7 +1205,7 @@ func main() { observeOnly = config.ObserveOnlyDriverSet(newCfg) capMu.Unlock() if thermalTwins != nil { - thermalTwins.SetZones(thermalTwinZones(newCfg.Drivers, reloadCatalog)) + thermalTwins.SetZones(thermalTwinZones(newCfg.Drivers, reloadCatalog, newCfg.Heat)) } heatCat.set(newCfg.Drivers, reloadCatalog) warnIfEVHasBatteryCapacity(newCfg.Drivers, newCfg.Loadpoints, reloadCatalog) @@ -1498,7 +1498,7 @@ func main() { } thermalTwins = thermaltwin.NewService(st, tel) thermalTwins.Temp = loadSvc.Temp - thermalTwins.SetZones(thermalTwinZones(twinDrivers(), driverCatalog)) + thermalTwins.SetZones(thermalTwinZones(twinDrivers(), driverCatalog, func() *config.Heat { cfgMu.RLock(); defer cfgMu.RUnlock(); return cfg.Heat }())) thermalTwins.PowerDrivers = func() []string { return thermalTwinPowerDrivers(twinDrivers()) } thermalTwins.Start(ctx) defer thermalTwins.Stop() diff --git a/go/cmd/ftw/thermal_twin.go b/go/cmd/ftw/thermal_twin.go index d0c964dda..b6845e255 100644 --- a/go/cmd/ftw/thermal_twin.go +++ b/go/cmd/ftw/thermal_twin.go @@ -2,6 +2,7 @@ package main import ( "sort" + "strings" "github.com/srcfl/ftw/go/internal/config" "github.com/srcfl/ftw/go/internal/drivers" @@ -16,7 +17,11 @@ import ( // // complete is false when an enabled driver has no catalog entry, so its // sensors are unknown rather than absent. The service then forgets no twin. -func thermalTwinZones(cfgDrivers []config.Driver, catalog []drivers.CatalogEntry) (zones []thermaltwin.Zone, complete bool) { +// +// A sensor the owner names in heat.zones is learned even when its driver +// does not declare it, as a room sensor on an underfloor gateway, and takes +// the heat input the owner named for it. +func thermalTwinZones(cfgDrivers []config.Driver, catalog []drivers.CatalogEntry, heat *config.Heat) (zones []thermaltwin.Zone, complete bool) { var out []thermaltwin.Zone complete = true for _, d := range cfgDrivers { @@ -39,6 +44,30 @@ func thermalTwinZones(cfgDrivers []config.Driver, catalog []drivers.CatalogEntry }) } } + if heat != nil { + enabled := map[string]bool{} + for _, d := range cfgDrivers { + if !d.Disabled && d.Lua != "" { + enabled[d.Name] = true + } + } + index := map[string]int{} + for i, z := range out { + index[z.Key] = i + } + for _, hz := range heat.Zones { + driver, metric, ok := strings.Cut(hz.Sensor, "/") + if !ok || !enabled[driver] { + continue + } + if i, ok := index[hz.Sensor]; ok { + out[i].HeatInput = hz.HeatInput + continue + } + index[hz.Sensor] = len(out) + out = append(out, thermaltwin.Zone{Key: hz.Sensor, SensorDriver: driver, SensorMetric: metric, HeatInput: hz.HeatInput}) + } + } sort.Slice(out, func(i, j int) bool { return out[i].Key < out[j].Key }) return out, complete } diff --git a/go/cmd/ftw/thermal_twin_test.go b/go/cmd/ftw/thermal_twin_test.go index 79a4e440b..0f75fac0f 100644 --- a/go/cmd/ftw/thermal_twin_test.go +++ b/go/cmd/ftw/thermal_twin_test.go @@ -39,7 +39,7 @@ func TestThermalTwinZonesFromDeclaredSensors(t *testing.T) { {Name: "grid", Lua: filepath.Join(dir, "meter.lua")}, } - got, complete := thermalTwinZones(cfg, catalog) + got, complete := thermalTwinZones(cfg, catalog, nil) if !complete { t.Error("complete = false with every enabled driver in the catalog") } @@ -53,10 +53,27 @@ func TestThermalTwinZonesFromDeclaredSensors(t *testing.T) { // A driver the catalog cannot describe has unknown sensors, not none: // the list is incomplete and no twin may be forgotten on its strength. missing := append(cfg, config.Driver{Name: "gone", Lua: filepath.Join(dir, "gone.lua")}) - if got, complete := thermalTwinZones(missing, catalog); complete || !reflect.DeepEqual(got, want) { + if got, complete := thermalTwinZones(missing, catalog, nil); complete || !reflect.DeepEqual(got, want) { t.Errorf("with an unreadable driver: zones = %+v, complete = %v; want the same zones, incomplete", got, complete) } - if got, complete := thermalTwinZones(cfg, nil); complete || len(got) != 0 { + // A sensor the owner names in heat.zones is learned though its driver + // declares nothing, with the heat input the owner named; a declared one + // takes the named input too. A disabled driver's sensor is not. + heat := &config.Heat{Zones: []config.HeatZone{ + {Sensor: "grid/zone_1_temp_c", HeatInput: "ctc/space_heat_w"}, + {Sensor: "wiser/room_bed_temp_c", HeatInput: "wiser/floor_heat_w"}, + {Sensor: "spare/room_bed_temp_c"}, + }} + withHeat, _ := thermalTwinZones(cfg, catalog, heat) + wantHeat := []thermaltwin.Zone{ + {Key: "grid/zone_1_temp_c", SensorDriver: "grid", SensorMetric: "zone_1_temp_c", HeatInput: "ctc/space_heat_w"}, + {Key: "wiser/room_bed_temp_c", SensorDriver: "wiser", SensorMetric: "room_bed_temp_c", HeatInput: "wiser/floor_heat_w"}, + {Key: "wiser/room_living_temp_c", SensorDriver: "wiser", SensorMetric: "room_living_temp_c"}, + } + if !reflect.DeepEqual(withHeat, wantHeat) { + t.Errorf("with heat zones = %+v, want %+v", withHeat, wantHeat) + } + if got, complete := thermalTwinZones(cfg, nil, nil); complete || len(got) != 0 { t.Errorf("without a catalog: zones = %+v, complete = %v; want none, incomplete", got, complete) } if p := thermalTwinPowerDrivers(cfg); !reflect.DeepEqual(p, []string{"wiser", "grid"}) { diff --git a/go/internal/config/heat.go b/go/internal/config/heat.go index bcd7a8994..707cb8155 100644 --- a/go/internal/config/heat.go +++ b/go/internal/config/heat.go @@ -34,6 +34,12 @@ type HeatZone struct { // Control is the declared control the plan moves, "/". // Empty means the zone is planned in shadow only. Control string `yaml:"control,omitempty" json:"control,omitempty"` + // HeatInput is the "/" that measures or estimates the + // heat warming this zone, for the thermal twin to learn against. Needed + // when the sensor is on one device and the heat comes from another, as + // room sensors on an underfloor gateway heated by a heat pump. Empty + // lets the twin find a heat pump's power by itself. + HeatInput string `yaml:"heat_input,omitempty" json:"heat_input,omitempty"` // Boundary is what the zone loses heat to: "outdoor" for the weather // forecast, or "/" for a measured temperature, such as // the room air around a floor. Required: a floor that loses heat to @@ -93,6 +99,9 @@ func (h *Heat) Validate() error { if z.Control != "" && !heatKey.MatchString(z.Control) { return fmt.Errorf("%s (%s): control must be \"/\"", at, z.Name) } + if z.HeatInput != "" && !heatKey.MatchString(z.HeatInput) { + return fmt.Errorf("%s (%s): heat_input must be \"/\"", at, z.Name) + } if z.Boundary != HeatBoundaryOutdoor && !heatKey.MatchString(z.Boundary) { return fmt.Errorf("%s (%s): boundary must be \"outdoor\" or \"/\"", at, z.Name) } diff --git a/go/internal/thermaltwin/service.go b/go/internal/thermaltwin/service.go index 7dda8fdea..983c43ebf 100644 --- a/go/internal/thermaltwin/service.go +++ b/go/internal/thermaltwin/service.go @@ -40,6 +40,11 @@ type Zone struct { Key string `json:"key"` SensorDriver string `json:"sensor_driver"` SensorMetric string `json:"sensor_metric"` + // HeatInput is the owner's "/" for the heat that warms + // this zone, such as a heat pump's estimated space heat for a room + // sensor on another device. Empty means the sensor's own driver's, or + // the single other driver's, HeatPowerMetric. + HeatInput string `json:"heat_input,omitempty"` } // MetricReader is the part of the telemetry store the service reads. @@ -222,7 +227,8 @@ func (s *Service) sampleLocked(zs *zoneState, now time.Time) { } zs.src = src if src != "" { - p, _, ok := s.read(src, HeatPowerMetric, now) + driver, metric := powerRef(src) + p, _, ok := s.read(driver, metric, now) if !ok { zs.gap = true return @@ -236,6 +242,14 @@ func (s *Service) sampleLocked(zs *zoneState, now time.Time) { // driver reporting heat power. Two candidates is no answer: the twin cannot // tell which one heats this zone. func (s *Service) powerSourceLocked(z Zone, now time.Time) string { + if z.HeatInput != "" { + // The owner named it: that one or none, never a guess. + driver, metric := powerRef(z.HeatInput) + if _, _, ok := s.read(driver, metric, now); ok { + return z.HeatInput + } + return "" + } if _, _, ok := s.read(z.SensorDriver, HeatPowerMetric, now); ok { return z.SensorDriver } @@ -254,6 +268,15 @@ func (s *Service) powerSourceLocked(z Zone, now time.Time) string { return "" } +// powerRef splits a heat input source: "/" as the owner +// named it, or a bare driver name for its HeatPowerMetric. +func powerRef(src string) (driver, metric string) { + if i := strings.Index(src, "/"); i >= 0 { + return src[:i], src[i+1:] + } + return src, HeatPowerMetric +} + func (s *Service) read(driver, metric string, now time.Time) (float64, time.Time, bool) { if s.Tele == nil || driver == "" { return 0, time.Time{}, false diff --git a/go/internal/thermaltwin/service_test.go b/go/internal/thermaltwin/service_test.go index 1fdb4f234..86c76c6d6 100644 --- a/go/internal/thermaltwin/service_test.go +++ b/go/internal/thermaltwin/service_test.go @@ -221,3 +221,34 @@ func TestServiceNeedsOutdoorTemperature(t *testing.T) { t.Errorf("samples = %d without outdoor temperature, want 0", got.Samples) } } + +// A room sensor on an underfloor gateway is heated by a heat pump on another +// device. The owner names the pump's space heat as its heat input, and that +// wins over every power the twin could otherwise find, even with several. +func TestServiceUsesTheHeatInputTheOwnerNamed(t *testing.T) { + tele := fakeTele{} + room := Zone{Key: "lk/zone_1_temp_c", SensorDriver: "lk", SensorMetric: "zone_1_temp_c", HeatInput: "ctc/space_heat_w"} + s := newTestService(tele, fakeStore{}, room) + run(s, t0, 31, func(now time.Time) { + tele["lk/zone_1_temp_c"] = metric{21, now} + tele["ctc/space_heat_w"] = metric{4000, now} + tele["heishamon/hp_power_w"] = metric{1500, now} + tele["nibe/hp_power_w"] = metric{900, now} + }) + if z := zoneStatus(t, s, room.Key); z.PowerSource != "ctc/space_heat_w" { + t.Errorf("power source = %q, want ctc/space_heat_w", z.PowerSource) + } + + // Without a reading from the named source there is no heat input: the + // twin does not fall back to a pump the owner did not name. + quiet := Zone{Key: "lk/zone_2_temp_c", SensorDriver: "lk", SensorMetric: "zone_2_temp_c", HeatInput: "ctc/space_heat_w"} + tele2 := fakeTele{} + s2 := newTestService(tele2, fakeStore{}, quiet) + run(s2, t0, 31, func(now time.Time) { + tele2["lk/zone_2_temp_c"] = metric{21, now} + tele2["heishamon/hp_power_w"] = metric{1500, now} + }) + if z := zoneStatus(t, s2, quiet.Key); z.PowerSource != "" { + t.Errorf("power source = %q, want none when the named input is silent", z.PowerSource) + } +} From 8454822288f7fbe532e3795c51d963a9e36ed832 Mon Sep 17 00:00:00 2001 From: hannesb90 <279736760+hannesb90@users.noreply.github.com> Date: Tue, 17 Nov 2026 16:51:34 +0100 Subject: [PATCH 6/8] feat(heat): plan a heat pump zone, and a curve offset with the owner'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 Signed-off-by: hannesb90 <279736760+hannesb90@users.noreply.github.com> --- .changeset/heat-shadow-plan.md | 4 ++ config.example.yaml | 15 ++++++ go/internal/config/heat.go | 74 +++++++++++++++++++++++++++-- go/internal/config/heat_test.go | 46 ++++++++++++++++++ go/internal/heatplan/source.go | 3 ++ go/internal/heatrun/service.go | 50 +++++++++++++------ go/internal/heatrun/service_test.go | 64 +++++++++++++++++++++++++ 7 files changed, 237 insertions(+), 19 deletions(-) diff --git a/.changeset/heat-shadow-plan.md b/.changeset/heat-shadow-plan.md index 163d0e324..df9d819b0 100644 --- a/.changeset/heat-shadow-plan.md +++ b/.changeset/heat-shadow-plan.md @@ -18,3 +18,7 @@ A zone can name its heat input (`heat_input: "/"`), so a room sensor on one device, such as an underfloor gateway, learns against the heat of another, such as a heat pump's estimated space heat. A sensor named in `heat.zones` is learned even when its driver does not declare it. + +A zone can be heated by a heat pump (`source: heat_pump`) with the owner's +efficiency and heat curve, and planned through a declared curve offset with +the owner's figures for what one unit does. diff --git a/config.example.yaml b/config.example.yaml index 54d66bf9d..b5dcd14dd 100644 --- a/config.example.yaml +++ b/config.example.yaml @@ -301,6 +301,21 @@ fleet_ping: # comfort_weight: 2 # price_comfort: { cheap_price: 150, normal_price: 260, dear_price: 400, raise_k: 1, lower_k: 0 } # peak_relief: { min_price: 200, factor: 3, window_h: 12, max_hours: 3 } +# # A house heated by a hydronic heat pump, its rooms read elsewhere. +# - name: house +# sensor: LK/zone_2_temp_c +# heat_input: CTC/space_heat_w # the pump's estimated space heat +# boundary: outdoor +# source: heat_pump +# heat_kw: 6 +# target_c: 21 +# min_c: 20 +# max_c: 22.5 +# heat_pump: # zero or absent: the planner's start point +# carnot_fraction: 0.5 +# supply: { cold_outdoor_c: -20, cold_supply_c: 45, mild_outdoor_c: 15, mild_supply_c: 24 } +# # control: CTC/set_heat_curve_offset # once the driver declares one +# # curve_effect: { zone_k_per_unit: 0.5, supply_k_per_unit: 1 } # Peak-power tariff (weekday 06–20 local time). Same minor units as # grid_tariff_ore_kwh, per kW, excluding VAT. 0 disables it. diff --git a/go/internal/config/heat.go b/go/internal/config/heat.go index 707cb8155..12c1db6d1 100644 --- a/go/internal/config/heat.go +++ b/go/internal/config/heat.go @@ -45,10 +45,16 @@ type HeatZone struct { // the room air around a floor. Required: a floor that loses heat to // outdoors is planned as a different thing. Boundary string `yaml:"boundary" json:"boundary"` - // Source is what makes the heat. Only "direct_electric" is planned yet; - // a heat pump needs its efficiency declared, which this section does not - // carry. + // Source is what makes the heat: "direct_electric" or "heat_pump". Source string `yaml:"source" json:"source"` + // HeatPump is the pump's efficiency, for source heat_pump. Nil, or a + // field left at zero, takes the planner's starting point (half the + // ideal COP, capped at 6), which is no claim about any pump. + HeatPump *HeatPump `yaml:"heat_pump,omitempty" json:"heat_pump,omitempty"` + // CurveEffect is what one unit of a curve_offset control does, the + // owner's figures until a twin learns them. Required for a zone whose + // control is a curve offset. + CurveEffect *CurveEffect `yaml:"curve_effect,omitempty" json:"curve_effect,omitempty"` // HeatKW is the heat at full output, the owner's figure: a floor's area // times its rating, a radiator's plate. HeatKW float64 `yaml:"heat_kw" json:"heat_kw"` @@ -69,8 +75,54 @@ type HeatZone struct { const ( HeatBoundaryOutdoor = "outdoor" HeatSourceDirectElectric = "direct_electric" + HeatSourceHeatPump = "heat_pump" ) +// HeatPump is a heat pump's efficiency as the owner knows it. +type HeatPump struct { + // CarnotFraction is the share of the ideal COP the pump reaches. + CarnotFraction float64 `yaml:"carnot_fraction,omitempty" json:"carnot_fraction,omitempty"` + // MaxCOP caps the COP. + MaxCOP float64 `yaml:"max_cop,omitempty" json:"max_cop,omitempty"` + // FrostLoss is the share of output an air-source pump loses to + // defrosting at its worst, around +1 °C. + FrostLoss float64 `yaml:"frost_loss,omitempty" json:"frost_loss,omitempty"` + // Supply is the heat curve of a hydronic pump: the flow temperature at + // a cold and a mild outdoor temperature. Nil for a pump that heats the + // zone itself. + Supply *HeatSupplyCurve `yaml:"supply,omitempty" json:"supply,omitempty"` +} + +// HeatSupplyCurve is a heat curve by two points, flat outside them. +type HeatSupplyCurve struct { + ColdOutdoorC float64 `yaml:"cold_outdoor_c" json:"cold_outdoor_c"` + ColdSupplyC float64 `yaml:"cold_supply_c" json:"cold_supply_c"` + MildOutdoorC float64 `yaml:"mild_outdoor_c" json:"mild_outdoor_c"` + MildSupplyC float64 `yaml:"mild_supply_c" json:"mild_supply_c"` +} + +// CurveEffect is one unit of a curve offset: how far it moves the zone and +// the flow. +type CurveEffect struct { + ZoneKPerUnit float64 `yaml:"zone_k_per_unit" json:"zone_k_per_unit"` + SupplyKPerUnit float64 `yaml:"supply_k_per_unit" json:"supply_k_per_unit"` +} + +// PlanSource is the zone's source as the planner reads it. +func (z HeatZone) PlanSource() heatplan.Source { + if z.Source != HeatSourceHeatPump { + return heatplan.Source{Kind: heatplan.SourceDirectElectric} + } + src := heatplan.Source{Kind: heatplan.SourceHeatPump} + if hp := z.HeatPump; hp != nil { + src.CarnotFraction, src.MaxCOP, src.FrostLoss = hp.CarnotFraction, hp.MaxCOP, hp.FrostLoss + if c := hp.Supply; c != nil { + src.Supply = &heatplan.SupplyCurve{ColdOutdoorC: c.ColdOutdoorC, ColdSupplyC: c.ColdSupplyC, MildOutdoorC: c.MildOutdoorC, MildSupplyC: c.MildSupplyC} + } + } + return src +} + var heatKey = regexp.MustCompile(`^[^/\s]+/[^/\s]+$`) // Validate refuses a heat section that cannot be read one way. @@ -105,8 +157,20 @@ func (h *Heat) Validate() error { if z.Boundary != HeatBoundaryOutdoor && !heatKey.MatchString(z.Boundary) { return fmt.Errorf("%s (%s): boundary must be \"outdoor\" or \"/\"", at, z.Name) } - if z.Source != HeatSourceDirectElectric { - return fmt.Errorf("%s (%s): source must be %q; a heat pump is not planned from this section yet", at, z.Name, HeatSourceDirectElectric) + if z.Source != HeatSourceDirectElectric && z.Source != HeatSourceHeatPump { + return fmt.Errorf("%s (%s): source must be %q or %q", at, z.Name, HeatSourceDirectElectric, HeatSourceHeatPump) + } + if z.HeatPump != nil && z.Source != HeatSourceHeatPump { + return fmt.Errorf("%s (%s): heat_pump is set but source is %q", at, z.Name, z.Source) + } + if err := z.PlanSource().Validate(); err != nil { + return fmt.Errorf("%s (%s): heat_pump: %w", at, z.Name, err) + } + if e := z.CurveEffect; e != nil { + if math.IsNaN(e.ZoneKPerUnit+e.SupplyKPerUnit) || math.IsInf(e.ZoneKPerUnit+e.SupplyKPerUnit, 0) || + e.ZoneKPerUnit <= 0 || e.ZoneKPerUnit > 5 || e.SupplyKPerUnit < 0 || e.SupplyKPerUnit > 10 { + return fmt.Errorf("%s (%s): curve_effect needs zone_k_per_unit above 0 and at most 5, supply_k_per_unit 0 to 10", at, z.Name) + } } if !(z.HeatKW > 0) || z.HeatKW > 500 { return fmt.Errorf("%s (%s): heat_kw must be above 0 and at most 500", at, z.Name) diff --git a/go/internal/config/heat_test.go b/go/internal/config/heat_test.go index b4553c4ac..22cffe307 100644 --- a/go/internal/config/heat_test.go +++ b/go/internal/config/heat_test.go @@ -65,6 +65,16 @@ func TestHeatSectionRefusesWhatCannotBeReadOneWay(t *testing.T) { "bad gate": {Heat{Savings: &heatplan.SavingsGate{MinPerDay: 5, KeepShare: 2}, Zones: []HeatZone{ok}}, "savings"}, "bad relief": {Heat{Zones: []HeatZone{with(ok, func(z *HeatZone) { z.PeakRelief = &heatplan.PeakRelief{MaxHours: 3, Factor: 1, WindowH: 12} })}}, "peak_relief"}, "write no control": {Heat{Write: true, Zones: []HeatZone{ok}}, "control"}, + "bad boundary": {Heat{Zones: []HeatZone{with(ok, func(z *HeatZone) { z.Boundary = "" })}}, "boundary"}, + "no heat": {Heat{Zones: []HeatZone{with(ok, func(z *HeatZone) { z.HeatKW = 0 })}}, "heat_kw"}, + "bad heat input": {Heat{Zones: []HeatZone{with(ok, func(z *HeatZone) { z.HeatInput = "ctc" })}}, "heat_input"}, + "unknown source": {Heat{Zones: []HeatZone{with(ok, func(z *HeatZone) { z.Source = "gas" })}}, "source"}, + "pump on electric": {Heat{Zones: []HeatZone{with(ok, func(z *HeatZone) { z.HeatPump = &HeatPump{} })}}, "heat_pump"}, + "bad curve": {Heat{Zones: []HeatZone{with(ok, func(z *HeatZone) { + z.Source = "heat_pump" + z.HeatPump = &HeatPump{Supply: &HeatSupplyCurve{ColdOutdoorC: 15, ColdSupplyC: 45, MildOutdoorC: -15, MildSupplyC: 25}} + })}}, "heat_pump"}, + "bad effect": {Heat{Zones: []HeatZone{with(ok, func(z *HeatZone) { z.CurveEffect = &CurveEffect{ZoneKPerUnit: 0} })}}, "curve_effect"}, } { err := tc.h.Validate() if err == nil || !strings.Contains(err.Error(), tc.want) { @@ -79,3 +89,39 @@ func TestHeatSectionRefusesWhatCannotBeReadOneWay(t *testing.T) { } func with(z HeatZone, f func(*HeatZone)) HeatZone { f(&z); return z } + +// The house the planner was built for: a CTC with an air-to-water pump on +// a heat curve, the rooms read by an underfloor gateway. +const houseHeatPumpYAML = ` +zones: + - name: house + sensor: LK/zone_2_temp_c + heat_input: CTC/space_heat_w + boundary: outdoor + source: heat_pump + heat_kw: 6 + target_c: 21 + min_c: 20 + max_c: 22.5 + heat_pump: + carnot_fraction: 0.45 + supply: { cold_outdoor_c: -20, cold_supply_c: 45, mild_outdoor_c: 15, mild_supply_c: 24 } + curve_effect: { zone_k_per_unit: 0.5, supply_k_per_unit: 1 } +` + +func TestHeatSectionReadsAHeatPump(t *testing.T) { + var h Heat + if err := yaml.Unmarshal([]byte(houseHeatPumpYAML), &h); err != nil { + t.Fatal(err) + } + if err := h.Validate(); err != nil { + t.Fatal(err) + } + src := h.Zones[0].PlanSource() + if src.Kind != heatplan.SourceHeatPump || src.CarnotFraction != 0.45 || src.Supply == nil || src.Supply.At(-20) != 45 { + t.Fatalf("source = %+v", src) + } + if h.Zones[0].CurveEffect.ZoneKPerUnit != 0.5 || h.Zones[0].HeatInput != "CTC/space_heat_w" { + t.Fatalf("zone = %+v", h.Zones[0]) + } +} diff --git a/go/internal/heatplan/source.go b/go/internal/heatplan/source.go index 138bd4368..327911485 100644 --- a/go/internal/heatplan/source.go +++ b/go/internal/heatplan/source.go @@ -95,6 +95,9 @@ type Source struct { MaxCOP float64 } +// Validate refuses a source the planner cannot read one way. +func (s Source) Validate() error { return s.validate() } + func (s Source) validate() error { switch s.Kind { case SourceDirectElectric: diff --git a/go/internal/heatrun/service.go b/go/internal/heatrun/service.go index 1714db85f..190edf6e9 100644 --- a/go/internal/heatrun/service.go +++ b/go/internal/heatrun/service.go @@ -462,6 +462,9 @@ func (s *Service) request(zc config.HeatZone, twins map[string]thermaltwin.ZoneS boundary = constant(n, b) } if outdoor == nil { + if zc.Source == config.HeatSourceHeatPump { + return nil, errors.New("a heat pump needs the outdoor forecast for the horizon") + } // Direct electric heat does not depend on the weather; the // planner still wants a series. outdoor = boundary @@ -508,7 +511,9 @@ func (s *Service) request(zc config.HeatZone, twins map[string]thermaltwin.ZoneS // control is planned as if a thermostat could be set anywhere in its band // in half-degree steps, so the owner sees what a control would do. func (s *Service) actuator(zc config.HeatZone) (heatplan.Actuator, *float64, error) { + act := heatplan.Actuator{Strategy: thermal.InfluenceSetpoint, MaxHeatKW: zc.HeatKW, Source: zc.PlanSource()} lo, hi, step := zc.MinC, zc.MaxC, 0.5 + var declaredDefault *float64 if zc.Control != "" { if s.in.Control == nil { return heatplan.Actuator{}, nil, errors.New("the control's declaration is not known") @@ -517,34 +522,51 @@ func (s *Service) actuator(zc config.HeatZone) (heatplan.Actuator, *float64, err if !ok { return heatplan.Actuator{}, nil, fmt.Errorf("%s is not a declared control", zc.Control) } - if c.Thermal == nil || c.Thermal.Strategy != thermal.InfluenceSetpoint { - return heatplan.Actuator{}, nil, fmt.Errorf("%s is not declared as a setpoint; only setpoints are planned yet", zc.Control) + if c.Thermal == nil { + return heatplan.Actuator{}, nil, fmt.Errorf("%s does not say what it does to heat", zc.Control) } in := c.Input if in.Min == nil || in.Max == nil { return heatplan.Actuator{}, nil, fmt.Errorf("%s declares no range", zc.Control) } - lo, hi = math.Max(lo, *in.Min), math.Min(hi, *in.Max) if in.Step != nil && *in.Step > 0 { step = *in.Step } + declaredDefault = in.Default + switch c.Thermal.Strategy { + case thermal.InfluenceSetpoint: + lo, hi = math.Max(lo, *in.Min), math.Min(hi, *in.Max) + case thermal.InfluenceCurveOffset: + if zc.CurveEffect == nil { + return heatplan.Actuator{}, nil, fmt.Errorf("%s is a curve offset; the zone needs curve_effect", zc.Control) + } + act.Strategy = thermal.InfluenceCurveOffset + act.ZoneKPerUnit, act.SupplyKPerUnit = zc.CurveEffect.ZoneKPerUnit, zc.CurveEffect.SupplyKPerUnit + lo, hi = *in.Min, *in.Max + default: + return heatplan.Actuator{}, nil, fmt.Errorf("%s is %s; only setpoints and curve offsets are planned yet", zc.Control, c.Thermal.Strategy) + } } - values := candidates(lo, hi, step) - if len(values) == 0 { + act.Values = candidates(lo, hi, step) + if len(act.Values) == 0 { return heatplan.Actuator{}, nil, errors.New("the control can reach nothing inside the band") } - neutral := values[0] - for _, v := range values { - if math.Abs(v-zc.TargetC) < math.Abs(neutral-zc.TargetC) { + // The device's own value: its declared default, or for a setpoint the + // step nearest the target, for an offset the step nearest zero. + aim := zc.TargetC + if act.Strategy == thermal.InfluenceCurveOffset { + aim = 0 + } + if declaredDefault != nil { + aim = *declaredDefault + } + neutral := act.Values[0] + for _, v := range act.Values { + if math.Abs(v-aim) < math.Abs(neutral-aim) { neutral = v } } - return heatplan.Actuator{ - Strategy: thermal.InfluenceSetpoint, - Values: values, - MaxHeatKW: zc.HeatKW, - Source: heatplan.Source{Kind: heatplan.SourceDirectElectric}, - }, &neutral, nil + return act, &neutral, nil } // candidates are the control's steps from lo to hi, at most 16; a fine step diff --git a/go/internal/heatrun/service_test.go b/go/internal/heatrun/service_test.go index 44dcf395f..460cdb81b 100644 --- a/go/internal/heatrun/service_test.go +++ b/go/internal/heatrun/service_test.go @@ -339,3 +339,67 @@ func TestShortDeviceHoldIsRenewedBetweenPlans(t *testing.T) { t.Fatalf("a stale meter did not hand the device back: %v", h.w.released) } } + +// The house heated by a CTC on a heat curve, its rooms read by an +// underfloor gateway: a heat pump zone planned on the outdoor forecast, in +// shadow, and through a curve offset once the pump declares one. +func heatPumpHouse(h *house, outdoor bool) *Service { + h.cfg = &config.Heat{Zones: []config.HeatZone{{ + Name: "house", Sensor: "wiser_7/floor_temp_c", HeatInput: "CTC/space_heat_w", + Boundary: "outdoor", Source: "heat_pump", HeatKW: 6, + TargetC: 21, MinC: 20, MaxC: 22.5, ComfortWeight: 2, + HeatPump: &config.HeatPump{Supply: &config.HeatSupplyCurve{ColdOutdoorC: -20, ColdSupplyC: 45, MildOutdoorC: 15, MildSupplyC: 24}}, + }}} + h.floor = 21 + s := h.service() + s.in.Twins = func() []thermaltwin.ZoneStatus { + return []thermaltwin.ZoneStatus{{Zone: thermaltwin.Zone{Key: "wiser_7/floor_temp_c"}, Status: h.status, + Params: thermaltwin.Params{TauH: fp(60), CapacityKWhPerK: fp(5)}}} + } + if outdoor { + s.in.Outdoor = func(_ time.Time, n int) ([]float64, bool) { return constant(n, 0), true } + } + return s +} + +func TestHeatPumpZoneNeedsTheForecastAndPlansWithIt(t *testing.T) { + h := newHouse() + s := heatPumpHouse(h, false) + s.Tick(context.Background()) + if z := s.Snapshot().Zones[0]; z.Planned || !strings.Contains(z.Reason, "outdoor forecast") { + t.Fatalf("without a forecast: planned %v, %q", z.Planned, z.Reason) + } + h = newHouse() + s = heatPumpHouse(h, true) + s.Tick(context.Background()) + if z := s.Snapshot().Zones[0]; !z.Planned || z.Value == nil { + t.Fatalf("with a forecast: %+v", z) + } +} + +func TestCurveOffsetIsPlannedOnlyWithItsEffect(t *testing.T) { + h := newHouse() + s := heatPumpHouse(h, true) + h.cfg.Zones[0].Control = "CTC/set_heat_curve_offset" + s.in.Control = func(driver, control string) (drivers.CatalogControl, bool) { + return drivers.CatalogControl{ID: control, + Input: drivers.CatalogControlInput{Type: "number", Min: fp(-5), Max: fp(5), Step: fp(1), Default: fp(0)}, + Thermal: &drivers.CatalogThermalControl{Asset: thermal.AssetSpaceHeat, Strategy: thermal.InfluenceCurveOffset}, + }, true + } + s.Tick(context.Background()) + if z := s.Snapshot().Zones[0]; z.Planned || !strings.Contains(z.Reason, "curve_effect") { + t.Fatalf("without an effect: planned %v, %q", z.Planned, z.Reason) + } + h.cfg.Zones[0].CurveEffect = &config.CurveEffect{ZoneKPerUnit: 0.5, SupplyKPerUnit: 1} + s.Tick(context.Background()) + z := s.Snapshot().Zones[0] + if !z.Planned || z.Neutral == nil || *z.Neutral != 0 { + t.Fatalf("with an effect: %+v", z) + } + for _, sl := range z.Slots { + if sl.Value < -5 || sl.Value > 5 { + t.Fatalf("offset %v outside the declared range", sl.Value) + } + } +} From d3db7f0f8b287efb906a07df039035db60629819 Mon Sep 17 00:00:00 2001 From: hannesb90 <279736760+hannesb90@users.noreply.github.com> Date: Tue, 17 Nov 2026 17:21:16 +0100 Subject: [PATCH 7/8] test(site): watch heatplan, which config now imports Co-Authored-By: Claude Opus 5.5 Signed-off-by: hannesb90 <279736760+hannesb90@users.noreply.github.com> --- go/test/site/runner/runner.go | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/go/test/site/runner/runner.go b/go/test/site/runner/runner.go index 821a8f3fc..3650fdb06 100644 --- a/go/test/site/runner/runner.go +++ b/go/test/site/runner/runner.go @@ -28,7 +28,8 @@ var watchedPaths = []string{ "go/internal/units/", // charge steps "go/internal/localzone/", // household clock: goal deadlines, import hour "go/internal/cars/", "go/internal/sitepower/", - "go/internal/thermal/", // control heat effects, imported by drivers + "go/internal/thermal/", // control heat effects, imported by drivers + "go/internal/heatplan/", // the owner's heat rules, imported by config "go/internal/events/", "go/internal/state/", "drivers/", "optimizer/native/bundle/", // bundled drivers and solver "go/test/site/", From 61ce7caf3cb89803428824d62275bd92a63f094c Mon Sep 17 00:00:00 2001 From: hannesb90 <279736760+hannesb90@users.noreply.github.com> Date: Wed, 18 Nov 2026 09:18:20 +0100 Subject: [PATCH 8/8] test(heat): the API and the heat control hold devices through one set 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 Signed-off-by: hannesb90 <279736760+hannesb90@users.noreply.github.com> --- go/cmd/ftw/heat_holds_wiring_test.go | 82 ++++++++++++++++++++ go/internal/api/api_heat_holds_test.go | 102 +++++++++++++++++++++++++ 2 files changed, 184 insertions(+) create mode 100644 go/cmd/ftw/heat_holds_wiring_test.go create mode 100644 go/internal/api/api_heat_holds_test.go diff --git a/go/cmd/ftw/heat_holds_wiring_test.go b/go/cmd/ftw/heat_holds_wiring_test.go new file mode 100644 index 000000000..22f19c724 --- /dev/null +++ b/go/cmd/ftw/heat_holds_wiring_test.go @@ -0,0 +1,82 @@ +package main + +import ( + "go/ast" + "go/parser" + "go/token" + "testing" +) + +// The heat control and the API must hold devices through one +// drivercontrol.Holds. If main handed the API none, the API would build its +// own, and an operator's hold and a planned value would sit on two locks: +// each would think the driver free and could expire into a default that +// undoes the other. main.go is read rather than run because building the +// whole process here would test everything but this. +func TestMainHandsTheHeatControlAndTheAPIOneSetOfHolds(t *testing.T) { + fset := token.NewFileSet() + file, err := parser.ParseFile(fset, "main.go", nil, 0) + if err != nil { + t.Fatal(err) + } + + var made []string // identifiers assigned from drivercontrol.New + heatHolds, apiHolds := "", "" + ast.Inspect(file, func(n ast.Node) bool { + switch n := n.(type) { + case *ast.AssignStmt: + for i, rhs := range n.Rhs { + call, ok := rhs.(*ast.CallExpr) + if !ok || !isSelector(call.Fun, "drivercontrol", "New") || i >= len(n.Lhs) { + continue + } + if id, ok := n.Lhs[i].(*ast.Ident); ok { + made = append(made, id.Name) + } + } + case *ast.CompositeLit: + switch { + case isSelector(n.Type, "heatrun", "HoldsWriter"): + heatHolds = fieldIdent(n, "Holds") + case isSelector(n.Type, "api", "Deps"): + apiHolds = fieldIdent(n, "ControlHolds") + } + } + return true + }) + + if len(made) != 1 { + t.Fatalf("main.go makes %d sets of control holds (%v), want 1", len(made), made) + } + if heatHolds != made[0] { + t.Errorf("heatrun.HoldsWriter{Holds: %q}, want %q", heatHolds, made[0]) + } + if apiHolds != made[0] { + t.Errorf("api.Deps{ControlHolds: %q}, want %q; without it the API builds its own", apiHolds, made[0]) + } +} + +func isSelector(e ast.Expr, pkg, name string) bool { + sel, ok := e.(*ast.SelectorExpr) + if !ok || sel.Sel.Name != name { + return false + } + id, ok := sel.X.(*ast.Ident) + return ok && id.Name == pkg +} + +// fieldIdent is the identifier a keyed composite literal sets field to, or "". +func fieldIdent(lit *ast.CompositeLit, field string) string { + for _, elt := range lit.Elts { + kv, ok := elt.(*ast.KeyValueExpr) + if !ok { + continue + } + if key, ok := kv.Key.(*ast.Ident); ok && key.Name == field { + if v, ok := kv.Value.(*ast.Ident); ok { + return v.Name + } + } + } + return "" +} diff --git a/go/internal/api/api_heat_holds_test.go b/go/internal/api/api_heat_holds_test.go new file mode 100644 index 000000000..529bb1bd6 --- /dev/null +++ b/go/internal/api/api_heat_holds_test.go @@ -0,0 +1,102 @@ +package api + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "os" + "path/filepath" + "sync" + "testing" + "time" + + "github.com/srcfl/ftw/go/internal/config" + "github.com/srcfl/ftw/go/internal/drivercontrol" + "github.com/srcfl/ftw/go/internal/drivers" + "github.com/srcfl/ftw/go/internal/heatrun" + "github.com/srcfl/ftw/go/internal/telemetry" +) + +// sharedHoldsServer is controlServer with the holds handed in, the way main +// hands the same holds to the API and to the heat control. +func sharedHoldsServer(t *testing.T) (*Server, *drivercontrol.Holds, *telemetry.Store) { + t.Helper() + dir := t.TempDir() + lua := filepath.Join(dir, "probe.lua") + if err := os.WriteFile(lua, []byte(controlProbeLua), 0o600); err != nil { + t.Fatal(err) + } + tel := telemetry.NewStore() + reg := drivers.NewRegistry(tel) + cfg := config.Driver{Name: "heat", Lua: lua} + if err := reg.Add(context.Background(), cfg); err != nil { + t.Fatalf("add driver: %v", err) + } + t.Cleanup(reg.ShutdownAll) + holds := drivercontrol.New(func() drivercontrol.Registry { return reg }) + srv := New(&Deps{ + Tel: tel, + Registry: reg, + Cfg: &config.Config{Drivers: []config.Driver{cfg}}, + CfgMu: &sync.RWMutex{}, + DriverDir: dir, + ConfigPath: filepath.Join(dir, "config.yaml"), + ControlHolds: holds, + }) + return srv, holds, tel +} + +// With one set of holds, an operator's hold is the heat control's to see and +// leave alone, and a planned value is the operator's to see and release. Two +// sets would each think the driver free and expire into a default that +// undoes the other. +func TestTheAPIAndTheHeatControlShareOneHold(t *testing.T) { + srv, holds, tel := sharedHoldsServer(t) + if srv.controlHolds != holds { + t.Fatal("the API built its own holds instead of using the ones it was given") + } + heat := heatrun.HoldsWriter{Holds: holds} + + if rec := post(t, srv, "/api/drivers/heat/control", + `{"control":"set_offset","value":2,"duration_s":600}`); rec.Code != http.StatusOK { + t.Fatalf("operator POST = %d, body %s", rec.Code, rec.Body.String()) + } + if control, _, ok := heat.Active("heat"); !ok || control != "set_offset" { + t.Fatalf("heat control sees hold %q %v, want the operator's set_offset", control, ok) + } + if rec := del(t, srv, "/api/drivers/heat/control"); rec.Code != http.StatusOK { + t.Fatalf("operator DELETE = %d", rec.Code) + } + waitMetric(t, tel, "heat", "defaulted", 1) + if _, _, ok := heat.Active("heat"); ok { + t.Fatal("the operator released, the heat control still sees a hold") + } + + if _, err := heat.Hold(context.Background(), "heat", "set_offset", 1, 10*time.Minute); err != nil { + t.Fatalf("planned hold: %v", err) + } + rec := httptest.NewRecorder() + srv.Handler().ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/api/drivers/heat", nil)) + var detail driverDetailResp + if err := json.Unmarshal(rec.Body.Bytes(), &detail); err != nil { + t.Fatal(err) + } + if detail.Hold == nil || detail.Hold.Control != "set_offset" { + t.Fatalf("the API shows hold %+v, want the planned set_offset", detail.Hold) + } + if rec := del(t, srv, "/api/drivers/heat/control"); rec.Code != http.StatusOK { + t.Fatalf("operator DELETE of a planned hold = %d", rec.Code) + } + waitMetric(t, tel, "heat", "defaulted", 2) + if _, _, ok := heat.Active("heat"); ok { + t.Fatal("the operator released a planned hold, it is still armed") + } +} + +func del(t *testing.T, srv *Server, path string) *httptest.ResponseRecorder { + t.Helper() + rec := httptest.NewRecorder() + srv.Handler().ServeHTTP(rec, httptest.NewRequest(http.MethodDelete, path, nil)) + return rec +}