cantabile_edge, cantabile_modbus, cantabile_eebus 0.1.400: full source

This commit is contained in:
Setti Solutions S.R.L committed 2026-10-30 08:26:45 +02:00
1 parent 343331d234
commit d5fbcacaa4
176 files changed
+32511 -19

No files matched your search

+589
View File
@@ -0,0 +1,589 @@
# 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)
"""
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 .executor import Executor, building_msg
from .gridorder import GridOrders
from .guard import Guard
from .policy import Policy
from .switchover import Switchover
from .inputs import Collector, History
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
try:
with open(self.path) as f:
m = json.load(f).get("mode")
self.current = m if m in MODES else default
except (OSError, ValueError, AttributeError):
self.current = default
def set(self, mode: str, by: str):
tmp = self.path + ".tmp"
with open(tmp, "w") as f:
json.dump({"mode": mode, "at": int(time.time()), "by": by}, f)
os.replace(tmp, self.path)
self.current = mode
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.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, cfg.default_price_ct)
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.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.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.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
# -- 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 entities(self) -> list[str]:
out = set(self.inputs.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)
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"
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)}
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)
# -- plans ---------------------------------------------------------------
def model_state(self) -> dict:
now = self.clock()
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)]
return 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))
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()
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
plan["mode"] = self.mode()
plan["id"] = f"{self.cfg.site_id[:8]}-{plan['made']}"
plan["model"] = self.bundles.model_id()
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())
log.info("plan %s (%s, %.1f s): %d changes in 48 h, %.2f EUR vs %.2f EUR baseline; %s",
plan["id"], plan["status"], plan["solve_s"], n, plan["cost_eur"], plan["baseline_eur"],
plan.get("price_note", ""))
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", ""),
"sources": plan.get("sources", {}),
# for the building (shed_w/grid_w per step, 24 h): absent from older agents
"flex": plan.get("flex", {})}
def inputs_fresh(self) -> bool:
"""The plan's room temperatures and the battery's state are not older
than an hour (a sensor that stopped must not steer)."""
now = self.clock()
for c in self.controls:
for role in ("temp", "soc"):
if role in c.entities and self.col.age(c.entities[role], now) > 3600:
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))]
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.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:
log.warning("plan: %s", e)
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),
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", self.col.total(self.inputs.load_power), now)
self.history.add("pv_w", self.col.total(self.inputs.pv_power), now)
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()
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)
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 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()}
for cid, qs in self.gridorders.limits(self.controls).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")
self.wake.set()
self.act_now.set()
return True
def grid_tick(self):
"""An order that went stale or ended takes its limits away."""
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"
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]}