Files
cantabile-ha-addons/src/edge/cantabile_edge/controller.py
T

1025 lines
53 KiB
Python

# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
"""v1's control loop beside the telemetry: inputs -> plan -> actions.
every control_interval_s (15 min): the model state (inputs.py), a plan
from the optimiser in a subprocess with a time limit (optimizer.py),
published: to the link in every mode (ctb.site.<id>.plan, for the
console), to Home Assistant in advisory and auto (announce.py)
every minute: owner overrides; in auto the executor's actions through the
guard (executor.py, guard.py)
Modes: off, shadow (plan and publish, act on nothing),
advisory (also show the plan in Home Assistant), auto (act through the
guard). The configuration may only say off or shadow: a new site starts in
shadow; advisory and auto come only by command from the console (`mode`),
and are kept in <state dir>/mode.json across restarts. No mode acts on a
control without its consent.
Commands (from the console through the link, which checked the signature):
mode {"mode": "off|shadow|advisory|auto"}
control {"asset", "set", "level": "flexible|binding|emergency",
"until": unix time | "minutes": n, "why"?}
release {"asset"}: back to the plan
limits {"asset", "quantity", "level": "cloud|building|grid",
"floor"?, "limit"? (empty: none), "until"?}
building {"v", "id", "building", "level", "control", "value", "from",
"until", "why"}: the building's requests (building.py:
load_limit, shift_request, thermostat_cap, battery_plan; a
battery_plan also "schedule": "w0,w1,..." W per step and
"step_s": "900", the building's plan its battery follows)
preferences {"msg": JSON of preferences.apply_msg's {"set": {"item",
"value"}}, "level": "installer|operator", "by"}: an installer's or
Cantabile's setting within the owner's limits (preferences.py);
the owner's own come from Home Assistant and the panel
The owner's preferences (preferences.py): into every model state (a room's
schedule, a car's ready-by, a battery's reserve, the overrides), a plan at
once after a change (not held back by steady.py), their feedback and the
settings with the plan to the cloud (public_plan "preferences").
"""
import asyncio
import json
import logging
import os
import sys
import time
from . import inputs as inputs_mod
from .building import Building
from .bundles import Bundles
from . import comfort, shades, steady
from .evphases import EvPhases
from .executor import Executor, building_msg
from .gridorder import GridOrders
from .guard import Guard, changed_by
from .policy import Policy
from .preferences import Preferences
from .switchover import Switchover
from . import storefit as storefit_mod
from .storefit import StoreFit
from .inputs import Collector, History
from . import localml
log = logging.getLogger(__name__)
MODES = ("off", "shadow", "advisory", "auto")
class Mode:
def __init__(self, state_dir: str, default: str):
self.path, self.default = os.path.join(state_dir, "mode.json"), default
self.at, self.by = None, "" # when and by whom the kept mode was set
try:
with open(self.path) as f:
d = json.load(f)
m = d.get("mode")
self.current = m if m in MODES else default
if m in MODES:
self.at, self.by = d.get("at"), str(d.get("by") or "")
except (OSError, ValueError, AttributeError):
self.current = default
def set(self, mode: str, by: str):
tmp = self.path + ".tmp"
now = int(time.time())
with open(tmp, "w") as f:
json.dump({"mode": mode, "at": now, "by": by}, f)
os.replace(tmp, self.path)
self.current, self.at, self.by = mode, now, by
def source(self) -> str:
"""Where the mode in force comes from, in words (the startup log):
the console's command kept in mode.json, or the configuration."""
if self.at is None:
return "from the configuration"
when = time.strftime("%Y-%m-%d %H:%M UTC", time.gmtime(self.at)) if isinstance(self.at, (int, float)) else "?"
cfg = f"; the configuration says {self.default}" if self.default != self.current else ""
return f"set by {self.by or 'the console'} at {when}, kept in {self.path}{cfg}"
def __call__(self) -> str:
return self.current
class Controller:
def __init__(self, cfg, mapping, consent, sink, clock=time.time):
self.cfg, self.mapping, self.sink, self.clock = cfg, mapping, sink, clock
self.consent = consent
self.controls = mapping.controls
self.inputs = mapping.inputs
self.mode = Mode(cfg.state_dir, cfg.mode)
self.col = Collector()
self.history = History(os.path.join(cfg.state_dir, "history.json"))
self.bundles = Bundles(cfg.state_dir, cfg.site_id)
self.guard = Guard(self.controls, consent, self.mode, override_hold_s=cfg.override_hold_s,
min_switch_s=cfg.min_switch_s, max_actions_per_hour=cfg.max_actions_per_hour, clock=clock)
self.saved_limits = self._load_limits() # the console's (limits.json)
self.gridorders = GridOrders(cfg.state_dir, clock) # the grid operator's, from the EEBUS bridge (3q)
self.evphases = EvPhases(cfg.state_dir) # each charger's phase count and its source
# what the box learns of its stores: a battery's idle loss, a tank's draw, UA, legionella (storefit.py)
self.storefit = StoreFit(os.path.join(cfg.state_dir, "storefit.json"), clock)
self.guard.extra_limits = self.saved_limits
self.policy = Policy(cfg.state_dir, cfg.site_id, clock)
self.guard.policy = self.policy
# a thermostat that heats and cools: one of its two controls at a time
self.switchover = Switchover(cfg.state_dir)
self.guard.switchover = self.switchover
self.tz = "UTC"
self.switchover.update(self.controls, clock(), self.tz, None)
self.building = Building(cfg.state_dir, clock)
self.executor = Executor(self.controls, self.guard, self.col, self._publish, stale_s=cfg.plan_stale_s,
clock=clock, building=self.building)
self.executor.shade_moves = shades.Moves(cfg.state_dir) # what each shade was last moved for
# the household's tolerance learnt from its changes by hand (comfort.py, methods.md G5)
self.tolerance = comfort.Tolerance(cfg.state_dir)
self.executor.on_override = self._learn_override
self.col.observers.append(self._observe)
self.client = None
self.tz = "UTC"
self.location: dict = {} # the site's latitude and longitude (HA's configuration)
self.plan: dict | None = None
self.plan_error = ""
self.forecast: list[dict] = [] # the weather entity's hourly forecast
self.wake = asyncio.Event()
self.calm = False # the next plan is for a bundle only: the quarter under way stays
self.act_now = asyncio.Event() # a control, release or new plan: act at once
self.on_plan = [] # callbacks (the announcer) when a plan is made
self.received: list[dict] = [] # the last commands and bundles (shown in HA, announce.py)
self.on_received = [] # callbacks (the announcer) for each
self.prefs = Preferences(cfg.state_dir, clock) # the owner's preferences (preferences.py)
self.on_prefs = [] # callbacks (the announcer) when they change
try:
self.prefs.write_view(self.controls, self.mode())
except Exception as e:
log.warning("preferences view: %s", e)
# the box trains its own models (boxtrain.py, methods.md B10): its
# history, the nightly job, and its models for the planner (bundles.own)
self.boxml = None
if getattr(cfg, "train", True):
try:
from .boxtrain import BoxTraining
from .trainhist import Store
self.boxml = BoxTraining(cfg, Store(os.path.join(cfg.state_dir, "training.db")), self.bundles,
kinds=self.planned_kinds, clock=clock)
self.bundles.own = self.boxml
except Exception as e: # never stops the controller
log.warning("the box's own training is off: %s", e)
self.boxml = None
# -- Home Assistant ----------------------------------------------------
def outside_entity(self) -> str:
"""The outdoor temperature: the inputs' (outside_temp), else the
mapped outside.temp."""
if self.inputs.outside_temp:
return self.inputs.outside_temp
a = self.mapping.by_asset.get("outside.temp") if hasattr(self.mapping, "by_asset") else None
return a.entity if a else ""
def switch_sides(self) -> bool:
"""Heating or cooling for each thermostat that does both (switchover.py);
True when a side changed (plan again)."""
ent = self.outside_entity()
t_out = self.col.value(ent) if ent else None
return self.switchover.update(self.controls, self.clock(), self.tz, t_out)
def presence_entities(self) -> list[str]:
"""The presence sources (methods.md A1, B16): the inputs' presence
and the mapped presence assets (room.<r>.occupied, person.<slug>.home:
inputs.presence_asset), each once."""
out = list(getattr(self.inputs, "presence", None) or [])
for a in getattr(self.mapping, "assets", None) or []:
if inputs_mod.presence_asset(getattr(a, "asset", "")) and a.entity not in out:
out.append(a.entity)
return out
def entities(self) -> list[str]:
out = set(self.inputs.entities())
out.update(self.presence_entities())
if self.outside_entity() and any(c.switchover or c.kind == "cover" for c in self.controls):
out.add(self.outside_entity())
for c in self.controls:
out.update(c.entities.values())
if c.kind == "cover":
out.update(a.entity for a in self.room_assets(c) if a)
return sorted(out)
# -- shades ---------------------------------------------------------------
def room_assets(self, c) -> tuple:
"""A shade's room readings in the mapping: room.<area>.temp and
.setpoint (params.area), or None each."""
area = str(c.p("area") or "")
by = getattr(self.mapping, "by_asset", {}) or {}
return (by.get(f"room.{area}.temp"), by.get(f"room.{area}.setpoint")) if area else (None, None)
def _asset_value(self, a):
if a is None:
return None
return inputs_mod.number(self.col.attr(a.entity, a.attribute) if a.attribute else self.col.state(a.entity))
def shade_ctx(self) -> dict:
"""Per shade its room for the rules (shades.py): the temperature and
setpoint (its room's heating or cooling control, else the mapping's
room.<area>.temp and .setpoint) and the season (the room control's
kind, of a thermostat that does both its active side)."""
by_id = {c.id: c for c in self.controls}
out = {}
for c in self.controls:
if c.kind != "cover":
continue
ctx = {}
room = by_id.get(str(c.p("room") or ""))
if room is not None:
side = room
if room.switchover and not self.switchover.active(room):
side = next((o for o in self.controls if o.switchover and o.id != room.id
and o.entities.get("climate") == room.entities.get("climate")), room)
ctx["season"] = side.kind
st = inputs_mod.device_state(room, self.col, self.clock())
ctx["temp_c"], ctx["setpoint_c"] = st.get("temp_c"), st.get("target_c")
ta, sa = self.room_assets(c)
if ctx.get("temp_c") is None:
ctx["temp_c"] = self._asset_value(ta)
if ctx.get("setpoint_c") is None:
ctx["setpoint_c"] = self._asset_value(sa)
# what the agent last moved it for, while it is still there (shades.Moves)
moves = getattr(self.executor, "shade_moves", None)
if moves is not None and "cover" in c.entities:
ours = moves.ours(c.id, inputs_mod.cover_position(self.col, c.entities["cover"]))
if ours:
ctx["ours"] = ours
if self.guard.overridden(c.id):
# moved by hand: the plan keeps it there while the guard keeps off it (G3: the override wins)
ctx["held_until"] = self.guard._t(c.id).override_until
out[c.id] = ctx
return out
async def on_connect(self, client):
self.client = client
try:
cfg = await client.send("get_config")
self.tz = (cfg or {}).get("time_zone") or "UTC"
self.prefs.tz = self.tz
lat, lon = (cfg or {}).get("latitude"), (cfg or {}).get("longitude")
if isinstance(lat, (int, float)) and isinstance(lon, (int, float)):
self.location = {"latitude": float(lat), "longitude": float(lon)}
write_cell(self.cfg.state_dir, float(lat), float(lon))
except Exception as e:
log.warning("get_config: %s", e)
ids = self.entities()
if ids:
await client.subscribe_entities(ids, self.col.on_entities)
log.info("control: %d controls, %d inputs, mode %s", len(self.controls), len(ids), self.mode())
self.wake.set()
def _observe(self, eid: str, st: dict, now: float):
for c in self.controls:
if not self.switchover.active(c):
continue # the other control of the thermostat watches it
for role, ent in c.writable().items():
if ent != eid:
continue
if c.kind == "cover":
if st.get("s") in ("opening", "closing"):
return # still moving to what it was told
value = st["a"].get("current_position")
if value is None: # open and close only
value = {"open": 100.0, "closed": 0.0}.get(st.get("s"))
elif ent.startswith("climate."):
value = st["a"].get("temperature")
cmd = self.guard._t(c.id).commanded.get(ent)
if cmd and inputs_mod.number(cmd[1]) is None:
value = st.get("s") # the agent last set the mode
else:
value = st.get("s")
self.guard.observe(c.id, eid, value, now, by=changed_by(st.get("c")))
def planned_kinds(self) -> set[str]:
"""The kinds of the devices the box plans whose power is inside the
load (heating, cooling, EV): its base load is trained where any is
metered (inputs.controlled_power), as the planner uses it."""
if not (getattr(self.inputs, "controlled_power", None) or []):
return set()
return {c.kind for c in self.controls if c.kind in ("heating", "cooling", "ev", "dhw_tank")}
# -- plans ---------------------------------------------------------------
def owner_ratings(self):
"""The owner's ratings of each control's device (the panel's Devices
page: devices-specs.json, written by the Hub's devices tool) into
the controls (Control.rated, rated_device): a battery's capacity,
power and efficiency where the mapping and the device say none."""
try:
with open(os.path.join(self.cfg.state_dir, "devices-specs.json")) as f:
specs = json.load(f).get("devices") or {}
except (OSError, ValueError, AttributeError):
specs = {}
by = {}
for d in specs.values() if isinstance(specs, dict) else []:
if not isinstance(d, dict):
continue
for cid in d.get("controls") or []:
by.setdefault(cid, (d.get("ratings") or {}, str(d.get("name") or "")))
for c in self.controls:
c.rated, c.rated_device = by.get(c.id, ({}, ""))
def model_state(self) -> dict:
now = self.clock()
self.owner_ratings()
start = int(now // inputs_mod.STEP_S * inputs_mod.STEP_S)
# sealed devices are not planned at all
# and of a thermostat that heats and cools only its active side
self.switch_sides()
controls = [c for c in self.controls if self.policy.plannable(c) and self.switchover.active(c)]
state = inputs_mod.model_state(now, controls, self.inputs, self.col, self.bundles,
self.history, self.tz, self.forecast, self.guard.extra_limits,
building=self.building.for_model(start, inputs_mod.STEP_S, inputs_mod.STEPS),
location=self.location, shade_ctx=self.shade_ctx(),
grid_order=self.gridorders.for_model(start, inputs_mod.STEP_S, inputs_mod.STEPS),
grid_max_w=getattr(self.cfg, "grid_max_w", None),
ev_phases=self.ev_phases(), presence=self.presence_entities(),
storefit=self.storefit,
comfort_ctx={"mode": self.prefs.comfort_mode(), "tolerance": self.tolerance})
# the owner's preferences per step (preferences.py)
return self.prefs.apply(state, {c.id: c for c in controls}, self.col, now)
async def make_plan(self) -> dict | None:
self.forecast = []
if self.client is not None and self.inputs.weather:
try:
self.forecast = await self.client.weather_forecast(self.inputs.weather)
except Exception as e:
log.info("weather forecast: %s", e)
state = self.model_state()
cands, net_load = state.pop("_cands", None) or {}, state.pop("_net_load", None)
# a battery bound to a building whose plan lapsed (building.py, A9.4): self-consumption only; said once
bound = (state.get("building") or {}).get("battery_bound") or {}
lapsed = bool(bound.get("lapsed"))
if lapsed and not getattr(self, "_bind_lapsed", False):
log.warning("building %s: its battery plan ended %s UTC and was not renewed: the battery runs in "
"self-consumption only (no grid charging) until the next one", bound.get("building"),
time.strftime("%d %b %H:%M", time.gmtime(bound.get("until") or 0)))
self._bind_lapsed = lapsed
plan = await solve(state, self.cfg.solve_timeout_s)
if "error" in plan:
self.plan_error = plan["error"]
log.warning("no new plan: %s (the last one stays while fresh)", plan["error"])
return None
calm, self.calm = self.calm, False
if calm:
steady.carry_quarter(plan, self.plan, self.clock())
# what the plan does for each preference, and what each must costs
self.prefs.take_plan(plan, self.clock())
# changes that do not matter stay out of it (deadband, hold, gain: steady.py);
# the owner's preference changes are not held back
steady.stabilise(plan, state, [c for c in self.controls if c.id in plan.get("devices", {})], self.col,
self.guard.last_change, self.clock(), free=self.prefs.free())
self.prefs.write_view(self.controls, self.mode())
plan["mode"] = self.mode()
plan["id"] = f"{self.cfg.site_id[:8]}-{plan['made']}"
plan["model"] = self.bundles.model_id()
if self.boxml is not None:
try: # SQLite and numpy: in a worker thread, the loop goes on
ml = await asyncio.to_thread(self.ml_after_plan, state, plan, cands, net_load)
# upward only with the owner's share consent: without it the box
# trains for itself and nothing of it leaves (no forecasts, no errors)
if getattr(self.consent, "share", False):
plan["ml"] = ml
except Exception as e:
log.warning("the box's model figures: %s", e)
self.plan, self.plan_error = plan, ""
self.executor.plan = plan
self.executor.inputs_ok = self.inputs_fresh()
self.act_now.set() # carry out a new plan now
n = sum(len(v) for v in plan["devices"].values())
cost = (f"{plan['cost_eur']:.2f} EUR vs {plan['baseline_eur']:.2f} EUR baseline"
if plan.get("cost_eur") is not None and plan.get("baseline_eur") is not None else "no cost (no tariff)")
log.info("plan %s (%s, %.1f s): %d changes, %s; %s%s", plan["id"], plan["status"], plan["solve_s"], n, cost,
plan.get("price_note", ""),
"".join(f"; {k} not planned: {v['why']}" for k, v in (plan.get("refused") or {}).items()))
await self._publish("plan", self.public_plan(plan))
for cb in self.on_plan:
await cb(plan)
return plan
def public_plan(self, plan: dict) -> dict:
"""The agreed form (v1): the plan's steps per asset, cost, baseline."""
return {"v": 1, "id": plan["id"], "made": plan["made"], "start": plan["start"], "step_s": plan["step_s"],
"mode": plan["mode"], "devices": plan["devices"], "cost_eur": plan["cost_eur"],
"baseline_eur": plan["baseline_eur"], "status": plan["status"],
"prices": plan.get("price_note", ""), "model": plan.get("model", ""),
# without a tariff: priced false, cost and baseline null (U1); controls not
# planned and why (U2); absent from older agents
"priced": plan.get("priced", True), "refused": plan.get("refused", {}),
# what the plan assumed for want of a fact (e.g. battery.end_value_pct missing)
"notes": plan.get("notes", []),
# cost_eur by carrier (its heat outlook a fixed term: the heat no room model plans),
# the plan's CO2 and its basis (methods A2): absent from older agents
**{k: plan[k] for k in ("cost_parts", "heat_outlook", "co2_kg", "co2_basis", "storage") if k in plan},
# the saving by carrier and lever (plansplit.py; the console's Savings page): absent from older agents
**({"saving_parts": plan["saving_parts"]} if plan.get("saving_parts") else {}),
"sources": plan.get("sources", {}),
# for the building (shed_w/grid_w per step, 24 h): absent from older agents
"flex": plan.get("flex", {}),
# the energy picture per step, 24 h (optimizer.plan_series; the console's plan chart): absent from older agents
**({"series": plan["series"]} if plan.get("series") else {}),
# the market's contracts in the plan (shadow): planned kWh and saving vs the grid
"market": plan.get("market", []),
# the owner's preferences: per level who set what and when, the
# overrides, and per preference met or not and each must's cost;
# builtin: the agent's own targets where none is set
"preferences": self.prefs.public(self.controls, bool(self.presence_entities()),
(plan.get("sources") or {}).get("occupancy")),
# the box's own models (boxtrain.py): held-out and live errors per source,
# hourly the forecasts it planned on; absent from older agents
**({"ml": plan["ml"]} if plan.get("ml") else {})}
# -- the owner's preferences (preferences.py) -------------------------------
async def prefs_change(self, msg: dict, level: str, by: str) -> tuple[bool, str]:
"""A change of the preferences (Home Assistant's entities and the
panel: the owner's; the console: an installer's or operator's): a
plan with it at once (not held back: steady.py), shown in HA."""
ok, why = self.prefs.apply_msg(msg, {c.id: c for c in self.controls}, self.tz, level, by)
log.info("preferences (%s, %s): %s %s", by, level, "applied" if ok else "refused", why)
await self._prefs_changed()
return ok, why
async def _prefs_changed(self):
self.prefs.write_view(self.controls, self.mode())
self.wake.set()
for cb in self.on_prefs:
try:
await cb()
except Exception as e:
log.warning("preferences: %s", e)
async def _prefs_watch(self, stop):
"""The panel's changes (prefs-inbox/), and overrides that expire."""
while not stop.is_set():
try:
n = self.prefs.take_inbox({c.id: c for c in self.controls}, self.tz)
while self.prefs.outbox: # the owner's own tariff to the cloud (link op own_tariff)
await self._publish("own_tariff", self.prefs.outbox.pop(0))
if n or self.prefs.prune(self.clock()):
await self._prefs_changed()
except Exception as e:
log.warning("preferences: %s", e)
try:
await asyncio.wait_for(stop.wait(), PREFS_POLL_S)
except asyncio.TimeoutError:
pass
def ml_after_plan(self, state: dict, plan: dict, cands: dict, net_load) -> dict:
"""After a plan (in a worker thread): the weather the box forecast
with and each source's forecast kept for the training and the live
error (trainhist.py), and the figures for the plan's "ml"
(boxtrain.status), with, at most hourly, the forecasts it planned on:
the load (as planned: the base load where it plans devices), PV and
the member's net draw (the plan's import less export where it acts,
auto; else the metered load's forecast less PV) for the building."""
b, now, start = self.boxml, self.clock(), int(state["start"])
st = b.store
if self.forecast:
# with the wind in m/s where the weather entity says its unit (localml.ha_hours)
unit = self.col.attr(self.inputs.weather, "wind_speed_unit") if self.inputs.weather else None
st.put_weather("forecast", "ha", localml.ha_hours(self.forecast, unit), now)
m = self.bundles.model.get()
if isinstance(m, dict) and m.get("site") == self.cfg.site_id:
if m.get("weather"):
st.put_weather("forecast", "cloud", localml.cloud_hours(m["weather"]), m.get("issued"))
if m.get("weather_past"):
st.put_weather("observed", "cloud", localml.cloud_hours(m["weather_past"]), now)
for key, series in (("load", "plan"), ("pv", "pv")):
if cands.get(key):
b.record(series, start, cands[key], now)
for key, c in cands.items(): # the carriers' (occupancy): under their own names
if key not in ("load", "pv") and c:
b.record(key, start, c, now)
auto = plan.get("mode") == "auto"
net = (plan.get("flex") or {}).get("net_w") if auto else \
([round(lo - pv) for lo, pv in zip(net_load, state["pv_w"])] if net_load else None)
if net:
b.record("net", start, {"own": net, "week_mean": b.week_mean("net", start, len(net))}, now)
fsrc = (state.get("sources") or {}).get("forecast") or {}
ups = {k: {"start": start, "step_s": state["step_s"], "values": [round(float(v), 1) for v in state[f"{k}_w"]],
"source": (fsrc.get(k) or {}).get("source") or (state.get("sources") or {}).get(k, "")[:80]}
for k in ("load", "pv")}
ups["load"]["series"] = "base_load" if b.kinds() else "load"
if net:
ups["net"] = {"start": start, "step_s": state["step_s"], "values": [float(v) for v in net],
"source": "plan" if auto else "forecast"}
return b.status(now, ups)
def inputs_fresh(self) -> bool:
"""The plan's room temperatures and the battery's state have a value
(a sensor that stopped must not steer). HA marks a device that went
away unavailable; a value that holds steady is not stale (the clone,
2026-10-30: a room at 23.5 °C for hours and a full battery held every
control at its safe default), and HA sends no update for an
unchanged value, so its age says nothing."""
for c in self.controls:
# a battery without its state of charge is not planned (inputs.battery_refusal), the rest is
for role in ("temp",):
if role in c.entities and self.col.value(c.entities[role]) is None:
return False
return True
async def _publish(self, kind, data):
pub = getattr(self.sink, "publish", None)
if pub is not None:
await pub(kind, data)
def actuators(self) -> dict:
"""Per control what the agent wants it at now and from whom (plan,
cloud: a hand control from the console, building, owner: an override
by hand that holds, safe default), whether it acts (auto and the
control's consent), and the limits in force per level and quantity
with the effective bounds. Shown in HA (announce.py)."""
now = self.clock()
out = {}
for c in self.controls:
want, level, why = self.executor.wanted(c, now)
if self.guard.overridden(c.id):
source = "owner"
elif why.startswith("building"):
source = "building"
elif level in ("flexible", "binding", "emergency") and c.id in self.executor.commands:
source = "cloud"
elif why.startswith("safe default"):
source = "safe default"
else:
source = "plan"
extra = self.guard.extra_limits.get(c.id) or {}
lims = {}
for q in set(c.limits) | set(extra):
layers = {**c.limits.get(q, {}), **extra.get(q, {})}
b = c.bounds(q, extra)
lims[q] = {"levels": {lvl: list(v) for lvl, v in layers.items()},
"effective": [b.lo, b.hi], "floor_by": b.lo_by, "limit_by": b.hi_by}
value = want.get("set") if isinstance(want, dict) else want
active = self.switchover.active(c)
attrs = {"source": source, "level": level, "why": why, "limits": lims,
"acting": self.mode() == "auto" and bool(c.consent) and active, "kind": c.kind}
if c.switchover:
attrs["switchover"] = dict(c.switchover, active=active)
if isinstance(want, dict) and "grid" in want:
attrs["charge_from_grid"] = bool(want["grid"])
out[c.id] = {"value": value, **attrs}
return out
# -- loops ---------------------------------------------------------------
async def run(self, stop: asyncio.Event):
if not self.controls:
log.info("control: no controls in the mapping (v3): nothing to plan")
await stop.wait()
return
tasks = [asyncio.create_task(self._planner(stop)), asyncio.create_task(self._actor(stop)),
asyncio.create_task(self._bundle_watch(stop)), asyncio.create_task(self._prefs_watch(stop))]
if self.boxml is not None:
# the nightly training (boxtrain.py): child processes, the loop only awaits them
tasks.append(asyncio.create_task(self.boxml.run(
stop, tz=lambda: self.tz, location=lambda: self.location, client=lambda: self.client,
weather_entity=lambda: self.inputs.weather or "")))
await stop.wait()
await asyncio.gather(*tasks, return_exceptions=True)
async def _bundle_watch(self, stop):
"""A new tariff or model (the link writes them) plans again at once,
not at the next 15-minute plan (a test run priced a plan made one
second before the tariff came with the old one)."""
last = self.bundles.stamps()
while not stop.is_set():
try:
await asyncio.wait_for(stop.wait(), self.cfg.bundle_poll_s)
except asyncio.TimeoutError:
pass
now = self.bundles.stamps()
if now != last:
for kind, a, b in zip(("tariff", "model"), last, now):
if a != b and b is not None:
f = self.bundles.tariff if kind == "tariff" else self.bundles.model
d = f.get() or {}
await self._received(kind, {"id": d.get("id", "")}, "cloud",
d != {}, f.error or "stored")
last = now
log.info("plan: a new tariff or model: planning again")
self.calm = True # nothing urgent: from the next quarter (steady.carry_quarter)
self.wake.set()
async def _planner(self, stop):
woken = False
while not stop.is_set():
if woken and self.cfg.replan_debounce_s > 0:
# several changes often come together (mode, limits, a
# tariff): one plan after a short pause, not one each
try:
await asyncio.wait_for(stop.wait(), self.cfg.replan_debounce_s)
except asyncio.TimeoutError:
pass
if self.mode() != "off" and self.client is not None:
try:
await self.make_plan()
except Exception as e:
# with its traceback: where it failed (the message alone did not say)
log.warning("plan: %s", e, exc_info=True)
self.wake.clear()
woken = False
try:
await asyncio.wait_for(asyncio.wait([asyncio.ensure_future(stop.wait()),
asyncio.ensure_future(self.wake.wait())],
return_when=asyncio.FIRST_COMPLETED),
plan_wait(self.clock(), self.cfg.control_interval_s))
woken = self.wake.is_set()
except asyncio.TimeoutError:
pass
async def _actor(self, stop):
while not stop.is_set():
now = self.clock()
self.history.add("load_w", inputs_mod.base_load(self.col, self.inputs), now)
self.history.add("pv_w", self.col.total(self.inputs.pv_power), now)
try:
self.sample_climate(now)
except Exception as e: # never stops the actions
log.warning("climate history: %s", e)
if self.sample_ev_phases(now) and self.gridorders.active():
self._merge_limits() # a learned count: the order's current bound again
try:
self.sample_stores(now)
except Exception as e: # never stops the actions
log.warning("stores: %s", e)
if int(now) % 900 < 60:
try:
self.history.save(now)
except OSError as e:
log.warning("history: %s", e)
self.executor.inputs_ok = self.inputs_fresh()
self.grid_tick()
try:
await self.grid_report()
except Exception as e:
log.warning("grid order report: %s", e)
if self.switch_sides():
self.wake.set() # heating <-> cooling: a plan for the new side
try:
await self.executor.tick(self.client, self.mode() == "auto")
except Exception as e:
log.warning("actions: %s", e)
self.act_now.clear()
try:
await asyncio.wait_for(asyncio.wait([asyncio.ensure_future(stop.wait()),
asyncio.ensure_future(self.act_now.wait())],
return_when=asyncio.FIRST_COMPLETED),
self.cfg.act_interval_s)
except asyncio.TimeoutError:
pass
# -- commands ------------------------------------------------------------
async def command(self, cmd: str, args: dict) -> tuple[bool, str]:
ok, why = await self._command(cmd, args)
await self._received(cmd, args, sender(cmd, args), ok, why)
return ok, why
async def _received(self, cmd: str, args: dict, by: str, ok: bool, why: str):
ev = {"at": int(self.clock()), "cmd": cmd, "by": by, "args": public_args(args),
"result": "applied" if ok else "refused", "why": why}
self.received = (self.received + [ev])[-50:]
for cb in self.on_received:
try:
await cb(ev)
except Exception as e:
log.warning("received: %s", e)
async def _command(self, cmd: str, args: dict) -> tuple[bool, str]:
now = self.clock()
if cmd == "mode":
m = args.get("mode", "")
if m not in MODES:
return False, f"mode: one of {', '.join(MODES)}"
self.mode.set(m, args.get("by", "console"))
log.info("mode %s (console)", m)
self.wake.set() # a plan in the new mode now
if m in ("advisory", "auto") and not any(c.consent for c in self.controls):
return True, f"mode {m}; note: no control has consent, nothing will be acted on"
return True, f"mode {m}"
if cmd == "control":
ok, msg = self.executor.command(args, now)
if ok:
self.act_now.set()
return ok, msg
if cmd == "release":
ok, msg = self.executor.release(args.get("asset", ""))
if ok:
self.act_now.set() # back to the plan now, not at the next round
return ok, msg
if cmd == "limits":
ok, msg = self.set_limit(args, now)
if ok:
self.wake.set() # a plan within the new limits now
return ok, msg
if cmd == "building":
return await self.building_command(args, now)
if cmd == "preferences":
# the console's: an installer's or Cantabile's, within the owner's limits
level = args.get("level", "")
if level not in ("installer", "operator"):
return False, "level: installer or operator (the owner's own come from Home Assistant or the panel)"
try:
msg = json.loads(args.get("msg") or "{}")
except ValueError:
return False, "msg: JSON"
if not isinstance(msg, dict) or "set" not in msg:
return False, "msg: {\"set\": {\"item\", \"value\"}} (overrides are the owner's)"
return await self.prefs_change(msg, level, f"{level}:{str(args.get('by') or 'console')[:60]}")
return False, f"unknown command {cmd!r}"
async def building_command(self, args: dict, now: float) -> tuple[bool, str]:
try:
c = Building.parse(args)
except ValueError as e:
return False, str(e)
floors = []
for ctl in self.controls:
if ctl.kind in ("heating", "cooling"):
b = ctl.bounds("temp_c", self.guard.extra_limits.get(ctl.id))
floors.append((ctl.id, b.lo, b.hi, ctl.kind))
ok, msg = self.building.take(c, floors)
await self._publish("action", building_msg(c, "done" if ok else "refused", msg if ok else msg, now))
if ok:
self.wake.set() # a plan with it now
return ok, msg
def set_limit(self, a: dict, now: float) -> tuple[bool, str]:
from .limits import QUANTITIES
c = {c.id: c for c in self.controls}.get(a.get("asset", ""))
if c is None:
return False, f"no control {a.get('asset')!r}"
q, lvl = a.get("quantity", ""), a.get("level", "")
if q not in QUANTITIES or lvl not in ("cloud", "building", "grid"):
return False, "quantity: one of " + ", ".join(QUANTITIES) + "; level: cloud, building or grid"
try:
f = float(a["floor"]) if a.get("floor") not in (None, "") else None
lim = float(a["limit"]) if a.get("limit") not in (None, "") else None
except ValueError:
return False, "floor and limit: numbers (or empty: none)"
if f is not None and lim is not None and f > lim:
return False, "floor above limit"
per = self.saved_limits.setdefault(c.id, {}).setdefault(q, {})
if f is None and lim is None:
per.pop(lvl, None)
else:
per[lvl] = (f, lim)
self._save_limits()
self._merge_limits()
b = c.bounds(q, self.guard.extra_limits.get(c.id))
self.wake.set()
return True, f"{c.id} {q}: {b.lo:g}..{b.hi:g} now (floor by {b.lo_by}, limit by {b.hi_by})"
def _load_limits(self) -> dict:
try:
with open(os.path.join(self.cfg.state_dir, "limits.json")) as f:
raw = json.load(f)
return {c: {q: {lvl: tuple(v) for lvl, v in lv.items()} for q, lv in qs.items()} for c, qs in raw.items()}
except (OSError, ValueError, AttributeError):
return {}
def _save_limits(self):
p = os.path.join(self.cfg.state_dir, "limits.json")
with open(p + ".tmp", "w") as f:
json.dump(self.saved_limits, f)
os.replace(p + ".tmp", p)
# -- the chargers' phases (evphases.py) ------------------------------------
def ev_phases(self) -> dict:
"""{control id: {"phases", "source", "plan", "order"}} for the EV controls."""
return self.evphases.all(self.controls, self.col)
def sample_ev_phases(self, now: float) -> bool:
"""A reading per charger for learning its phases: its power (its own
`power` sensor, else the site's ev.power where it is the only
charger) and current (measured, else its setpoint). True when a
learned count changed."""
evs = [c for c in self.controls if c.kind == "ev"]
site_ev = self.mapping.by_asset.get("ev.power") if len(evs) == 1 and hasattr(self.mapping, "by_asset") else None
changed = False
for c in evs:
pw = c.entities.get("power") or (site_ev.entity if site_ev else "")
cur = c.entities.get("current_measured") or c.entities.get("current") or ""
p = inputs_mod.watts(self.col, pw) if pw else None
a = self.col.value(cur) if cur else None
changed |= self.evphases.sample(c.id, p, a, float(c.p("voltage")), now)
return changed
def _learn_override(self, ev: dict):
"""A change by hand to a planned room's setpoint (the guard's
override): into the household's tolerance (comfort.Tolerance, G5).
Only a thermostat's setpoint against the plan's own (not a
command's)."""
c = next((x for x in self.controls if x.id == ev.get("control")), None)
if c is None or c.kind not in ("heating", "cooling") or ev.get("level", "plan") != "plan":
return
if ev.get("entity") != c.entities.get("climate"):
return
self.tolerance.record(c.id, c.kind, ev.get("agent_set"), ev.get("value"), ev.get("at") or self.clock())
# -- the climate's history: the comfort band's running mean, the flat's mass (G2, G5) ----
def sample_climate(self, now: float):
"""The outdoor temperature now ("t_out") and each heating or cooling
control's room temperature ("room:<id>") into the history (8 days):
the comfort band's running mean outdoor temperature (comfort.py) and
the flat's mass now (inputs.mass_start)."""
self.history.add("t_out", inputs_mod.outdoor_now(self.col, self.inputs), now)
for c in self.controls:
if c.kind in ("heating", "cooling"):
t = inputs_mod.device_state(c, self.col, now).get("temp_c")
if t is not None:
self.history.add(f"room:{c.id}", float(t), now)
# -- what the box learns of its stores (storefit.py) ---------------------------
def sample_stores(self, now: float):
"""A reading of each battery (its SoC, its own power, the PV, its
grid charging) and each tank (its mean temperature, the room, its
heater's heat) for the idle-loss fit, the tank's draw (S.7), UA and
legionella time; the fits once a day, saved each quarter-hour."""
bp = self.bundles.box_params(now) if hasattr(self.bundles, "box_params") else {}
caps = {}
bats = [c for c in self.controls if c.kind == "battery"]
for c in self.controls:
if c.kind == "battery":
e = c.entities
pw = inputs_mod.watts(self.col, e["power"]) if e.get("power") else None
if pw is None and len(bats) == 1 and hasattr(self.mapping, "by_asset"):
a = self.mapping.by_asset.get("battery.power")
pw = inputs_mod.watts(self.col, a.entity) if a else None
pv = self.col.total(self.inputs.pv_power) if self.inputs.pv_power else None
self.storefit.sample_battery(c.id, now, self.col.value(e.get("soc", "")), pw, pv,
self.col.state(e.get("charge_from_grid", "")) == "on")
f, _, _ = c.battery_facts()
if f.get("capacity_wh"):
caps[c.id] = f["capacity_wh"]
elif c.kind == "dhw_tank" and c.resolved:
st = inputs_mod.device_state(c, self.col, now)
f = c.resolved
temp = storefit_mod.mean_temp(st.get("temp_top"), st.get("temp_bottom"),
float(f.get("top_share") or 1.0))
room = st.get("room_c") if st.get("room_c") is not None else f.get("room_temp_c")
heat = st.get("heater_w")
if heat is not None and f.get("heater") == "heat_pump":
# its heat by its COP (a COP curve's is not known here: no heat, no draw then)
heat = heat * float(f["cop"]) if f.get("cop") else None
facts = dict(f, draw_detect_k=bp.get("dhw.draw_detect_k_per_15min"))
if room is not None:
self.storefit.sample_tank(c.id, now, temp, float(room), heat, facts)
if int(now) % 900 < 60:
self.storefit.fit_batteries(caps, bp, now)
for c in self.controls:
if c.kind == "dhw_tank" and c.resolved:
self.storefit.fit_tank(c.id, dict(c.resolved, label_ua_w_k=c.resolved.get("ua_w_k")), bp)
self.storefit.save()
# -- the grid operator's limit (EEBUS LPC, gridorder.py) -----------------
def _merge_limits(self):
"""The guard's limits: the console's, and over them the grid order's
at level grid (the lower limit of the two holds)."""
merged = {c: {q: dict(lv) for q, lv in qs.items()} for c, qs in self.saved_limits.items()}
phases = {cid: v["phases"] for cid, v in self.ev_phases().items()}
self._grid_connected = self.ev_connected()
for cid, qs in self.gridorders.limits(self.controls, phases, self._grid_connected).items():
for q, (f, lim) in qs.items():
per = merged.setdefault(cid, {}).setdefault(q, {})
old = per.get("grid")
if old and old[1] is not None and lim is not None:
lim = min(lim, old[1])
per["grid"] = (old[0] if old else f, lim)
self.guard.extra_limits = merged
async def grid_order(self, payload: bytes) -> bool:
"""A message on cantabile-eebus/gridorder (the announcer's MQTT
session): a changed order is a grid operator's decision: limits now,
a plan within them now, and shown to the owner like a command."""
changed, why = self.gridorders.take(payload)
if not changed:
return False
self._merge_limits()
o = self.gridorders.active()
args = {"level": "emergency", "control": "load_limit", "source": "eebus-lpc"}
if o:
args.update(id=o["id"], value=str(o["limit_w"]), until=str(o.get("until") or ""), state=o.get("state", ""),
proof=self.gridorders.proof())
log.warning("grid operator's limit %.0f W (%s, order %s): planning within it", o["limit_w"], o.get("state"), o["id"])
else:
args.update(value="", state="normal")
log.info("grid operator's limit ended")
await self._received("grid", args, "grid", True, "limited" if o else "ended")
await self.grid_report()
self.wake.set()
self.act_now.set()
return True
async def grid_report(self):
"""The order to the cloud as an action (gridorder.py action()): each
quarter-hour it holds, and its end."""
a = self.gridorders.action()
if a is not None:
await self._publish("action", a)
def ev_connected(self) -> dict:
"""Each charger's car: plugged in (True), not (False), unknown (None: no connected entity or no
state yet), for the order's shares (gridorder.limits)."""
out = {}
for c in self.controls:
if c.kind == "ev":
st = self.col.state(c.entities["connected"]) if "connected" in c.entities else None
out[c.id] = True if st == "on" else False if st == "off" else None
return out
def grid_tick(self):
"""An order that went stale or ended takes its limits away; while one holds, a car plugged in or out
gets its share again (the chargers share the one limit, gridorder.limits)."""
if self.gridorders.active() and self.ev_connected() != getattr(self, "_grid_connected", None):
self._merge_limits()
self.wake.set()
return
if self.gridorders.order and not self.gridorders.active() and any(
"grid" in lv for qs in self.guard.extra_limits.values() for lv in qs.values()) \
and not any("grid" in lv for qs in self.saved_limits.values() for lv in qs.values()):
self._merge_limits()
self.wake.set()
def sender(cmd: str, args: dict) -> str:
"""Who a command comes from, for the owner (HA): the building's requests
(a relayed grid order: the grid operator), limits at their level, the
rest from Cantabile's cloud (the console)."""
if cmd == "building":
return "grid" if args.get("level") == "emergency" else "building"
if cmd == "limits" and args.get("level") in ("building", "grid"):
return args["level"]
return "cloud"
def write_cell(state_dir: str, lat: float, lon: float) -> bool:
"""The site's weather cell (0.1°, ~10 km) for the link: site_cell.json
in the state directory; the heartbeat carries it to the cloud only with
the owner's share consent (edge/link). Written when it changed."""
cell = {"lat": round(lat, 1), "lon": round(lon, 1)}
path = os.path.join(state_dir, "site_cell.json")
try:
with open(path) as f:
if json.load(f) == cell:
return False
except (OSError, ValueError):
pass
try:
tmp = path + ".tmp"
with open(tmp, "w") as f:
json.dump(cell, f)
os.replace(tmp, path)
except OSError as e:
log.warning("site cell: %s", e)
return False
return True
SECRET_ARGS = ("proof", "sig", "bundle", "token", "password")
def public_args(args: dict) -> dict:
"""A command's arguments as HA may show them: no signatures, proofs or
bundles, short values."""
return {k: str(v)[:120] for k, v in (args or {}).items() if k not in SECRET_ARGS}
async def solve(state: dict, timeout: float) -> dict:
"""The optimiser in a subprocess: a bad model or a long solve never
stops the agent; past the timeout it is killed."""
proc = await asyncio.create_subprocess_exec(
sys.executable, "-m", "cantabile_edge.optimizer", str(max(5.0, timeout - 5)),
stdin=asyncio.subprocess.PIPE, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE)
try:
out, err = await asyncio.wait_for(proc.communicate(json.dumps(state).encode()), timeout)
except asyncio.TimeoutError:
proc.kill()
await proc.wait()
return {"error": f"the optimiser took longer than {timeout:g} s"}
try:
return json.loads(out)
except ValueError:
return {"error": (err.decode(errors="replace").strip().splitlines() or ["no output"])[-1][:300]}
PLAN_AT_S = 5.0 # a plan this long after a quarter hour: its first step is the quarter just begun
PREFS_POLL_S = 2.0 # how often the panel's preference changes are looked for
def plan_wait(now: float, interval: float, at: float = PLAN_AT_S) -> float:
"""Seconds to the next regular plan: just after the next boundary of
the interval (the quarter hours), not interval after the last plan. A
plan made mid-quarter takes the room as it is now for the quarter's
start, and its first step's setpoint differed from the plan before it
for that same quarter: a heat pump was set 20.5 at the quarter hour and
back to 20.0 when the next plan came 12 minutes later (sim-munich-1,
2026-11-03)."""
if interval <= 0:
return 0.0
nxt = (now - at) // interval * interval + interval + at
return max(1.0, nxt - now)