# 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..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 /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..occupied, person..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..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..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:") 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)