cantabile_edge, cantabile_modbus, cantabile_eebus 0.1.629: full source

This commit is contained in:
Setti Solutions S.R.L committed 2026-11-03 23:26:41 +02:00
1 parent d5fbcacaa4
commit 85edd56ec8
46 files changed
+3518 -267

No files matched your search

+34 -2
View File
@@ -21,6 +21,7 @@ from .consent import Consent
from .controller import Controller
from .inventory import Inventory
from .dashboards import Dashboards
from .gridorder import GridOrders
from .devpage import App, Devices
from .joinpage import Fleet
from .mapping import Mapping, convert, scaled, value_of
@@ -61,9 +62,14 @@ class Agent:
self.control = Controller(cfg, mapping, self.consent, sink) if mapping.controls else None
if self.control is not None and hasattr(sink, "on_command"):
sink.on_command = self.control.command
# the grid operator's orders (EEBUS LPC, gridorder.py): the controller's,
# or, on a site without controls, checked and told to the cloud only
self.gridorders = self.control.gridorders if self.control is not None else GridOrders(cfg.state_dir)
# the devices' specs for the cloud (inventory.py)
self.inventory = Inventory(cfg, mapping, self.consent, sink,
self.control.policy if self.control is not None else None)
if self.control is not None:
self.inventory.ev_phases = self.control.ev_phases
self.client = None
self.exit_code = 0 # RESTART: start again (restart())
# A mapping for a site without one (propose.py): the HA add-on
@@ -234,10 +240,10 @@ class Agent:
async def inventory_loop(self):
"""The inventory at connecting, then every 30 minutes if it changed
(and once a day anyway)."""
(and once a day anyway); every minute while the link is not connected."""
while not self.stop.is_set():
try:
await asyncio.wait_for(self.inventory_now.wait(), 1800)
await asyncio.wait_for(self.inventory_now.wait(), 60 if self.inventory.waiting else 1800)
except asyncio.TimeoutError:
pass
self.inventory_now.clear()
@@ -263,6 +269,27 @@ class Agent:
time.strftime("%H:%M", time.gmtime(start)), seq, len(records),
self.queue.depth(), self.queue.dropped())
async def grid_order(self, payload) -> bool:
"""A message on cantabile-eebus/gridorder (announce.py): the
controller's when there is one (limits and a plan within them);
otherwise only checked and told to the cloud (nothing to limit)."""
if self.control is not None:
return await self.control.grid_order(payload)
changed, _ = self.gridorders.take(payload)
await self.grid_report()
return changed
async def grid_report(self):
"""The grid operator's order to the cloud as an action per
quarter-hour (gridorder.py action()): fleet's market ledger exempts
those slots."""
if self.control is not None:
return await self.control.grid_report()
a = self.gridorders.action()
pub = getattr(self.sink, "publish", None)
if a is not None and pub is not None:
await pub("action", a)
async def ticker(self):
i = self.cfg.interval_s
while not self.stop.is_set():
@@ -271,6 +298,11 @@ class Agent:
await asyncio.wait_for(self.stop.wait(), max(0.0, end - time.time()))
except asyncio.TimeoutError:
self.close_window(end)
if self.control is None: # the controller's own loop reports otherwise
try:
await self.grid_report()
except Exception as e:
log.warning("grid order report: %s", e)
async def uploader(self):
wait = 1.0
+174 -4
View File
@@ -27,6 +27,15 @@ building and the home, and what the agent does to each device):
sensor set_<control> per control: the value the agent wants it at now
and from whom (plan, cloud, building, owner, safe
default), whether it acts, the limits per level
sensor market_<contract>, market_position[_building], market_price, market_actuator_<device>
the shadow market (market.json, a signed `market`
bundle): per contract the exchange with its
counterpart (kW in the last settled quarter-hour,
a sentence in plain words, the period), the net
position, the shared energy's price, per border
actuator its contract target vs its state now;
sensors only, unavailable when the bundle is
stale (cantabile/<site>/market/availability)
On a building's own box (flats.json, a signed `flats` bundle from the
cloud: bundles.py) each flat is a device of its own ("Flat", via the
building's Cantabile device, area "Flats"): its grid power, its
@@ -229,6 +238,162 @@ class Announcer:
"json_attributes_template": "{{ {'commands': value_json.commands} | tojson }}", **common}
return out
# -- the shadow market (a `market` bundle: bundles.py) -------------------
def _market_avail(self) -> dict:
"""Unavailable when the agent is offline or the bundle is stale."""
return {"availability": [{"topic": f"{self.base}/availability"}, {"topic": f"{self.base}/market/availability"}],
"availability_mode": "all"}
@staticmethod
def _party(c: dict, lang: str) -> str:
p = c.get("counterpart") or {}
if p.get("type") == "homes":
return names.name("mk_flats", lang, p.get("count") or "")
return p.get("name") or p.get("type") or "?"
def _market_objects(self, m: dict | None) -> dict:
"""Per contract the exchange with its counterpart, the net position
of each of the box's nodes, the shared energy's price, per border
actuator its contract target: sensors only (never a control: the
actuators keep their own entities and protection)."""
ctl = getattr(self.agent, "control", None)
if m is None or (ctl is not None and ctl.mode() == "off"):
return {}
dev, out, lang = self._device(), {}, self.lang
common = {"state_topic": f"{self.base}/market", "json_attributes_topic": f"{self.base}/market",
**self._market_avail(), "device": dev}
for c in m.get("contracts") or []:
k = _slug(c["id"])
out[("sensor", f"market_{k}")] = {
"name": names.name("market_exchange", lang, self._party(c, lang)), "unique_id": f"{self.uid}_market_{k}",
"unit_of_measurement": "kW", "device_class": "power", "state_class": "measurement", "icon": "mdi:swap-horizontal",
"value_template": "{%% set v = value_json.contracts['%s'].kw %%}{{ v if v is not none else none }}" % k,
"json_attributes_template": "{{ value_json.contracts['%s'] | tojson }}" % k, **common}
nodes = {n.get("id"): n.get("name") for n in m.get("nodes") or []}
for p in m.get("positions") or []:
kind = str(p.get("node", "")).split(":")[0]
obj = "market_position" if kind == "site" else f"market_position_{_slug(kind)}"
out[("sensor", obj)] = {
"name": names.name("market_position", lang) if kind == "site" else
names.name("market_position_of", lang, nodes.get(p.get("node")) or kind),
"unique_id": f"{self.uid}_{obj}", "unit_of_measurement": "kWh", "state_class": "measurement",
"icon": "mdi:scale-balance",
"value_template": "{{ value_json.positions['%s'].net_kwh }}" % obj,
"json_attributes_template": "{{ value_json.positions['%s'] | tojson }}" % obj, **common}
if m.get("contracts"):
out[("sensor", "market_price")] = {
"name": names.name("market_price", lang), "unique_id": f"{self.uid}_market_price",
"unit_of_measurement": "EUR/kWh", "suggested_display_precision": 3, "state_class": "measurement",
"icon": "mdi:cash-multiple",
"value_template": "{% set v = value_json.price.now %}{{ (v / 100) | round(4) if v is not none else none }}",
"json_attributes_template": "{{ value_json.price | tojson }}", **common}
for a in m.get("actuators") or []:
k = _slug(a["device"])
out[("sensor", f"market_actuator_{k}")] = {
"name": names.name("market_actuator", lang, a.get("name") or a["device"]),
"unique_id": f"{self.uid}_market_actuator_{k}", "icon": "mdi:electric-switch",
"value_template": "{{ value_json.actuators['%s'].target }}" % k,
"json_attributes_template": "{{ value_json.actuators['%s'] | tojson }}" % k, **common}
return out
def _actual(self, device: str):
"""A border actuator's state in HA now, from the agent's own view of
the device's controls (None: not one the agent watches)."""
ctl = getattr(self.agent, "control", None)
col = getattr(ctl, "col", None)
if ctl is None or col is None:
return None
for c in ctl.controls:
if getattr(c, "device", "") == device:
for eid in (c.entities or {}).values():
st = col.state(eid)
if st is not None:
return st
return None
def market_state(self, m: dict) -> dict:
"""The market's values for HA: per contract (kW in the last settled
quarter-hour, a sentence in plain words, the details), positions,
the price now, the actuators' target and actual state."""
lang = self.lang
num = names.number
out = {"contracts": {}, "positions": {}, "actuators": {}, "price": {}, "shadow": True, "stale": bool(m.get("stale")),
"note": names.name("mk_shadow_note", lang), "issued": m.get("issued"), "slot": m.get("slot")}
links = {lk.get("id"): lk for lk in m.get("links") or []}
prices, applying = {}, []
for c in m.get("contracts") or []:
k = _slug(c["id"])
last, slot, per = c.get("last") or None, c.get("slot") or {}, c.get("period") or {}
party = self._party(c, lang)
head = names.name("mk_sells" if c["direction"] == "sells" else "mk_buys", lang, party)
kw = None
if last and last.get("measured"):
d = float(last.get("delivered_kwh") or 0)
kw = round(d * 4, 3)
amount = float(last.get("max_kwh") or 0) or float(last.get("guaranteed_kwh") or 0)
part = names.name("mk_slot", lang, num(d, lang, 2), num(amount, lang, 2)) if amount > 0 else \
names.name("mk_slot_open", lang, num(d, lang, 2))
else:
part = names.name("mk_no_value", lang)
price = slot.get("price_ct")
bits = [f"{head}: {part}"]
if price is not None:
bits.append(f"{num(float(price), lang)} ct/kWh")
prices[k] = price
if slot.get("applies"):
applying.append(float(price))
if not slot.get("applies"):
bits.append(names.name("mk_not_now", lang))
bits.append(names.name("mk_shadow", lang))
details = []
if last and last.get("kind") and last.get("deviation_kwh"):
dev = num(abs(float(last["deviation_kwh"])), lang, 2)
details.append(names.name("mk_deviation_self" if last.get("cause") == "self" else "mk_deviation_other", lang, dev))
if last.get("exempt"):
details.append(names.name("mk_exempt", lang, last.get("exempt_why") or ""))
pname = names.name("mk_" + (per.get("period") or "month"), lang) if ("mk_" + (per.get("period") or "month")) in names.NAMES \
else per.get("period", "")
period = names.name("mk_period", lang, pname, num(float(per.get("delivered_kwh") or 0), lang),
num(float(per.get("amount_eur") or 0), lang, 2))
if per.get("penalties_paid_eur") or per.get("penalties_received_eur"):
period += " · " + names.name("mk_penalties", lang, num(float(per.get("penalties_paid_eur") or 0), lang, 2),
num(float(per.get("penalties_received_eur") or 0), lang, 2))
meas = (links.get(c.get("link")) or {}).get("measurement") or {}
out["contracts"][k] = {
"kw": kw, "summary": " · ".join(bits), "details": "; ".join(details), "period_words": period,
"contract": c["id"], "name": c.get("name", ""), "direction": c["direction"], "counterpart": party,
"counterpart_type": (c.get("counterpart") or {}).get("type", ""), "link_kind": c.get("link_kind", ""),
"slot": slot, "last": last, "period": per, "kwh_period": per.get("delivered_kwh"), "price_ct": price,
"penalty_last_eur": (last or {}).get("penalty_eur"), "measurement": meas.get("kind", ""),
"trust": meas.get("trust", ""), "shadow": True}
out["price"] = {"now": round(sum(applying) / len(applying), 3) if applying else None, "unit": "ct/kWh",
"per_contract": prices}
for p in m.get("positions") or []:
kind = str(p.get("node", "")).split(":")[0]
obj = "market_position" if kind == "site" else f"market_position_{_slug(kind)}"
out["positions"][obj] = dict(p)
for a in m.get("actuators") or []:
k = _slug(a["device"])
tgt = a.get("target") or {}
actual = self._actual(a["device"])
if actual is None and a.get("last"):
actual = a["last"].get("value")
def say(x):
return names.name(f"mk_state_{x}", lang) if f"mk_state_{x}" in names.NAMES else \
(str(x) if x not in (None, "") else names.name("mk_unknown", lang))
kwb = f" ({num(float(tgt['kw']), lang)} kW)" if tgt.get("kw") is not None else ""
words = (f"{names.name('mk_target', lang)}: **{say(tgt.get('state'))}**{kwb} · {names.name('mk_actual', lang)}: "
f"**{say(actual)}** · {names.name('mk_protection', lang, a.get('protection') or 'none')} · "
+ names.name("mk_default", lang, say(a.get("default_state")), int((a.get("fallback_s") or 0) // 60)))
out["actuators"][k] = {"target": tgt.get("state"), "target_kw": tgt.get("kw"), "why": tgt.get("why", ""),
"actual": actual, "agrees": actual is not None and str(actual) == str(tgt.get("state")),
"words": words, "device": a["device"], "name": a.get("name", ""), "link": a.get("link"),
"protection": a.get("protection"), "default_state": a.get("default_state"),
"default_set": a.get("default_set"), "fallback_s": a.get("fallback_s"),
"last": a.get("last"), "shadow": True}
return out
def objects(self) -> dict:
"""Every discovery config HA should have now: (node, component,
object) -> config; node is the site's or a flat's."""
@@ -236,7 +401,8 @@ class Announcer:
tariff, model = self.bundles.tariff_now(now), self.bundles.model_info()
out = {}
for (comp, obj), conf in {**self._configs(), **self._plan_objects(),
**self._exchange_objects(tariff, model)}.items():
**self._exchange_objects(tariff, model),
**self._market_objects(self.bundles.market_now(now))}.items():
out[(self.uid, comp, obj)] = conf
out.update(self._flat_objects(self.bundles.flat_list()))
# The entity ids themselves (HA 2025.10+): without them HA makes them
@@ -332,6 +498,10 @@ class Announcer:
if ctl is not None and ctl.received:
# kept (retained) across restarts until new ones come
await c.publish(f"{self.base}/received", json.dumps({"commands": self.received_list(ctl)}), retain=True)
market = self.bundles.market_now(now)
if market is not None:
await c.publish(f"{self.base}/market/availability", "offline" if market["stale"] else "online", retain=True)
await c.publish(f"{self.base}/market", json.dumps(self.market_state(market), default=str), retain=True)
for f in self.bundles.flat_list()[:MAX_FLATS]:
await c.publish(f"{self.base}/flat/{_slug(f['id'])}", json.dumps(self.flat_state(f, now)), retain=True)
@@ -371,13 +541,13 @@ class Announcer:
async def _grid_orders(self, c):
"""The EEBUS bridge's grid order (gridorder.py), to the
controller: the grid operator's limit as a higher-rank decision."""
ctl = getattr(self.agent, "control", None)
if ctl is None:
take = getattr(self.agent, "grid_order", None)
if take is None:
return
def on(topic, payload):
if topic == gridorder.TOPIC and payload:
asyncio.ensure_future(ctl.grid_order(payload))
asyncio.ensure_future(take(payload))
c.on_message = on
try:
await c.subscribe(gridorder.TOPIC)
+247 -6
View File
@@ -1,5 +1,6 @@
# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
"""Data bundles the optimiser reads: tariffs and the forecast model.
"""Data bundles the optimiser reads: tariffs and the forecast model (and,
for Home Assistant only, a building's flats and the shadow market).
Both arrive as signed commands; the link checks the signature with the
bundle key, the kind, site and expiry, keeps only the newest, and writes the
@@ -24,10 +25,35 @@ Model v1 (the forecasts' data; the ML in ml/ is a placeholder, 2026-10-28):
hour_of_week = weekday (Monday 0) * 24 + hour, in the site's time zone.
Without a model (or a series): the same quarter hour yesterday from the
agent's own history (inputs.History), else 0.
Optional (2026-10-30; an older agent ignores them):
- per series "series": {"start": <unix, a quarter hour>, "step_s": 900,
"values": [at most 400 numbers]}: the cloud's trained forecast (W) for
the next ~48 h; where it covers a step it is taken, elsewhere the
hour_of_week profile.
- "rooms": {"<key>": {"r_k_per_kw": 0.5-200, "c_kwh_per_k": 0.1-100,
"power": "thermal"|"electric" (default thermal), ...}}: a room's R and C
identified in the cloud from its history (electric: fitted against the
heating's electric power; inputs.model_state converts with the cop).
Only from a model for this site (not "*"). A heating or cooling control
takes its room by its id, its id without _heating/_cooling/_heat/_cool,
its area, or, as the site's only such control, the model's only room
(room_rc). The mapping's own r_k_per_kw/c_kwh_per_k win.
- forecasts "base_load_w" (2026-11-03, Finding A2-a): the load without the
devices the box plans (load.power less heatpump.power, ac.power and
ev.power where the site has those controls); the plan's load. A model
without it: its load_w only where the box has no meter of a planned
device inside the load (inputs.model_state), else the box's history.
- per room "gain_w" (a constant internal gain, W of heat, or 24 values by
local hour) and "solar_w_per_kw" (W of heat per kW/m² of global
irradiance) (2026-11-03, Finding B6-a): the fit's other terms, taken
into the room's model with R and C (room_rc). Absent: 0, as before.
A malformed series or room refuses the whole bundle.
"""
import json
import logging
import math
import os
import re
import time
from dataclasses import dataclass
from datetime import datetime, timezone
@@ -85,14 +111,60 @@ def _check_tariff(d: dict):
raise ValueError("no import price")
SERIES_MAX = 400 # a model's series: steps of 900 s (~4 days)
ROOM_R = (0.5, 200.0) # K/kW
ROOM_C = (0.1, 100.0) # kWh/K
ROOM_SUFFIX = re.compile(r"_(heating|cooling|heat|cool)$")
# a room's fitted gains (Finding B6-a), as the planner takes them: outside
# these the fit's artefact (a negative sun, a gain above any home's) is cut
ROOM_GAIN_W = (-2000.0, 5000.0) # W of heat, internal (people, appliances)
ROOM_SOLAR_M2 = (0.0, 50.0) # W of heat per W/m² of global irradiance
def _clip(x: float, lo_hi) -> float:
return min(max(float(x), lo_hi[0]), lo_hi[1])
def _finite(x) -> bool:
return isinstance(x, (int, float)) and not isinstance(x, bool) and math.isfinite(x)
def _check_model(d: dict):
if d.get("v") != 1 or d.get("kind") != "model":
raise ValueError("not a v1 model")
for name, f in (d.get("forecasts") or {}).items():
if f.get("profile") != "hour_of_week" or len(f.get("values") or []) != 168:
if not isinstance(f, dict) or f.get("profile") != "hour_of_week" or len(f.get("values") or []) != 168:
raise ValueError(f"{name}: an hour_of_week profile of 168 values")
if not all(isinstance(x, (int, float)) for x in f["values"]):
raise ValueError(f"{name}: numbers")
s = f.get("series")
if s is None:
continue
if not isinstance(s, dict) or s.get("step_s") != 900 or not _finite(s.get("start")) or s["start"] % 900:
raise ValueError(f"{name}: a series in steps of 900 s from a quarter hour")
v = s.get("values")
if not isinstance(v, list) or len(v) > SERIES_MAX or not all(_finite(x) for x in v):
raise ValueError(f"{name}: a series of at most {SERIES_MAX} numbers")
rooms = d.get("rooms")
if rooms is None:
return
if not isinstance(rooms, dict):
raise ValueError("rooms: an object")
for key, r in rooms.items():
if not isinstance(r, dict):
raise ValueError(f"room {key}: an object")
rk, ck = r.get("r_k_per_kw"), r.get("c_kwh_per_k")
if not _finite(rk) or not ROOM_R[0] <= rk <= ROOM_R[1]:
raise ValueError(f"room {key}: r_k_per_kw {ROOM_R[0]}-{ROOM_R[1]}")
if not _finite(ck) or not ROOM_C[0] <= ck <= ROOM_C[1]:
raise ValueError(f"room {key}: c_kwh_per_k {ROOM_C[0]}-{ROOM_C[1]}")
if r.get("power", "thermal") not in ("thermal", "electric"):
raise ValueError(f"room {key}: power thermal or electric")
g = r.get("gain_w")
if g is not None and not (_finite(g) or (isinstance(g, list) and len(g) == 24 and all(_finite(x) for x in g))):
raise ValueError(f"room {key}: gain_w a number or 24 numbers (by local hour)")
if r.get("solar_m2") is not None and not _finite(r["solar_m2"]):
raise ValueError(f"room {key}: solar_m2 a number")
def _check_flats(d: dict):
@@ -108,6 +180,32 @@ def _check_flats(d: dict):
raise ValueError("flat label: a string")
MARKET_STALE_S = 4 * 900 # without stale_after_s in the bundle: four slots
def _check_market(d: dict):
"""The shadow market's values for this box's own nodes (fleet's
marketbundle.go, the market's step 1.5). Written by the link from a
signed `market` bundle; shown in HA (announce.py, dashboards.py), never
acted on: a bundle that is not marked shadow-only is refused."""
if d.get("v") != 1 or d.get("kind") != "market":
raise ValueError("not a v1 market bundle")
if d.get("shadow") is not True or d.get("commands") != "none":
raise ValueError("a market bundle is shadow only (commands: none)")
for key, most in (("contracts", 200), ("links", 200), ("actuators", 100), ("positions", 10), ("nodes", 10)):
v = d.get(key) or []
if not isinstance(v, list) or len(v) > most:
raise ValueError(f"{key}: a list of at most {most}")
for c in d.get("contracts") or []:
if not isinstance(c.get("id"), str) or not c["id"] or len(c["id"]) > 80:
raise ValueError("contract id: a string")
if c.get("direction") not in ("sells", "buys"):
raise ValueError("contract direction: sells or buys")
for a in d.get("actuators") or []:
if not isinstance(a.get("device"), str) or not a["device"] or len(a["device"]) > 80:
raise ValueError("actuator device: a string")
@dataclass
class Prices:
import_ct: list[float]
@@ -115,12 +213,49 @@ class Prices:
note: str # what the prices are ("tariff <id>", "flat fallback ...")
def _ahead_terms(ah, start: int, step_s: int, steps: int, terms) -> list | None:
"""A contract's coming slots (fleet marketbundle.go "ahead": windows of
slot indices with their amounts, the price as [count, ct] runs) as the
plan's steps: per step None (outside its windows or the slots told) or
terms(price, guaranteed_kwh, minimum_kwh, max_kwh). None when the
contract has no usable "ahead" (the caller then holds its slot's terms)."""
if not isinstance(ah, dict):
return None
try:
a0, astep, n = int(ah["start"]), int(ah.get("step_s") or 900), int(ah.get("slots") or 0)
prices = []
for cnt, ct in ah.get("price_ct") or []:
prices += [float(ct)] * int(cnt)
wins = [(int(w["from"]), int(w["to"]), w) for w in ah.get("windows") or []]
except (KeyError, TypeError, ValueError):
return None
if astep <= 0 or n <= 0 or n > 2000 or len(prices) < n:
return None
by_slot: dict[int, dict] = {}
for f, t, w in wins:
for i in range(max(0, f), min(n, t)):
by_slot[i] = w
out = []
for k in range(steps):
i = (start + k * step_s - a0) // astep
w = by_slot.get(i) if 0 <= i < n else None
if w is None:
out.append(None)
continue
try:
out.append(terms(prices[i], w.get("guaranteed_kwh"), w.get("minimum_kwh"), w.get("max_kwh")))
except (TypeError, ValueError):
out.append(None)
return out
class Bundles:
def __init__(self, state_dir: str, site: str, default_price_ct: float = 30.0):
self.site, self.default = site, default_price_ct
self.tariff = _File(os.path.join(state_dir, "tariff.json"), _check_tariff)
self.model = _File(os.path.join(state_dir, "model.json"), _check_model)
self.flats = _File(os.path.join(state_dir, "flats.json"), _check_flats)
self.market = _File(os.path.join(state_dir, "market.json"), _check_market)
self.flat: float | None = None # the last known tariff's mean import price
def stamps(self):
@@ -136,16 +271,19 @@ class Bundles:
imp = [x for x in t["import"] if x is not None]
self.flat = sum(imp) / len(imp)
flat = self.flat if self.flat is not None else self.default
# feed-in without a price is counted at 0 ct: the plan then values PV
# export at nothing (it may curtail or self-consume more), so its note says so
if t is None:
note = "no tariff yet: default price" if self.flat is None else "no tariff: last known flat price"
return Prices([flat] * steps, [0.0] * steps, note)
return Prices([flat] * steps, [0.0] * steps, note + "; feed-in at 0 ct/kWh")
expired = now >= t.get("expires", 0)
out_i, out_e, outside = [], [], 0
out_i, out_e, outside, no_export = [], [], 0, 0
for k in range(steps):
i = (start + k * step_s - t["start"]) // 900
pi = t["import"][i] if not expired and 0 <= i < len(t["import"]) else None
pe = (t.get("export") or [])[i] if not expired and 0 <= i < len(t.get("export") or []) else None
outside += pi is None
no_export += pe is None
out_i.append(pi if pi is not None else flat)
out_e.append(pe if pe is not None else 0.0)
if expired:
@@ -154,6 +292,10 @@ class Bundles:
note = f"tariff {t.get('id')}; {outside} of {steps} steps at the flat {flat:.1f} ct/kWh"
else:
note = f"tariff {t.get('id')}"
if no_export == steps:
note += "; feed-in at 0 ct/kWh"
elif no_export:
note += f"; feed-in at 0 ct/kWh in {no_export} of {steps} steps (no export price)"
return Prices(out_i, out_e, note)
def tariff_now(self, now: float) -> dict | None:
@@ -178,7 +320,8 @@ class Bundles:
if m is None or m.get("site") not in (self.site, "*"):
return None
return {"id": m.get("id"), "source": m.get("source") or m.get("id"), "issued": m.get("issued"),
"expires": m.get("expires"), "series": sorted((m.get("forecasts") or {}))}
"expires": m.get("expires"), "series": sorted((m.get("forecasts") or {})),
"rooms": sorted(m.get("rooms") or {}) if m.get("site") == self.site else []}
def flat_list(self) -> list[dict]:
d = self.flats.get()
@@ -188,6 +331,69 @@ class Bundles:
return []
return list(d.get("flats") or [])
def market_now(self, now: float) -> dict | None:
"""The market bundle for HA, or None (none, another site's, expired,
or nothing in it). "stale": older than its stale_after_s (the
entities go unavailable then)."""
d = self.market.get()
if d is None or d.get("site") not in (self.site,) or (d.get("expires") and d["expires"] <= now):
return None
if not (d.get("contracts") or d.get("actuators")):
return None
age = now - max(d.get("issued") or 0, d.get("slot") or 0)
return dict(d, stale=age > float(d.get("stale_after_s") or MARKET_STALE_S), age_s=int(age))
def market_for_model(self, start: int, step_s: int, steps: int, now: float) -> list[dict]:
"""The contracts in force as energy sources and sinks for the plan
(the market's step 2; shadow: the plan only, no commands). Per
contract: id, name, direction (buys: an import source, sells: an
export sink), price_ct, guaranteed_w (firm), minimum_wh (take-or-pay,
per step), max_w (0: none), from_step, to_step (the plan's steps it
applies in) and, from a bundle with the coming slots, terms: per plan
step None (it does not apply) or {price_ct, guaranteed_w, minimum_wh,
max_w}; the scalars are then those of its first step.
The coming slots (a contract's "ahead", fleet marketbundle.go since
market-polish): each step gets its own slot's terms (window, amounts,
price) as far as the bundle tells them, while the bundle is fresh.
A bundle without them (an older fleet) carries one slot's terms; they
are held for the steps while the bundle is fresh (its slot .. slot +
stale_after_s), nothing beyond: the plan never assumes a contract it
hasn't been told of."""
d = self.market_now(now)
if d is None or d.get("stale"):
return []
slot = int(d.get("slot") or 0)
h = int(d.get("step_s") or 900) / 3600.0 # the bundle's slot in hours: kWh per slot -> W
def terms(price, g_kwh, min_kwh, max_kwh):
return {"price_ct": float(price),
"guaranteed_w": max(0.0, float(g_kwh or 0)) * 1000.0 / h,
"minimum_wh": max(0.0, float(min_kwh or 0)) * 1000.0 * (step_s / 3600.0) / h,
"max_w": max(0.0, float(max_kwh or 0)) * 1000.0 / h}
until = slot + int(float(d.get("stale_after_s") or MARKET_STALE_S))
a = max(0, -(-(slot - start) // step_s))
b = min(steps, -(-(until - start) // step_s))
out = []
for c in d.get("contracts") or []:
head = {"id": c["id"], "name": str(c.get("name") or "")[:200], "direction": c["direction"]}
per = _ahead_terms(c.get("ahead"), start, step_s, steps, terms)
if per is not None:
on = [t for t, x in enumerate(per) if x is not None]
if on:
out.append({**head, **per[on[0]], "from_step": on[0], "to_step": on[-1] + 1, "terms": per})
continue
sl = c.get("slot") or {}
if b <= a or not sl.get("applies"):
continue
try:
x = terms(sl.get("price_ct"), sl.get("guaranteed_kwh"), sl.get("minimum_kwh"), sl.get("max_kwh"))
except (TypeError, ValueError):
continue
out.append({**head, **x, "from_step": a, "to_step": b})
return out
def forecast(self, name: str, start: int, step_s: int, steps: int, tz: str) -> list[float] | None:
"""A model series for the horizon, or None (no model or no such
series: the caller falls back to history)."""
@@ -198,12 +404,47 @@ class Bundles:
if f is None:
return None
zone = ZoneInfo(tz or "UTC")
ser = f.get("series") or {}
s0, sv = ser.get("start"), ser.get("values") or []
out = []
for k in range(steps):
d = datetime.fromtimestamp(start + k * step_s, timezone.utc).astimezone(zone)
t = start + k * step_s
i = int((t - s0) // 900) if sv else -1
if 0 <= i < len(sv):
out.append(float(sv[i])) # the trained series where it covers
continue
d = datetime.fromtimestamp(t, timezone.utc).astimezone(zone)
out.append(float(f["values"][d.weekday() * 24 + d.hour]))
return out
def room_rc(self, control_id: str, area: str = "", only_one: bool = False,
now: float | None = None) -> dict | None:
"""A heating or cooling control's room in the model (R and C fitted
in the cloud): by its id, its id without _heating/_cooling/_heat/
_cool, its area; else, when the caller says it is the site's only
such control (only_one), the model's only room. None without a
model for this site (a shared "*" model has no rooms), expired, or
no match. {"r_k_per_kw", "c_kwh_per_k", "power", "gain_w" (W, a
number or 24 by local hour; 0 when the model has none),
"solar_m2"}."""
m = self.model.get()
now = time.time() if now is None else now
if m is None or m.get("site") != self.site or (m.get("expires") and m["expires"] <= now):
return None
rooms = m.get("rooms") or {}
key = next((k for k in (control_id, ROOM_SUFFIX.sub("", control_id or ""), area or "")
if k and k in rooms), None)
if key is None and only_one and len(rooms) == 1:
key = next(iter(rooms))
if key is None:
return None
r = rooms[key]
g = r.get("gain_w") or 0.0
return {"r_k_per_kw": float(r["r_k_per_kw"]), "c_kwh_per_k": float(r["c_kwh_per_k"]),
"power": r.get("power") or "thermal",
"gain_w": [_clip(x, ROOM_GAIN_W) for x in g] if isinstance(g, list) else _clip(g, ROOM_GAIN_W),
"solar_m2": _clip(r.get("solar_m2") or 0.0, ROOM_SOLAR_M2)}
def model_id(self) -> str:
m = self.model.get()
return m.get("id", "") if m else ""
+4
View File
@@ -55,6 +55,10 @@ class Config:
solve_timeout_s: float = 60.0 # the optimiser's subprocess is killed after this
plan_stale_s: int = 1800 # older plans: the safe defaults
default_price_ct: float = 30.0 # ct/kWh when no tariff ever came
# The site's grid connection (W): the plan's import and export are at most
# this. 3 x 230 V x 63 A, a German house connection's usual main fuse;
# a site with a smaller fuse (or a building's larger one) sets its own.
grid_max_w: float = 43470.0
override_hold_s: int = 7200 # hands off a control the owner changed by hand
min_switch_s: int = 600 # anti-cycling: a switch stays on/off at least this long
max_actions_per_hour: int = 12 # per control
+77 -8
View File
@@ -35,6 +35,7 @@ import time
from . import inputs as inputs_mod
from .building import Building
from .bundles import Bundles
from .evphases import EvPhases
from .executor import Executor, building_msg
from .gridorder import GridOrders
from .guard import Guard
@@ -81,6 +82,7 @@ class Controller:
min_switch_s=cfg.min_switch_s, max_actions_per_hour=cfg.max_actions_per_hour, clock=clock)
self.saved_limits = self._load_limits() # the console's (limits.json)
self.gridorders = GridOrders(cfg.state_dir, clock) # the grid operator's, from the EEBUS bridge (3q)
self.evphases = EvPhases(cfg.state_dir) # each charger's phase count and its source
self.guard.extra_limits = self.saved_limits
self.policy = Policy(cfg.state_dir, cfg.site_id, clock)
self.guard.policy = self.policy
@@ -180,6 +182,7 @@ class Controller:
lat, lon = (cfg or {}).get("latitude"), (cfg or {}).get("longitude")
if isinstance(lat, (int, float)) and isinstance(lon, (int, float)):
self.location = {"latitude": float(lat), "longitude": float(lon)}
write_cell(self.cfg.state_dir, float(lat), float(lon))
except Exception as e:
log.warning("get_config: %s", e)
ids = self.entities()
@@ -222,7 +225,9 @@ class Controller:
self.history, self.tz, self.forecast, self.guard.extra_limits,
building=self.building.for_model(start, inputs_mod.STEP_S, inputs_mod.STEPS),
location=self.location, shade_ctx=self.shade_ctx(),
grid_order=self.gridorders.for_model(start, inputs_mod.STEP_S, inputs_mod.STEPS))
grid_order=self.gridorders.for_model(start, inputs_mod.STEP_S, inputs_mod.STEPS),
grid_max_w=getattr(self.cfg, "grid_max_w", None),
ev_phases=self.ev_phases())
async def make_plan(self) -> dict | None:
self.forecast = []
@@ -261,15 +266,20 @@ class Controller:
"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", {})}
"flex": plan.get("flex", {}),
# the market's contracts in the plan (shadow): planned kWh and saving vs the grid
"market": plan.get("market", [])}
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()
"""The plan's room temperatures and the battery's state have a value
(a sensor that stopped must not steer). HA marks a device that went
away unavailable; a value that holds steady is not stale (the clone,
2026-10-30: a room at 23.5 °C for hours and a full battery held every
control at its safe default), and HA sends no update for an
unchanged value, so its age says nothing."""
for c in self.controls:
for role in ("temp", "soc"):
if role in c.entities and self.col.age(c.entities[role], now) > 3600:
if role in c.entities and self.col.value(c.entities[role]) is None:
return False
return True
@@ -378,8 +388,10 @@ class Controller:
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("load_w", inputs_mod.base_load(self.col, self.inputs), now)
self.history.add("pv_w", self.col.total(self.inputs.pv_power), now)
if self.sample_ev_phases(now) and self.gridorders.active():
self._merge_limits() # a learned count: the order's current bound again
if int(now) % 900 < 60:
try:
self.history.save(now)
@@ -387,6 +399,10 @@ class Controller:
log.warning("history: %s", e)
self.executor.inputs_ok = self.inputs_fresh()
self.grid_tick()
try:
await self.grid_report()
except Exception as e:
log.warning("grid order report: %s", e)
if self.switch_sides():
self.wake.set() # heating <-> cooling: a plan for the new side
try:
@@ -506,12 +522,34 @@ class Controller:
os.replace(p + ".tmp", p)
# -- the chargers' phases (evphases.py) ------------------------------------
def ev_phases(self) -> dict:
"""{control id: {"phases", "source", "plan", "order"}} for the EV controls."""
return self.evphases.all(self.controls, self.col)
def sample_ev_phases(self, now: float) -> bool:
"""A reading per charger for learning its phases: its power (its own
`power` sensor, else the site's ev.power where it is the only
charger) and current (measured, else its setpoint). True when a
learned count changed."""
evs = [c for c in self.controls if c.kind == "ev"]
site_ev = self.mapping.by_asset.get("ev.power") if len(evs) == 1 and hasattr(self.mapping, "by_asset") else None
changed = False
for c in evs:
pw = c.entities.get("power") or (site_ev.entity if site_ev else "")
cur = c.entities.get("current_measured") or c.entities.get("current") or ""
p = inputs_mod.watts(self.col, pw) if pw else None
a = self.col.value(cur) if cur else None
changed |= self.evphases.sample(c.id, p, a, float(c.p("voltage")), now)
return changed
# -- 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():
phases = {cid: v["phases"] for cid, v in self.ev_phases().items()}
for cid, qs in self.gridorders.limits(self.controls, phases).items():
for q, (f, lim) in qs.items():
per = merged.setdefault(cid, {}).setdefault(q, {})
old = per.get("grid")
@@ -538,10 +576,18 @@ class Controller:
args.update(value="", state="normal")
log.info("grid operator's limit ended")
await self._received("grid", args, "grid", True, "limited" if o else "ended")
await self.grid_report()
self.wake.set()
self.act_now.set()
return True
async def grid_report(self):
"""The order to the cloud as an action (gridorder.py action()): each
quarter-hour it holds, and its end."""
a = self.gridorders.action()
if a is not None:
await self._publish("action", a)
def 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(
@@ -562,6 +608,29 @@ def sender(cmd: str, args: dict) -> str:
return "cloud"
def write_cell(state_dir: str, lat: float, lon: float) -> bool:
"""The site's weather cell (0.1°, ~10 km) for the link: site_cell.json
in the state directory; the heartbeat carries it to the cloud only with
the owner's share consent (edge/link). Written when it changed."""
cell = {"lat": round(lat, 1), "lon": round(lon, 1)}
path = os.path.join(state_dir, "site_cell.json")
try:
with open(path) as f:
if json.load(f) == cell:
return False
except (OSError, ValueError):
pass
try:
tmp = path + ".tmp"
with open(tmp, "w") as f:
json.dump(cell, f)
os.replace(tmp, path)
except OSError as e:
log.warning("site cell: %s", e)
return False
return True
SECRET_ARGS = ("proof", "sig", "bundle", "token", "password")
+31 -6
View File
@@ -67,6 +67,7 @@ from dataclasses import dataclass, field
from . import limits as limits_mod
from . import switchover as switchover_mod
from .evphases import ASSUMED
log = logging.getLogger(__name__)
@@ -78,7 +79,9 @@ ENTITIES = {
"cooling": {"climate": ("climate",), "temp": ("sensor",)},
"ev": {"switch": ("switch", "input_boolean"), "current": ("number", "input_number"),
"connected": ("binary_sensor", "input_boolean"), "soc": ("sensor", "input_number"),
"energy_needed": ("sensor",), "departure": ("sensor", "input_datetime")},
"energy_needed": ("sensor",), "departure": ("sensor", "input_datetime"),
# read only, for its phase count (evphases.py): reported, or learned from power and current
"phases": ("sensor",), "power": ("sensor",), "current_measured": ("sensor",)},
"cover": {"cover": ("cover",)},
}
WRITES = {"charge_from_grid", "setpoint", "mode", "climate", "switch", "current", "cover"}
@@ -91,15 +94,31 @@ PARAMS = {
"manual_option": "manual", "auto_option": "self-consumption", "min_switch_s": 0.0},
"heating": {"r_k_per_kw": 10.0, "c_kwh_per_k": 3.0, "max_power_w": 2000.0, "comfort_c": 21.0,
"setback_c": 17.0, "cop": 1.0, # cop 1: electric; a heat pump ~3
"min_switch_s": 600.0},
"min_switch_s": 600.0,
# the room's other heat (W; the model's fit, inputs._room_rc): internal
# (a number, or 24 by local hour) and the sun's per W/m² of irradiance
"internal_gain_w": 0.0, "solar_m2": 0.0},
"cooling": {"r_k_per_kw": 10.0, "c_kwh_per_k": 3.0, "max_power_w": 1500.0, "comfort_c": 25.0,
"setup_c": 28.0, "cop": 3.0, "min_switch_s": 600.0},
"setup_c": 28.0, "cop": 3.0, "min_switch_s": 600.0, "internal_gain_w": 0.0, "solar_m2": 0.0},
"ev": {"need_wh": 10000.0, "departure": "07:00", "min_current_a": 6.0, "max_current_a": 16.0,
"phases": 1.0, "voltage": 230.0, "min_switch_s": 0.0},
"phases": None, "voltage": 230.0, "min_switch_s": 0.0}, # phases: None, not said (evphases.py)
"cover": {"room": "", "gain_w": 800.0, "min_switch_s": 0.0, "area": "", "facing": -1.0,
"open_pct": 100.0, "shade_pct": 30.0, "closed_pct": 0.0, "quiet_from": "22:00", "quiet_to": "07:00",
"night_moves": 0.0, "min_move_s": 1800.0, "override_hold_s": 14400.0},
}
def ev_volts(params: dict, purpose: str) -> float:
"""A charger's volts x phases (W per A) for a purpose: "plan" (the
plan's power per A) or "order" (the grid order's current bound,
gridorder.limits). params["phases"]: the count from the best evidence
(evphases.py: mapping, device, learned); without it each purpose takes
its own safe side (evphases.ASSUMED: the order 3, the plan 1)."""
v = float(params.get("voltage") or PARAMS["ev"]["voltage"])
return v * float(params.get("phases") or ASSUMED[purpose])
HHMM_RE = re.compile(r"^([01][0-9]|2[0-3]):[0-5][0-9]$")
# each kind's device range per quantity (firmware's; limits.effective)
RANGE = {
@@ -254,16 +273,22 @@ class Inputs:
load_power: str | list = "" # sensor W: the house's load (history fallback)
pv_power: str | list = "" # sensor W: PV (history fallback); a list: their sum
humidity: list[str] = field(default_factory=list)
# sensors W of the planned devices' own draw inside load_power (heat pump,
# A/C, charger): taken off it, so the plan's base load is the house
# without the devices it plans itself (inputs.base_load). None: from the
# mapping's assets (mapping.controlled_power); an empty list: load_power
# has none of them in it.
controlled_power: list[str] | None = None
def entities(self) -> list[str]:
one = [self.outside_temp, self.weather, self.sun]
summed = [e for x in (self.load_power, self.pv_power) for e in ([x] if isinstance(x, str) else x)]
return [e for e in self.presence + self.humidity + one + summed if e]
return [e for e in self.presence + self.humidity + one + summed + list(self.controlled_power or []) if e]
def parse_inputs(raw: dict | None) -> Inputs:
raw = dict(raw or {})
for k in ("presence", "humidity"):
for k in ("presence", "humidity", "controlled_power"):
if isinstance(raw.get(k), str):
raw[k] = [raw[k]]
unknown = set(raw) - set(Inputs.__dataclass_fields__)
+169 -20
View File
@@ -32,7 +32,10 @@
and dearest hour of the next 24; the coming actions by
the controls' names or "nothing planned", the prices of 48 h
as a table, what Cantabile sets in words: only in auto, the
commands received: only when there are any); the building
commands received: only when there are any); the market
(shadow; only when the site has contracts: positions, the
price, a card per contract in plain words, the border
actuators' contract target against their state); the building
the home is in or asked to join
energy power and price over time, energy per day and month (if mapped)
climate rooms, thermostats, heat pump (if mapped)
@@ -81,8 +84,9 @@ class Home:
def __init__(self, mapping, uid: str, ours: dict[str, str], flats: list[dict], lang: str,
mode: str = "shadow", reg: dict | None = None, states: list[dict] | None = None,
links: dict[str, str] | None = None, joining: dict | None = None,
profiles: list[dict] | None = None):
profiles: list[dict] | None = None, market: dict | None = None):
self.m, self.uid, self.ours, self.flats, self.lang = mapping, uid, ours, flats, lang
self.market = market # the shadow market's bundle (bundles.market_now), or None
self.mode, self.links, self.joining, self.profiles = mode, links or {}, joining, profiles or []
self._views: dict[str, devview.DeviceView] = {}
self.assets = {a.asset: a for a in mapping.assets}
@@ -146,6 +150,17 @@ class Home:
return [a.entity for a in self.m.assets
if a.kind == "counter" and a.asset.startswith(prefix) and self.alive(a.entity)]
def thermal(self) -> set[str]:
"""The entities of heat (heat.power, heat.energy and their parts):
thermal, never shown or summed as electricity."""
return {a.entity for a in self.m.assets
if a.asset.split(".")[0] == "heat" and a.asset.rsplit(".", 1)[-1] in ("power", "energy")}
def heat_label(self) -> str:
"""Heat delivered by a heat pump of this site, else heat from the
building (a heat meter: district heat, the building's heat pump)."""
return self.n("heat_delivered" if self.each("heatpump.power") else "heat_building")
def our(self, suffix: str) -> str | None:
return self.ours.get(f"{self.uid}_{suffix}")
@@ -300,6 +315,48 @@ def energy_now(h: "Home") -> list[dict]:
return now
def _kilo(e: str, unit: str, dec: str) -> str:
"""A jinja expression of a heat sensor in kW or kWh (from W/Wh too)."""
return ("{% set u = state_attr('" + e + "', 'unit_of_measurement') %}{% set v = states('" + e + "') | float(none) %}"
"{% if v is none %}–{% else %}{{ ('%.1f' | format(v / 1000 if u in ['W', 'Wh'] else v))"
" | replace('.', '" + dec + "') }} " + unit + "{% endif %}")
def _thermal(h: "Home", e: str, label: str, cols=6, value: bool = False) -> dict:
"""A heat value (thermal) as its label and kW or kWh: never a tile that
could pass for electricity. value: one of a device's values."""
a = next((a for a in h.m.assets if a.entity == e), None)
unit = "kWh" if a is not None and a.kind == "counter" else "kW"
dec = "," if h.lang.split("-")[0] in DECIMAL_COMMA else "."
c = {"type": "markdown", "text_only": True, "grid_options": {"columns": cols}, "entity_id": e,
"content": f"<ha-icon icon=\"mdi:radiator\"></ha-icon> {label} \n**{_kilo(e, unit, dec)}**"}
return dict(c, _value=True) if value else c
def heat_band(h: "Home") -> list[dict]:
"""Heat now and today, thermal, in a band of its own below the
electricity: from the building (district heat, a heat meter) or
delivered by the site's heat pump, then with its electric power and the
COP (heat ÷ electricity). Never summed with electric power."""
heat, hp = h.each("heat.power"), h.each("heatpump.power")
if not heat and not h.each("heat.energy"):
return []
label = h.heat_label()
out = [_thermal(h, e, f"{label} {n}".strip()) for n, e in heat]
out += [_today(e, f"{h.n('heat_today')} {n}".strip(), "mdi:radiator") for n, e in h.each("heat.energy")]
if hp:
out += [_tile(e, f"{h.n('heat_pump_electric')} {n}".strip(), "mdi:heat-pump", "deep-purple")
for n, e in hp]
if len(heat) == 1 and len(hp) == 1:
q, w = heat[0][1], hp[0][1]
dec = "," if h.lang.split("-")[0] in DECIMAL_COMMA else "."
out.append(_md("{% set q = states('" + q + "') | float(none) %}{% set w = states('" + w + "') | float(none) %}"
+ h.n("cop") + " \n**{% if q is not none and w %}{{ ('%.1f' | format(q / w)) | replace('.', '"
+ dec + "') }}{% else %}–{% endif %}**", 6, text_only=True))
out.append(_md("<small>ⓘ " + h.n("heat_not_electric") + "</small>", text_only=True))
return out
def _label(h: "Home", c) -> str:
"""A control as people call it: the mapping's name, else the name HA
shows for its device's main entity, else its id in words."""
@@ -408,6 +465,46 @@ def plan_cards(h: "Home") -> list[dict]:
return out[:1 if price else 0] + _fill(out[1 if price else 0:])
def market_band(h: "Home") -> dict | None:
"""The shadow market, only when the site has contracts (a `market`
bundle): the net position(s) and the shared energy's price (quarters),
per contract a card in plain words (halves: "Sells to Home B: 1.2 kWh
last quarter-hour (contract 1.5) · 16.4 ct/kWh · shadow", the period
below), the border actuators' contract target against their state now,
and what shadow means. HA's core cards only."""
m = h.market
if not m or not m.get("contracts"):
return None
top = []
for p in m.get("positions") or []:
kind = str(p.get("node", "")).split(":")[0]
top.append(_tile(h.our("market_position" if kind == "site" else f"market_position_{_slug(kind)}"),
icon="mdi:scale-balance", cols=6))
top.append(_tile(h.our("market_price"), h.n("market_price"), "mdi:cash-multiple", cols=6))
stale = "<small>" + h.n("mk_stale") + "</small>"
deals = []
for c in m.get("contracts") or []:
e = h.our(f"market_{_slug(c['id'])}")
if not e:
continue
deals.append(_md(
"{% set e = '" + e + "' %}{% if states(e) == 'unavailable' or not state_attr(e, 'summary') %}" + stale
+ "{% else %}**{{ state_attr(e, 'summary') }}**{% set d = state_attr(e, 'details') %}"
"{% if d %} \n<small>{{ d }}</small>{% endif %} \n<small>{{ state_attr(e, 'period_words') }}</small>{% endif %}",
12))
rows = []
for a in m.get("actuators") or []:
e = h.our(f"market_actuator_{_slug(a['device'])}")
if e:
rows.append("**" + (a.get("name") or a["device"]).replace("*", "") + "**: {% set e = '" + e + "' %}"
"{% if states(e) == 'unavailable' %}" + stale + "{% else %}{{ state_attr(e, 'words') }}{% endif %}")
acts = _md(" \n".join(rows)) if rows else None
if not deals and not acts:
return None
note = _md("<small>ⓘ " + h.n("mk_shadow_note") + "</small>")
return _band(*_fill([c for c in top if c]), *_fill(deals), acts, note, heading=h.n("card_market"), icon="mdi:handshake-outline")
# -- the views ----------------------------------------------------------------------
def view_overview(h: Home) -> dict | None:
@@ -444,10 +541,11 @@ def view_overview(h: Home) -> dict | None:
return _view(h.n("dash_main"), "overview", "mdi:leaf",
_band(*status), _band(*now),
_band(*_fill(heat_band(h)), heading=h.n("heat"), icon="mdi:radiator"),
devices_heading(h, bool(devices)), *devices,
_band(*today, heading=h.n("today"), icon="mdi:calendar-today"),
_band(*plan_cards(h), heading=h.n("card_plan"), icon="mdi:chart-timeline-variant"),
building_section(h), columns=WIDE)
market_band(h), building_section(h), columns=WIDE)
def view_energy(h: Home) -> dict | None:
@@ -475,9 +573,13 @@ def view_climate(h: Home) -> dict | None:
for e in dict.fromkeys(c.entities["climate"] for c in rooms if "climate" in c.entities)],
_history(h.n("card_rooms"), list(dict.fromkeys(e for e in temps if e))
+ [h.our(f"set_{c.id}") for c in rooms] + [h.asset("outside.temp")])),
# electric and thermal apart, never in one graph
_section(_heading(h.n("heat_pump"), "mdi:heat-pump"),
_history(h.n("card_power"), h.all("heatpump.power", "heat.power")),
_stats(h.n("card_daily"), h.all("heatpump.energy", "heat.energy"))))
_history(h.n("electric_power"), h.all("heatpump.power")),
_stats(h.n("card_daily"), h.all("heatpump.energy"))),
_section(_heading(h.n("heat"), "mdi:radiator"),
_history(h.heat_label(), h.all("heat.power")),
_stats(h.n("heat_today"), h.all("heat.energy"))))
def _short(name: str, device: str) -> str:
@@ -560,9 +662,15 @@ def device_cards(h: Home, d: dict, detail: bool = False) -> list[dict]:
cards, used = [], set()
thermal = h.thermal()
def tile(eid, trend=None, cols=6):
if eid and eid not in used:
used.add(eid)
if eid in thermal: # heat: thermal, never like electricity
label = h.heat_label() if eid in h.all("heat.power") else h.n("heat_today")
cards.append(_thermal(h, eid, label, cols))
return
cards.append(_tile(eid, nm(eid), trend=power(eid) if trend is None else trend, cols=cols))
soc = dv.flow.get("soc") or next((e for e in dv.headline if st(e).get("device_class") == "battery"), None)
if dv.card in ("flow", "gauge") and soc:
@@ -592,7 +700,7 @@ def device_cards(h: Home, d: dict, detail: bool = False) -> list[dict]:
for e in dv.headline:
tile(e, None if dv.card in ("flow", "meter", "charger") or detail else False)
if dv.channels:
power_ch = [c for c in dv.channels if c.get("power")]
power_ch = [c for c in dv.channels if c.get("power") and c["power"] not in thermal] # never heat
if power_ch:
cards.append(_sum(h.n("total"), [c["power"] for c in power_ch]))
cards.append({"type": "distribution", "grid_options": {"columns": "full"},
@@ -735,10 +843,13 @@ def device_card(h: Home, d: dict, skip: set[str] = frozenset()) -> dict | None:
picked.append(e)
picked = picked[:HEADLINE]
used |= set(picked)
cards += [{"type": "tile", "entity": e, "name": nm(e), "_value": True,
thermal = h.thermal()
cards += [_thermal(h, e, h.heat_label() if e in h.all("heat.power") else h.n("heat_today"), value=True)
if e in thermal else
{"type": "tile", "entity": e, "name": nm(e), "_value": True,
**({"icon_tap_action": {"action": "more-info"}}
if e.split(".")[0] in ("switch", "light", "fan", "input_boolean") else {})} for e in picked]
power_ch = [c for c in dv.channels if c.get("power") and c["power"] not in skip]
power_ch = [c for c in dv.channels if c.get("power") and c["power"] not in skip and c["power"] not in thermal]
if power_ch:
cards.append({"type": "markdown", "text_only": True, "content":
"{% set e = " + json.dumps([c["power"] for c in power_ch]) + " %}" + h.n("total")
@@ -798,18 +909,22 @@ def device_subview(h: Home, d: dict) -> dict | None:
value it has (not diagnostic), and its power over the last day."""
dv = h.view(d)
cards = device_cards(h, d, detail=True)
shown = {x if isinstance(x, str) else x.get("entity") for c in cards for x in [c, *(c.get("entities") or [])]}
shown = {x if isinstance(x, str) else x.get("entity") or x.get("entity_id")
for c in cards for x in [c, *(c.get("entities") or [])]}
shown |= set(dv.switches)
thermal = h.thermal()
rest = [e["entity_id"] for e in h.ents_of(d) if not e.get("entity_category") and e["entity_id"] not in shown
and e["entity_id"].split(".")[0] in VALUES and h.alive(e["entity_id"])]
powers = [e for e in dv.entities() | set(rest) if (((h.states or {}).get(e) or {}).get("attributes") or {})
.get("device_class") == "power"]
.get("device_class") == "power" and e not in thermal]
heat = sorted(e for e in dv.entities() | set(rest) | shown if e in thermal and e in h.all("heat.power"))
return {"type": "sections", "title": _name(d), "path": _subpath(d), "subview": True,
"back_path": f"/{URL}/overview", "max_columns": 3, "sections": [x for x in (
_section(_heading(_name(d), "mdi:information-outline"), *cards),
_section(_heading(h.n("values"), "mdi:format-list-bulleted"),
{"type": "entities", "entities": rest, "grid_options": {"columns": "full"}} if rest else None),
_section(_heading(h.n("card_power"), "mdi:flash"), _history(h.n("card_power"), sorted(powers))))
_section(_heading(h.n("card_power"), "mdi:flash"), _history(h.n("card_power"), sorted(powers))),
_section(_heading(h.n("heat"), "mdi:radiator"), _history(h.heat_label(), heat)))
if x]}
@@ -858,15 +973,19 @@ def dashboard(h: Home) -> dict | None:
def energy_prefs(h: Home) -> dict | None:
"""HA's Energy preferences from the mapping, or None (nothing to show).
Parts (two inverters, two batteries) are each a source of their own."""
Parts (two inverters, two batteries) are each a source of their own.
The grid in HA's current form (energy storage 1.3, in HA 2026.10): a
source per grid connection with its import and export meter side by
side (parts paired in order); legacy_grid() gives the older form."""
src = []
imp, exp = h.all("grid.import_energy"), h.all("grid.export_energy")
if imp or exp:
for i in range(max(len(imp), len(exp))):
e_in, e_out = (imp[i] if i < len(imp) else None), (exp[i] if i < len(exp) else None)
src.append({"type": "grid", "cost_adjustment_day": 0,
"flow_from": [{"stat_energy_from": e, "stat_cost": None, "number_energy_price": None,
"entity_energy_price": h.our("price_import_now")} for e in imp],
"flow_to": [{"stat_energy_to": e, "stat_compensation": None, "number_energy_price": None,
"entity_energy_price": h.our("price_export_now")} for e in exp]})
"stat_energy_from": e_in, "stat_cost": None, "number_energy_price": None,
"entity_energy_price": h.our("price_import_now") if e_in else None,
"stat_energy_to": e_out, "stat_compensation": None, "number_energy_price_export": None,
"entity_energy_price_export": h.our("price_export_now") if e_out else None})
for e in h.all("pv.energy"):
src.append({"type": "solar", "stat_energy_from": e, "config_entry_solar_forecast": None})
ins, outs = dict(h.each("battery.charge_energy")), dict(h.each("battery.discharge_energy"))
@@ -883,6 +1002,23 @@ def energy_prefs(h: Home) -> dict | None:
return {"energy_sources": src, "device_consumption": devices}
def legacy_grid(prefs: dict) -> dict:
"""The preferences in HA's older grid form (energy storage before 1.3):
one grid source, its import and export meters in flow_from / flow_to.
The same dict when there is no grid."""
grids = [s for s in prefs["energy_sources"] if s["type"] == "grid"]
if not grids:
return prefs
one = {"type": "grid", "cost_adjustment_day": 0,
"flow_from": [{"stat_energy_from": g["stat_energy_from"], "stat_cost": None, "number_energy_price": None,
"entity_energy_price": g["entity_energy_price"]}
for g in grids if g["stat_energy_from"]],
"flow_to": [{"stat_energy_to": g["stat_energy_to"], "stat_compensation": None, "number_energy_price": None,
"entity_energy_price": g["entity_energy_price_export"]}
for g in grids if g["stat_energy_to"]]}
return dict(prefs, energy_sources=[one] + [s for s in prefs["energy_sources"] if s["type"] != "grid"])
class Dashboards:
def __init__(self, agent):
self.agent = agent
@@ -918,9 +1054,10 @@ class Dashboards:
links: dict[str, str] | None = None) -> Home:
ctl = getattr(self.agent, "control", None)
flats = ctl.bundles.flat_list() if ctl is not None else []
market = ctl.bundles.market_now(time.time()) if ctl is not None else None
return Home(self.agent.mapping, f"cantabile_{self.agent.cfg.site_id}", ours, flats,
getattr(self.agent, "ha_language", "en"), self.mode(), reg, states, links,
self.joining() if self.agent.cfg.join_page_port else None, self.profiles)
self.joining() if self.agent.cfg.join_page_port else None, self.profiles, market)
@staticmethod
async def links(client, devices: list[dict]) -> dict[str, str]:
@@ -985,9 +1122,21 @@ class Dashboards:
if prefs and (prefs.get("energy_sources") or prefs.get("device_consumption")):
return # the owner's: never overwritten
want = energy_prefs(h)
if want is not None:
if want is None:
return
try:
await client.dashboard("energy/save_prefs", **want)
log.info("HA's Energy dashboard set up from the mapping")
except HAError as e:
# an HA from before the unified grid (energy storage 1.3) takes
# only flow_from / flow_to: the same preferences in that form
old = legacy_grid(want)
if old is want or "invalid_format" not in str(e):
raise
await client.dashboard("energy/save_prefs", **old)
log.info("HA's Energy dashboard set up from the mapping (HA %s: the older grid form)",
getattr(client, "version", None))
return
log.info("HA's Energy dashboard set up from the mapping")
async def run(self, stop: asyncio.Event):
while not stop.is_set():
+329 -124
View File
@@ -66,16 +66,67 @@ SWITCHOVER_WORDS = {"heating": M("Heating"), "cooling": M("Cooling"),
"outdoor": M("By outdoor temperature")}
CUSTODIAN_WORDS = {"building_operator": M("the building's operator"), "grid_operator": M("the grid operator"),
"metering_operator": M("the metering operator"), "community_operator": M("the energy community's operator")}
PROFILE_STATUS = {"verified": M("Checked on a device"),
"documented": M("From the maker's documentation, not yet checked on a device"),
"draft": M("Draft: check the values before you turn reading on")}
PROFILE_STATUS = {"verified": (M("checked"), "ok", M("Checked on a device: its values are known to be right.")),
"documented": (M("untested"), "quiet", M("Made from the maker's documentation, not yet checked on a "
"device. Look at its values before you turn reading on.")),
"draft": (M("draft"), "warn", M("A draft profile: check the values before you turn reading on."))}
CONTROL_WORDS = {"battery": M("battery"), "heating": M("heating"), "cooling": M("cooling"), "ev": M("charging"),
"cover": M("blinds and curtains")}
# What a device reads, by meaning (the devices tool gives the keys:
# devprofiles.reads); never the asset ids.
QUANTITY_WORDS = {
"room.temp": M("room temperature"), "room.humidity": M("humidity"), "room.setpoint": M("setpoint"),
"room.setpoint_range": M("heat/cool range"), "heating_cooling.state": M("heating/cooling state"),
"heating.state": M("heating state"), "cooling.state": M("cooling state"),
"room.setpoint_low": M("heat/cool range"), "room.setpoint_high": M("heat/cool range"),
"room.shade_position": M("position"), "room.shade_tilt": M("tilt"),
"pv.power": M("solar power"), "pv.energy": M("solar energy"), "grid.power": M("grid power"),
"grid.import_power": M("power from the grid"), "grid.export_power": M("power to the grid"),
"grid.import_energy": M("energy from the grid"), "grid.export_energy": M("energy to the grid"),
"battery.power": M("battery power"), "battery.soc": M("battery charge"),
"battery.charge_energy": M("energy charged"), "battery.discharge_energy": M("energy discharged"),
"load.power": M("home consumption"), "load.energy": M("home energy"),
"heatpump.power": M("heat pump power"), "heatpump.energy": M("heat pump energy"),
"heat.power": M("heat delivered (thermal)"), "heat.energy": M("heat energy (thermal)"), "heatpump.flow_temp": M("flow temperature"),
"heatpump.dhw_temp": M("hot water temperature"), "outside.temp": M("outdoor temperature"),
"outside.humidity": M("outdoor humidity"), "gas.energy": M("gas"), "ev.power": M("charging power"),
"ev.energy": M("energy charged"), "circuit.power": M("power"), "circuit.energy": M("energy")}
# A device's main values now (devprofiles.live) on the list.
LIVE_WORDS = {"room.setpoint": M("set to {v}"), "room.setpoint_range": M("set to {low}–{high}"),
"pv.power": M("solar {v}"), "battery.soc": M("battery {v}"), "battery.power": M("battery {v}"),
"grid.power": M("grid {v}"), "load.power": M("home {v}"), "ev.power": M("charging {v}"),
"heatpump.power": M("heat pump {v}"), "heat.power": M("heat {v} (thermal)"), "heatpump.flow_temp": M("flow {v}"),
"outside.temp": M("outside {v}"), "room.humidity": M("humidity {v}"), "room.shade_position": M("{v} open")}
HVAC_WORDS = {"heating": M("heating"), "cooling": M("cooling"), "idle": M("idle")}
LIVE_UNITS = {"room.temp": "°C", "room.setpoint": "°C", "room.setpoint_range": "°C", "heatpump.flow_temp": "°C",
"outside.temp": "°C", "battery.soc": "%", "room.humidity": "%", "room.shade_position": "%"}
MORE_CSS = """nav{display:flex;gap:1rem;margin:0 0 1rem;border-bottom:1px solid #d5ded9;padding-bottom:.5rem}
nav a{color:inherit;text-decoration:none}nav a.on{font-weight:600;border-bottom:2px solid #2f6f55}
.badge{display:inline-block;font-size:.8rem;padding:.05rem .45rem;border-radius:4px;background:#e2e9e5;margin-left:.3rem}
ul.plain{margin:.3rem 0;padding-left:1.2rem}form.inline{display:inline}form.inline button{margin:0 0 0 .4rem;padding:.2rem .6rem}
@media (prefers-color-scheme:dark){nav{border-color:#2b3a32}.badge{background:#2b3a32}}"""
a{color:#2f6f55}.muted,.model{color:#5a6b62;font-size:.85rem}
.badge{display:inline-block;font-size:.75rem;padding:0 .45rem;border-radius:1rem;background:#e2e9e5;margin-left:.3rem;vertical-align:.1em}
.badge.quiet{background:none;box-shadow:inset 0 0 0 1px #d5ded9;color:#5a6b62}.badge.warn{background:#fbe9c9;color:#7a4b00}
ul.plain{list-style:none;margin:.3rem 0;padding:0}input[type=radio]{width:auto}select{font:inherit;padding:.45rem .6rem;border-radius:6px;width:100%}
a.box.dev{display:flex;gap:.8rem;align-items:center;color:inherit;text-decoration:none}a.box.dev:hover{border-color:#2f6f55}
.grow{flex:1;min-width:0}.grow>span{display:block}.grow>span.name{display:inline;font-weight:600}.grow>span.badge{display:inline-block}
.chev{color:#5a6b62;font-size:1.4rem}.state{font-size:.9rem}.values{font-size:1.05rem;font-weight:600}.box.now>span{display:block}
.dot{display:inline-block;width:.55rem;height:.55rem;border-radius:50%;margin-right:.45rem;background:#9fb0a6}.dot.on{background:#2f9e6e}
.offer .top{display:flex;gap:.8rem;align-items:center}.offer .top form{margin:0}.offer .top button{margin:0;white-space:nowrap}.offer p.note{margin:.4rem 0 0;font-size:.9rem}
.add{margin-top:2rem;border-top:2px solid #d5ded9}a.back{text-decoration:none;font-size:.9rem}.model.head{margin:-.6rem 0 .6rem}
section.set{border-top:1px solid #d5ded9;margin-top:1rem}section.set h3{margin:.9rem 0 .4rem}section.set p{margin:.35rem 0}
.switch{display:flex;align-items:center;justify-content:space-between;gap:.8rem;padding:.3rem 0}.switch form{margin:0}.switch button{margin:0;white-space:nowrap}
.pill{display:inline-block;font-size:.75rem;padding:0 .5rem;border-radius:1rem;background:#e2e9e5;color:#5a6b62;font-weight:600}.pill.on{background:#e3f4ea;color:#1f5d3a}
.row{display:flex;gap:.6rem}.row>div{flex:1}.right{text-align:right}
details.remove summary{color:#b3261e;cursor:pointer;padding:.8rem 0 .2rem}button.danger{background:none;color:#b3261e;box-shadow:inset 0 0 0 2px #b3261e}
details.more summary{cursor:pointer;margin:.6rem 0}
details.info{display:inline;position:relative}details.info>summary{display:inline-flex;align-items:center;justify-content:center;width:1.2rem;height:1.2rem;margin:0 .35rem;vertical-align:.1em;list-style:none;border:1px solid #5a6b62;border-radius:50%;color:#5a6b62;font:italic 600 .72rem/1 Georgia,serif;cursor:pointer}
details.info>summary::-webkit-details-marker{display:none}details.info>.info-body{position:absolute;left:0;z-index:3;width:min(22rem,80vw);margin-top:.4rem;padding:.7rem .9rem;background:#fff;color:#1d2a24;border:1px solid #d5ded9;border-radius:8px;box-shadow:0 6px 24px rgba(0,0,0,.18);font-size:.9rem;font-weight:normal}
@supports selector(:has(a)){form.changes .save{display:none}form.changes:has(input:default:not(:checked),input:checked:not(:default),option:checked:not(:default),input[value=outdoor]:checked) .save{display:inline-block}
form.changes:not(:has(input[value=outdoor]:checked)) .outdoor{display:none}}
@media (prefers-color-scheme:dark){nav{border-color:#2b3a32}a{color:#5cc493}.badge,.pill{background:#2b3a32}.muted,.model,.chev{color:#9fb0a6}
.badge.quiet{background:none;box-shadow:inset 0 0 0 1px #2b3a32;color:#9fb0a6}.badge.warn{background:#3a2c12;color:#f3c77e}.pill.on{background:#19302a;color:#a6e0bf}
.dot.on{background:#5cc493}.add,section.set{border-color:#2b3a32}a.box.dev:hover{border-color:#5cc493}select{background:#18221d;color:#e3ebe6;border:1px solid #3a4b42}
details.remove summary{color:#f08a80}button.danger{background:none;color:#f08a80;box-shadow:inset 0 0 0 2px #f08a80}
details.info>.info-body{background:#18221d;color:#e3ebe6;border-color:#2b3a32}details.info>summary{border-color:#9fb0a6;color:#9fb0a6}}"""
# HA's hash (#devices, #building: Cantabile's dashboard) to this page's ?p=
HASH_SCRIPT = ("(function(){try{var P=window.parent;if(P===window)return;var m=/^#(devices|building)$/.exec(P.location.hash||'');"
"if(m&&location.search.indexOf('p=')<0&&location.search.indexOf('code=')<0)location.replace('?p='+m[1])}"
@@ -101,10 +152,6 @@ def _write_json(path: str, data, mode: int = 0o644):
os.replace(tmp, path)
def quantity_words(q: str) -> str:
return q.replace("_", " ").replace(".", ": ", 1)
def with_attrs(ents: list[dict], states: dict) -> list[dict]:
"""Registry entries with HA's attributes now (where the state is known:
the profiles' conditions on attributes, as the Hub's registry has them)."""
@@ -235,19 +282,25 @@ class Devices:
"""The page's data: the devices used here, HA's devices with a
profile (and what each would give), the rest, or HA's error."""
devs, policy = self.load(), self.policy()
try:
reg, states = await self.snapshot()
ha_error = ""
except Exception as e:
reg, states, ha_error = {}, {}, str(e)
used = []
for d in sorted(devs.values(), key=lambda d: d.get("added", 0)):
frag, p = self.frag(d["id"]), self.profile(d["profile"]) or {}
targets = dp.device_targets(d, frag, self.local())
assets = frag.get("assets", [])
used.append(dict(d, manufacturer=p.get("manufacturer", ""), model=p.get("name", d["profile"]),
status=p.get("status", ""), assets=frag.get("assets", []), controls=frag.get("controls", []),
status=p.get("status", ""), generic=bool(p) and dp.fallback(p), assets=assets,
controls=frag.get("controls", []), reads=dp.reads(assets), live=dp.live(assets, states),
assumed=dp.reads([a for a in assets if a.get("assumed")]), lacks=dp.lacks(d.get("missing")),
switchover=dp.switchover_of(frag), shade=dp.shade_of(frag), place=dp.place_of(frag),
weather=dp.weather_of(frag), policy={t: policy[t] for t in targets if t in policy},
protection=dp.level_of(policy, [f"device:{d['id']}"])[0]))
try:
reg, states = await self.snapshot()
except Exception as e:
return {"devices": used, "offers": [], "rest": [], "ha_error": str(e), "site": self.site(), "rooms": []}
if ha_error:
return {"devices": used, "offers": [], "rest": [], "ha_error": ha_error, "site": self.site(), "rooms": []}
main = self.main()
src = main.get("source")
mapped = {}
@@ -445,8 +498,9 @@ def custodian(e: dict | None) -> str:
# ---- the page -----------------------------------------------------------------------------
def form(do: str, inner: str, button: str, cls: str = "", inline: bool = False) -> str:
return (f'<form method="post" action=""{" class=" + chr(34) + "inline" + chr(34) if inline else ""}>'
def form(do: str, inner: str, button: str, cls: str = "", inline: bool = False, form_cls: str = "") -> str:
fc = " ".join(x for x in ("inline" if inline else "", form_cls) if x)
return (f'<form method="post" action=""{" class=" + chr(34) + fc + chr(34) if fc else ""}>'
f'<input type="hidden" name="do" value="{E(do)}">{inner}'
f'<button{" class=" + chr(34) + cls + chr(34) if cls else ""}>{E(button)}</button></form>')
@@ -455,55 +509,163 @@ def hidden(**kw) -> str:
return "".join(f'<input type="hidden" name="{E(k)}" value="{E(str(v))}">' for k, v in kw.items())
def what_lines(assets: list, controls: list, would: bool) -> str:
reads = ", ".join(quantity_words(a["asset"]) for a in assets) or T("nothing")
kinds = ", ".join(dict.fromkeys(T(CONTROL_WORDS.get(c["kind"], c["kind"])) for c in controls))
if would:
out = T("Cantabile would read: {values}.", values=reads)
if kinds:
out += " " + T("It could control: {controls}.", controls=kinds)
else:
out = T("Cantabile reads: {values}.", values=reads)
if kinds:
out += " " + T("It may control: {controls}.", controls=kinds)
return f'<p class="note">{E(out)}</p>'
def info(body: str) -> str:
"""An "i": its explanation (escaped HTML) opens below on a click or tap."""
name = E(T("More information"))
return (f'<details class="info"><summary title="{name}" aria-label="{name}">i</summary>'
f'<div class="info-body">{body}</div></details>')
def notes(d: dict) -> str:
def quantity_words(q: str) -> str:
"""A quantity without words of its own: room.living_room.x -> room: living room.x."""
return q.replace("_", " ").replace(".", ": ", 1)
def room_name(place: str, rooms) -> str:
"""An asset's place (an area's slug) as HA names it: living_room -> Living room."""
return next((r for r in rooms or [] if dp.slug(r) == place), place.replace("_", " ").capitalize())
def reads_words(keys, rooms=()) -> str:
"""[(key, place)] (devprofiles.reads) in words: room temperature
(Living room), setpoint, heating/cooling state; a room named once."""
named, out = set(), []
for k, place in keys or []:
w = T(QUANTITY_WORDS[k]) if k in QUANTITY_WORDS else quantity_words(k)
if place and place not in named:
named.add(place)
w = T("{what} ({room})", what=w, room=room_name(place, rooms))
out.append(w)
return ", ".join(dict.fromkeys(out))
def ids_words(ids, rooms=()) -> str:
return reads_words(dp.reads(list(ids)), rooms)
def control_words(controls) -> str:
return ", ".join(dict.fromkeys(T(CONTROL_WORDS.get(c["kind"], c["kind"])) for c in controls or []))
def _num(v, digits: int = 1) -> str:
v = round(float(v), digits)
return i18n.number(int(v) if v == int(v) else v)
def live_words(k: str, v) -> str:
"""One of a device's values now (devprofiles.live): 21.5 °C, set to 22 °C, heating."""
if k == dp.HVAC:
return T(HVAC_WORDS.get(v, HVAC_WORDS["idle"]))
if k in ("heating.state", "cooling.state"):
return T(HVAC_WORDS[k.split(".")[0] if v else "idle"])
if k == dp.RANGE:
return T(LIVE_WORDS[k], low=_num(v[0]), high=_num(v[1])) + " °C"
unit = LIVE_UNITS.get(k)
s = f"{_num(v)} {unit}" if unit else f"{_num(v / 1000)} kW" if abs(v) >= 1000 or k == "heat.power" else f"{_num(v, 0)} W"
return T(LIVE_WORDS[k], v=s) if k in LIVE_WORDS else s
def device_values(d: dict) -> str:
return ", ".join(live_words(k, v) for k, v in d.get("live") or [])
def device_state(d: dict) -> str:
"""In use · reading on · control off / Added · reading off, with a dot."""
on = bool(d.get("read"))
parts = [T("In use"), T("reading on")] if on else [T("Added"), T("reading off")]
if d.get("controls"):
parts.append(T("control on") if d.get("control") else T("control off"))
return f'<span class="dot{" on" if on else ""}" aria-hidden="true"></span>' + E(" · ".join(parts))
def model_line(d: dict) -> str:
if d.get("generic"):
return E(d.get("model", "").split(" (")[0]) + f' · <span class="muted">{E(T("generic profile"))}</span>'
return E(f"{d.get('manufacturer', '')} {d.get('model', '')}".strip())
def status_badge(status, explain: bool = True) -> str:
"""A profile's status as a small badge, its explanation behind an "i"."""
if status not in PROFILE_STATUS:
return ""
word, cls, why = PROFILE_STATUS[status]
return f'<span class="badge {cls}">{E(T(word))}</span>' + (info(E(T(why))) if explain else "")
def protection_badge(d: dict) -> str:
if d.get("protection") == "sealed":
return f'<span class="badge warn">{E(T("sealed"))}</span>'
if any((e or {}).get("level") == "protected" for e in (d.get("policy") or {}).values()):
return f'<span class="badge">{E(T("protected"))}</span>'
return ""
def section(title: str, body: str, extra: str = "") -> str:
return f'<section class="set"><h3>{E(title)}{extra}</h3>{body}</section>'
def save_button() -> str:
"""Save, shown only once something changed (by CSS)."""
return f'<div class="right"><button class="save">{E(T("Save"))}</button></div>'
def notes(d: dict, rooms=(), values: bool = True) -> str:
"""What a device lacks or leaves to others, in words (quietly); the
values it does not report only on its own page (values)."""
out = []
if d.get("missing"):
out.append(T("Not found in Home Assistant: {entities}.", entities=", ".join(d["missing"])))
gone = d.get("left_out") or {}
if gone.get("values"):
lacks = dp.lacks(d.get("missing"))
if lacks["values"] and values:
out.append(T("This device does not report: {values}.", values=reads_words([(k, "") for k in lacks["values"]])))
gone = [T("{control} control", control=T(CONTROL_WORDS.get(k, k))) for k in lacks["controls"]] + lacks["other"]
if gone:
out.append(T("Not found in Home Assistant: {entities}.", entities=", ".join(gone)))
left = d.get("left_out") or {}
if left.get("values"):
out.append(T("Read by your own mapping already, so left out here: {values}.",
values=", ".join(quantity_words(q) for q in gone["values"])))
if gone.get("controls"):
values=ids_words(left["values"], rooms)))
if left.get("controls"):
out.append(T("Another control writes to this device already, so Cantabile leaves out: {controls}.",
controls=", ".join(T(CONTROL_WORDS.get(k, k)) for k in gone["controls"])))
assumed = [a["asset"] for a in d.get("assets") or [] if a.get("assumed")]
controls=", ".join(T(CONTROL_WORDS.get(k, k)) for k in left["controls"])))
assumed = d.get("assumed") if "assumed" in d else dp.reads([a for a in d.get("assets") or [] if a.get("assumed")])
if assumed:
out.append(T("Assumed, not measured: {values}. This device does not report back (infrared): Cantabile shows "
"what was last sent to it and never takes it as feedback.",
values=", ".join(quantity_words(q) for q in assumed)))
"what was last sent to it and never takes it as feedback.", values=reads_words(assumed)))
return "".join(f'<p class="note">{E(x)}</p>' for x in out)
def consent_html(d: dict, site: dict) -> str:
"""Reading and control, the owner's per device, as on the Hub's Devices
page; only with the site's consent (the add-on's configuration)."""
kinds = ", ".join(dict.fromkeys(T(CONTROL_WORDS.get(c["kind"], c["kind"])) for c in d.get("controls") or []))
"""Reading and control, each a switch that takes effect at once, as on
the Hub's Devices page; only with the site's consent (the add-on's
configuration)."""
kinds = control_words(d.get("controls"))
if not site.get("share"):
return ('<p class="note">' + E(T("Reading and control are off. To switch them on, first give your consent in the "
"add-on's configuration (Settings, Add-ons, Cantabile Edge Agent, Configuration)."))
+ "</p>")
ctl = ('<label class="check"><input type="checkbox" name="control" value="1"' + (" checked" if d.get("control") else "")
+ "><span>" + E(T("Cantabile may control it ({controls}), within your limits", controls=kinds))
+ "</span></label>") if kinds else ""
note = ('<p class="note">' + E(T("Control also needs your consent to control devices in the add-on's configuration."))
+ "</p>") if kinds and not site.get("control") else ""
return form("consent", hidden(id=d["id"]) + '<label class="check"><input type="checkbox" name="read" value="1"'
+ (" checked" if d.get("read") else "") + "><span>" + E(T("Cantabile may read these values"))
+ f"</span></label>{ctl}", T("Save")) + note
return section(T("Reading and control"), '<p class="note">' + E(T(
"Reading and control are off. To switch them on, first give your consent in the add-on's configuration "
"(Settings, Add-ons, Cantabile Edge Agent, Configuration).")) + "</p>")
read, control = bool(d.get("read")), bool(d.get("control"))
def row(title, note, on, values):
pill = f'<span class="pill{" on" if on else ""}">{E(T("On") if on else T("Off"))}</span>'
inner = hidden(id=d["id"]) + "".join(f'<input type="hidden" name="{k}" value="{"1" if v else ""}">'
for k, v in values.items())
return (f'<div class="switch"><div><b>{E(title)}</b> {pill}<br><span class="note">{E(note)}</span></div>'
+ form("consent", inner, T("Turn off") if on else T("Turn on"), "secondary") + "</div>")
rows = row(T("Reading"), T("Cantabile may read these values."), read, {"read": not read, "control": control and not read})
if kinds:
rows += row(T("Control"), T("Cantabile may control it ({controls}), within your limits.", controls=kinds), control,
{"read": read or not control, "control": not control})
if not site.get("control"):
rows += '<p class="note">' + E(T("Control also needs your consent to control devices in the add-on's "
"configuration.")) + "</p>"
return section(T("Reading and control"), rows)
def reads_html(d: dict, rooms=()) -> str:
lines = [f'<p>{E(T("Reads: {values}", values=reads_words(d.get("reads"), rooms) or T("nothing")))}</p>']
kinds = control_words(d.get("controls"))
if kinds:
lines.append(f'<p>{E(T("Controls: {controls}", controls=kinds))}</p>')
return section(T("What Cantabile reads"), "".join(lines) + notes(d, rooms))
def switchover_html(d: dict) -> str:
@@ -514,14 +676,14 @@ def switchover_html(d: dict) -> str:
lo, hi = sw.get("heat_below_c", 15), sw.get("cool_above_c", 22)
radios = "".join(f'<label class="check"><input type="radio" name="mode" value="{k}"{" checked" if k == mode else ""}>'
f"<span>{E(T(w))}</span></label>" for k, w in SWITCHOVER_WORDS.items())
inner = (hidden(id=d["id"]) + f'<p class="note">{E(T("This thermostat can heat and cool. Cantabile uses one at a time; the other is never touched."))}</p>'
+ radios
+ f'<label for="lo-{E(d["id"])}">{E(T("By outdoor temperature: heat below (°C)"))}</label>'
f'<input id="lo-{E(d["id"])}" type="number" step="0.5" name="heat_below_c" value="{E(f"{lo:g}")}">'
f'<label for="hi-{E(d["id"])}">{E(T("cool above (°C)"))}</label>'
f'<input id="hi-{E(d["id"])}" type="number" step="0.5" name="cool_above_c" value="{E(f"{hi:g}")}">'
f'<p class="note">{E(T("Between the two it stays as it is, so it does not switch back and forth on a mild day."))}</p>')
return f"<details><summary>{E(T('Heating or cooling'))}</summary>{form('switchover', inner, T('Save'))}</details>"
inner = (hidden(id=d["id"]) + radios + '<div class="outdoor row">'
f'<div><label for="lo-{E(d["id"])}">{E(T("Heat below (°C)"))}</label>'
f'<input id="lo-{E(d["id"])}" type="number" step="0.5" name="heat_below_c" value="{E(f"{lo:g}")}"></div>'
f'<div><label for="hi-{E(d["id"])}">{E(T("Cool above (°C)"))}</label>'
f'<input id="hi-{E(d["id"])}" type="number" step="0.5" name="cool_above_c" value="{E(f"{hi:g}")}"></div></div>'
f'<p class="note outdoor">{E(T("Between the two it stays as it is, so it does not switch back and forth on a mild day."))}</p>')
about = info(E(T("This thermostat can heat and cool. Cantabile uses one at a time; the other is never touched.")))
return section(T("Heating or cooling"), form("switchover", inner, T("Save"), "save", form_cls="changes"), about)
FACING_WORDS = {"": M("Not known"), "N": M("North"), "NE": M("North-east"), "E": M("East"), "SE": M("South-east"),
@@ -532,7 +694,7 @@ def _room_options(rooms, current: str) -> str:
names = list(rooms)
if current and current not in {dp.slug(r) for r in names}:
names.append(current)
return f'<option value="">{E(T("No room"))}</option>' + "".join(
return f'<option value=""{"" if current else " selected"}>{E(T("No room"))}</option>' + "".join(
f'<option value="{E(r)}"{" selected" if dp.slug(r) == current else ""}>{E(r)}</option>' for r in names)
@@ -546,15 +708,16 @@ def shade_html(d: dict, rooms) -> str:
opts = "".join(f'<option value="{k}"{" selected" if k == cur else ""}>{E(T(w))}</option>' for k, w in FACING_WORDS.items())
if cur is None:
opts += f'<option value="{face:g}" selected>{face:g}°</option>'
inner = (hidden(id=d["id"]) + '<p class="note">' + E(T(
inner = (hidden(id=d["id"]) + '<div class="row">'
f'<div><label for="area-{E(d["id"])}">{E(T("Room it shades"))}</label><select id="area-{E(d["id"])}" name="area">'
f'{_room_options(rooms, sh.get("area") or "")}</select></div>'
f'<div><label for="face-{E(d["id"])}">{E(T("The window faces"))}</label><select id="face-{E(d["id"])}" name="facing">{opts}</select></div></div>'
'<p class="note">' + E(T("Without the window's direction Cantabile only closes it at night in winter.")) + "</p>")
about = info(E(T(
"Cantabile moves it by the sun: in summer it closes it while the sun is on the window and the room is warm; in "
"winter it opens it for the sun's warmth and closes it at night. Never between 22:00 and 07:00, and after you "
"move it by hand it waits 4 hours.")) + "</p>"
f'<label for="area-{E(d["id"])}">{E(T("Room it shades"))}</label><select id="area-{E(d["id"])}" name="area">'
f'{_room_options(rooms, sh.get("area") or "")}</select>'
f'<label for="face-{E(d["id"])}">{E(T("The window faces"))}</label><select id="face-{E(d["id"])}" name="facing">{opts}</select>'
'<p class="note">' + E(T("Without the window's direction Cantabile only closes it at night in winter.")) + "</p>")
return f"<details><summary>{E(T('Room and window'))}</summary>{form('shade', inner, T('Save'))}</details>"
"move it by hand it waits 4 hours.")))
return section(T("Room and window"), form("shade", inner, T("Save"), "save", form_cls="changes"), about)
def place_html(d: dict, rooms) -> str:
@@ -566,9 +729,9 @@ def place_html(d: dict, rooms) -> str:
inner = (hidden(id=d["id"])
+ f'<label class="check"><input type="radio" name="place" value="indoor"{chk("indoor")}><span>{E(T("Indoor, in the room:"))}</span></label>'
+ f'<select name="area" aria-label="{E(T("Room"))}">{_room_options(rooms, pl.get("area") or "")}</select>'
+ f'<label class="check"><input type="radio" name="place" value="outdoor"{chk("outdoor")}><span>{E(T("Outdoor: Cantabile's outside temperature"))}</span></label>'
+ '<p class="note">' + E(T("An outdoor sensor counts before the weather service's temperature.")) + "</p>")
return f"<details><summary>{E(T('Indoor or outdoor'))}</summary>{form('place', inner, T('Save'))}</details>"
+ f'<label class="check"><input type="radio" name="place" value="outdoor"{chk("outdoor")}><span>{E(T("Outdoor: Cantabile's outside temperature"))}</span></label>')
about = info(E(T("An outdoor sensor counts before the weather service's temperature.")))
return section(T("Indoor or outdoor"), form("place", inner, T("Save"), "save", form_cls="changes"), about)
def weather_html(d: dict) -> str:
@@ -577,9 +740,11 @@ def weather_html(d: dict) -> str:
if not w:
return ""
if w.get("active"):
return '<p class="note">' + E(T("Cantabile plans with this forecast: solar, heating, cooling and the shades.")) + "</p>"
return ('<p class="note">' + E(T("Not used for planning: Cantabile plans with one weather forecast, another one's."))
+ "</p>" + form("weather", hidden(id=d["id"]), T("Plan with this forecast"), "secondary"))
return section(T("Forecast"), '<p class="note">' + E(T(
"Cantabile plans with this forecast: solar, heating, cooling and the shades.")) + "</p>")
return section(T("Forecast"), '<p class="note">' + E(T(
"Not used for planning: Cantabile plans with one weather forecast, another one's.")) + "</p>"
+ form("weather", hidden(id=d["id"]), T("Plan with this forecast"), "secondary"))
def protection_html(d: dict) -> str:
@@ -589,11 +754,15 @@ def protection_html(d: dict) -> str:
targets = [f"device:{d['id']}"] + [f"control:{c['id']}" for c in d.get("controls") or [] if c.get("id")]
targets += [t for t in pol if t not in targets]
seal = (pol.get(f"device:{d['id']}") or {}) if d.get("protection") == "sealed" else None
profile_name = f"{d.get('manufacturer', '')} {d.get('model', '')}".strip()
rows = []
covers = {f"control:{c['id']}" for c in d.get("controls") or [] if c.get("kind") == "cover" and c.get("id")}
kinds = {f"control:{c['id']}": c.get("kind") for c in d.get("controls") or [] if c.get("id")}
covers = {t for t, k in kinds.items() if k == "cover"}
for t in targets:
e = pol.get(t) or {}
kind, _, name = t.partition(":")
if kind == "control" and kinds.get(t) in CONTROL_WORDS:
name = T(CONTROL_WORDS[kinds[t]])
what = {"device": T("The whole device"), "control": T("Control {name}", name=name)}.get(kind, name)
lift = T("Allow Cantabile to move it") if t in covers else T("Allow switching off")
lvl = "sealed" if seal else e.get("level", "none")
@@ -602,54 +771,61 @@ def protection_html(d: dict) -> str:
rows.append(f'<li>{E(what)}: <b>{E(T("Sealed"))}</b> · {E(T("only {who} can change it", who=custodian(seal or e)))}'
f'{": " + E(why) if why else ""}</li>')
continue
why = f" ({E(e['why'])})" if e.get("why") and lvl == "protected" else ""
# the profile's default says only the profile's name: not repeated
why = f" ({E(e['why'])})" if e.get("why") and e["why"] != profile_name and lvl == "protected" else ""
state = f"<b>{E(T('protected'))}</b>" if lvl == "protected" else E(T("not protected"))
rows.append(f"<li>{E(what)}: {state}{why} "
rows.append(f'<li class="switch"><span>{E(what)}: {state}{why}</span>'
+ form("protect", hidden(id=d["id"], target=t, level="none" if lvl == "protected" else "protected"),
lift if lvl == "protected" else T("Protect"), "secondary", inline=True)
lift if lvl == "protected" else T("Protect"), "secondary")
+ "</li>")
return (f"<details><summary>{E(T('Protection'))}</summary><p class=\"note\">"
+ E(T("Protected: Cantabile never switches it off or cuts it; you still can, by hand. Sealed: only its "
"custodian can change it.")) + ("" if not covers else " " + E(T(
"A protected blind or curtain is not moved by Cantabile at all.")))
+ f'</p><ul class="plain">{"".join(rows)}</ul></details>')
about = E(T("Protected: Cantabile never switches it off or cuts it; you still can, by hand. Sealed: only its "
"custodian can change it.") + ("" if not covers else " " + T(
"A protected blind or curtain is not moved by Cantabile at all.")))
return section(T("Protection"), f'<ul class="plain">{"".join(rows)}</ul>', info(about))
def badges(d: dict) -> str:
st = PROFILE_STATUS.get(d.get("status"))
out = f'<span class="badge">{E(d.get("manufacturer", ""))} {E(d.get("model", ""))}</span>'
if d.get("generic"):
out += f'<span class="badge">{E(T("generic profile"))}</span>'
if st:
out += f'<span class="badge">{E(T(st))}</span>'
return out
def remove_html(d: dict) -> str:
return ('<section class="set"><details class="remove"><summary>' + E(T("Remove from Cantabile")) + "</summary>"
+ '<p class="note">' + E(T("Cantabile stops using it. Home Assistant keeps the device as it is.")) + "</p>"
+ form("remove", hidden(id=d["id"]), T("Yes, remove it"), "danger") + "</details></section>")
def device_card(d: dict, site: dict, rooms=()) -> str:
return (f'<div class="box"><b>{E(d["name"])}</b>{badges(d)}{what_lines(d.get("assets") or [], d.get("controls") or [], False)}'
f'{notes(d)}{consent_html(d, site)}{switchover_html(d)}{shade_html(d, rooms)}{place_html(d, rooms)}'
f'{weather_html(d)}{protection_html(d)}'
f"<details><summary>{E(T('Remove'))}</summary><p class=\"note\">"
+ E(T("Cantabile stops using it. Home Assistant keeps the device as it is."))
+ "</p>" + form("remove", hidden(id=d["id"]), T("Stop using it with Cantabile"), "secondary") + "</details></div>")
def device_row(d: dict) -> str:
"""A device in use on the list: name, state in words, main values now,
protection; its settings on its own page."""
vals = device_values(d)
return (f'<a class="box dev" href="?p=devices&amp;d={urllib.parse.quote(d["id"])}"><span class="grow">'
f'<span class="name">{E(d["name"])}</span> {protection_badge(d)}'
f'<span class="model">{model_line(d)}</span><span class="state">{device_state(d)}</span>'
+ (f'<span class="values">{E(vals)}</span>' if vals else "")
+ '</span><span class="chev" aria-hidden="true">›</span></a>')
def offer_card(h: dict) -> str:
def offer_card(h: dict, rooms=()) -> str:
"""A device HA has that a profile knows, not used yet: what it would
give, "Use with Cantabile"."""
p = h["profile"]
name = h["name"] or h["model"]
generic = f' · <span class="muted">{E(T("generic profile"))}</span>' if h.get("generic") else ""
would = T("Cantabile would read: {values}.", values=reads_words(dp.reads(h["assets"]), rooms) or T("nothing"))
kinds = control_words(h["controls"])
if kinds:
would += " " + T("It could control: {controls}.", controls=kinds)
proposed = ""
if h.get("in_mapping"):
ids = ", ".join(quantity_words(i) for i in h["in_mapping"])
ids = ids_words(h["in_mapping"], rooms)
proposed = '<p class="note">' + E(
T("Proposed by Cantabile (not checked yet): {values}. Use it with Cantabile to confirm it as this profile "
"sees it.", values=ids) if h.get("mapping_source") in ("proposed", "imported")
else T("In your own mapping: {values}. Those stay as they are.", values=ids)) + "</p>"
body = what_lines(h["assets"], h["controls"], True) + notes(h) + proposed
view = dict(h, status=p.get("status"))
head = (f'<span class="grow"><span class="name">{E(name)}</span> {status_badge(p.get("status"), False)}'
f'<span class="model">{E((h.get("manufacturer", "") + " " + h.get("model", "")).strip())}{generic}</span></span>')
body = f'<p class="note">{E(would)}</p>' + notes(h, rooms, False) + proposed
if not h["assets"] and not h["controls"]:
return f'<div class="box"><b>{E(name)}</b>{badges(view)}{body}</div>'
return (f'<div class="box"><b>{E(name)}</b>{badges(view)}{body}'
+ form("use", hidden(ha_device=h["id"], profile=p["id"], name=name), T("Use with Cantabile")) + "</div>")
return f'<div class="box offer"><div class="top">{head}</div>{body}</div>'
return (f'<div class="box offer"><div class="top">{head}'
+ form("use", hidden(ha_device=h["id"], profile=p["id"], name=name), T("Use with Cantabile"), "secondary")
+ f"</div>{body}</div>")
def nav(page: str) -> str:
@@ -664,32 +840,55 @@ def html(title: str, body: str, page: str) -> str:
f"<script>{HASH_SCRIPT}</script></head><body>{nav(page)}{body}</body></html>")
def messages(msg: str, err: str) -> str:
return (f'<div class="box ok">{E(msg)}</div>' if msg else "") + (f'<div class="box err">{E(err)}</div>' if err else "")
def page_devices(v: dict, msg: str = "", err: str = "") -> str:
body = [f"<h2>{E(T('Devices'))}</h2><p class=\"note\">"
+ E(T("Home Assistant's devices that a Cantabile device profile knows. Use one with Cantabile to see it on "
"Cantabile's dashboard and to let Cantabile read it once you have given your consent.")) + "</p>"]
if msg:
body.append(f'<div class="box ok">{E(msg)}</div>')
if err:
body.append(f'<div class="box err">{E(err)}</div>')
about = E(T("Home Assistant's devices that a Cantabile device profile knows. Use one with Cantabile to see it on "
"Cantabile's dashboard and to let Cantabile read it once you have given your consent."))
body = [f"<h2>{E(T('Devices'))}{info(about)}</h2>" + messages(msg, err)]
rooms = v.get("rooms") or []
if v.get("devices"):
body.append(f"<h3>{E(T('Used with Cantabile'))}</h3>")
body += [device_card(d, v.get("site") or {}, v.get("rooms") or []) for d in v["devices"]]
n = len(v["devices"])
body.append(f"<h3>{E(TN('{n} device in use with Cantabile', '{n} devices in use with Cantabile', n))}</h3>")
body += [device_row(dict(d, rooms=rooms)) for d in v["devices"]]
elif not v.get("ha_error"):
body.append('<p class="note">' + E(T("No device is used with Cantabile yet. Add one below.")) + "</p>")
body.append(f'<div class="add"><h2>{E(T("Add a device"))}</h2>')
if v.get("offers"):
body.append(f"<h3>{E(T('In Home Assistant, with a profile'))}</h3>")
body += [offer_card(h) for h in v["offers"]]
elif not v.get("ha_error") and not v.get("devices"):
body.append('<p class="note">' + E(T("No device in Home Assistant fits a Cantabile profile yet.")) + "</p>")
body.append(f"<h3>{E(T('Devices in Home Assistant you can add'))}</h3>")
body += [offer_card(h, rooms) for h in v["offers"]]
elif not v.get("ha_error"):
body.append('<p class="note">' + E(T("No other device in Home Assistant fits a Cantabile profile.")) + "</p>")
if v.get("rest"):
n = len(v["rest"])
body.append(f"<details><summary>{E(TN('{n} more in Home Assistant without a profile (not used by Cantabile)', '{n} more in Home Assistant without a profile (not used by Cantabile)', n))}</summary><ul class=\"plain\">"
+ "".join(f"<li>{E(h['name'] or h['model'])} <small>{E(h['manufacturer'])} {E(h['model'])}</small></li>"
body.append(f"<details class=\"more\"><summary class=\"note\">{E(TN('{n} more in Home Assistant without a profile (not used by Cantabile)', '{n} more in Home Assistant without a profile (not used by Cantabile)', n))}</summary><ul class=\"plain\">"
+ "".join(f"<li>{E(h['name'] or h['model'])} <small class=\"muted\">{E(h['manufacturer'])} {E(h['model'])}</small></li>"
for h in v["rest"]) + "</ul></details>")
if v.get("ha_error"):
body.append('<p class="note">' + E(T("Home Assistant's devices could not be read: {error}", error=v["ha_error"])) + "</p>")
body.append("</div>")
return html(T("Cantabile: devices"), "".join(body), "devices")
def page_device(v: dict, dev_id: str, msg: str = "", err: str = "") -> str:
"""One device in use: its state and values, then its settings, each
section saving on its own. The list when there is no such device."""
d = next((x for x in v.get("devices") or [] if x["id"] == dev_id), None)
if not d:
return page_devices(v, msg, err)
rooms = v.get("rooms") or []
vals = device_values(d)
body = (f'<a class="back" href="?p=devices">‹ {E(T("Devices"))}</a><h2>{E(d["name"])}</h2>'
f'<div class="model head">{model_line(d)} {status_badge(d.get("status"))}</div>{messages(msg, err)}'
f'<div class="box now"><span class="state">{device_state(d)}</span>'
+ (f'<span class="values">{E(vals)}</span>' if vals else "") + "</div>"
+ consent_html(d, v.get("site") or {}) + reads_html(d, rooms) + switchover_html(d) + shade_html(d, rooms)
+ place_html(d, rooms) + weather_html(d) + protection_html(d) + remove_html(d))
return html(f'Cantabile: {d["name"]}', body, "devices")
def page_refused(why: str, page: str = "devices") -> str:
head = T("Devices") if page == "devices" else T("Building or community")
return html("Cantabile", f"<h2>{E(head)}</h2><div class=\"box err\">{E(why)}</div>", page)
@@ -733,8 +932,10 @@ class App(JoinPage):
return status, out
if url.path not in ("/", "") or method not in ("GET", "POST"):
return 404, T("Not found")
dev_id = (q.get("d") or [""])[0]
if method == "GET":
return 200, page_devices(await self.devices.view())
v = await self.devices.view()
return 200, page_device(v, dev_id) if dev_id else page_devices(v)
f = {k: v[0] for k, v in urllib.parse.parse_qs(data.decode("utf-8", "replace")).items()}
by = hdr.get("x-remote-user-display-name") or hdr.get("x-remote-user-name") or "owner"
return 200, await self.post_devices(f, by)
@@ -747,6 +948,7 @@ class App(JoinPage):
msg = T("{name} is used with Cantabile now. It is on Cantabile's dashboard; reading and control are off "
"until you switch them on below.",
name=d["name"])
return page_device(await dv.view(), d["id"], msg)
elif do == "remove":
await dv.remove(f.get("id", ""))
msg = T("Cantabile no longer uses it.")
@@ -773,4 +975,7 @@ class App(JoinPage):
msg = T("Saved. Cantabile starts again to apply it (a few seconds).")
except dp.Fail as e:
err = str(e)
return page_devices(await dv.view(), msg, err)
# a device's setting: back to its page (removed: the list)
if do in ("use", "remove") or not f.get("id"):
return page_devices(await dv.view(), msg, err)
return page_device(await dv.view(), f["id"], msg, err)
+99
View File
@@ -695,3 +695,102 @@ def one_weather(frag: dict, others) -> None:
frag["weather_entity"] = ent
if any((o.get("inputs") or {}).get("weather") for o in others):
frag.pop("inputs", None)
# --- what a device reads, in the pages' words (both Devices pages) -------------------------
# The Hub panel and the add-on's page show a device's values by their
# meaning, never by asset id: room.living_room.setpoint_low and _high are
# one "heat/cool range", heating.state and cooling.state one "heating/
# cooling state". Here only the keys and values; each page has its words
# (its own catalogue) for each key.
RANGE, HVAC = "room.setpoint_range", "heating_cooling.state"
# A device's main values on the list, in this order (at most a few).
HEADLINE = ("room.temp", "room.setpoint", RANGE, HVAC, "heating.state", "cooling.state", "pv.power", "battery.soc",
"battery.power", "grid.power", "load.power", "ev.power", "heatpump.power", "heat.power",
"heatpump.flow_temp", "outside.temp", "room.humidity", "room.shade_position", "circuit.power")
def base_quantity(q: str) -> tuple[str, str]:
"""(quantity, place) of an asset id or a profile's value: room.living_room.temp
-> ("room.temp", "living_room"), room.{area}.humidity -> ("room.humidity", ""),
pv.2.power -> ("pv.power", ""), room.kitchen.temp_2 -> ("room.temp", "kitchen")."""
head, _, rest = q.partition(".")
if head in PER_PLACE and "." in rest:
place, _, last = rest.rpartition(".")
base = f"{head}.{last}"
if base not in QUANTITIES:
base = f"{head}.{re.sub(r'_[0-9]+$', '', last)}"
return base, ("" if place.startswith("{") else place)
part = part_of(q)
if part:
return part[0], ""
return (q if q in QUANTITIES else re.sub(r"_[0-9]+$", "", q)), ""
def reads(assets) -> list:
"""What a device reads: [(key, place)] in its order, each once; a
setpoint's low and high as RANGE, heating and cooling state as HVAC."""
keys = [base_quantity(a["asset"] if isinstance(a, dict) else a) for a in assets or []]
have = {k for k, _ in keys}
out = []
for k, place in keys:
if k in ("room.setpoint_low", "room.setpoint_high"):
k = RANGE
elif k in ("heating.state", "cooling.state") and {"heating.state", "cooling.state"} <= have:
k = HVAC
if [k, place] not in out:
out.append([k, place])
return out
def lacks(missing) -> dict:
"""mapping_for's missing in parts: the values a device does not give
(keys, as reads()), the controls not found (kinds), anything else."""
out = {"values": [], "controls": [], "other": []}
for m in missing or []:
m = str(m)
if re.fullmatch(r"[a-z_]+ control \(.*\)", m):
out["controls"].append(m.split(" ", 1)[0])
elif quantity_of(m) or quantity_of(base_quantity(m)[0]):
k = [x for x, _ in reads([m])][0]
if k not in out["values"]:
out["values"].append(k)
else:
out["other"].append(m)
return out
def asset_value(a: dict, states: dict):
"""One value now from HA's states ({entity_id: {"state", "attributes"}}):
a number (scaled), True/False (an "equals"), or None (not known)."""
s = (states or {}).get(a.get("entity"))
if not s:
return None
raw = (s.get("attributes") or {}).get(a["attribute"]) if a.get("attribute") else s.get("state")
if raw is None or raw in ("unavailable", "unknown", ""):
return None
if a.get("equals") is not None:
return str(raw) == str(a["equals"])
try:
return float(raw) * float(a.get("scale", 1))
except (TypeError, ValueError):
return None
def live(assets, states, limit: int = 3) -> list:
"""A device's main values now: [(key, value)] in HEADLINE's order, at
most limit; RANGE's value [low, high], HVAC's "heating", "cooling" or
"idle"; values not known left out."""
now = {}
for a in assets or []:
k = base_quantity(a["asset"])[0]
if k not in now:
v = asset_value(a, states)
if v is not None:
now[k] = v
if now.get("room.setpoint") is None and now.get("room.setpoint_low") is not None \
and now.get("room.setpoint_high") is not None:
now[RANGE] = [now["room.setpoint_low"], now["room.setpoint_high"]]
if "heating.state" in now and "cooling.state" in now:
now[HVAC] = "heating" if now.pop("heating.state") else "cooling" if now.pop("cooling.state") else "idle"
return [[k, now[k]] for k in HEADLINE if k in now][:limit]
+165
View File
@@ -0,0 +1,165 @@
# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
"""How many phases a charger charges on (docs/methods.md, finding A8-a): one
or three, never one fixed default. Per EV control, from the best evidence,
with where it came from:
mapping the control's `phases` (the installer's, or the device profile's)
device the charger reports it: the control's `phases` entity (the
EEBUS bridge's "phases" value; a sensor 1..3)
learned seen by the box while the car charged steadily: power / (volts
x current) is about 1, 2 or 3 (within 0.3) over ~10 minutes of
samples with more than 1 kW and more than 5 A, the power within
10 % and the current within 0.5 A. Kept in <state>/ev_phases.json
(phases, n: the times seen, at); learned again when the next
readings disagree CONFIRM times in a row
assumed nothing known: each use takes its own safe side
(ASSUMED): the §14a order's current bound 3 phases (a 3-phase
charger then never draws above the ordered power), the plan 1
phase (it reckons with a slower charger: starts earlier and
still meets the departure)
The current in the ratio is the charger's measured current (the control's
`current_measured` sensor) where mapped, else its setpoint (`current`); a
car that draws less than the setpoint gives a ratio between the steps,
which decides nothing, or a wrong one, which the next sessions put right.
"""
import json
import logging
import os
log = logging.getLogger(__name__)
ASSUMED = {"order": 3.0, "plan": 1.0}
WINDOW_S = 600.0 # ~10 minutes of samples decide
MIN_SPAN_S = 540.0
MIN_SAMPLES = 5
MIN_POWER_W = 1000.0
MIN_CURRENT_A = 5.0
POWER_STEADY = 0.10 # (max - min) / mean
CURRENT_STEADY_A = 0.5
TOLERANCE = 0.3
CONFIRM = 3 # disagreeing decisions in a row before the learned count changes
def ratio_phases(power_w: float, volts: float, current_a: float) -> int | None:
"""1, 2 or 3 when power / (volts x current) is within TOLERANCE of it."""
if volts <= 0 or current_a <= 0:
return None
r = power_w / (volts * current_a)
k = round(r)
return int(k) if 1 <= k <= 3 and abs(r - k) <= TOLERANCE else None
def steady(samples: list[tuple[float, float, float]]) -> tuple[float, float] | None:
"""(mean power, mean current) of samples (t, W, A) that are steady
charging over the window, else None."""
if len(samples) < MIN_SAMPLES or samples[-1][0] - samples[0][0] < MIN_SPAN_S:
return None
ps, cs = [s[1] for s in samples], [s[2] for s in samples]
if min(ps) <= MIN_POWER_W or min(cs) <= MIN_CURRENT_A:
return None
mp = sum(ps) / len(ps)
if (max(ps) - min(ps)) / mp > POWER_STEADY or max(cs) - min(cs) > CURRENT_STEADY_A:
return None
return mp, sum(cs) / len(cs)
class EvPhases:
def __init__(self, state_dir: str):
self.path = os.path.join(state_dir, "ev_phases.json")
self.learned: dict[str, dict] = {}
self.window: dict[str, list] = {}
try:
with open(self.path) as f:
raw = json.load(f)
self.learned = {k: v for k, v in raw.items() if isinstance(v, dict) and v.get("phases") in (1, 2, 3)}
except (OSError, ValueError, AttributeError):
pass
def _save(self):
tmp = self.path + ".tmp"
try:
with open(tmp, "w") as f:
json.dump(self.learned, f)
os.replace(tmp, self.path)
except OSError as e:
log.warning("ev phases: %s", e)
def sample(self, cid: str, power_w: float | None, current_a: float | None, volts: float, now: float) -> bool:
"""One reading while it charges (or not); True when the learned
phase count changed."""
w = self.window.setdefault(cid, [])
if power_w is None or current_a is None or power_w <= MIN_POWER_W or current_a <= MIN_CURRENT_A:
w.clear() # not charging steadily: start again
return False
w.append((now, float(power_w), float(current_a)))
while w and now - w[0][0] > WINDOW_S:
w.pop(0)
st = steady(w)
if st is None:
return False
k = ratio_phases(st[0], volts, st[1])
if k is None:
if w[-1][0] - w[0][0] >= WINDOW_S - 1:
w.pop(0) # a steady but odd ratio: slide on
return False
w.clear()
return self.decide(cid, k, now)
def decide(self, cid: str, k: int, now: float) -> bool:
cur = self.learned.get(cid)
if cur is None:
self.learned[cid] = {"phases": k, "n": 1, "at": int(now)}
log.info("ev %s: %d phase(s), learned", cid, k)
self._save()
return True
if cur["phases"] == k:
cur.update(n=int(cur.get("n", 0)) + 1, at=int(now))
cur.pop("against", None)
self._save()
return False
against = cur.get("against") or {}
n = int(against.get("n", 0)) + 1 if against.get("phases") == k else 1
if n >= CONFIRM:
self.learned[cid] = {"phases": k, "n": n, "at": int(now)}
log.info("ev %s: %d phase(s) now, learned again (was %d)", cid, k, cur["phases"])
self._save()
return True
cur["against"] = {"phases": k, "n": n}
self._save()
return False
def resolve(self, c, col=None) -> tuple[float | None, str]:
"""A control's phase count and its source (module docstring); None
and "assumed" when nothing says."""
p = c.params.get("phases")
if p:
return float(p), "mapping"
ent = c.entities.get("phases")
if ent and col is not None:
v = col.value(ent)
if v is not None and 1 <= round(v) <= 3:
return float(round(v)), "device"
got = self.learned.get(c.id)
if got:
return float(got["phases"]), "learned"
return None, "assumed"
def all(self, controls, col=None) -> dict[str, dict]:
"""{control id: {"phases": n or None, "source", "plan", "order"}}
for the EV controls (plan and order: the count each use takes)."""
out = {}
for c in controls:
if c.kind != "ev":
continue
n, src = self.resolve(c, col)
out[c.id] = {"phases": n, "source": src, "plan": n or ASSUMED["plan"], "order": n or ASSUMED["order"]}
return out
def words(info: dict) -> str:
"""'1 phase, learned', '3 phases, assumed for the grid order (1 for the plan)'."""
n, src = info.get("phases"), info.get("source", "")
if n:
return f"{int(n)} phase{'s' if n != 1 else ''}, {src}"
return f"phases unknown: {int(ASSUMED['order'])} assumed for the grid order, {int(ASSUMED['plan'])} for the plan"
+38 -5
View File
@@ -44,13 +44,18 @@ import base64
import hashlib
import json
import logging
import math
import os
import time
from .controls import ev_volts
log = logging.getLogger(__name__)
TOPIC = "cantabile-eebus/gridorder"
STALE_S = 300
SLOT_S = 900 # the cloud's ledger slots (fleet marketrun.go)
ACTION_ENTITY, ACTION_SERVICE = "grid:eebus-lpc", "grid.load_limit"
PENALTY_EUR_KWH = 500.0 # like a relayed emergency (building.py): nobody overrides it
# -- Ed25519 verification (RFC 8032, 5.1.7), pure Python ----------------------
@@ -136,6 +141,7 @@ class GridOrders:
self.order: dict | None = None # the last good order
self.received = 0.0
self.error = ""
self.reported = None # (order id, limit, slot) last told to the cloud
def pinned(self) -> str:
try:
@@ -198,6 +204,30 @@ class GridOrders:
o = self.active()
return f"verified:eebus-lpc:{o['control_box']['ski']}:{o['id']}" if o else ""
def action(self) -> dict | None:
"""What the cloud records of the order (an `action`, kind grid
limit): once per quarter-hour while it holds (and when it changes),
once when it ends. Fleet's market ledger takes a slot with one as
under a grid operator's order (higher rank: the contracts' deviations
in it are exempt). None: nothing new to tell."""
o, now = self.active(), self.clock()
if o:
key = (o["id"], o.get("limit_w"), int(now) // SLOT_S)
if key == self.reported:
return None
self.reported = key
cb = o.get("control_box") or {}
until = f", until {time.strftime('%H:%M', time.gmtime(o['until']))} UTC" if o.get("until") else ""
return {"v": 1, "at": int(now), "asset": "", "entity": ACTION_ENTITY, "service": ACTION_SERVICE,
"value": str(float(o["limit_w"])), "result": "done",
"why": f"a grid operator's order: EEBUS LPC {o.get('state', 'limited')}, {float(o['limit_w']):.0f} W, "
f"control box {cb.get('ski', '')}, order {o['id']}{until}"[:500]}
if self.reported is None:
return None
self.reported = None
return {"v": 1, "at": int(now), "asset": "", "entity": ACTION_ENTITY, "service": ACTION_SERVICE, "value": "",
"result": "done", "why": "the grid operator's order ended"}
def for_model(self, start: int, step_s: int, steps: int) -> dict:
"""The optimiser's constraint: the controllable consumers' draw from
the grid at most limit_w (state["grid_order"])."""
@@ -212,11 +242,12 @@ 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) -> dict:
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. {control id: {quantity: (floor,
limit)}}."""
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)}}."""
o = self.active()
if not o:
return {}
@@ -224,8 +255,10 @@ class GridOrders:
out = {}
for c in controls:
if c.kind == "ev":
volts = float(c.params.get("voltage", 230)) * float(c.params.get("phases", 3))
out[c.id] = {"current_a": (None, round(w / volts, 1))}
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":
out[c.id] = {"power_w": (None, w)}
return out
+94 -17
View File
@@ -201,10 +201,6 @@ MESSAGES = {
"dashboard and to let Cantabile read it once you have given your consent.":
"Geräte aus Home Assistant, die ein Geräteprofil von Cantabile kennt. Nutzen Sie eines mit Cantabile, um es im "
"Dashboard von Cantabile zu sehen und, sobald Sie eingewilligt haben, von Cantabile auslesen zu lassen.",
"Used with Cantabile": "Mit Cantabile genutzt",
"In Home Assistant, with a profile": "In Home Assistant, mit Profil",
"No device in Home Assistant fits a Cantabile profile yet.":
"Noch passt kein Gerät in Home Assistant zu einem Profil von Cantabile.",
("{n} more in Home Assistant without a profile (not used by Cantabile)",
"{n} more in Home Assistant without a profile (not used by Cantabile)"):
("{n} weiteres Gerät in Home Assistant ohne Profil (von Cantabile nicht genutzt)",
@@ -212,10 +208,6 @@ MESSAGES = {
"Home Assistant's devices could not be read: {error}": "Die Geräte von Home Assistant konnten nicht gelesen werden: {error}",
"Use with Cantabile": "Mit Cantabile nutzen",
"generic profile": "allgemeines Profil",
"Checked on a device": "An einem Gerät geprüft",
"From the maker's documentation, not yet checked on a device":
"Aus der Dokumentation des Herstellers, noch nicht an einem Gerät geprüft",
"Draft: check the values before you turn reading on": "Entwurf: Prüfen Sie die Werte, bevor Sie das Auslesen einschalten",
"nothing": "nichts",
"battery": "Batterie",
"heating": "Heizen",
@@ -259,8 +251,6 @@ MESSAGES = {
"Eine geschützte Jalousie oder ein geschützter Vorhang wird von Cantabile gar nicht bewegt.",
"Cantabile would read: {values}.": "Cantabile würde auslesen: {values}.",
"It could control: {controls}.": "Steuern könnte es: {controls}.",
"Cantabile reads: {values}.": "Cantabile liest aus: {values}.",
"It may control: {controls}.": "Steuern darf es: {controls}.",
"Not found in Home Assistant: {entities}.": "In Home Assistant nicht gefunden: {entities}.",
"Read by your own mapping already, so left out here: {values}.":
"Schon von Ihrer eigenen Zuordnung ausgelesen, daher hier weggelassen: {values}.",
@@ -274,7 +264,6 @@ MESSAGES = {
"Von Cantabile vorgeschlagen (noch nicht geprüft): {values}. Nutzen Sie es mit Cantabile, um es so zu bestätigen, "
"wie dieses Profil es sieht.",
"In your own mapping: {values}. Those stay as they are.": "In Ihrer eigenen Zuordnung: {values}. Diese bleiben, wie sie sind.",
"Cantabile may read these values": "Cantabile darf diese Werte auslesen",
"Save": "Speichern",
"Saved.": "Gespeichert.",
"Heating or cooling": "Heizen oder Kühlen",
@@ -285,8 +274,6 @@ MESSAGES = {
"By outdoor temperature": "Nach Außentemperatur",
"This thermostat can heat and cool. Cantabile uses one at a time; the other is never touched.":
"Dieses Thermostat kann heizen und kühlen. Cantabile nutzt immer nur eines; das andere bleibt unberührt.",
"By outdoor temperature: heat below (°C)": "Nach Außentemperatur: heizen unter (°C)",
"cool above (°C)": "kühlen über (°C)",
"Between the two it stays as it is, so it does not switch back and forth on a mild day.":
"Dazwischen bleibt es, wie es ist, damit es an einem milden Tag nicht hin und her schaltet.",
"Protection": "Schutz",
@@ -307,10 +294,8 @@ MESSAGES = {
"the grid operator": "der Netzbetreiber",
"the metering operator": "der Messstellenbetreiber",
"the energy community's operator": "der Betreiber der Energiegemeinschaft",
"Remove": "Entfernen",
"Cantabile stops using it. Home Assistant keeps the device as it is.":
"Cantabile nutzt es nicht mehr. Home Assistant behält das Gerät, wie es ist.",
"Stop using it with Cantabile": "Nicht mehr mit Cantabile nutzen",
"Cantabile no longer uses it.": "Cantabile nutzt es nicht mehr.",
"Cantabile could not ask Home Assistant who you are ({error}).":
"Cantabile konnte Home Assistant nicht fragen, wer Sie sind ({error}).",
@@ -335,8 +320,6 @@ MESSAGES = {
"First give your consent in the add-on's configuration (Settings, Add-ons, Cantabile Edge Agent, Configuration).":
"Geben Sie zuerst Ihre Einwilligung in der Konfiguration des Add-ons (Einstellungen, Add-ons, Cantabile Edge "
"Agent, Konfiguration).",
"Cantabile may control it ({controls}), within your limits":
"Cantabile darf es steuern ({controls}), innerhalb Ihrer Grenzen",
"Control also needs your consent to control devices in the add-on's configuration.":
"Zum Steuern braucht es außerdem Ihre Einwilligung zum Steuern von Geräten in der Konfiguration des Add-ons.",
"Saved. Cantabile starts again to apply it (a few seconds).":
@@ -347,4 +330,98 @@ MESSAGES = {
"bis Sie sie unten einschalten.",
"Only an administrator of Home Assistant can use this page.":
"Nur ein Administrator von Home Assistant kann diese Seite nutzen.",
'room temperature': 'Raumtemperatur',
'humidity': 'Luftfeuchte',
'setpoint': 'Solltemperatur',
'heat/cool range': 'Heiz-/Kühlbereich',
'heating/cooling state': 'Heiz-/Kühlzustand',
'heating state': 'Heizzustand',
'cooling state': 'Kühlzustand',
'position': 'Stellung',
'tilt': 'Neigung',
'solar power': 'Solarleistung',
'solar energy': 'Solarertrag',
'grid power': 'Netzleistung',
'power from the grid': 'Bezug aus dem Netz',
'power to the grid': 'Einspeisung ins Netz',
'energy from the grid': 'Energie aus dem Netz',
'energy to the grid': 'Energie ins Netz',
'battery power': 'Batterieleistung',
'battery charge': 'Batterieladestand',
'energy charged': 'geladene Energie',
'energy discharged': 'entladene Energie',
'home consumption': 'Hausverbrauch',
'home energy': 'Hausenergie',
'heat pump power': 'Leistung der Wärmepumpe',
'heat pump energy': 'Energie der Wärmepumpe',
'flow temperature': 'Vorlauftemperatur',
'hot water temperature': 'Warmwassertemperatur',
'outdoor temperature': 'Außentemperatur',
'outdoor humidity': 'Außenluftfeuchte',
'gas': 'Gas',
'charging power': 'Ladeleistung',
'power': 'Leistung',
'energy': 'Energie',
'set to {v}': 'eingestellt auf {v}',
'set to {low}–{high}': 'eingestellt auf {low}–{high}',
'solar {v}': 'Solar {v}',
'battery {v}': 'Batterie {v}',
'grid {v}': 'Netz {v}',
'home {v}': 'Haus {v}',
'charging {v}': 'lädt mit {v}',
'heat pump {v}': 'Wärmepumpe {v}',
'flow {v}': 'Vorlauf {v}',
'outside {v}': 'außen {v}',
'humidity {v}': 'Luftfeuchte {v}',
'{v} open': '{v} offen',
'idle': 'in Ruhe',
'checked': 'geprüft',
'Checked on a device: its values are known to be right.':
'An einem Gerät geprüft: Seine Werte stimmen nachweislich.',
'untested': 'ungeprüft',
"Made from the maker's documentation, not yet checked on a device. Look at its values before you turn reading on.":
'Nach der Dokumentation des Herstellers erstellt, noch nicht an einem Gerät geprüft. Sehen Sie sich seine Werte an, bevor Sie das Auslesen einschalten.',
'draft': 'Entwurf',
'A draft profile: check the values before you turn reading on.':
'Ein Profil im Entwurf: Prüfen Sie die Werte, bevor Sie das Auslesen einschalten.',
'Reading': 'Auslesen',
'Cantabile may read these values.': 'Cantabile darf diese Werte auslesen.',
'Reading and control': 'Auslesen und Steuern',
'What Cantabile reads': 'Was Cantabile ausliest',
'Forecast': 'Wettervorhersage',
'{what} ({room})': '{what} ({room})',
'In use': 'In Betrieb',
'reading on': 'Auslesen an',
'Added': 'Hinzugefügt',
'reading off': 'Auslesen aus',
'Control': 'Steuern',
'Cantabile may control it ({controls}), within your limits.':
'Cantabile darf es steuern ({controls}), innerhalb Ihrer Grenzen.',
'{control} control': 'Steuerung {control}',
'control on': 'Steuern an',
'control off': 'Steuern aus',
'sealed': 'versiegelt',
'Add a device': 'Ein Gerät hinzufügen',
'On': 'An',
'Off': 'Aus',
'Heat below (°C)': 'Heizen unter (°C)',
'Cool above (°C)': 'Kühlen über (°C)',
'Devices in Home Assistant you can add': 'Geräte in Home Assistant, die Sie hinzufügen können',
'This device does not report: {values}.': 'Dieses Gerät meldet nicht: {values}.',
'Remove from Cantabile': 'Aus Cantabile entfernen',
'Yes, remove it': 'Ja, entfernen',
'No device is used with Cantabile yet. Add one below.':
'Noch kein Gerät wird mit Cantabile genutzt. Fügen Sie unten eines hinzu.',
'Turn off': 'Ausschalten',
'Turn on': 'Einschalten',
('{n} device in use with Cantabile', '{n} devices in use with Cantabile'):
('{n} Gerät mit Cantabile in Betrieb', '{n} Geräte mit Cantabile in Betrieb'),
'More information': 'Mehr Informationen',
'No other device in Home Assistant fits a Cantabile profile.':
'Kein weiteres Gerät in Home Assistant passt zu einem Cantabile-Profil.',
'Reads: {values}': 'Liest: {values}',
'Controls: {controls}': 'Steuert: {controls}',
'heat delivered (thermal)': 'gelieferte Wärme (thermisch)',
'heat energy (thermal)': 'Wärmemenge (thermisch)',
'heat {v} (thermal)': 'Wärme {v} (thermisch)',
}
+123 -13
View File
@@ -2,7 +2,9 @@
"""Inputs for the optimiser: the latest states of the controls' and the
inputs' entities (presence, temperatures, humidity, outside temperature,
sun, weather), a short local history of load and PV (the fallback when no
model bundle says), and the 15-minute model state for the horizon.
model bundle says), and the 15-minute model state for the horizon. A
room's R and C: the mapping's, else the model bundle's (its rooms), else
the defaults; sources.rooms says which per control.
None of this leaves the site; only the plan does (controller.py).
@@ -138,10 +140,36 @@ def _hourly(forecast: list[dict], key: str, start: int, steps: int) -> list[floa
return out
def _series(name, start, bundles, history, tz, now_value, default):
s = bundles.forecast(name, start, STEP_S, STEPS, tz) if bundles else None
if s is not None:
return s, "model"
def watts(col: Collector, eid: str) -> float | None:
"""A power sensor's value in W (HA's kW converted)."""
v = col.value(eid)
if v is not None and col.attr(eid, "unit_of_measurement") == "kW":
v *= 1000.0
return v
def base_load(col: Collector, inputs) -> float | None:
"""The house's load without the devices the plan plans itself (Finding
A2-a): load_power less the planned devices' own meters
(inputs.controlled_power: heat pump, A/C, charger), never below 0. A
device meter without a value counts 0 (a charger's sensor goes
unavailable while idle). None while the load has none."""
eids = [inputs.load_power] if isinstance(inputs.load_power, str) else list(inputs.load_power or [])
vals = [watts(col, e) for e in eids if e]
if not vals or None in vals:
return None
ctl = sum(watts(col, e) or 0.0 for e in getattr(inputs, "controlled_power", None) or [])
return max(0.0, sum(vals) - ctl)
def _series(name, start, bundles, history, tz, now_value, default, model_names=None):
"""A series for the horizon: the model bundle's (the first of
model_names it has, default name), else the same quarter hour 1 or 2
days back, else the value now, else the default."""
for m in (model_names if model_names is not None else (name,)):
s = bundles.forecast(m, start, STEP_S, STEPS, tz) if bundles else None
if s is not None:
return s, "model" if m == name else f"model ({m})"
out, have = [], 0
for k in range(STEPS):
t = start + k * STEP_S
@@ -228,15 +256,28 @@ def cover_position(col: Collector, ent: str) -> float | None:
def model_state(now: float, controls, inputs, col: Collector, bundles, history, tz: str,
weather_forecast: list[dict] | None, extra_limits: dict | None = None,
occupied_hours=(6, 22), building: dict | None = None, location: dict | None = None,
shade_ctx: dict | None = None, grid_order: dict | None = None) -> dict:
shade_ctx: dict | None = None, grid_order: dict | None = None,
grid_max_w: float | None = None, ev_phases: dict | None = None) -> dict:
"""The 48 h, 15-minute input for the optimiser (JSON: it runs in a
subprocess). location: the site's latitude and longitude (HA's
configuration); shade_ctx: per cover control its room (temp_c,
setpoint_c, season: shades.py)."""
setpoint_c, season: shades.py); grid_max_w: the site's connection (W,
config; the optimiser's default without it); ev_phases: per EV control
its phase count and source (evphases.EvPhases.all), else the mapping's."""
start = int(now // STEP_S * STEP_S)
zone = ZoneInfo(tz or "UTC")
prices = bundles.prices(start, STEP_S, STEPS, now)
load, load_src = _series("load_w", start, bundles, history, tz, col.total(inputs.load_power), 500.0)
# the base load: the house without the planned devices (Finding A2-a), so
# the plan, the building's shift and the grid order's base (optimizer)
# do not count them twice. The model's base_load_w is that; its load_w
# (load.power as metered) is too only where no planned device has a meter
# inside it, else the history of the base load stands in.
ctl = getattr(inputs, "controlled_power", None) or []
load, load_src = _series("load_w", start, bundles, history, tz, base_load(col, inputs), 500.0,
("base_load_w",) if ctl else ("base_load_w", "load_w"))
if ctl and not load_src.startswith("model") and bundles and \
bundles.forecast("load_w", start, STEP_S, 1, tz) is not None:
load_src += " (the model's load_w includes the planned devices: not used)"
pv, pv_src = _series("pv_w", start, bundles, history, tz, None, 0.0)
t_out = _hourly(weather_forecast or [], "temperature", start, STEPS)
t_src = "weather forecast"
@@ -270,7 +311,8 @@ def model_state(now: float, controls, inputs, col: Collector, bundles, history,
continue
h = datetime.fromtimestamp(start + k * STEP_S, timezone.utc).astimezone(zone).hour
occupied.append(1 if occupied_hours[0] <= h < occupied_hours[1] else 0)
devices = []
devices, rooms_src, phases_src = [], {}, {}
one_room = sum(c.kind in ("heating", "cooling") for c in controls) == 1
for c in controls:
if hasattr(c, "learn_range"):
c.learn_range(col) # a climate's own min_temp..max_temp
@@ -278,18 +320,34 @@ def model_state(now: float, controls, inputs, col: Collector, bundles, history,
for q in _quantities(c):
b = c.bounds(q, (extra_limits or {}).get(c.id))
bounds[q] = [b.lo, b.hi, b.lo_by, b.hi_by]
devices.append({"id": c.id, "kind": c.kind, "params": {k: c.p(k) for k in _param_names(c)},
params = {k: c.p(k) for k in _param_names(c)}
if c.kind == "ev":
# the count from the best evidence (evphases.py); None: the plan assumes 1
info = (ev_phases or {}).get(c.id) or \
({"phases": float(c.params["phases"]), "source": "mapping"} if c.params.get("phases") else
{"phases": None, "source": "assumed"})
params["phases"] = info["phases"]
phases_src[c.id] = {"phases": info["phases"], "source": info["source"]}
if c.kind in ("heating", "cooling"):
rooms_src[c.id] = _room_rc(c, params, bundles, one_room, now)
devices.append({"id": c.id, "kind": c.kind, "params": params,
"state": device_state(c, col, now), "bounds": bounds,
"channels": sorted(c.writable())})
clouds = _hourly(weather_forecast or [], "cloud_coverage", start, STEPS)
sky = [max(0.0, min(1.0, 1 - c / 100.0)) for c in clouds] if clouds else [1.0] * STEPS
ghi, ghi_src = irradiance(start, location, sky, sun if peak > 100 else None)
out = {"v": 1, "start": start, "step_s": STEP_S, "steps": STEPS, "tz": tz,
"price_import": prices.import_ct, "price_export": prices.export_ct, "price_note": prices.note,
"load_w": load, "pv_w": pv, "t_out": t_out, "sun": sun, "occupied": occupied, "sky": sky,
"location": location or {},
"ghi_w_m2": ghi, "location": location or {},
"sources": {"load": load_src, "pv": pv_src, "t_out": t_src, "model": bundles.model_id(),
"sky": "weather forecast" if clouds else "clear"},
"devices": devices, "building": building or {}, "grid_order": grid_order or {}}
"sky": "weather forecast" if clouds else "clear", "rooms": rooms_src, "ghi": ghi_src,
"ev_phases": phases_src},
"devices": devices, "building": building or {}, "grid_order": grid_order or {},
# the market's contracts in force as sources and sinks (shadow, the market's step 2)
"market": bundles.market_for_model(start, STEP_S, STEPS, now) if hasattr(bundles, "market_for_model") else []}
if grid_max_w:
out["grid_max_w"] = float(grid_max_w)
# a shade's moves by rules on the sun and its room (shades.py); the
# optimiser takes them as they are
from . import shades
@@ -299,6 +357,58 @@ def model_state(now: float, controls, inputs, col: Collector, bundles, history,
return out
def irradiance(start: int, location: dict | None, sky: list[float],
pv_sun: list[float] | None) -> tuple[list[float], str]:
"""Global irradiance per step (W/m²) for a room's fitted sun
(solar_m2): Haurwitz's clear sky, 1098 cos z exp(-0.057 / cos z), at
the step's middle where the site's location is known, times the sky
(1 - the forecast's cloud cover); else the PV forecast scaled to its
peak (pv_sun, A1.2) times 1000 W/m², a rough stand-in; else none (the
sun's elevation now, held, would shine all night)."""
from .shades import sun_position
lat, lon = (location or {}).get("latitude"), (location or {}).get("longitude")
if lat is None or lon is None:
if pv_sun is None:
return [0.0] * STEPS, "none (no location, no PV forecast)"
return [1000.0 * max(0.0, x) for x in pv_sun], "PV forecast"
out = []
for k in range(STEPS):
elev, _ = sun_position(start + k * STEP_S + STEP_S / 2, float(lat), float(lon))
cz = math.sin(math.radians(elev))
clear = 1098.0 * cz * math.exp(-0.057 / cz) if cz > 0.01 else 0.0
out.append(round(clear * max(0.0, min(1.0, sky[k] if k < len(sky) else 1.0)), 1))
return out, "clear sky x the sky"
def _room_rc(c, params: dict, bundles, only_one: bool, now: float) -> str:
"""A heating or cooling control's R and C: the mapping's own, else the
model's room (bundles.room_rc), else the defaults. A room fitted against
the electric power: C * cop and R / cop (the same RC; the optimiser's
heat is cop * P). Into params; where they came from."""
if "r_k_per_kw" in c.params or "c_kwh_per_k" in c.params:
return "mapping"
get = getattr(bundles, "room_rc", None)
rc = get(c.id, str(c.params.get("area") or ""), only_one, now) if get else None
if rc is None:
return "defaults"
r, cap = rc["r_k_per_kw"], rc["c_kwh_per_k"]
gain, solar = rc.get("gain_w") or 0.0, rc.get("solar_m2") or 0.0
cop = number(params.get("cop")) or 1.0
if rc.get("power") == "electric" and cop > 0:
# fitted in electric equivalents: the heat is cop times (like C)
r, cap = r / cop, cap * cop
gain = [g * cop for g in gain] if isinstance(gain, list) else gain * cop
solar *= cop
params["r_k_per_kw"], params["c_kwh_per_k"] = r, cap
# the fit's internal gain and sun (Finding B6-a): R and C were fitted
# with them; the mapping's own, where it sets them, win
if "internal_gain_w" not in c.params:
params["internal_gain_w"] = gain
if "solar_m2" not in c.params:
params["solar_m2"] = solar
return "model"
def _quantities(c) -> list[str]:
return {"battery": ["soc_pct", "power_w"], "heating": ["temp_c"], "cooling": ["temp_c"],
"ev": ["current_a"], "cover": ["position_pct"]}[c.kind]
+47 -7
View File
@@ -53,7 +53,27 @@ def _hash(eid: str) -> str:
return "h" + hashlib.sha256(eid.encode()).hexdigest()[:12]
def build(mapping, registries: dict, specs: dict, policy: dict, now: float) -> dict:
def battery_ratings(controls) -> dict:
"""A mapping's battery's ratings (an installer's mapping, an HA add-on
site: no devices tool's specs): the capacity and power its control's
params state (battery_kwh, battery_kw), never the defaults (a guess is
no rating). The cloud's planners (tenant power, Energy Sharing) read
them."""
kwh = kw = 0.0
for c in {c.id: c for c in controls if c.kind == "battery"}.values():
if "capacity_wh" in c.params:
kwh += float(c.params["capacity_wh"]) / 1000
if "max_charge_w" in c.params or "max_discharge_w" in c.params:
kw += max(float(c.p("max_charge_w")), float(c.p("max_discharge_w"))) / 1000
out = {"battery_kwh": round(kwh, 3)} if kwh > 0 else {}
if out and kw > 0:
out["battery_kw"] = round(kw, 3)
return out
def build(mapping, registries: dict, specs: dict, policy: dict, now: float, ev_phases: dict | None = None) -> dict:
"""ev_phases: per EV control its phase count and source (evphases.py),
told on the device of the control ("1 phase, learned" in the console)."""
ents = {e["entity_id"]: e for e in registries.get("entities") or []}
devs = {d["id"]: d for d in registries.get("devices") or []}
asset_of = {a.entity: a.asset for a in mapping.assets}
@@ -65,6 +85,7 @@ def build(mapping, registries: dict, specs: dict, policy: dict, now: float) -> d
"""The readings that are assumed, not measured (mapping.py)."""
return sorted({a.asset for e in eids for a in of_entity.get(e, []) if getattr(a, "assumed", False)})
control_of = {}
controls = {c.id: c for c in mapping.controls}
for c in mapping.controls:
for e in c.entities.values():
control_of.setdefault(e, c.id)
@@ -102,13 +123,18 @@ def build(mapping, registries: dict, specs: dict, policy: dict, now: float) -> d
continue
d = (ents.get(eid) or {}).get("device_id")
groups.setdefault(d or "", []).append(eid)
for d, eids in sorted(groups.items()):
# a control's ratings once (on its first device); not where the devices tool's spec has it (its own ratings)
rated: set[str] = {c for s in (specs.get("devices") or {}).values() for c in s.get("controls") or []}
for d, eids in sorted(groups.items(), key=lambda kv: (not kv[0], kv[0])):
hd = devs.get(d) or {}
if not d:
continue # entities without a device: nothing to tell
out.append({"id": "ha:" + hashlib.sha256(d.encode()).hexdigest()[:12], "source": "ha",
mine = {control_of[e] for e in eids if e in control_of}
ratings = battery_ratings([controls[i] for i in sorted(mine - rated)])
rated |= mine
if not d and not ratings:
continue # entities without a device: nothing to tell but a battery's ratings
out.append({"id": "ha:" + (hashlib.sha256(d.encode()).hexdigest()[:12] if d else "mapping"), "source": "ha",
**{k: hd.get(k) or "" for k in VERSION_KEYS}, **_eebus(hd),
"category": "", "profile": "", "profile_version": "", "ratings": {},
"category": "", "profile": "", "profile_version": "", "ratings": ratings,
"assets": sorted({asset_of[e] for e in eids if e in asset_of}),
"assumed": assumed_of(eids),
"controls": sorted({control_of[e] for e in eids if e in control_of}),
@@ -121,6 +147,11 @@ def build(mapping, registries: dict, specs: dict, policy: dict, now: float) -> d
if kind == "entity":
t = f"asset:{asset_of[name]}" if name in asset_of else f"entity:{_hash(name)}"
prot.append({"target": t, **{k: e.get(k) for k in ("level", "custodian", "source", "set_by", "role", "at", "why")}})
for d in out:
ph = {c: {"phases": ev_phases[c]["phases"], "source": ev_phases[c]["source"]}
for c in d.get("controls") or [] if c in (ev_phases or {})}
if ph:
d["ev_phases"] = ph
return {"v": 1, "made": int(now), "devices": out, "protection": prot}
@@ -132,6 +163,8 @@ class Inventory:
self.policy = policy or Policy(cfg.state_dir, cfg.site_id, clock)
self.specs_path = os.path.join(cfg.state_dir, "devices-specs.json")
self.sent_digest, self.sent_at = "", 0.0
self.waiting = False # the link was not connected: try again soon (agent.inventory_loop)
self.ev_phases = None # () -> per EV control its phases and source (the controller's; agent.py)
def specs(self) -> dict:
try:
@@ -147,6 +180,12 @@ class Inventory:
pub = getattr(self.sink, "publish", None)
if pub is None or client is None:
return False
# The link drops what comes before its NATS connection is up (at
# start the agent reaches HA first): not sent then, tried again.
cloud = getattr(self.sink, "cloud", None)
self.waiting = cloud is not None and not await cloud()
if self.waiting:
return False
try:
reg = await client.registries()
except Exception as e:
@@ -155,7 +194,8 @@ class Inventory:
now = self.clock()
if self.sent_at and now - self.sent_at < MIN_GAP_S:
return False
inv = build(self.mapping, reg, self.specs(), self.policy.entries(), now)
inv = build(self.mapping, reg, self.specs(), self.policy.entries(), now,
self.ev_phases() if self.ev_phases else None)
body = {k: v for k, v in inv.items() if k != "made"}
digest = hashlib.sha256(json.dumps(body, sort_keys=True).encode()).hexdigest()
if digest == self.sent_digest and now - self.sent_at < RESEND_S:
+31
View File
@@ -127,6 +127,8 @@ class Mapping:
for key, total in (("pv_power", "pv.power"), ("load_power", "load.power")):
if not getattr(self.inputs, key) and total in self.totals:
setattr(self.inputs, key, list(self.totals[total].entities))
if self.inputs.controlled_power is None:
self.inputs.controlled_power = controlled_power(self)
@classmethod
def load(cls, path: str) -> "Mapping":
@@ -334,3 +336,32 @@ def suggest(states: list[dict], registries: dict) -> dict:
out.append({"entity": eid, "asset": asset, "kind": "counter" if counter else "gauge",
"unit": target, "consent": False})
return {"version": 1, "assets": out}
# The metered draw of the devices the plan plans itself, per control kind
# (Finding A2-a): a site's load.power (an inverter's "house load", the sim's)
# is the whole house with them; the plan adds them as decisions, so their
# own meters come off the load (inputs.base_load). Not the battery: a house
# load never includes its charging.
CONTROLLED_POWER = {"heating": ("heatpump.power", "heating.power"), "cooling": ("ac.power", "cooling.power"),
"ev": ("ev.power",)}
def controlled_power(m: "Mapping") -> list[str]:
"""The entities of the planned devices' own power assets: for each kind
of control the mapping has, its assets (or their parts: ev.1.power, ...),
once each (a heat pump that heats and cools is one meter)."""
kinds = {c.kind for c in m.controls}
out = []
for kind, names in CONTROLLED_POWER.items():
if kind not in kinds:
continue
for name in names:
if name in m.by_asset:
ents = [m.by_asset[name].entity]
elif name in m.totals:
ents = list(m.totals[name].entities)
else:
ents = []
out += [e for e in ents if e not in out]
return out
+57
View File
@@ -36,6 +36,44 @@ NAMES = {
"flat_flex": {"en": "Flexibility", "de": "Flexibilität"},
"flat_request": {"en": "Building's request", "de": "Anfrage des Gebäudes"},
"flat_state": {"en": "State", "de": "Zustand"},
# the shadow market (a `market` bundle; announce.py, dashboards.py)
"market_exchange": {"en": "Exchange with {0}", "de": "Austausch mit {0}"},
"market_position": {"en": "Market net position", "de": "Markt: Nettoposition"},
"market_position_of": {"en": "{0}: market net position", "de": "{0}: Markt-Nettoposition"},
"market_price": {"en": "Shared energy price", "de": "Preis geteilter Energie"},
"market_actuator": {"en": "{0}: contract target", "de": "{0}: Vertragsvorgabe"},
"card_market": {"en": "Market (shadow)", "de": "Markt (Schattenbetrieb)"},
"mk_sells": {"en": "Sells to {0}", "de": "Verkauft an {0}"},
"mk_buys": {"en": "Buys from {0}", "de": "Kauft von {0}"},
"mk_flats": {"en": "{0} flats, summed", "de": "{0} Wohnungen, summiert"},
"mk_slot": {"en": "{0} kWh last quarter-hour (contract {1})", "de": "{0} kWh letzte Viertelstunde (Vertrag {1})"},
"mk_slot_open": {"en": "{0} kWh last quarter-hour", "de": "{0} kWh letzte Viertelstunde"},
"mk_no_value": {"en": "no metered value yet", "de": "noch kein Messwert"},
"mk_not_now": {"en": "not in force this quarter-hour", "de": "in dieser Viertelstunde nicht gültig"},
"mk_shadow": {"en": "shadow", "de": "Schattenbetrieb"},
"mk_period": {"en": "So far this {0}: {1} kWh · {2} €", "de": "Bisher in diesem {0}: {1} kWh · {2} €"},
"mk_month": {"en": "month", "de": "Monat"},
"mk_quarter": {"en": "quarter", "de": "Quartal"},
"mk_year": {"en": "year", "de": "Jahr"},
"mk_penalties": {"en": "penalties {0} € paid, {1} € received", "de": "Vertragsstrafen {0} € gezahlt, {1} € erhalten"},
"mk_deviation_self": {"en": "deviation {0} kWh, caused here", "de": "Abweichung {0} kWh, hier verursacht"},
"mk_deviation_other": {"en": "deviation {0} kWh, caused by the other side", "de": "Abweichung {0} kWh, von der Gegenseite verursacht"},
"mk_exempt": {"en": "exempt: {0}", "de": "ausgenommen: {0}"},
"mk_state_on": {"en": "on", "de": "ein"},
"mk_state_off": {"en": "off", "de": "aus"},
"mk_state_hold": {"en": "hold", "de": "halten"},
"mk_target": {"en": "contract", "de": "Vertrag"},
"mk_actual": {"en": "now", "de": "jetzt"},
"mk_unknown": {"en": "unknown", "de": "unbekannt"},
"mk_default": {"en": "falls back to {0} after {1} min", "de": "fällt nach {1} min auf {0} zurück"},
"mk_protection": {"en": "protection: {0}", "de": "Schutz: {0}"},
"mk_net_bought": {"en": "Net bought this month", "de": "Netto gekauft diesen Monat"},
"mk_shadow_note": {"en": "Shadow market: computed and shown only. Nothing is switched by it, no money moves; "
"your devices keep their own settings and protection.",
"de": "Schattenmarkt: nur berechnet und angezeigt. Nichts wird dadurch geschaltet, kein Geld "
"fließt; Ihre Geräte behalten ihre eigenen Einstellungen und ihren Schutz."},
"mk_stale": {"en": "The market's values are out of date (no new values from Cantabile Cloud).",
"de": "Die Marktwerte sind veraltet (keine neuen Werte von der Cantabile Cloud)."},
# dashboards (dashboards.py)
"dash_main": {"en": "Cantabile"},
"dash_climate": {"en": "Heating & cooling", "de": "Heizung & Kühlung"},
@@ -82,6 +120,16 @@ NAMES = {
"from_grid": {"en": "From the grid", "de": "Aus dem Netz"},
"to_grid": {"en": "To the grid", "de": "Ins Netz"},
"heat_pump": {"en": "Heat pump", "de": "Wärmepumpe"},
# heat (heat.power, heat.energy) is thermal: never shown as electricity
"heat": {"en": "Heat (thermal)", "de": "Wärme (thermisch)"},
"heat_building": {"en": "Heat from the building (thermal)", "de": "Wärme aus dem Gebäude (thermisch)"},
"heat_delivered": {"en": "Heat delivered (thermal)", "de": "Gelieferte Wärme (thermisch)"},
"heat_today": {"en": "Heat today (thermal)", "de": "Wärme heute (thermisch)"},
"heat_pump_electric": {"en": "Heat pump, electric", "de": "Wärmepumpe, elektrisch"},
"cop": {"en": "COP (heat ÷ electricity)", "de": "COP (Wärme ÷ Strom)"},
"electric_power": {"en": "Electric power", "de": "Elektrische Leistung"},
"heat_not_electric": {"en": "Heat, not electricity: not part of solar, home or grid above.",
"de": "Wärme, kein Strom: nicht Teil von Solar, Haus oder Netz oben."},
"ev": {"en": "Car", "de": "Auto"},
"circuits": {"en": "Circuits", "de": "Stromkreise"},
"of": {"en": "of", "de": "von"},
@@ -126,6 +174,15 @@ NAMES = {
}
COMMA = ("de", "fr", "it", "es", "nl", "ro", "ru", "pt", "pl", "cs", "da", "sv", "nb", "fi", "tr", "uk")
def number(v: float, language: str | None, digits: int = 1) -> str:
"""A number with the language's decimal mark (1.5 / 1,5)."""
s = f"{v:.{digits}f}"
return s.replace(".", ",") if lang(language) in COMMA else s
def lang(code: str | None) -> str:
"""HA's language ("de", "de-CH", "pt-BR") as our two-letter key."""
return (code or "en").split("-")[0].split("_")[0].lower() or "en"
+188 -20
View File
@@ -14,9 +14,12 @@ Device models (one function each, small and replaceable):
battery state of charge (estimated from params.soc_pct when no sensor),
charge/discharge power, efficiency, never both at once (binary)
heating a room's first-order thermal model (R in K/kW, C in kWh/K, the
cooling outside temperature, heat from the device and from the sun
through the room's covers); comfort target when occupied,
setback/setup otherwise; a switched boiler is on/off (binary)
cooling outside temperature, heat from the device, from the sun
through the room's covers, and the fit's internal gain and sun
(internal_gain_w, solar_m2 x the irradiance; the sun's only
where the room has no cover in the plan, which carries it));
comfort target when occupied, setback/setup otherwise; a
switched boiler is on/off (binary)
ev the energy needed by the departure time, between min and max
current (binary), only while connected
cover the share of the sun's heat into its room (0 closed .. 1 open);
@@ -31,6 +34,16 @@ limit_w from the grid beyond the household's own net load, i.e. the import
at most max(0, load - pv) + limit_w per step, with a penalty far above any
building request (nobody overrides it).
The market's contracts in force (state["market"], from the market bundle;
the market's step 2, minimal, shadow: the plan only, no commands): a contract
the home buys on is an import source at its price, one it sells on an
export sink, through the same meter as the grid (which keeps the tariff's
import and feed-in prices), so the plan exchanges where the contract beats
the grid. Each step uses its own slot's terms (window, amounts, price) when
the bundle carries the coming slots (a contract's "terms", term_at). The
plan's "market" lists per contract the planned kWh and the saving against
the grid (vs_grid_eur).
The building's requests (building.py, state["building"]): a load limit on
the grid import and a thermostat cap are constraints with a penalty (binding
far above any price, flexible with a price), a shift request a soft target
@@ -46,6 +59,9 @@ from zoneinfo import ZoneInfo
import highspy
from highspy.highs import highs_linear_expression as Lin
from .controls import ev_volts
from .evphases import words as phase_words
PENALTY_LIMIT = 5.0 # EUR per unit and step across a floor or limit (K, % of a battery, kWh)
COMFORT_EUR_KH = 2.0 # EUR per K and hour below (heating) or above (cooling) the comfort target
# while someone is home: above any price (0.30 let a room cool by 1.3 K
@@ -56,6 +72,10 @@ CHANGE_EUR_KW = 0.002 # EUR per kW a device's power changes from one step to
# plans (equal prices would otherwise give any order, and a charger or
# boiler must not be switched back and forth)
CLOSED_EUR = 0.00002 # EUR per step for a closed cover: open when nothing is at stake
MARKET_MAX_W = 100000.0 # W: a contract without a maximum, and the meter's import/export switch
GRID_MAX_W = 43470.0 # W: the site's connection when the state does not say (state["grid_max_w"],
# config grid_max_w): a German house connection's usual 63 A main fuse,
# 3 x 230 V x 63 A
class Model:
@@ -89,31 +109,112 @@ class Model:
# -- the house -------------------------------------------------------
def grid(self):
"""Import and export through the meter, each at most the site's
connection (grid_max_w; never below the house's own net load or
surplus, so there is always a plan). The meter either imports or
exports in a step: a binary where the feed-in pays at least the
import price (else importing to export at once would earn money and
the plan would run to the bound). Elsewhere none is needed: doing
both costs more than doing less of each, which keeps the balance and
only loosens every other constraint on the import (all are upper
bounds: the building's, the grid order's); steps with a market
contract have their own switch (market)."""
s = self.s
self.gin, self.gout = [], []
cap = float(s.get("grid_max_w") or GRID_MAX_W)
self.gin, self.gout, self.gcap = [], [], []
for t in range(self.T):
gi = self.var(cost=self.eur_wh(t, s["price_import"][t]))
go = self.var(cost=-self.eur_wh(t, s["price_export"][t]))
net = s["load_w"][t] - s["pv_w"][t]
hi_in, hi_out = max(cap, net), max(cap, -net)
gi = self.var(0.0, hi_in, cost=self.eur_wh(t, s["price_import"][t]))
go = self.var(0.0, hi_out, cost=-self.eur_wh(t, s["price_export"][t]))
spill = self.var(0.0, max(0.0, s["pv_w"][t]))
self.gin.append(gi)
self.gout.append(go)
self.gcap.append((hi_in, hi_out))
self.flows[t] += [(1, gi), (-1, go), (-1, spill)]
def grid_switch(self, skip):
"""The meter's import/export switch where the feed-in pays at least
the import price (grid), outside the steps in skip (market's own)."""
s = self.s
for t in range(self.T):
if t in skip or s["price_export"][t] < s["price_import"][t]:
continue
hi_in, hi_out = self.gcap[t]
imp = self.var(0.0, 1.0, integer=True)
self.h.addConstr(self.gin[t] - hi_in * imp <= 0)
self.h.addConstr(self.gout[t] + hi_out * imp <= hi_out)
def market(self):
"""The market's contracts in force (state["market"], bundles.py
market_for_model; shadow, the market's step 2): a contract the home
buys on is an import source at its price, one it sells on an export
sink, both through the same meter as the grid. Bounds per step: the
best-effort maximum; a firm amount (bought: at least that much; sold:
a shortfall costs the contract's price again, a stand-in for its
penalty); take-or-pay (the minimum is paid whether used or not). The
meter either imports or exports in a step (a binary where a contract
applies), so nothing bought is resold."""
self.buy = [[] for _ in range(self.T)] # contract import vars per step
self.sell = [[] for _ in range(self.T)]
self.contracts = [] # (contract, {step: var}, {step: paid var})
steps = set()
for c in self.s.get("market") or []:
vars_, paid_ = {}, {}
for t in range(max(0, c["from_step"]), min(self.T, c["to_step"])):
k = term_at(c, t) # this step's terms (the coming slots), else the contract's
if k is None:
continue
hi = k["max_w"] if k.get("max_w") else MARKET_MAX_W
eur = self.eur_wh(t, k["price_ct"])
if c["direction"] == "buys":
lo = min(k.get("guaranteed_w") or 0.0, hi)
mwh = k.get("minimum_wh") or 0.0
if mwh > 0: # take-or-pay: what is paid covers at least the minimum
v = self.var(lo, hi)
paid = self.var(mwh / self.dt, cost=eur)
self.h.addConstr(paid - v >= 0)
paid_[t] = paid
else:
v = self.var(lo, hi, cost=eur)
self.buy[t].append(v)
self.flows[t].append((1, v))
else:
v = self.var(0.0, hi, cost=-eur)
g = min(k.get("guaranteed_w") or 0.0, hi)
if g > 0:
short = self.var(cost=eur)
self.h.addConstr(v + short >= g)
self.sell[t].append(v)
self.flows[t].append((-1, v))
vars_[t] = v
steps.add(t)
self.contracts.append((c, vars_, paid_))
for t in steps:
imp = self.var(0.0, 1.0, integer=True)
self.h.addConstr(sum(self.buy[t], start=Lin()) + self.gin[t] - MARKET_MAX_W * imp <= 0)
self.h.addConstr(sum(self.sell[t], start=Lin()) + self.gout[t] + MARKET_MAX_W * imp <= MARKET_MAX_W)
self.grid_switch(steps)
def meter_in(self, t):
"""The meter's import in step t: the grid's and the contracts' bought."""
return self.gin[t] + sum(self.buy[t], start=Lin()) if self.buy[t] else self.gin[t]
def building(self):
"""The building's load limit and shift request (on the grid import)."""
"""The building's load limit and shift request (on the meter's import)."""
req = self.s.get("building") or {}
lim = req.get("load_limit")
if lim:
for t in range(lim["from_step"], lim["to_step"]):
over = self.var(cost=lim["penalty"] * self.dt / 1000.0)
self.h.addConstr(self.gin[t] - over <= lim["value"])
self.h.addConstr(self.meter_in(t) - over <= lim["value"])
sh = req.get("shift_request")
if sh:
a, b = sh["from_step"], sh["to_step"]
base = sum(max(0.0, self.s["load_w"][t] - self.s["pv_w"][t]) * self.dt for t in range(a, b))
target = max(0.0, base - sh["value"] * 1000.0)
miss = self.var(cost=sh["penalty"] / 1000.0)
imp = sum((self.dt * self.gin[t] for t in range(a, b)), start=Lin())
imp = sum((self.dt * self.meter_in(t) for t in range(a, b)), start=Lin())
self.h.addConstr(imp - miss <= target)
def grid_order(self):
@@ -124,7 +225,7 @@ class Model:
for t in range(o["from_step"], min(o["to_step"], self.T)):
base = max(0.0, self.s["load_w"][t] - self.s["pv_w"][t])
over = self.var(cost=o["penalty"] * self.dt / 1000.0)
self.h.addConstr(self.gin[t] - over <= base + o["limit_w"])
self.h.addConstr(self.meter_in(t) - over <= base + o["limit_w"])
def balance(self):
s = self.s
@@ -180,6 +281,9 @@ class Model:
switched = not cooling and "switch" in d["channels"] and "climate" not in d["channels"]
temps, powers, prev = [], [], t0
a = self.dt / (r * c)
internal = self.hourly(p.get("internal_gain_w") or 0.0)
solar = float(p.get("solar_m2") or 0.0)
ghi = self.s.get("ghi_w_m2") or [0.0] * self.T
for t in range(self.T):
if switched:
u = self.var(0.0, 1.0, integer=True)
@@ -190,10 +294,13 @@ class Model:
self.flows[t].append((-1, pw))
tt = self.var(-50.0, 80.0)
sign = -1.0 if cooling else 1.0
gain = sum((g * gx for g, gx in gains(t)), start=Lin())
# T[t+1] = T[t] (1 - a) + a T_out + dt/C (± cop P/1000 + sun gain/1000)
covers = gains(t)
gain = sum((g * gx for g, gx in covers), start=Lin())
# the fit's (B6): its internal gain, and its sun where no cover carries it
fixed = internal[t] + (solar * ghi[t] if not covers and t < len(ghi) else 0.0)
# T[t+1] = T[t] (1 - a) + a T_out + dt/C (± cop P/1000 + sun gain/1000 + fixed gains/1000)
self.h.addConstr(tt - (1 - a) * prev - sign * self.dt / c * cop / 1000.0 * pw
- self.dt / c / 1000.0 * gain == a * self.s["t_out"][t])
- self.dt / c / 1000.0 * gain == a * self.s["t_out"][t] + self.dt / c / 1000.0 * fixed)
occ = self.s["occupied"][t + 1] if t + 1 < self.T else self.s["occupied"][t]
target = min(max(comfort if occ else other, lo), hi)
miss = self.var(cost=COMFORT_EUR_KH * self.dt)
@@ -219,12 +326,21 @@ class Model:
self.devices[d["id"]] = ("cooling" if cooling else "heating",
{"temp": temps, "power": powers, "pmax": pmax, "switched": switched})
def hourly(self, v) -> list[float]:
"""A number, or 24 by local hour, per step."""
if not isinstance(v, list):
return [float(v)] * self.T
zone = ZoneInfo(self.s.get("tz") or "UTC")
start, step = self.s["start"], self.s["step_s"]
return [float(v[datetime.fromtimestamp(start + t * step, timezone.utc).astimezone(zone).hour % len(v)])
for t in range(self.T)]
def ev(self, d):
p, st, b = d["params"], d["state"], d["bounds"]
if not st.get("connected"):
self.devices[d["id"]] = ("ev", None)
return
volts = float(p["voltage"]) * float(p["phases"])
volts = ev_volts(p, "plan")
imax = min(float(p["max_current_a"]), b["current_a"][1])
imin = max(float(p["min_current_a"]), b["current_a"][0])
dep = departure_step(self.s, str(st.get("departure") or p["departure"]))
@@ -279,6 +395,7 @@ class Model:
def solve(self, time_limit: float):
s = self.s
self.grid()
self.market()
covers = [d for d in s["devices"] if d["kind"] == "cover"]
rooms = {d["id"] for d in s["devices"] if d["kind"] in ("heating", "cooling")}
for d in covers:
@@ -349,10 +466,59 @@ def plan(s: dict, time_limit: float = 30.0) -> dict:
devices[d["id"]] = entries
energy = sum(m.eur_wh(t, pi[t]) * x(m.gin[t]) - m.eur_wh(t, s["price_export"][t]) * x(m.gout[t])
for t in range(T))
return {"v": 1, "made": int(time.time()), "start": start, "step_s": step, "status": status,
"solve_s": round(time.time() - t0, 2), "devices": devices, "flex": flexibility(m, x),
"cost_eur": round(energy, 2), "baseline_eur": round(baseline(s, m, x), 2),
"price_note": s.get("price_note", ""), "sources": s.get("sources", {})}
market = market_plan(s, m, x)
energy += sum(c["cost_eur"] for c in market)
out = {"v": 1, "made": int(time.time()), "start": start, "step_s": step, "status": status,
"solve_s": round(time.time() - t0, 2), "devices": devices, "flex": flexibility(m, x),
"cost_eur": round(energy, 2), "baseline_eur": round(baseline(s, m, x), 2),
"price_note": s.get("price_note", ""), "sources": s.get("sources", {})}
if market:
out["market"] = market
return out
def term_at(c: dict, t: int) -> dict | None:
"""A market contract's terms in plan step t: its per-step terms when the
bundle told the coming slots (None: it does not apply then), else the
contract's own (held over from_step .. to_step)."""
per = c.get("terms")
if per is None:
return c
return per[t] if 0 <= t < len(per) else None
def market_plan(s, m, x) -> list[dict]:
"""Per contract in the plan (shadow): the planned energy per step and in
all (kWh), what is paid, and what it saves against the grid: bought,
import price x kWh used - contract price x kWh paid; sold, (contract
price - feed-in) x kWh (EUR; < 0: dearer than the grid). A take-or-pay
contract's paid energy is at least its minimum, used or not (what the
optimisation pays). Fields: id, name, direction, price_ct, steps [{t,
kwh, paid_kwh}] (steps with energy used or paid only), planned_kwh,
paid_kwh, cost_eur (> 0 paid, < 0 received), vs_grid_eur."""
out = []
pi, pe = s["price_import"], s["price_export"]
for c, vars_, paid_ in getattr(m, "contracts", []):
steps, kwh, paid_kwh, cost, vs = [], 0.0, 0.0, 0.0, 0.0
for t, v in sorted(vars_.items()):
e = max(x(v), 0.0) * m.dt / 1000.0
pay = max(x(paid_[t]) * m.dt / 1000.0, e) if t in paid_ else e
if pay < 1e-6:
continue
price = (term_at(c, t) or c)["price_ct"]
steps.append({"t": s["start"] + t * s["step_s"], "kwh": round(e, 4), "paid_kwh": round(pay, 4)})
kwh += e
paid_kwh += pay
if c["direction"] == "buys":
cost += pay * price / 100.0
vs += (e * pi[t] - pay * price) / 100.0
else:
cost -= e * price / 100.0
vs += e * (price - pe[t]) / 100.0
out.append({"id": c["id"], "name": c.get("name", ""), "direction": c["direction"], "price_ct": c["price_ct"],
"steps": steps, "planned_kwh": round(kwh, 4), "paid_kwh": round(paid_kwh, 4),
"cost_eur": round(cost, 4), "vs_grid_eur": round(vs, 4)})
return out
FLEX_STEPS = 96 # 24 h at 15 min: what a building plans with
@@ -432,9 +598,11 @@ def _entry(d, kind, v, t, x, s, pi):
if p is None:
return {"set": "off", "why": "after departure"}
amps = round(x(p) / v["volts"])
ph = ((s.get("sources") or {}).get("ev_phases") or {}).get(d["id"])
ph = f"; {phase_words(ph)}" if ph else ""
if amps < 1:
return {"set": "off", "why": "wait for cheaper hours"}
return {"set": amps, "why": f"cheapest hours before departure ({pi[t]:.1f} ct)"}
return {"set": "off", "why": "wait for cheaper hours" + ph}
return {"set": amps, "why": f"cheapest hours before departure ({pi[t]:.1f} ct){ph}"}
if kind == "cover" and v.get("schedule"):
sch = v["schedule"]
return {"set": sch["set"][t], "why": sch["why"][t] if sch["set"][t] is not None else ""}