cantabile_edge, cantabile_modbus, cantabile_eebus 0.1.1789: full source

This commit is contained in:
Setti Solutions S.R.L committed 2026-11-12 06:28:42 +02:00
1 parent 94f46db8f8
commit b24675fe9c
25 files changed
+765 -39

No files matched your search

+1 -1
View File
@@ -22,7 +22,7 @@ Settings → Add-ons → Add-on store → ⋮ → Repositories, add
`https://git.setti.solutions/Daniel/cantabile-ha-addons`, then install the
add-on. The Supervisor pulls the prebuilt images
(`git.setti.solutions/daniel/cantabile-ha-<edge|modbus|eebus>-<arch>:<version>`,
named by `image:` in each `config.yaml`); this version: `0.1.1541`, arch amd64.
named by `image:` in each `config.yaml`); this version: `0.1.1789`, arch amd64.
## Layout
+16
View File
@@ -6,6 +6,22 @@ names the commit; the agent inside is the Edge Agent image of that commit.
## 0.1.x
- The grid operator's limit (§14a EnWG) is shared by your controllable
devices: wallboxes in turn, each its share, then a battery's charging and
a hot-water element with what is left; a wallbox is held to its share
even when no plan had commanded it. A limit the control box renews keeps
running from each renewal (Cantabile EEBUS).
- A meter's total that drops for a moment while Home Assistant restarts is
no longer counted as a reset (before, the whole total could appear as one
minute's use).
- The plan now carries its energy per carrier and use for the next 24 hours,
and says why a carrier saves nothing (no device to shift, a flat price).
- Overrides are reported: when you or a device change what the plan or a
limit set, the add-on reports who, until when and the plan's value.
- A building's battery plan holds after the add-on restarts.
- A hot-water store on a gas boiler uses the boiler's part-load curve where
its data sheet gives one.
- Invitations: when a building or an energy community invites your home,
the add-on's page shows the invitation with three buttons: Look at it
(what joining means for you), Join and Decline. Until now an invitation
+1 -1
View File
@@ -3,7 +3,7 @@
# the Hub's, wrapped by addon-run (Dockerfile). The image is prebuilt,
# per arch (README.md: building it from src/).
name: Cantabile Edge Agent
version: "0.1.1541"
version: "0.1.1789"
slug: cantabile_edge
description: Plans your home's energy with Cantabile and, with your consent, runs the devices you choose.
url: https://cantabile.cloud
+1 -1
View File
@@ -4,7 +4,7 @@
# Assistant that isn't a Cantabile Hub. Devices are paired on its page
# (ingress), by their SKI.
name: Cantabile EEBUS
version: "0.1.1541"
version: "0.1.1789"
slug: cantabile_eebus
description: Pairs with EEBUS devices (the grid operator's control box, heat pumps, wallboxes, inverters), shows them in Home Assistant under Cantabile's names and hands the grid operator's §14a limit to the Cantabile agent; every control with its protection.
url: https://cantabile.cloud
+1 -1
View File
@@ -4,7 +4,7 @@
# Home Assistant that isn't a Cantabile Hub. Devices come from the options;
# the page (ingress) shows them and each control's protection.
name: Cantabile Modbus bridge
version: "0.1.1541"
version: "0.1.1789"
slug: cantabile_modbus
description: Reads inverters, meters, relays and circuits by Cantabile's device profiles (Modbus, or Home Assistant's own entities) and shows them in Home Assistant, each control with its protection.
url: https://cantabile.cloud
+8
View File
@@ -92,6 +92,14 @@ class Building:
self.bound = b if isinstance(b, dict) and b.get("building") else None
except (OSError, ValueError, AttributeError):
pass
c = self.active.get("battery_plan")
if c and not self.bound:
# a plan taken by an agent before the binding existed (2026-11-09, the farm's upgrade to 0.1.0-dev.db2193861454:
# Berlin's and Durlach's plans of the night carried no binding, so A9.4b did not hold and the owner's 10 % floor
# was refilled from the grid against the building's 0 W): the plan in force binds as if taken now
self.bound = {"building": c["building"], "level": c.get("level", "binding"), "since": int(self.clock()),
"until": c["until"], "id": c["id"]}
self._save()
self.drop_ended()
def memberships(self) -> set[str] | None:
+22 -4
View File
@@ -51,7 +51,7 @@ from . import shades, steady
from .evphases import EvPhases
from .executor import Executor, building_msg
from .gridorder import GridOrders
from .guard import Guard
from .guard import Guard, changed_by
from .policy import Policy
from .preferences import Preferences
from .switchover import Switchover
@@ -284,7 +284,7 @@ class Controller:
value = st.get("s") # the agent last set the mode
else:
value = st.get("s")
self.guard.observe(c.id, eid, value, now)
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
@@ -411,6 +411,8 @@ class Controller:
"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
@@ -843,7 +845,8 @@ class Controller:
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()}
for cid, qs in self.gridorders.limits(self.controls, 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")
@@ -882,8 +885,23 @@ class Controller:
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."""
"""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()):
+5 -1
View File
@@ -205,7 +205,10 @@ PARAMS = {
# a hot-water tank's choices (its facts: FACTS, no default): the legionella run left to the
# device's own program unless the installer says "plan" (or "none"); a heating control whose
# compressor it shares; the SG-Ready select's option per state "1".."4"; anti-cycling as heating
"dhw_tank": {"legionella": "device", "shares_with": "", "sg_options": {}, "cop_curve": [],
# a boiler-heated tank: the burner's part load as a heating control's (boiler_type, part_load_curve: the data
# sheet's; inputs.tank_inputs passes them to the plan; 2026-11-09: refused as unknown before)
"dhw_tank": {"legionella": "device", "shares_with": "", "sg_options": {}, "cop_curve": [], "boiler_type": "",
"part_load_curve": [],
"min_switch_s": 600.0, "hold_mode_s": 1800.0, "hold_set_s": 900.0, "min_gain_ct": 1.0},
}
@@ -750,6 +753,7 @@ def _check_tank(cid: str, p: dict):
SG-Ready options for states "1".."4", a COP curve as heating's."""
if "heater" in p and p["heater"] not in TANK_HEATERS:
raise ValueError(f"control {cid}: heater is one of {', '.join(TANK_HEATERS)}")
_check_part_load(cid, p)
if "erp_class" in p and p["erp_class"] not in ERP_CLASSES:
raise ValueError(f"control {cid}: erp_class is one of {', '.join(ERP_CLASSES)}")
if "top_share" in p and not 0 < float(p["top_share"]) <= 1:
+71 -4
View File
@@ -183,7 +183,38 @@ class Executor:
# -- what is wanted ------------------------------------------------------
def wanted(self, c, now):
want, level, why = self._wanted(c, now)
return self._capped(c, want, level, why, now)
return self._grid_bound(c, *self._capped(c, want, level, why, now))
def _grid_bound(self, c, want, level, why):
"""The grid operator's order (gridorder.limits, at level grid in the guard's limits) on every
controllable consumer, whatever its plan says: a charger the plan leaves as it is (a building's garage
charger: no session to plan) or plans above its share is set to its share, or paused where its share is
below its minimum current; a battery charges at most its share. Before 2026-11-09 only the plan kept
the order and the guard checked commands, so a charger nobody commanded kept drawing (Sim Durlach's
garage, feeder 6, 2026-11-08 16:32-17:32 at 30-37 kW under a 4.2 kW order)."""
q = "current_a" if c.kind == "ev" else "power_w" if c.kind in ("battery", "dhw_tank") else ""
lims = getattr(self.guard, "extra_limits", None) or {}
g = ((lims.get(c.id) or {}).get(q) or {}).get("grid") if q else None
if not g or g[1] is None:
return want, level, why
cap = float(g[1])
tag = f"the grid operator's limit: {cap:g} {'A' if q == 'current_a' else 'W'} (its share of the order)"
v = want.get("set") if isinstance(want, dict) else want
if c.kind == "ev":
if v == "off":
return want, level, why
lo = float(c.p("min_current_a") or 0)
n = number(v)
if cap < lo or cap <= 0:
return "off", "emergency", tag
if n is None or n > cap:
return cap, "emergency", tag
return want, level, why
if c.kind == "battery" and isinstance(want, dict) and number(v) is not None and float(v) > cap:
return {**want, "set": cap}, "emergency", tag
if c.kind == "dhw_tank" and number(v) is not None and "power" in c.entities and float(v) > cap:
return ({**want, "set": cap} if isinstance(want, dict) else cap), "emergency", tag
return want, level, why
def _wanted(self, c, now):
cmd = self.commands.get(c.id)
@@ -273,25 +304,47 @@ class Executor:
return lambda d, s, ent: (d, s, ent) == (a.domain, a.service, a.entity)
async def _overrides(self, now):
"""Each change by hand the guard saw: reported as an `overridden`
action with what the agent had set, who changed it (guard.changed_by:
resident, automation, device), until when the agent keeps off it, and
what it overrode (the level: plan, a command's level; its id), for the
console's overrides and deviations report."""
while self.guard.events:
ev = self.guard.events.pop(0)
c = self.controls.get(ev["control"])
cap, bcmd = self.building.cap(c.kind, now) if self.building is not None and c else (None, None)
if bcmd is not None and "climate" in c.entities and ev["entity"] == c.entities["climate"]:
await self._building_override(bcmd, ev)
bplan = self._battery_plan(c, now)
if bplan is not None:
await self._battery_plan_override(bplan, ev)
cmd = self.commands.get(ev["control"])
until, level = ev["until"], "plan"
if cmd and cmd["level"] == "flexible":
self.commands.pop(ev["control"], None) # the owner wins over a flexible command
why = f"the owner changed it by hand: flexible command {cmd.get('id', '')} ended"
level = "flexible"
elif cmd:
why = f"the owner changed it by hand: {cmd['level']} command applied again"
until, level = int(now), cmd["level"] # applied again at once: no hands-off time
else:
why = f"the owner changed it by hand: hands off until {time.strftime('%H:%M UTC', time.gmtime(ev['until']))}"
await self.publish("action", {"v": 1, "at": ev["at"], "asset": ev["control"], "entity": ev["entity"],
"service": "", "value": ev["value"], "result": "overridden", "why": why})
msg = {"v": 1, "at": ev["at"], "asset": ev["control"], "entity": ev["entity"],
"service": "", "value": ev["value"], "result": "overridden", "why": why,
"level": level, "by": ev.get("by", ""), "until": int(until), "agent_set": ev.get("agent_set")}
if cmd and cmd.get("id"):
msg["id"] = cmd["id"]
await self.publish("action", msg)
log.info("override: %s %s=%s (%s)", ev["control"], ev["entity"], ev["value"], why)
self.log.append({"result": "overridden", **ev})
def _battery_plan(self, c, now):
"""The building's battery_plan in force for this battery, or None."""
if self.building is None or c is None or c.kind != "battery":
return None
bp = self.building.active.get("battery_plan")
return bp if bp and bp["from"] <= now < bp["until"] else None
async def _building_override(self, bcmd, ev):
"""The owner changed a room the building's cap holds: a flexible cap
ends, a binding one stays (applied again)."""
@@ -300,7 +353,21 @@ class Executor:
why = "the owner changed it by hand: the flexible cap ended"
else:
why = "the owner changed it by hand: the binding cap applied again"
await self.publish("action", building_msg(bcmd, "overridden", why, ev["at"]))
msg = building_msg(bcmd, "overridden", why, ev["at"])
msg.update({"by": ev.get("by", ""), "asset": ev["control"], "agent_set": ev.get("agent_set"), "set": ev["value"],
"until": int(bcmd["until"]) if bcmd["level"] == "flexible" else int(ev["at"])})
await self.publish("action", msg)
async def _battery_plan_override(self, bp, ev):
"""The owner changed a battery the building's battery_plan holds: told
to the building as an override of that plan (reported only; whether a
flexible plan is lifted then is still open: until then the
plan stays, the guard's hands-off time holds the battery)."""
why = f"the owner changed the battery by hand: the building's {bp['level']} battery plan overridden"
msg = building_msg(bp, "overridden", why, ev["at"])
msg.update({"by": ev.get("by", ""), "asset": ev["control"], "agent_set": ev.get("agent_set"), "set": ev["value"],
"until": int(ev["until"])})
await self.publish("action", msg)
async def _report(self, a: Action, result, why, now):
msg = {"v": 1, "at": int(now), "asset": a.control, "entity": a.entity,
+32 -14
View File
@@ -48,7 +48,7 @@ import math
import os
import time
from .controls import ev_volts
from .controls import PARAMS, ev_volts
log = logging.getLogger(__name__)
@@ -242,24 +242,42 @@ class GridOrders:
return {"limit_w": float(o["limit_w"]), "from_step": int(a), "to_step": int(b), "penalty": PENALTY_EUR_KWH,
"id": o["id"], "proof": self.proof(), "state": o.get("state", "")}
def limits(self, controls, phases: dict | None = None) -> dict:
"""Grid-level bounds per controllable device (§14a: chargers,
batteries' charging; heat pumps are held by the bridge itself): no
single one above the whole limit. phases: {control id: count} from
evphases (else the mapping's; unknown: 3, never above the ordered
power). {control id: {quantity: (floor, limit)}}."""
def limits(self, controls, phases: dict | None = None, connected: dict | None = None) -> dict:
"""Grid-level bounds per controllable device (§14a with an energy
management system: the controllable consumers' sum at most the
limit; heat pumps are held by the bridge itself). The one limit is
shared, not given whole to each (before 2026-11-09 each charger and
the battery got all of it: three garage chargers could draw three
times the order): the chargers first, in turn, each its share down to
0.1 A (never above the order's power) or 0 where less than its
minimum current is left (it pauses: a car charging at its minimum
and another paused is the redistribution, not every car below its
minimum); a car known not plugged in takes nothing (connected:
{control id: bool}); then a battery's charging and a tank's stepless
element get what is left (no battery reserve is kept for orders: the
owner, 2026-11-09). phases: {control id: count} from evphases (else
the mapping's; unknown: 3, never above the ordered power).
{control id: {quantity: (floor, limit)}}."""
o = self.active()
if not o:
return {}
w = float(o["limit_w"])
left = float(o["limit_w"])
out = {}
for c in controls:
if c.kind == "ev":
con = connected or {}
evs = sorted((c for c in controls if c.kind == "ev"), key=lambda c: con.get(c.id) is False)
for c in evs:
n = (phases or {}).get(c.id) or c.params.get("phases")
volts = ev_volts({**c.params, "phases": n}, "order")
# down to 0.1 A: never above the ordered power (6.1 A x 690 V = 4209 W)
out[c.id] = {"current_a": (None, math.floor(w / volts * 10 + 1e-9) / 10)}
elif c.kind == "battery" or c.kind == "dhw_tank" and "power" in c.entities:
lo = float(c.params.get("min_current_a") or PARAMS["ev"]["min_current_a"])
hi = float(c.params.get("max_current_a") or PARAMS["ev"]["max_current_a"])
# down to 0.1 A: never above the power left (6.1 A x 690 V = 4209 W)
amps = math.floor(max(left, 0.0) / volts * 10 + 1e-9) / 10
if con.get(c.id) is False or amps < lo:
amps = 0.0
out[c.id] = {"current_a": (None, amps)}
left -= min(amps, hi) * volts
for c in controls:
if c.kind == "battery" or c.kind == "dhw_tank" and "power" in c.entities:
# a battery's charging; a tank's stepless element (its relay: the plan's limit on the meter)
out[c.id] = {"power_w": (None, w)}
out[c.id] = {"power_w": (None, max(0.0, round(left, 1)))}
return out
+28 -3
View File
@@ -172,10 +172,11 @@ class Guard:
if entity not in tr.commanded:
tr.commanded[entity] = (self.clock() - self.settle, value)
def observe(self, control_id: str, entity: str, value, now: float | None = None):
def observe(self, control_id: str, entity: str, value, now: float | None = None, by: str = ""):
"""A state change of a control's entity: if it differs from what the
agent set, and not right after the agent set it, the owner changed
it by hand."""
it by hand. by: who changed it (changed_by), reported with the
override."""
now = self.clock() if now is None else now
tr = self._t(control_id)
cmd = tr.commanded.get(entity)
@@ -191,7 +192,7 @@ class Guard:
tr.override_entity = entity
tr.commanded.pop(entity, None)
self.events.append({"control": control_id, "entity": entity, "value": value, "agent_set": want,
"until": int(tr.override_until), "at": int(now)})
"until": int(tr.override_until), "at": int(now), "by": by})
def last_change(self, control_id: str, kind: str) -> float | None:
"""When the agent last changed a control's mode or setpoint (kind
@@ -202,6 +203,30 @@ class Guard:
return self.clock() < self._t(control_id).override_until
def changed_by(ctx) -> str:
"""Who changed an entity, from Home Assistant's context of the new state
(subscribe_entities sends it as "c": the context's id alone when it has
no user and no parent, else {"id", "user_id", "parent_id"}):
resident a person signed in to HA (its app or dashboard, the box's
panel through HA): the context has a user
automation an automation or script in HA: a parent context, no user
device neither: the device or its integration reported the change
itself (a button or dial on the device, its own app, its
manual mode)
"" no context reported (an older HA, a test)
The agent's own calls never reach here as overrides: the guard skips a
value it set itself."""
if isinstance(ctx, str) and ctx:
return "device"
if isinstance(ctx, dict):
if ctx.get("user_id"):
return "resident"
if ctx.get("parent_id"):
return "automation"
return "device" if ctx.get("id") else ""
return ""
def _same(a, b, tol: float = 0.26) -> bool:
try:
return abs(float(a) - float(b)) < tol
+3 -1
View File
@@ -55,12 +55,14 @@ class Collector:
def on_entities(self, ev: dict, now: float | None = None):
now = time.time() if now is None else now
for eid, s in (ev.get("a") or {}).items():
self.states[eid] = {"s": s.get("s"), "a": dict(s.get("a") or {}), "t": s.get("lc") or now}
self.states[eid] = {"s": s.get("s"), "a": dict(s.get("a") or {}), "t": s.get("lc") or now, "c": s.get("c")}
for eid, c in (ev.get("c") or {}).items():
cur = self.states.setdefault(eid, {"s": None, "a": {}, "t": now})
plus, minus = c.get("+") or {}, c.get("-") or {}
if "s" in plus:
cur["s"] = plus["s"]
# the change's context (HA: an id alone, or {"id", "user_id", "parent_id"}): who made it (guard.changed_by)
cur["c"] = plus.get("c")
cur["a"].update(plus.get("a") or {})
for k in minus.get("a") or []:
cur["a"].pop(k, None)
+70
View File
@@ -946,6 +946,8 @@ class Model:
"lo_c": lo_c, "hi_c": hi_c, "heater": heater, "pmax": pmax, "cops": cops, "switched": switched,
"eff": sup.curve["full"] if heater == "boiler" else None, "e_leg": e_leg, "window": window,
"qmax": sup.qmax if sup else None,
# a boiler-heated tank's fuel (gas or heating oil: the plan's series, plan_series)
"fuel": sup.carrier if heater == "boiler" and sup else None,
"src": "electric" if heater in ("element", "heat_pump") else heater})
def cover(self, d, room_ids):
@@ -1307,6 +1309,10 @@ def plan(s: dict, time_limit: float = 30.0) -> dict:
notes += m.notes
if notes:
out["notes"] = notes
# the site's energy per carrier and use, per step for 24 h (the console's plan chart; methods A2.17)
series = plan_series(s, m, x, outlook)
if series:
out["series"] = series
steps_eur = step_costs(s, m, x)
if steps_eur is not None:
out["steps_eur"] = steps_eur # per step and carrier: with and without the plan (costs.py)
@@ -1619,6 +1625,70 @@ def flexibility(m, x) -> dict:
return out
def plan_series(s, m, x, outlook) -> dict:
"""The plan's energy picture per step for the next 24 h (FLEX_STEPS; W,
the mean power in the step: docs/methods.md A2.17), for the console's
plan chart: electricity's sources (import_w, pv_w: the forecast, the
battery's discharge) and uses (load_w: the house's own forecast,
heating_w / cooling_w: electric heat and cooling, ev_w, dhw_element_w:
a tank's electric heater, the battery's charge, export_w), and the other
carriers' inputs: gas_w and oil_w (a boiler's fuel, Hi), heat_w (heat
bought from a district or the building), dhw_w (hot water's heat drawn,
where forecast); per hot-water tank its planned temperature
("tank_c:<id>", °C). Only what the site has (a key absent: not in the plan,
never 0 for it); the heat outlook (A2.16) adds its fixed heat as drawn."""
n = min(m.T, FLEX_STEPS)
out: dict[str, list] = {}
def add(key, t, w):
out.setdefault(key, [0.0] * n)[t] += w
for t in range(n):
add("import_w", t, x(m.gin[t]) + sum((x(v) for v in m.buy[t]), 0.0))
add("export_w", t, x(m.gout[t]) + sum((x(v) for v in m.sell[t]), 0.0))
add("load_w", t, max(0.0, float(s["load_w"][t])))
if any(float(v) > 0 for v in s["pv_w"][:n]):
out["pv_w"] = [max(0.0, float(v)) for v in s["pv_w"][:n]]
temps = {}
for did, (kind, v) in m.devices.items():
if not v:
continue
if kind == "battery":
for t in range(min(n, len(v["ch"]))):
add("battery_charge_w", t, _x(x, v["ch"][t]))
add("battery_discharge_w", t, _x(x, v["dis"][t]))
continue
if kind == "ev":
for t in range(min(n, len(v["power"]))):
add("ev_w", t, _x(x, v["power"][t]))
continue
if kind not in ("heating", "cooling", "dhw_tank"):
continue
el = "dhw_element_w" if kind == "dhw_tank" else kind + "_w"
fuel = (v.get("fuel") or "gas") + "_w"
for col, key in (("power", el), ("gas", fuel), ("district", "heat_w")):
xs = v.get(col) or []
if not any(c is not None and hasattr(c, "index") for c in xs[:n]):
continue
for t in range(min(n, len(xs))):
add(key, t, _x(x, xs[t]))
if kind == "dhw_tank":
# its planned mean temperature at each step's end (°C, not W: "tank_c:<id>")
temps["tank_c:" + did] = [round(tank_temp(v, t, x), 1) for t in range(min(n, len(v["e"])))]
for t in range(min(n, len(v.get("draw") or []))):
d = v["draw"][t]
add("dhw_w", t, float(d) if isinstance(d, (int, float)) else _x(x, d))
if outlook:
key = {"gas": "gas_w", "oil": "oil_w", "heat": "heat_w"}.get(outlook.get("carrier"))
for kind, ln in (outlook.get("lines") or {}).items():
for t in range(min(n, len(ln["input_w"]))):
if key:
add(key, t, float(ln["input_w"][t]))
if kind == "dhw":
add("dhw_w", t, float(ln["heat_w"][t]))
return {**{k: [round(w) for w in v] for k, v in out.items()}, **temps}
def _x(x, v) -> float:
"""A step's value: a variable's, or 0 where there is none (an EV's steps after departure)."""
return x(v) if v is not None and hasattr(v, "index") else 0.0
+52
View File
@@ -30,6 +30,19 @@ owner: "we still have no saving from gas/oil?"; methods E14):
not_planned the heating or tank on it was refused (its refusal's why: e.g.
no gas price); 0 in plan and base, nothing of it is planned
Electricity whose saving rounds to 0.00 EUR carries why and note too (audit
2026-11-09: 28 homes showed electricity 0 without a reason):
no_lever the plan moves no electricity: no battery, no car plugged in
or expected, no electric heating (heat pump, heater) and no
electric hot water; the household's own use is a fixed term
(a district-heat or gas flat, a car away)
flat_price it has a lever, but one import price at every step and no
battery: the lever's draw costs the same whenever it runs
not_shifted the price varies (or a battery could store), but the plan
found nothing cheaper than the baseline: the draw already lies
in the cheapest hours, or nothing is due in the horizon
The levers found are in the note.
base_eur − plan_eur summed over the carriers is the plan's own saving,
baseline_eur − cost_eur: the plan's electricity carries the market's
contracts (a tenant-power flat's energy bought from its building at the
@@ -56,6 +69,10 @@ def saving_parts(s: dict, m, x, steps: dict | None) -> dict | None:
if p is not None:
heating += m.eur_wh(t, mean - pi[t]) * x(p)
out["electricity"]["heating_eur"] = round(heating, 4)
if "electricity" in out:
why = electricity_zero_why(s, m, out["electricity"])
if why is not None:
out["electricity"].update(why)
for carrier in HEAT_CARRIERS:
why = zero_why(s, m, carrier, out.get(carrier))
if why is not None:
@@ -95,3 +112,38 @@ def zero_why(s: dict, m, carrier: str, part: dict | None) -> dict | None:
+ ("; a lower room temperature is not counted as a saving" if rooms else "")
+ tail}
return {"why": "not_shifted", "note": f"the {words} price varies, but the heat was needed when it was made" + tail}
def electric_levers(m) -> list[str]:
"""What in this plan can move electricity in time (its words)."""
out = []
for kind, v in m.devices.values():
if not v:
continue # e.g. a car not plugged in and none expected
if kind == "battery" and float(v.get("cap") or 0) > 0:
out.append("battery")
elif kind == "ev":
out.append("car")
elif kind in ("heating", "cooling") and v.get("src") in ("electric", "heat_pump", "hybrid"):
out.append({"heat_pump": "heat pump", "hybrid": "hybrid's heat pump"}.get(v["src"], "electric heating")
if kind == "heating" else "cooling")
elif kind == "dhw_tank" and v.get("src") == "electric":
out.append("electric hot water")
return sorted(set(out))
def electricity_zero_why(s: dict, m, part: dict) -> dict | None:
"""Why the electricity saving is 0 in this plan ({why, note}; module docstring), None where it has one."""
if abs(part["base_eur"] - part["plan_eur"]) >= ZERO_EUR:
return None
levers = electric_levers(m)
if not levers:
return {"why": "no_lever", "note": "nothing in this plan moves electricity in time (no battery, no car plugged in "
"or expected, no heat pump or electric heating, no electric hot water): "
"the household's own use is the same with and without the plan"}
ps = [p for p in (s.get("price_import") or [])[:m.T] if p is not None]
if ps and max(ps) - min(ps) < 1e-9 and "battery" not in levers:
return {"why": "flat_price", "note": f"one electricity price ({ps[0]:.2f} ct/kWh) at every hour of the plan: "
f"the {', '.join(levers)} costs the same whenever it runs"}
return {"why": "not_shifted", "note": f"the {', '.join(levers)} found nothing cheaper in this plan: its draw "
"already lies in the cheapest hours, or nothing is due in the horizon"}
+16 -2
View File
@@ -8,7 +8,16 @@ next window, so a steady sensor that reports rarely still has a mean.
Counters (a growing total: energy): the delta over the window. A total
that goes down is a meter reset or replacement: the new reading counts
from zero instead of a negative delta.
from zero instead of a negative delta. A drop is judged by the reading after
it: Home Assistant reports 0 for a moment while it restarts, and after a
restart it may show the total it had saved minutes before until the device
reports again, so a return to at least the previous total means the drop
was "unavailable" (the increase since the last real reading counts, no
reset); a reading below it means the meter really started again (a reset).
Before, the 0 was a reset, and the meter's whole total became one minute's
increase (a test site 2026-11-08 11:21 UTC: 2 124 kWh of load in a minute); the
stale total too (Sim Berlin 1 2026-11-08 14:44 UTC: heat.energy 462 477 →
461 809 Wh after the farm's reboot, back at 462 4xx with its simulator).
Unavailable: seconds of the window without a valid value are reported, so
the platform can tell "0 W" from "unknown".
@@ -39,6 +48,7 @@ class _Counter:
delta: float = 0.0
resets: int = 0
n: int = 0
drop: float | None = None # a reading below the total, judged by the next different one
@dataclass
@@ -58,11 +68,15 @@ class Aggregator:
if value is None:
return
if c.last is not None:
if value < c.last and (c.drop is None or value == c.drop or value == 0):
c.drop = value # unavailable until a different reading says otherwise
return
if value >= c.last:
c.delta += value - c.last
else:
c.delta += value
c.resets += 1
c.drop = None
c.last, c.n = value, c.n + 1
return
g = self.gauges.setdefault(asset, _Gauge(since=self.start))
@@ -90,6 +104,6 @@ class Aggregator:
for asset, c in sorted(self.counters.items()):
out.append({"asset": asset, "kind": "counter", "delta": c.delta, "last": c.last,
"resets": c.resets, "n": c.n})
self.counters[asset] = _Counter(last=c.last)
self.counters[asset] = _Counter(last=c.last, drop=c.drop)
self.start = end
return out
+22
View File
@@ -190,3 +190,25 @@ def test_the_building_may_charge_from_the_grid(tmp_path):
p, _ = solved(s)["battery"]
assert p[:4] == pytest.approx([2000] * 4, abs=1)
assert all(w <= 1 for w in p[4:36])
def test_plan_taken_before_the_binding_binds_at_night(tmp_path):
# the farm 2026-11-09 03:50 UTC: building.json written by the agent before 0.1.0-dev.db2193861454 held the
# night's battery_plan (0 W) but no binding; after the upgrade the box refilled the owner's 10 % floor from the
# grid (Durlach +700 W at 7 %, Berlin +300 W at 7 %). The plan in force binds on load: nothing charged at night
import json
plan = Building.parse({"v": "1", "id": "p0", "building": "house-7", "level": "binding", "control": "battery_plan",
"value": "0", "from": str(START), "until": str(START + 96 * 900), "why": "the building's plan",
"schedule": ",".join(["0"] * 96), "step_s": "900"})
(tmp_path / "building.json").write_text(json.dumps({"battery_plan": plan})) # as the older agent kept it
b = Building(str(tmp_path), Clock(START))
assert b.bound and b.bound["building"] == "house-7"
assert '"battery_bound"' in (tmp_path / "building.json").read_text()
s = pv_day(house([battery(soc=7, floor=10)]))
s["building"] = b.for_model(START, 900, s["steps"])
assert s["building"]["battery_bound"]["lapsed"] is False
p, soc = solved(s)["battery"]
assert all(w <= 1 for w in p[:36]) # 00:00-09:00 UTC, no PV: no grid charging
assert max(soc[36:60]) >= 1000 - 1 # the floor refilled from the PV
e = [x for x in optimizer.plan(s, 20)["devices"]["battery"] if x["t"] < START + 36 * 900]
assert e and all(x["set"] <= 0 and not x["grid"] for x in e)
+5 -3
View File
@@ -109,10 +109,12 @@ class C:
def test_order_bound_never_above_the_order(tmp_path):
g = GridOrders(str(tmp_path), clock=lambda: NOW)
g.take(message()) # 4200 W
for cid in ("unknown", "three"): # each alone: a 3-phase charger never above 4.2 kW
amps = g.limits([C(cid, {"phases": 3} if cid == "three" else {})], {"unknown": None})[cid]["current_a"][1]
assert amps == 6.0 and amps * 3 * V <= 4200.0
# both: they share the one limit (the second paused: less than its 6 A left)
lim = g.limits([C("unknown", {}), C("three", {"phases": 3})], {"unknown": None})
for cid in ("unknown", "three"):
amps = lim[cid]["current_a"][1]
assert amps == 6.0 and amps * 3 * V <= 4200.0 # a 3-phase charger: never above 4.2 kW
assert lim["unknown"]["current_a"][1] == 6.0 and lim["three"]["current_a"][1] == 0.0
# a 1-phase charger learned as one: 4200 / 230 = 18.26, down to 18.2 A (4186 W)
lim = g.limits([C("one", {})], {"one": 1.0})
assert lim["one"]["current_a"][1] == 18.2 and 18.2 * V <= 4200.0
+82 -1
View File
@@ -115,7 +115,48 @@ def test_model_constraint_and_limits(tmp_path):
def __init__(self, id, kind, params):
self.id, self.kind, self.params = id, kind, params
lim = g.limits([C("ev", "ev", {"phases": 3, "voltage": 230}), C("bat", "battery", {}), C("room", "heating", {})])
assert lim == {"ev": {"current_a": (None, 6.0)}, "bat": {"power_w": (None, 4200.0)}}
# the one limit shared: the charger 6 A x 690 V = 4140 W, the battery's charging the 60 W left
assert lim == {"ev": {"current_a": (None, 6.0)}, "bat": {"power_w": (None, 60.0)}}
class _C:
def __init__(self, id, kind, params, entities=None):
self.id, self.kind, self.params, self.entities = id, kind, params, entities or {}
def test_chargers_share_the_one_limit(tmp_path):
# a building's three garage chargers (Sim Durlach, feeder 6, 2026-11-08): before, each got the whole 4.2 kW
g = GridOrders(str(tmp_path), clock=lambda: NOW)
g.take(message())
evs = [_C(f"garage_{n}", "ev", {"phases": 3, "voltage": 230, "min_current_a": 6, "max_current_a": 16}) for n in (1, 2, 3)]
lim = g.limits(evs + [_C("bat", "battery", {})])
amps = [lim[f"garage_{n}"]["current_a"][1] for n in (1, 2, 3)]
assert amps == [6.0, 0.0, 0.0] # one at its minimum, the others paused: within the order
assert sum(a * 690 for a in amps) + lim["bat"]["power_w"][1] <= 4200.0
# the first has no car: the second takes the share
lim = g.limits(evs, connected={"garage_1": False, "garage_2": True, "garage_3": None})
assert [lim[f"garage_{n}"]["current_a"][1] for n in (1, 2, 3)] == [0.0, 6.0, 0.0]
# a larger order: each its share in turn, never above the order
g.take(message(limit_w=16000.0, id="cb01-2"))
lim = g.limits(evs)
amps = [lim[f"garage_{n}"]["current_a"][1] for n in (1, 2, 3)]
# the first's bound is above its 16 A (it draws at most 16 A = 11 040 W), the second gets the 4 960 W left
assert amps == [23.1, 7.1, 0.0] and sum(min(a, 16) * 690 for a in amps) <= 16000.0
def test_renewed_order_holds(tmp_path):
# the bridge renews the order (the same id, a later end): it holds past the first end
t = [NOW]
g = GridOrders(str(tmp_path), clock=lambda: t[0])
assert g.take(message()) == (True, "taken")
t[0] = NOW + 290
assert g.take(message(until=NOW + 1500)) == (False, "taken") # the same order: no new decision
t[0] = NOW + 880
g.take(message(until=NOW + 1500)) # the bridge repeats it (every 15 s)
t[0] = NOW + 1000
assert g.active() and g.active()["until"] == NOW + 1500
t[0] = NOW + 1501
assert g.active() is None
highspy = pytest.importorskip("highspy")
@@ -225,3 +266,43 @@ def test_controller_publishes_the_order_as_an_action(tmp_path):
assert asyncio.run(ctl.grid_order(message().encode()))
assert [k for k, _ in sink.sent].count("action") == 1
assert [d for k, d in sink.sent if k == "action"][0]["service"] == "grid.load_limit"
def test_executor_holds_every_charger_to_its_share(tmp_path):
"""Under an order the executor sets each charger to its share whatever the plan says: a charger the plan
leaves alone (no session to plan), one planned above its share, one whose share is 0 (paused)."""
import yaml
from cantabile_edge.config import Config
from cantabile_edge.consent import Consent
from cantabile_edge.controller import Controller
from cantabile_edge.executor import RELEASE
from cantabile_edge.mapping import Mapping
m = tmp_path / "mapping.yaml"
m.write_text(yaml.safe_dump({"version": 3, "assets": [], "controls": [
{"id": f"garage_{n}", "kind": "ev", "consent": True,
"entities": {"switch": f"switch.ev{n}", "current": f"number.ev{n}_amps", "connected": f"binary_sensor.ev{n}"},
"params": {"phases": 3, "voltage": 230, "min_current_a": 6, "max_current_a": 16}} for n in (1, 2, 3)]}))
t = [NOW]
ctl = Controller(Config(site_id="ab" * 16, mapping=str(m), state_dir=str(tmp_path)), Mapping.load(str(m)),
Consent(str(tmp_path)), sink=None, clock=lambda: t[0])
ctl.col.on_entities({"a": {f"binary_sensor.ev{n}": {"s": "on", "a": {}} for n in (1, 2, 3)}})
assert asyncio.run(ctl.grid_order(message().encode()))
ex = ctl.executor
cs = {c.id: c for c in ctl.controls}
ex.commands.clear()
ex.plan = None # no plan: each control's safe value (release)
want = {cid: ex.wanted(cs[cid], t[0]) for cid in cs}
assert want["garage_1"][0] == 6.0 and want["garage_1"][1] == "emergency" and "grid operator" in want["garage_1"][2]
assert want["garage_2"][0] == "off" and want["garage_3"][0] == "off"
# a plan above the share is capped; a plan below it stays the plan's
assert ex._grid_bound(cs["garage_1"], 16.0, "plan", "")[0] == 6.0
assert ex._grid_bound(cs["garage_1"], "off", "plan", "x") == ("off", "plan", "x")
assert ex._grid_bound(cs["garage_1"], RELEASE, "plan", "")[0] == 6.0
# the car on charger 1 leaves: the next round gives charger 2 the share
ctl.col.on_entities({"a": {"binary_sensor.ev1": {"s": "off", "a": {}}}})
ctl.grid_tick()
assert ctl.guard.extra_limits["garage_2"]["current_a"]["grid"] == (None, 6.0)
assert ctl.guard.extra_limits["garage_1"]["current_a"]["grid"] == (None, 0.0)
# the order ends: no bound, the plan's want again
assert asyncio.run(ctl.grid_order(message(active=False, state="normal", limit_w=0.0, id="cb01-9").encode()))
assert ex._grid_bound(cs["garage_1"], 16.0, "plan", "")[0] == 16.0
+135
View File
@@ -0,0 +1,135 @@
# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
"""What the box reports about a change by hand (the console's
overrides and deviations report): who made it (Home Assistant's context:
a person, an automation, the device itself), what the agent had set, until
when the agent keeps off it, and what it overrode (the plan, a command and
its id, the building's thermostat cap or battery plan)."""
import asyncio
from cantabile_edge.building import Building
from cantabile_edge.executor import Executor
from cantabile_edge.guard import changed_by
from cantabile_edge.inputs import Collector
from test_control_parts import FakeHA, Clock, mapping, consent, mk_guard, states # noqa: F401 (fixtures)
START = 1_800_000_000
def cmd(control, value, level="binding", frm=START, until=START + 4 * 3600, cid="b1"):
return {"v": "1", "id": cid, "building": "house-7", "level": level, "control": control, "value": str(value),
"from": str(frm), "until": str(until), "why": "peak shaving"}
def bplan(ws, level="binding", frm=START, cid="p1"):
return {"v": "1", "id": cid, "building": "house-7", "level": level, "control": "battery_plan",
"value": str(ws[0]), "from": str(frm), "until": str(frm + 900 * len(ws)), "why": "the building's plan",
"schedule": ",".join(str(w) for w in ws), "step_s": "900"}
def test_changed_by_from_the_context():
assert changed_by({"id": "01J", "user_id": "u1", "parent_id": None}) == "resident"
assert changed_by({"id": "01J", "user_id": None, "parent_id": "01P"}) == "automation"
assert changed_by("01JCONTEXTID") == "device" # HA sends the id alone: no user, no parent
assert changed_by({"id": "01J", "user_id": None, "parent_id": None}) == "device"
assert changed_by(None) == "" and changed_by("") == "" and changed_by({}) == ""
def _executor(mapping, consent, clk, building=None):
g = mk_guard(mapping, consent, clock=clk)
col = Collector()
def observe(eid, st, now):
# as controller._observe: the climate's setpoint, the battery's power, with the change's context
by = changed_by(st.get("c"))
if eid == "climate.living":
g.observe("living", eid, st["a"].get("temperature"), now, by=by)
elif eid == "number.batt_power":
g.observe("battery", eid, st.get("s"), now, by=by)
col.observers.append(observe)
sent = []
async def publish(kind, data):
sent.append(data)
return Executor(mapping.controls, g, col, publish, clock=clk, building=building), col, sent
def test_override_of_the_plan_names_who_and_until(mapping, consent): # noqa: F811
clk = Clock(START)
ex, col, sent = _executor(mapping, consent, clk)
states(col, climate__living=("heat", {"temperature": 20}))
ex.plan = {"made": clk.t, "devices": {"living": [{"t": START - 60, "set": 21.0, "why": "warm up"}]}}
ha = FakeHA()
asyncio.run(ex.tick(ha, auto=True))
assert ("climate", "set_temperature", "climate.living", {"temperature": 21.0}) in ha.calls
clk.t += 300
# a person in HA's app turns it up
col.on_entities({"c": {"climate.living": {"+": {"a": {"temperature": 23.5}, "c": {"id": "x", "user_id": "u9"}}}}}, clk.t)
asyncio.run(ex.tick(ha, auto=True))
m = [x for x in sent if x["result"] == "overridden"]
assert len(m) == 1, sent
m = m[0]
assert (m["asset"], m["by"], m["level"], m["agent_set"], m["value"]) == ("living", "resident", "plan", 21.0, 23.5)
assert m["until"] == int(clk.t) + 7200 and m["at"] == int(clk.t)
assert "id" not in m
def test_override_of_a_command_names_its_level_and_id(mapping, consent): # noqa: F811
clk = Clock(START)
ex, col, sent = _executor(mapping, consent, clk)
states(col, climate__living=("heat", {"temperature": 21}))
ex.command({"asset": "living", "set": "22", "level": "flexible", "minutes": "120", "id": "cmd-7"}, clk.t)
ha = FakeHA()
asyncio.run(ex.tick(ha, auto=True))
clk.t += 300
# the thermostat's own dial: HA sends the context's id alone
col.on_entities({"c": {"climate.living": {"+": {"a": {"temperature": 19}, "c": "01JDIAL"}}}}, clk.t)
asyncio.run(ex.tick(ha, auto=True))
m = next(x for x in sent if x["result"] == "overridden")
assert (m["by"], m["level"], m["id"], m["agent_set"]) == ("device", "flexible", "cmd-7", 22.0)
# a binding command is applied again at once: no hands-off time (until = the moment)
ex.command({"asset": "living", "set": "22", "level": "binding", "minutes": "120", "id": "cmd-8"}, clk.t)
asyncio.run(ex.tick(ha, auto=True))
clk.t += 300
col.on_entities({"c": {"climate.living": {"+": {"a": {"temperature": 24}, "c": {"id": "y", "parent_id": "p"}}}}}, clk.t)
asyncio.run(ex.tick(ha, auto=True))
m = [x for x in sent if x["result"] == "overridden"][-1]
assert (m["by"], m["level"], m["id"], m["until"]) == ("automation", "binding", "cmd-8", int(clk.t))
def test_override_of_the_building_cap_and_battery_plan(tmp_path, mapping, consent): # noqa: F811
clk = Clock(START + 600)
b = Building(str(tmp_path), clk)
b.take(b.parse(cmd("thermostat_cap", 21.0, "binding", frm=START, until=START + 7200)), [("living", 20.5, 24, "heating")])
b.take(b.parse(bplan([1000.0] * 8, level="binding", frm=START)), [])
ex, col, sent = _executor(mapping, consent, clk, building=b)
states(col, climate__living=("heat", {"temperature": 22}), switch__grid_charge=("off",), number__batt_power=("0",))
ex.plan = {"made": clk.t, "devices": {
"living": [{"t": START, "set": 23.0, "why": "keep warm"}],
"battery": [{"t": START, "set": 1000.0, "grid": False, "why": "building house-7: its battery plan (+1000 W)"}]}}
ha = FakeHA()
asyncio.run(ex.tick(ha, auto=True))
assert ("number", "set_value", "number.batt_power", {"value": 1000.0}) in ha.calls
clk.t += 300
col.on_entities({"c": {"climate.living": {"+": {"a": {"temperature": 24}, "c": {"id": "x", "user_id": "u1"}}},
"number.batt_power": {"+": {"s": "-2000", "c": "01JINVERTER"}}}}, clk.t)
asyncio.run(ex.tick(ha, auto=True))
bmsgs = [x for x in sent if x["result"] == "overridden" and x["entity"] == "building:house-7"]
cap = next(x for x in bmsgs if x["service"] == "building.thermostat_cap")
assert (cap["by"], cap["level"], cap["id"], cap["asset"], cap["set"], cap["value"]) == ("resident", "binding", "b1", "living", 24, 21.0)
bp = next(x for x in bmsgs if x["service"] == "building.battery_plan")
assert (bp["by"], bp["level"], bp["id"], bp["asset"], bp["agent_set"]) == ("device", "binding", "p1", "battery", 1000.0)
assert bp["until"] == int(clk.t) + 7200
assert "battery_plan" in b.active # reported only: lifting a flexible one is still open
# the flat's own overrides are reported as before, with who
own = {x["asset"]: x for x in sent if x["result"] == "overridden" and x["entity"] != "building:house-7"}
assert own["battery"]["by"] == "device" and own["living"]["by"] == "resident"
def test_collector_keeps_the_context():
col = Collector()
col.on_entities({"a": {"switch.x": {"s": "on", "a": {}, "c": "01A"}}}, 1.0)
assert col.states["switch.x"]["c"] == "01A"
col.on_entities({"c": {"switch.x": {"+": {"s": "off", "c": {"id": "01B", "user_id": "u"}}}}}, 2.0)
assert col.states["switch.x"]["c"] == {"id": "01B", "user_id": "u"}
col.on_entities({"c": {"switch.x": {"+": {"s": "on"}}}}, 3.0)
assert col.states["switch.x"]["c"] is None # no context with the change: not known
+13
View File
@@ -145,3 +145,16 @@ def test_a_hybrids_boiler_uses_the_curve():
assert p["gas_eur"] > 0
assert {e.get("source") for e in p["devices"]["heating"] if e.get("source")} == {"boiler"}
assert p["devices"]["heating"][0]["t"] == START
def test_a_boiler_heated_tank_takes_the_burners_part_load():
"""A central boiler's store (Sim Durlach's GB192i.2-35, its ErP sheet's curve): a dhw_tank takes
boiler_type and part_load_curve as a heating control does (they were refused as unknown params), checked alike."""
tank = {"id": "hot_water", "kind": "dhw_tank", "entities": {"switch": "switch.charge"},
"params": {"heater": "boiler", "boiler_type": "condensing", "part_load_curve": [[0.339, 1.123], [1.0, 1.0]]}}
cs = controls.parse([tank], set())
assert cs[0].p("boiler_type") == "condensing" and cs[0].p("part_load_curve") == [[0.339, 1.123], [1.0, 1.0]]
with pytest.raises(ValueError):
controls.parse([{**tank, "params": {"heater": "boiler", "part_load_curve": [[1.5, 1.0]]}}], set())
with pytest.raises(ValueError):
controls.parse([{**tank, "params": {"heater": "boiler", "boiler_type": "wood"}}], set())
+59
View File
@@ -0,0 +1,59 @@
# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
"""The plan's energy picture per step (optimizer.plan_series, docs/methods.md
A2.17; the console's plan chart): electricity's sources and
uses and the other carriers' inputs, W per step for 24 h, only what the site
has (a key absent is "not in the plan", never 0)."""
import pytest
highspy = pytest.importorskip("highspy")
from cantabile_edge import optimizer # noqa: E402
from test_combi_boiler import combi_house, combi_with_store # noqa: E402
from test_heat_sources import house, room # noqa: E402
def test_a_district_heat_flat_draws_heat_and_its_hot_water():
s = house([room("district", max_heat_w=6000)], heat=9.3)
s["t_out"] = [0.0] * 96
s["heat_site"] = {"from": "heating", "source": "district", "space": False}
s["dhw_w"] = [400.0] * 96
p = optimizer.plan(s, 20)
se = p["series"]
assert len(se["import_w"]) == 96 and se["load_w"][0] == 400
assert sum(se["heat_w"]) > 0 # the rooms' heat and the hot water's, bought
assert se["dhw_w"] == [400] * 96
# electricity balances: import + PV + discharge = uses + export (no PV, no battery here)
for t in range(96):
assert se["import_w"][t] == pytest.approx(se["load_w"][t] + se["export_w"][t], abs=2)
for k in ("pv_w", "gas_w", "oil_w", "heating_w", "battery_charge_w", "ev_w"):
assert k not in se # the site has none: absent, never 0
def test_a_combi_burns_gas_for_the_rooms_and_the_water():
p = optimizer.plan(combi_house(500.0), 20)
se = p["series"]
assert sum(se["gas_w"]) > 0 and se["dhw_w"][0] == 500
assert "heat_w" not in se and "heating_w" not in se
def test_a_store_heated_by_the_boiler_burns_gas_and_shows_its_draws():
p = optimizer.plan(combi_with_store(), 20)
se = p["series"]
assert sum(se["gas_w"]) > 0 and max(se["dhw_w"]) == 6000
assert "dhw_element_w" not in se
temps = [v for k, v in se.items() if k.startswith("tank_c:")]
assert len(temps) == 1 and len(temps[0]) == 96 and 30 < temps[0][0] < 70
def test_pv_and_the_battery():
from test_battery_plan import house as bhouse
from test_optimizer import battery
s = bhouse([battery()])
s["pv_w"] = [0.0] * 40 + [3000.0] * 16 + [0.0] * (s["steps"] - 56)
p = optimizer.plan(s, 20)
se = p["series"]
assert se["pv_w"][40] == 3000 and "battery_charge_w" in se and "battery_discharge_w" in se
for t in range(96):
src = se["import_w"][t] + se["pv_w"][t] + se["battery_discharge_w"][t]
use = se["load_w"][t] + se["battery_charge_w"][t] + se["export_w"][t]
assert src >= use - 3 # PV may be curtailed (spill), never more used than there is
+23
View File
@@ -249,3 +249,26 @@ def test_the_thermostat_from_a_warm_start_coasts_then_holds_its_least():
# then it holds the least: the draw and the loss at 45 °C in an 18 °C room
later = [t for t in range(first + 8, len(q)) if v["draw"][t] == 0]
assert q[later[-1]] == pytest.approx(v["ua"] * (v["lo_c"] - v["room"]), rel=1e-6)
# -- electricity 0.00: a reason, as the heat carriers (audit 2026-11-09: 28 homes with a bare 0) -------------------
def test_no_lever_electricity_zero_says_why():
# a flat with nothing that moves electricity (district heat, no battery, no car)
p = optimizer.plan(house([]), 20)
el = p["saving_parts"]["electricity"]
assert saved(el) == pytest.approx(0, abs=0.005)
assert el["why"] == "no_lever" and "battery" in el["note"]
def test_flat_price_with_a_heater_says_why():
s = house([heating()])
s["price_import"] = [30.0] * len(s["price_import"])
el = optimizer.plan(s, 20)["saving_parts"]["electricity"]
assert saved(el) == pytest.approx(0, abs=0.005)
assert el["why"] == "flat_price" and "30.00 ct/kWh" in el["note"] and "electric heating" in el["note"]
def test_a_real_electricity_saving_has_no_why():
el = optimizer.plan(house([battery()]), 20)["saving_parts"]["electricity"]
assert saved(el) > 0 and "why" not in el
+54
View File
@@ -65,9 +65,63 @@ def test_counter_delta_and_reset():
assert (r["delta"], r["resets"], r["last"]) == (200 + 50 + 30, 1, 80)
def test_counter_brief_zero_is_not_a_reset():
# Home Assistant restarting reports 0 for a moment, then the total again
a = agg()
a.sample("load.energy", "counter", 2123995.0, 961)
a.sample("load.energy", "counter", 0.0, 970) # the restart's 0
a.sample("load.energy", "counter", 2124157.0, 990) # back at the total and on
r = rec(a.flush(1020), "load.energy")
assert (r["delta"], r["resets"], r["last"]) == (162, 0, 2124157)
# the 0 at the end of a window, the total in the next: still no reset
a.sample("load.energy", "counter", 0.0, 1030)
r = rec(a.flush(1080), "load.energy")
assert (r["delta"], r["resets"], r["last"]) == (0, 0, 2124157)
a.sample("load.energy", "counter", 2124200.0, 1090)
r = rec(a.flush(1140), "load.energy")
assert (r["delta"], r["resets"]) == (43, 0)
def test_counter_zero_then_lower_is_a_reset():
# a meter really started again from 0: the reading after the 0 is below the old total
a = agg()
a.sample("grid.import_energy", "counter", 1000.0, 961)
a.sample("grid.import_energy", "counter", 0.0, 970)
a.sample("grid.import_energy", "counter", 20.0, 990)
r = rec(a.flush(1020), "grid.import_energy")
assert (r["delta"], r["resets"], r["last"]) == (20, 1, 20)
def test_counter_without_samples_is_zero():
a = agg()
a.sample("grid.import_energy", "counter", 10.0, 970)
a.flush(1020)
r = rec(a.flush(1080), "grid.import_energy")
assert (r["delta"], r["n"], r["last"]) == (0, 0, 10)
def test_counter_stale_lower_total_is_not_a_reset():
# after a restart Home Assistant showed the total it had saved minutes before
# (Sim Berlin 1, 2026-11-08 14:44 UTC), then the device's own total again
a = agg()
a.sample("heat.energy", "counter", 462454.0, 961)
a.sample("heat.energy", "counter", 462477.0, 990)
a.sample("heat.energy", "counter", 461809.0, 1000) # the stale total
r = rec(a.flush(1020), "heat.energy")
assert (r["delta"], r["resets"], r["last"]) == (23, 0, 462477)
a.sample("heat.energy", "counter", 461809.0, 1030) # repeated: still judged later
r = rec(a.flush(1080), "heat.energy")
assert (r["delta"], r["resets"]) == (0, 0)
a.sample("heat.energy", "counter", 462480.0, 1090) # the device again
r = rec(a.flush(1140), "heat.energy")
assert (r["delta"], r["resets"], r["last"]) == (3, 0, 462480)
def test_counter_lower_then_lower_still_is_a_reset():
# a replaced meter: a lower total and the next reading again below the old one
a = agg()
a.sample("grid.import_energy", "counter", 1000.0, 961)
a.sample("grid.import_energy", "counter", 30.0, 970)
a.sample("grid.import_energy", "counter", 45.0, 990)
r = rec(a.flush(1020), "grid.import_energy")
assert (r["delta"], r["resets"], r["last"]) == (45, 1, 45)
+10 -2
View File
@@ -63,6 +63,10 @@ type Grid struct {
lastHeartbeat time.Time
lastLimit time.Time
failsafeAt time.Time
// rewritten: the control box wrote its limit since the last values (LimitWritten): its duration starts
// again from now even when value, on/off and duration are the same (the control box's renewal; before,
// an equal write kept the first end: Sim feeder 6 2026-11-08, the order ended 16:47 while renewed to 17:32)
rewritten bool
}
func (g Grid) Active() bool { return g.State == "limited" || g.State == "failsafe" }
@@ -244,7 +248,8 @@ func (c *Core) Update(ski string, useCases []string, values map[string]any) {
}
if d.Kind == KindControlBox {
// a new limit (value, on/off or duration): its end from now
if after := fmt.Sprint(d.Values["grid_limit"], d.Values["grid_limit_active"], d.Values["_limit_duration"]); after != before {
if after := fmt.Sprint(d.Values["grid_limit"], d.Values["grid_limit_active"], d.Values["_limit_duration"]); after != before || c.grid.rewritten {
c.grid.rewritten = false
c.grid.lastLimit = now
until := 0.0
if s, ok := d.Number("_limit_duration"); ok && s > 0 {
@@ -544,6 +549,7 @@ func (c *Core) LimitWritten(ski string) {
defer c.mu.Unlock()
if d := c.devices[strings.ToLower(ski)]; d != nil && d.Kind == KindControlBox {
c.grid.lastLimit = c.now()
c.grid.rewritten = true // its duration from now, with the values that follow (Update)
}
}
@@ -688,8 +694,10 @@ func (c *Core) evaluateGrid() {
case g.State == "failsafe" && g.lastLimit.Before(g.failsafeAt) && now.Sub(g.failsafeAt).Seconds() < g.FailsafeS:
// the heartbeat is back, but no new limit yet: failsafe holds
case active && limit > 0:
if g.State != "limited" || g.LimitW != limit || g.Until != int64(until) {
if g.State != "limited" || g.LimitW != limit {
g.State, g.LimitW, g.Since, g.Until = "limited", limit, now.Unix(), int64(until)
} else if g.Until != int64(until) {
g.Until = int64(until) // renewed: the same order (its id from Since) holds longer
}
default:
if g.State != "normal" {
+35
View File
@@ -535,3 +535,38 @@ func TestLimitLiftedWithoutAKnownMaximum(t *testing.T) {
t.Fatalf("lifted: %v", w)
}
}
// TestRenewedLimitHolds: the control box writes the same limit again before its duration ends (a renewal):
// the order holds 15 min from the renewal, with the same id (Sim feeder 6, 2026-11-08: the substation renewed
// every 10 min from 16:32 to 17:32, the bridge's order still ended at 16:47).
func TestRenewedLimitHolds(t *testing.T) {
h := newHarness(t, Options{PassOn: true})
h.home()
write := func() {
h.core.LimitWritten("cb01")
h.core.Update("cb01", nil, map[string]any{"grid_limit": 4200.0, "grid_limit_active": true, "_limit_duration": 900.0, "heartbeat": true})
}
write()
o1 := h.order()
if o1["state"] != "limited" || o1["until"].(float64) != float64(h.clock.Unix()+900) {
t.Fatalf("limited: %v", o1)
}
h.clock = h.clock.Add(600 * time.Second)
write()
o2 := h.order()
if o2["until"].(float64) != float64(h.clock.Unix()+900) || o2["id"] != o1["id"] || o2["from"] != o1["from"] {
t.Fatalf("renewed: %v (was %v)", o2, o1)
}
// past the first end: still limited
h.clock = h.clock.Add(400 * time.Second)
h.core.Update("cb01", nil, map[string]any{"heartbeat": true})
if o := h.order(); o["state"] != "limited" || o["active"] != true {
t.Fatalf("held past the first end: %v", o)
}
// values without a write (a read of the same limit) don't renew it: it ends at the renewal's end
h.clock = h.clock.Add(501 * time.Second)
h.core.Update("cb01", nil, map[string]any{"grid_limit": 4200.0, "grid_limit_active": true, "_limit_duration": 900.0, "heartbeat": true})
if o := h.order(); o["state"] != "normal" {
t.Fatalf("ended at the renewal's end: %v", o)
}
}