Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/thermal-twin-shadow.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"ftw": patch
---

FTW now learns a thermal twin, in shadow, for each room sensor a driver declares (`sensors` with `asset = "space_heat"`). Every 30 minutes it fits the room's inertia, heat capacity, heat loss and other gains from the room temperature, the outdoor temperature and the heat pump's `hp_power_w`, and checks itself by predicting three hours ahead against what the sensor then measured. `GET /api/thermal/twins` shows each twin as learning, unproven, trusted or drifting, or says it has no heat input to learn from. A twin is trusted only when its error is small, it beats assuming the temperature stays as it is, and the heat input varied enough to learn from; a room a thermostat holds still stays unproven. `hp_power_w` is the pump's whole electrical power, so hot-water charging and defrost count as room heat until a driver can report space heat alone. A twin is deleted when its sensor is no longer declared. The twin commands nothing, and nothing plans from it yet.
28 changes: 28 additions & 0 deletions go/cmd/ftw/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,7 @@ import (
"github.com/srcfl/ftw/go/internal/selfupdate"
"github.com/srcfl/ftw/go/internal/state"
"github.com/srcfl/ftw/go/internal/telemetry"
"github.com/srcfl/ftw/go/internal/thermaltwin"
"github.com/srcfl/ftw/go/protocol/cloudwire"
)

