cantabile_edge, cantabile_modbus, cantabile_eebus 0.1.1289: full source

This commit is contained in:
Setti Solutions S.R.L committed 2026-11-08 16:35:35 +02:00
1 parent 165dda4479
commit 05802d6f87
57 files changed
+5928 -232

No files matched your search

+408
View File
@@ -0,0 +1,408 @@
# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
"""What the box learns about its stores from their own telemetry
(docs/methods.md A13, design note docs/design/storage-losses.md 2.4, 3.5):
battery its idle loss (the standby W, the cells' self-discharge) from
the quarter-hours it sat still: the power method (the median of
the battery's own power while idle: P⁰ = -median) and the SoC
drift method (ΔE/Δt = -P⁰ - λ·E over idle runs of at least
battery.idle_fit_min_run_h, by least squares where runs at
several charge levels exist, else P⁰ alone). Gated: at least
battery.idle_fit_min_hours idle in the last 14 days, the two
methods within battery.idle_fit_agree_pct where both exist,
P⁰ ≥ 0. A fit a day; the one in force is the median of the last
FITS_KEPT (a bad night does not move it).
dhw_tank the draw from the tank's own sensors (S.7: D = (φE_{t-1} - E_t)/Δt
+ Q - P⁰), kept per quarter-hour, as the box's own hour-of-week
profile where no hot-water forecast exists (after
dhw.draw_history_min_days); its UA from cooling curves (heater
off, no draw: ln(T̄ - T_room) falls by UA/(c_w V) per hour)
after dhw.ua_fit_min_hours, kept only within dhw.ua_fit_band of
the label's (else noted: the tank loses more than its label);
and the last time it was at the legionella temperature.
Every threshold is a Parameters row (the tariff bundle's params); without
one nothing is fitted (the plan keeps the owner's or the Parameters' value).
State in <state_dir>/storefit.json.
"""
import json
import logging
import math
import os
import statistics
import time
from datetime import datetime, timezone
from zoneinfo import ZoneInfo
log = logging.getLogger(__name__)
SLOT_S = 900
KEEP_S = 14 * 86400 # ENG: the window a fit looks at (two weeks: two of each weekday)
FITS_KEPT = 4 # ENG: the fits whose median is in force
REFIT_S = 86400 # ENG: a fit a day
WATER_WH_PER_L_K = 1.163 # physics: water's heat capacity, Wh per litre and kelvin
# the Parameters rows (docs/parameters.md; design note 10.6)
P_MIN_RUN_H = "battery.idle_fit_min_run_h"
P_MIN_HOURS = "battery.idle_fit_min_hours"
P_DEAD_BAND = "battery.idle_dead_band_w"
P_IDLE_MAX = "battery.idle_max_w"
P_AGREE = "battery.idle_fit_agree_pct"
P_DRAW_K = "dhw.draw_detect_k_per_15min"
P_UA_HOURS = "dhw.ua_fit_min_hours"
P_UA_BAND = "dhw.ua_fit_band"
P_DRAW_DAYS = "dhw.draw_history_min_days"
def _num(v):
try:
x = float(v)
except (TypeError, ValueError):
return None
return x if math.isfinite(x) else None
# -- the battery ---------------------------------------------------------------
def idle_slot(power_w: list[float], pv_w: float | None, grid_charge: bool, soc: float | None,
dead_band: float, idle_max: float) -> bool:
"""A quarter-hour the battery sat still: its power steady (max - min
within the dead band: a standby is constant, a battery following the
house is not) between -idle_max and +dead_band W, no PV on its side
(pv below the dead band, or none mapped), its grid charging off, its
charge neither empty nor full (a full battery's BMS may top it up)."""
if not power_w or grid_charge or soc is None or not 0 < soc < 100:
return False
if pv_w is not None and pv_w > dead_band:
return False
mean = sum(power_w) / len(power_w)
return -idle_max <= mean <= dead_band and max(power_w) - min(power_w) <= dead_band
def fit_battery(slots: list[dict], cap_wh: float, params: dict) -> dict | None:
"""One fit from quarter-hours [{"t", "idle", "p" (mean W, + charge),
"soc0", "soc1" (% at its start and end)}] (the last 14 days): {"standby_w",
"loss_pct_h" (None: one charge level only), "n_hours", "method", "power_w",
"soc_w"}, or None (gate not passed, or a parameter missing)."""
min_run_h, min_hours, agree = (_num(params.get(k)) for k in (P_MIN_RUN_H, P_MIN_HOURS, P_AGREE))
if min_run_h is None or min_hours is None or agree is None or not cap_wh:
return None
idle = sorted((s for s in slots if s.get("idle")), key=lambda s: s["t"])
n_hours = len(idle) * SLOT_S / 3600.0
if n_hours < min_hours:
return None
pw = [s["p"] for s in idle if s.get("p") is not None]
p_power = -statistics.median(pw) if pw else None
# runs of consecutive idle quarter-hours, at least min_run_h long: the SoC's drift over each
runs, cur = [], []
for s in idle:
if cur and s["t"] - cur[-1]["t"] != SLOT_S:
runs.append(cur)
cur = []
cur.append(s)
if cur:
runs.append(cur)
pts = [] # (stored Wh at the run's middle, loss W)
for r in runs:
h = len(r) * SLOT_S / 3600.0
if h < min_run_h or r[0].get("soc0") is None or r[-1].get("soc1") is None:
continue
de = (r[-1]["soc1"] - r[0]["soc0"]) / 100.0 * cap_wh
pts.append(((r[0]["soc0"] + r[-1]["soc1"]) / 200.0 * cap_wh, -de / h))
p_soc = lam = None
if pts:
es = [e for e, _ in pts]
if len(pts) >= 2 and max(es) - min(es) >= 0.1 * cap_wh:
# loss = P⁰ + λ·E by least squares (λ per hour, as a share of the stored energy)
me, ml = sum(es) / len(es), sum(w for _, w in pts) / len(pts)
sxx = sum((e - me) ** 2 for e in es)
slope = sum((e - me) * (w - ml) for e, w in pts) / sxx if sxx else 0.0
if slope >= 0:
lam, p_soc = slope, ml - slope * me
else:
p_soc = statistics.median(w for _, w in pts)
else:
p_soc = statistics.median(w for _, w in pts)
if p_power is None and p_soc is None:
return None
if p_power is not None and p_soc is not None:
ref = max(abs(p_power), abs(p_soc), 1e-9)
if abs(p_power - p_soc) / ref * 100.0 > agree:
return None # the two disagree: no fit this time
p0 = p_power if p_power is not None else p_soc
if p0 is None or p0 < 0:
return None
return {"standby_w": round(p0, 1), "loss_pct_h": round(lam * 100.0, 5) if lam is not None else None,
"n_hours": round(n_hours, 1), "method": "power" if p_power is not None else "soc",
"power_w": None if p_power is None else round(p_power, 1),
"soc_w": None if p_soc is None else round(p_soc, 1)}
# -- the tank --------------------------------------------------------------------
def tank_energy_wh(volume_l: float, temp_c: float, cold_c: float) -> float:
"""S.4: the stored heat above the cold water (Wh)."""
return WATER_WH_PER_L_K * volume_l * (temp_c - cold_c)
def mean_temp(top: float | None, bottom: float | None, top_share: float) -> float | None:
"""S.4: the tank's mean temperature from its sensors (both: weighted by
the top sensor's share of the volume; one: that one)."""
if top is not None and bottom is not None:
return top_share * top + (1 - top_share) * bottom
return top if top is not None else bottom
def draw_w(e_prev: float, e_now: float, heat_w: float, ua_w_k: float, volume_l: float, room_c: float,
cold_c: float, dt_h: float) -> float:
"""S.7: the hot water drawn in a step (W of heat): what the tank lost
beyond its standing loss and the heat put in, never below 0. The loss
UA(T̄ - T_room) in E: λ·E + P⁰ with λ = UA/(c_w V), P⁰ = UA(T_cw - T_room)."""
lam = ua_w_k / (WATER_WH_PER_L_K * volume_l)
phi = 1.0 - lam * dt_h
p0 = ua_w_k * (cold_c - room_c)
return max(0.0, (phi * e_prev - e_now) / dt_h + heat_w - p0)
def fit_ua(curves: list[list[tuple[float, float]]], volume_l: float) -> tuple[float, float] | None:
"""UA (W/K) from cooling runs [[(hours, T̄ - T_room), ...], ...] (heater
off, no draw): the slope of ln(ΔT) against time, pooled over the runs
(each run's own intercept); (UA, hours used) or None."""
num = den = 0.0
hours = 0.0
for run in curves:
pts = [(t, math.log(d)) for t, d in run if d > 1.0]
if len(pts) < 3:
continue
mt = sum(t for t, _ in pts) / len(pts)
my = sum(y for _, y in pts) / len(pts)
num += sum((t - mt) * (y - my) for t, y in pts)
den += sum((t - mt) ** 2 for t, _ in pts)
hours += pts[-1][0] - pts[0][0]
if den <= 0:
return None
slope = num / den # 1/h, negative while cooling
if slope >= 0:
return None
return -slope * WATER_WH_PER_L_K * volume_l, hours
class StoreFit:
"""The box's samples and fits for its batteries and tanks (one file)."""
def __init__(self, path: str, clock=time.time):
self.path, self.clock = path, clock
self.bat: dict = {} # cid -> {"slots": {t: {...}}, "fits": [...], "at": last fit time}
self.tank: dict = {} # cid -> {"draw": {t: W}, "cool": [[t, T̄ - T_room], ...] runs, "ua": {...},
# "legionella": last ts, "last": {t, e, heat}}
try:
with open(path) as f:
raw = json.load(f)
self.bat = {k: {"slots": {int(t): v for t, v in d.get("slots", {}).items()},
"fits": d.get("fits", []), "at": d.get("at", 0)} for k, d in raw.get("battery", {}).items()}
self.tank = {k: {"draw": {int(t): v for t, v in d.get("draw", {}).items()}, "cool": d.get("cool", []),
"ua": d.get("ua"), "legionella": d.get("legionella"), "last": d.get("last"),
"since": d.get("since")} for k, d in raw.get("tank", {}).items()}
except (OSError, ValueError, AttributeError):
pass
self._cur: dict = {} # (cid, slot) -> samples in the open quarter-hour
# -- battery ------------------------------------------------------------------
def sample_battery(self, cid: str, now: float, soc: float | None, power_w: float | None, pv_w: float | None,
grid_charge: bool):
"""A reading of a battery (once a minute or so): closed into its
quarter-hour when the next one starts."""
slot = int(now // SLOT_S * SLOT_S)
cur = self._cur.get(("b", cid))
if cur is not None and cur["t"] != slot:
self._close_battery(cid, cur)
cur = None
if cur is None:
cur = self._cur[("b", cid)] = {"t": slot, "p": [], "soc": [], "pv": [], "grid": False}
if power_w is not None:
cur["p"].append(float(power_w))
if soc is not None:
cur["soc"].append(float(soc))
if pv_w is not None:
cur["pv"].append(float(pv_w))
cur["grid"] = cur["grid"] or bool(grid_charge)
def _close_battery(self, cid, cur):
if not cur["p"] and not cur["soc"]:
return
d = self.bat.setdefault(cid, {"slots": {}, "fits": [], "at": 0})
d["slots"][cur["t"]] = {"p": sum(cur["p"]) / len(cur["p"]) if cur["p"] else None,
"pmin": min(cur["p"]) if cur["p"] else None, "pmax": max(cur["p"]) if cur["p"] else None,
"soc0": cur["soc"][0] if cur["soc"] else None, "soc1": cur["soc"][-1] if cur["soc"] else None,
"pv": max(cur["pv"]) if cur["pv"] else None, "grid": cur["grid"]}
def fit_batteries(self, caps: dict, params: dict, now: float | None = None) -> dict:
"""A fit a day per battery (caps: cid -> capacity Wh in force): the
new fits; old slots dropped."""
now = self.clock() if now is None else now
dead, idle_max = _num(params.get(P_DEAD_BAND)), _num(params.get(P_IDLE_MAX))
out = {}
for cid, d in self.bat.items():
d["slots"] = {t: v for t, v in d["slots"].items() if t >= now - KEEP_S}
if now - d.get("at", 0) < REFIT_S or dead is None or idle_max is None or not caps.get(cid):
continue
d["at"] = now
slots = []
for t, v in sorted(d["slots"].items()):
ps = [x for x in (v.get("pmin"), v.get("pmax")) if x is not None]
soc = v.get("soc0") if v.get("soc0") is not None else v.get("soc1")
idle = bool(ps) and idle_slot(ps, v.get("pv"), v.get("grid", False), soc, dead, idle_max)
slots.append({"t": t, "idle": idle, "p": v.get("p"), "soc0": v.get("soc0"), "soc1": v.get("soc1")})
f = fit_battery(slots, caps[cid], params)
if f is not None:
f["at"] = int(now)
d["fits"] = (d.get("fits") or [])[-(FITS_KEPT - 1):] + [f]
out[cid] = f
return out
def battery_in_force(self, cid: str) -> dict | None:
"""The fit in force: the median of the last fits' standby (and
self-discharge, where fitted), with the newest's hours, method and
time; None without a fit."""
fits = (self.bat.get(cid) or {}).get("fits") or []
if not fits:
return None
lams = [f["loss_pct_h"] for f in fits if f.get("loss_pct_h") is not None]
last = fits[-1]
return {"standby_w": round(statistics.median(f["standby_w"] for f in fits), 1),
"loss_pct_h": statistics.median(lams) if lams else None,
"n_hours": last["n_hours"], "method": last["method"], "at": last["at"], "fits": len(fits)}
# -- tank ---------------------------------------------------------------------
def sample_tank(self, cid: str, now: float, temp_c: float | None, room_c: float, heat_w: float | None,
facts: dict):
"""A reading of a tank (its mean temperature, the room, the heat put
in: W of heat): per quarter-hour the draw (S.7) and, while it cools
alone, the cooling curve; the last time it held the legionella
temperature."""
if temp_c is None or not facts.get("volume_l"):
return
d = self.tank.setdefault(cid, {"draw": {}, "cool": [], "ua": None, "legionella": None, "last": None,
"since": None})
d["since"] = d.get("since") or int(now)
lt = _num(facts.get("legionella_temp_c"))
if lt is not None and temp_c >= lt:
d["legionella"] = int(now)
slot = int(now // SLOT_S * SLOT_S)
cur = self._cur.get(("t", cid))
if cur is not None and cur["t"] != slot:
self._close_tank(cid, cur, facts)
cur = None
if cur is None:
cur = self._cur[("t", cid)] = {"t": slot, "temp": [], "heat": [], "room": room_c}
cur["temp"].append(float(temp_c))
cur["heat"].append(float(heat_w or 0.0))
cur["room"] = room_c
def _close_tank(self, cid, cur, facts):
d = self.tank[cid]
temp, heat = cur["temp"][-1], sum(cur["heat"]) / len(cur["heat"])
vol, cold = float(facts["volume_l"]), _num(facts.get("cold_water_c"))
ua = _num(facts.get("ua_w_k"))
last = d.get("last")
if cold is not None and ua and last and cur["t"] - last["t"] == SLOT_S:
e0, e1 = tank_energy_wh(vol, last["temp"], cold), tank_energy_wh(vol, temp, cold)
d["draw"][cur["t"]] = round(draw_w(e0, e1, heat, ua, vol, cur["room"], cold, SLOT_S / 3600.0), 1)
# cooling alone: heater off and the fall no faster than the draw threshold allows
k = _num(facts.get("draw_detect_k"))
alone = heat < 1.0 and k is not None and -k <= last["temp"] - temp <= k
runs = d["cool"]
if alone:
if runs and runs[-1] and runs[-1][-1][0] == last["t"]:
runs[-1].append([cur["t"], temp - cur["room"]])
else:
runs.append([[last["t"], last["temp"] - cur["room"]], [cur["t"], temp - cur["room"]]])
d["last"] = {"t": cur["t"], "temp": temp}
cut = cur["t"] - KEEP_S
d["draw"] = {t: v for t, v in d["draw"].items() if t >= cut}
d["cool"] = [r for r in d["cool"] if r and r[-1][0] >= cut]
def fit_tank(self, cid: str, facts: dict, params: dict) -> dict | None:
"""UA from the cooling runs, where the hours are enough: {"ua_w_k",
"hours", "label_ua_w_k", "kept": within the band of the label's, "at"}."""
d = self.tank.get(cid)
hours_min, band = _num(params.get(P_UA_HOURS)), params.get(P_UA_BAND)
if not d or hours_min is None or not facts.get("volume_l"):
return None
curves = [[((t - r[0][0]) / 3600.0, dlt) for t, dlt in r] for r in d["cool"] if len(r) >= 3]
got = fit_ua(curves, float(facts["volume_l"]))
if got is None or got[1] < hours_min:
return d.get("ua")
ua, hours = got
label = _num(facts.get("label_ua_w_k"))
lo, hi = _band(band)
kept = label is None or (lo is not None and lo * label <= ua <= hi * label)
d["ua"] = {"ua_w_k": round(ua, 3), "hours": round(hours, 1), "label_ua_w_k": label, "kept": bool(kept),
"at": int(self.clock())}
return d["ua"]
def tank_learnt(self, cid: str) -> dict:
"""What the plan takes from the box's fits: ua_w_k where kept; the
last legionella time; the draw history's days."""
d = self.tank.get(cid) or {}
out = {"legionella": d.get("legionella"), "ua": d.get("ua")}
if d.get("ua") and d["ua"].get("kept"):
out["ua_w_k"] = d["ua"]["ua_w_k"]
if d.get("draw"):
out["draw_days"] = round((max(d["draw"]) - min(d["draw"]) + SLOT_S) / 86400.0, 2)
return out
def draw_profile(self, cid: str, start: int, steps: int, tz: str, min_days: float | None) -> list[float] | None:
"""The box's own draw forecast: per step the mean of the same
quarter-hour of the week in the history, else of the day; None
before min_days of history (or without the parameter)."""
d = self.tank.get(cid) or {}
draw = d.get("draw") or {}
if min_days is None or not draw or (max(draw) - min(draw) + SLOT_S) / 86400.0 < min_days:
return None
zone = ZoneInfo(tz or "UTC")
def keys(t):
lt = datetime.fromtimestamp(t, timezone.utc).astimezone(zone)
q = lt.hour * 4 + lt.minute // 15
return lt.weekday() * 96 + q, q
week, day = {}, {}
for t, w in draw.items():
kw, kd = keys(t)
week.setdefault(kw, []).append(w)
day.setdefault(kd, []).append(w)
out = []
for k in range(steps):
kw, kd = keys(start + k * SLOT_S)
xs = week.get(kw) or day.get(kd) or []
out.append(sum(xs) / len(xs) if xs else 0.0)
return out
def draw_now(self, cid: str) -> float | None:
"""The last quarter-hour's draw (W; published as dhw.power)."""
draw = (self.tank.get(cid) or {}).get("draw") or {}
return draw[max(draw)] if draw else None
def save(self):
raw = {"battery": {k: {"slots": d["slots"], "fits": d.get("fits", []), "at": d.get("at", 0)}
for k, d in self.bat.items()},
"tank": self.tank}
tmp = self.path + ".tmp"
try:
with open(tmp, "w") as f:
json.dump(raw, f)
os.replace(tmp, self.path)
except OSError as e:
log.warning("storefit: %s", e)
def _band(raw) -> tuple[float | None, float | None]:
"""dhw.ua_fit_band: {"min": 0.5, "max": 3} (or [0.5, 3], or its JSON)."""
if isinstance(raw, str):
try:
raw = json.loads(raw)
except ValueError:
return None, None
if isinstance(raw, dict):
return _num(raw.get("min")), _num(raw.get("max"))
if isinstance(raw, (list, tuple)) and len(raw) == 2:
return _num(raw[0]), _num(raw[1])
return None, None