Expand Down Expand Up @@ -1064,6 +1065,9 @@ func main() {
// the telemetry store + state DB are wired. Closure capture
// works because Go closes over the variable, not its value.
var loadSvc *loadmodel.Service
// Likewise constructed further down; the applier hands it the zones a
// changed configuration or driver catalog declares.
var thermalTwins *thermaltwin.Service

// Caller holds forecastConfigMu for a live transition. Keep persisted state
// intact during a short unconfirmed startup; only confirmed live bindings
Expand Down Expand Up @@ -1193,6 +1197,9 @@ func main() {
}
observeOnly = config.ObserveOnlyDriverSet(newCfg)
capMu.Unlock()
if thermalTwins != nil {
thermalTwins.SetZones(thermalTwinZones(newCfg.Drivers, reloadCatalog))
}
warnIfEVHasBatteryCapacity(newCfg.Drivers, newCfg.Loadpoints, reloadCatalog)

// Swap inverter-group tags (#143) and per-driver power
Expand Down Expand Up @@ -1468,6 +1475,26 @@ func main() {
defer loadSvc.Stop()
slog.Info("loadmodel started", "peak_w", loadPeakW, "quality", loadSvc.Model().Quality())

// ---- Thermal twins, shadow only (docs/adr/0012) ----
// Learns each declared room sensor's inertia and heat response from the
// same outdoor temperature as the load model. It reads and stores, and
// nothing plans or dispatches from it.
//
// The zones come from the catalog already loaded for the drivers, here
// and again whenever a saved configuration reloads it, so the service
// reads no driver file itself.
twinDrivers := func() []config.Driver {
cfgMu.RLock()
defer cfgMu.RUnlock()
return append([]config.Driver(nil), cfg.Drivers...)
}
thermalTwins = thermaltwin.NewService(st, tel)
thermalTwins.Temp = loadSvc.Temp
thermalTwins.SetZones(thermalTwinZones(twinDrivers(), driverCatalog))
thermalTwins.PowerDrivers = func() []string { return thermalTwinPowerDrivers(twinDrivers()) }
thermalTwins.Start(ctx)
defer thermalTwins.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
Expand Down Expand Up @@ -2598,6 +2625,7 @@ func main() {
PlannerPrefs: plannerPrefs,
PVModel: pvSvc,
LoadModel: loadSvc,
ThermalTwin: thermalTwins,
ForecastLearning: forecastTrackerSvc,
Loadpoints: lpMgr,
Cars: carsRT,
Expand Down
56 changes: 56 additions & 0 deletions go/cmd/ftw/thermal_twin.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
package main

import (
"sort"

"github.com/srcfl/ftw/go/internal/config"
"github.com/srcfl/ftw/go/internal/drivers"
"github.com/srcfl/ftw/go/internal/thermal"
"github.com/srcfl/ftw/go/internal/thermaltwin"
)

// thermalTwinZones lists one shadow twin zone per room sensor an enabled
// driver declares. Only space heat for now: a tank or buffer has the same
// form but loses heat to the room it stands in, not to outdoors, and the
// service has no such temperature yet.
//
// 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) {
var out []thermaltwin.Zone
complete = true
for _, d := range cfgDrivers {
if d.Disabled || d.Lua == "" {
continue
}
entry := drivers.EntryForDriver(catalog, d.Lua)
if entry == nil {
complete = false
continue
}
for _, s := range entry.Sensors {
if s.Asset != thermal.AssetSpaceHeat {
continue
}
out = append(out, thermaltwin.Zone{
Key: d.Name + "/" + s.Metric,
SensorDriver: d.Name,
SensorMetric: s.Metric,
})
}
}
sort.Slice(out, func(i, j int) bool { return out[i].Key < out[j].Key })
return out, complete
}

// thermalTwinPowerDrivers lists the enabled drivers that may report heat
// pump power.
func thermalTwinPowerDrivers(cfgDrivers []config.Driver) []string {
var out []string
for _, d := range cfgDrivers {
if !d.Disabled {
out = append(out, d.Name)
}
}
return out
}
65 changes: 65 additions & 0 deletions go/cmd/ftw/thermal_twin_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
package main

import (
"os"
"path/filepath"
"reflect"
"testing"

"github.com/srcfl/ftw/go/internal/config"
"github.com/srcfl/ftw/go/internal/drivers"
"github.com/srcfl/ftw/go/internal/thermaltwin"
)

func TestThermalTwinZonesFromDeclaredSensors(t *testing.T) {
dir := t.TempDir()
write := func(name, body string) {
if err := os.WriteFile(filepath.Join(dir, name), []byte(body), 0o600); err != nil {
t.Fatal(err)
}
}
write("thermo.lua", `DRIVER = {
id = "thermo",
sensors = {
{ metric = "room_living_temp_c", asset = "space_heat", zone = "living" },
{ metric = "room_bed_temp_c", asset = "space_heat" },
{ metric = "tank_temp_c", asset = "dhw" },
},
}
`)
write("meter.lua", `DRIVER = { id = "meter" }
`)
catalog, err := drivers.LoadCatalog(dir)
if err != nil {
t.Fatal(err)
}
cfg := []config.Driver{
{Name: "wiser", Lua: filepath.Join(dir, "thermo.lua")},
{Name: "spare", Lua: filepath.Join(dir, "thermo.lua"), Disabled: true},
{Name: "grid", Lua: filepath.Join(dir, "meter.lua")},
}

got, complete := thermalTwinZones(cfg, catalog)
if !complete {
t.Error("complete = false with every enabled driver in the catalog")
}
want := []thermaltwin.Zone{
{Key: "wiser/room_bed_temp_c", SensorDriver: "wiser", SensorMetric: "room_bed_temp_c"},
{Key: "wiser/room_living_temp_c", SensorDriver: "wiser", SensorMetric: "room_living_temp_c"},
}
if !reflect.DeepEqual(got, want) {
t.Errorf("zones = %+v, want %+v (no tank, no disabled driver)", got, want)
}
// 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) {
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 {
t.Errorf("without a catalog: zones = %+v, complete = %v; want none, incomplete", got, complete)
}
if p := thermalTwinPowerDrivers(cfg); !reflect.DeepEqual(p, []string{"wiser", "grid"}) {
t.Errorf("power drivers = %v", p)
}
}
6 changes: 5 additions & 1 deletion go/internal/api/api.go
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,7 @@ import (
"github.com/srcfl/ftw/go/internal/selfupdate"
"github.com/srcfl/ftw/go/internal/state"
"github.com/srcfl/ftw/go/internal/telemetry"
"github.com/srcfl/ftw/go/internal/thermaltwin"
"github.com/srcfl/ftw/go/internal/units"
v2xpolicy "github.com/srcfl/ftw/go/internal/v2x"
"github.com/srcfl/ftw/go/protocol"
Expand Down Expand Up @@ -174,7 +175,9 @@ type Deps struct {
PVModel *pvmodel.Service

// Optional: load digital-twin self-learner.
LoadModel *loadmodel.Service
LoadModel *loadmodel.Service
// Optional: shadow thermal twins of declared room sensors.
ThermalTwin *thermaltwin.Service
ForecastLearning ForecastLearning

// Optional: EV loadpoint state consumed by the API and MPC.
Expand Down Expand Up @@ -544,6 +547,7 @@ func (s *Server) routes() {
s.handle("GET /api/pvmodel", Read, s.handlePVModel)
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("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)
Expand Down
1 change: 1 addition & 0 deletions go/internal/api/api_agent_catalog.go
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ 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/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"}},
Expand Down
23 changes: 23 additions & 0 deletions go/internal/api/api_thermal_twin.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
package api

import (
"net/http"

"github.com/srcfl/ftw/go/internal/thermaltwin"
)

// GET /api/thermal/twins — each declared room sensor's learned twin, in
// shadow. `shadow: true` is part of the answer, not decoration: nothing in
// Core plans or commands from these, and a reader must not infer that a
// trusted twin is steering anything.
func (s *Server) handleThermalTwins(w http.ResponseWriter, r *http.Request) {
twins := []thermaltwin.ZoneStatus{}
if s.deps.ThermalTwin != nil {
twins = s.deps.ThermalTwin.Snapshot()
}
writeJSON(w, http.StatusOK, map[string]any{
"shadow": true,
"enabled": s.deps.ThermalTwin != nil,
"twins": twins,
})
}
53 changes: 53 additions & 0 deletions go/internal/api/api_thermal_twin_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
package api

import (
"encoding/json"
"net/http"
"net/http/httptest"
"testing"
"time"

"github.com/srcfl/ftw/go/internal/thermaltwin"
)

type twinTele struct{}

func (twinTele) LatestMetric(string, string) (float64, time.Time, bool) { return 0, time.Time{}, false }

func getThermalTwins(t *testing.T, srv *Server) map[string]json.RawMessage {
t.Helper()
rec := httptest.NewRecorder()
srv.Handler().ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/api/thermal/twins", nil))
if rec.Code != http.StatusOK {
t.Fatalf("GET /api/thermal/twins = %d, body %s", rec.Code, rec.Body.String())
}
var got map[string]json.RawMessage
if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
t.Fatal(err)
}
return got
}

// Every answer says shadow, whether or not twins exist, so no reader can
// take a trusted twin for one that steers anything.
func TestThermalTwinsAreAlwaysMarkedShadow(t *testing.T) {
got := getThermalTwins(t, New(&Deps{}))
if string(got["shadow"]) != "true" || string(got["enabled"]) != "false" || string(got["twins"]) != "[]" {
t.Errorf("without a service = %v", got)
}

svc := thermaltwin.NewService(nil, twinTele{})
svc.SetZones([]thermaltwin.Zone{{Key: "wiser/room_temp_c", SensorDriver: "wiser", SensorMetric: "room_temp_c"}}, true)
svc.Tick(time.Now())
got = getThermalTwins(t, New(&Deps{ThermalTwin: svc}))
if string(got["shadow"]) != "true" || string(got["enabled"]) != "true" {
t.Errorf("with a service = %v", got)
}
var twins []thermaltwin.ZoneStatus
if err := json.Unmarshal(got["twins"], &twins); err != nil {
t.Fatal(err)
}
if len(twins) != 1 || twins[0].Key != "wiser/room_temp_c" || twins[0].Status != thermaltwin.StatusNoHeatInput {
t.Errorf("twins = %+v", twins)
}
}
8 changes: 8 additions & 0 deletions go/internal/state/store.go
Original file line number Diff line number Diff line change
Expand Up @@ -1293,6 +1293,14 @@ func (s *Store) SaveConfig(key, value string) error {
})
}

// DeleteConfig removes a config k/v. A missing key is not an error.
func (s *Store) DeleteConfig(key string) error {
return s.durableConfigWrite(func(tx *sql.Tx) error {
_, err := tx.Exec(`DELETE FROM config WHERE key = ?`, key)
return err
})
}

// LoadConfig returns the value for key, or ok=false if missing.
func (s *Store) LoadConfig(key string) (string, bool) {
var v string
Expand Down
22 changes: 22 additions & 0 deletions go/internal/state/store_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,28 @@ func TestTimeSeriesInternCacheIsPerStore(t *testing.T) {
}
}

func TestDeleteConfig(t *testing.T) {
s := freshStore(t)
if err := s.SaveConfig("thermaltwin/a", "1"); err != nil {
t.Fatal(err)
}
if err := s.SaveConfig("thermaltwin/b", "2"); err != nil {
t.Fatal(err)
}
if err := s.DeleteConfig("thermaltwin/a"); err != nil {
t.Fatal(err)
}
if _, ok := s.LoadConfig("thermaltwin/a"); ok {
t.Error("deleted key still loads")
}
if v, ok := s.LoadConfig("thermaltwin/b"); !ok || v != "2" {
t.Errorf("other key = %q ok=%v, want kept", v, ok)
}
if err := s.DeleteConfig("missing"); err != nil {
t.Errorf("deleting a missing key: %v", err)
}
}

func TestConfigRoundtrip(t *testing.T) {
s := freshStore(t)
if err := s.SaveConfig("mode", "self_consumption"); err != nil {
Expand Down
Loading
Loading