cantabile_edge, cantabile_modbus, cantabile_eebus 0.1.400: full source
This commit is contained in:
1 parent
343331d234
commit
d5fbcacaa4
176 files changed
+32511
-19
No files matched your search
@@ -0,0 +1,202 @@
|
||||
# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
|
||||
"""The actuation guard: every action the agent would take goes through
|
||||
check() first, and only an allowed one becomes a Home Assistant service
|
||||
call (executor.py). In this order:
|
||||
|
||||
0. policy the device's protection (policy.py): never
|
||||
anything on a sealed device, never off on a protected one,
|
||||
whatever the command's level
|
||||
0b. switchover a thermostat that heats and cools: only its active control
|
||||
(heating or cooling, switchover.py) may act
|
||||
1. mode only in `auto` (shadow and advisory never act)
|
||||
2. consent the owner's for the site ("control" in consent.json) and the
|
||||
control's own (mapping v3), both off by default
|
||||
3. allow-list the control's own entities, with the service its kind uses
|
||||
4. bounds inside the effective floors and limits (limits.py: the
|
||||
device's range, the owner's, the building's, the cloud's, the
|
||||
grid operator's)
|
||||
5. override the owner changed it by hand: the agent keeps off it for
|
||||
override_hold_s (flexible), unless a binding or emergency
|
||||
command says otherwise (3b command levels)
|
||||
6. cycling a switch stays on/off for its minimum time (anti-cycling; only
|
||||
for equipment that wears from short cycles: heating, cooling)
|
||||
7. rate at most max_actions_per_hour per control; a cover moves at
|
||||
most once in its params.min_move_s (default 30 min)
|
||||
|
||||
Emergency commands skip 5-7 (nobody overrides them; device safety and the
|
||||
bounds still hold). Binding ones skip 5: the flat cannot lift them, only the
|
||||
building or the cloud. Every refusal has a reason, and is reported once per
|
||||
control and reason per hour (not every minute).
|
||||
"""
|
||||
import time
|
||||
from dataclasses import dataclass, field
|
||||
|
||||
LEVELS = ("plan", "flexible", "binding", "emergency") # plan: the optimiser's own
|
||||
|
||||
|
||||
@dataclass
|
||||
class Action:
|
||||
control: str
|
||||
channel: str # the entity role (charge_from_grid, setpoint, climate, switch, current, cover)
|
||||
entity: str
|
||||
domain: str
|
||||
service: str
|
||||
data: dict
|
||||
value: float | str # what is set (W, °C, A, %, "on"/"off"/"cool"/...)
|
||||
quantity: str = "" # what bounds it (temp_c, power_w, current_a, position_pct; "" for on/off)
|
||||
level: str = "plan"
|
||||
why: str = ""
|
||||
|
||||
|
||||
@dataclass
|
||||
class _Track:
|
||||
times: list = field(default_factory=list) # when actions were taken (rate limit)
|
||||
switched: dict = field(default_factory=dict) # channel -> (time, value) of the last on/off change
|
||||
commanded: dict = field(default_factory=dict) # entity -> (time, value) the agent last set
|
||||
override_until: float = 0.0
|
||||
override_entity: str = ""
|
||||
moved: float = -1e18 # when a cover was last moved by the agent
|
||||
|
||||
|
||||
# The service each channel uses, by domain: nothing else can be called.
|
||||
SERVICES = {
|
||||
"switch": {"turn_on", "turn_off"},
|
||||
"input_boolean": {"turn_on", "turn_off"},
|
||||
"number": {"set_value"},
|
||||
"input_number": {"set_value"},
|
||||
"climate": {"set_temperature", "set_hvac_mode"},
|
||||
"cover": {"set_cover_position", "open_cover", "close_cover"},
|
||||
"select": {"select_option"},
|
||||
"input_select": {"select_option"},
|
||||
}
|
||||
|
||||
|
||||
class Guard:
|
||||
def __init__(self, controls, consent, mode=lambda: "shadow", *, override_hold_s=7200, min_switch_s=600,
|
||||
max_actions_per_hour=12, settle_s=90, clock=time.time):
|
||||
self.controls = {c.id: c for c in controls}
|
||||
self.consent, self.mode, self.clock = consent, mode, clock
|
||||
self.hold, self.min_switch, self.max_rate, self.settle = override_hold_s, min_switch_s, max_actions_per_hour, settle_s
|
||||
self.extra_limits: dict = {} # control -> quantity -> level -> (floor, limit), from commands
|
||||
self.policy = None # policy.Policy: the devices' protection
|
||||
self.switchover = None # switchover.Switchover: heating or cooling now
|
||||
self.track: dict[str, _Track] = {}
|
||||
self.events: list[dict] = [] # overrides seen (the executor reports them)
|
||||
|
||||
def min_switch_for(self, c) -> float:
|
||||
"""Anti-cycling time for this control: the mapping's
|
||||
params.min_switch_s if set; else the guard's min_switch_s for kinds
|
||||
whose equipment wears from short cycles (heating, cooling: their
|
||||
default is > 0), and 0 for batteries, EV chargers and covers."""
|
||||
if "min_switch_s" in (c.params or {}):
|
||||
return float(c.params["min_switch_s"])
|
||||
from .controls import PARAMS
|
||||
return float(self.min_switch) if PARAMS.get(c.kind, {}).get("min_switch_s", 0) > 0 else 0.0
|
||||
|
||||
def _t(self, cid) -> _Track:
|
||||
return self.track.setdefault(cid, _Track())
|
||||
|
||||
def bounds(self, c, q):
|
||||
return c.bounds(q, self.extra_limits.get(c.id))
|
||||
|
||||
def check(self, a: Action) -> tuple[bool, str]:
|
||||
now = self.clock()
|
||||
c = self.controls.get(a.control)
|
||||
if c is None:
|
||||
return False, "no such control"
|
||||
if self.policy is not None:
|
||||
why = self.policy.refuses(a, c)
|
||||
if why:
|
||||
return False, why
|
||||
if self.switchover is not None and not self.switchover.active(c):
|
||||
return False, f"{c.kind} is not active now (switchover: the thermostat's other control is)"
|
||||
if self.mode() != "auto":
|
||||
return False, f"mode {self.mode()}: the agent does not act"
|
||||
if not self.consent.control:
|
||||
return False, "the owner has not allowed control (site consent)"
|
||||
if not c.consent:
|
||||
return False, "no consent for this control"
|
||||
if c.writable().get(a.channel) != a.entity:
|
||||
return False, f"{a.entity} is not this control's {a.channel}"
|
||||
if a.service not in SERVICES.get(a.domain, ()) or a.entity.split(".", 1)[0] != a.domain:
|
||||
return False, f"{a.domain}.{a.service} is not allowed for {a.entity}"
|
||||
if a.quantity:
|
||||
b = self.bounds(c, a.quantity)
|
||||
try:
|
||||
v = float(a.value)
|
||||
except (TypeError, ValueError):
|
||||
return False, f"{a.value!r} is not a number"
|
||||
if not b.holds(v):
|
||||
return False, (f"{v:g} outside {b.lo:g}..{b.hi:g} {a.quantity} "
|
||||
f"(floor by {b.lo_by}, limit by {b.hi_by})")
|
||||
tr = self._t(c.id)
|
||||
urgent = a.level == "emergency"
|
||||
if now < tr.override_until and a.level not in ("binding", "emergency"):
|
||||
return False, f"the owner changed {tr.override_entity} by hand: hands off until {_hhmm(tr.override_until)}"
|
||||
min_switch = self.min_switch_for(c)
|
||||
if not urgent and min_switch > 0 and a.quantity == "" and a.channel in tr.switched:
|
||||
when, last = tr.switched[a.channel]
|
||||
if last != a.value and now - when < min_switch:
|
||||
return False, f"switched {last} {int(now - when)} s ago (minimum {min_switch:g} s)"
|
||||
tr.times = [t for t in tr.times if now - t < 3600]
|
||||
if not urgent and c.kind == "cover" and now - tr.moved < float(c.p("min_move_s")):
|
||||
return False, (f"moved {int(now - tr.moved)} s ago (at most once in {float(c.p('min_move_s')):g} s)")
|
||||
if not urgent and len(tr.times) >= self.max_rate:
|
||||
return False, f"{len(tr.times)} actions in the last hour (at most {self.max_rate})"
|
||||
return True, ""
|
||||
|
||||
def done(self, a: Action):
|
||||
"""An action was carried out: count it, remember what was set."""
|
||||
now = self.clock()
|
||||
tr = self._t(a.control)
|
||||
tr.times.append(now)
|
||||
tr.commanded[a.entity] = (now, a.value)
|
||||
if a.domain == "cover":
|
||||
tr.moved = now
|
||||
if a.quantity == "":
|
||||
prev = tr.switched.get(a.channel)
|
||||
if prev is None or prev[1] != a.value:
|
||||
tr.switched[a.channel] = (now, a.value)
|
||||
|
||||
def expect(self, control_id: str, entity: str, value):
|
||||
"""The agent wants this value and the device already has it (no
|
||||
action needed): a later change by hand counts as an override, as if
|
||||
the agent had set it (not counted as an action)."""
|
||||
tr = self._t(control_id)
|
||||
if entity not in tr.commanded:
|
||||
tr.commanded[entity] = (self.clock() - self.settle, value)
|
||||
|
||||
def observe(self, control_id: str, entity: str, value, now: float | None = None):
|
||||
"""A state change of a control's entity: if it differs from what the
|
||||
agent set, and not right after the agent set it, the owner changed
|
||||
it by hand."""
|
||||
now = self.clock() if now is None else now
|
||||
tr = self._t(control_id)
|
||||
cmd = tr.commanded.get(entity)
|
||||
if cmd is None:
|
||||
return
|
||||
when, want = cmd
|
||||
c = self.controls.get(control_id)
|
||||
cover = c is not None and c.kind == "cover"
|
||||
if now - when < self.settle or _same(value, want, 3.0 if cover else 0.26):
|
||||
return
|
||||
# a shade the owner moved: off it for its own pause (params.override_hold_s)
|
||||
tr.override_until = now + (float(c.p("override_hold_s")) if cover else self.hold)
|
||||
tr.override_entity = entity
|
||||
tr.commanded.pop(entity, None)
|
||||
self.events.append({"control": control_id, "entity": entity, "value": value, "agent_set": want,
|
||||
"until": int(tr.override_until), "at": int(now)})
|
||||
|
||||
def overridden(self, control_id: str) -> bool:
|
||||
return self.clock() < self._t(control_id).override_until
|
||||
|
||||
|
||||
def _same(a, b, tol: float = 0.26) -> bool:
|
||||
try:
|
||||
return abs(float(a) - float(b)) < tol
|
||||
except (TypeError, ValueError):
|
||||
return str(a) == str(b)
|
||||
|
||||
|
||||
def _hhmm(t: float) -> str:
|
||||
return time.strftime("%H:%M UTC", time.gmtime(t))
|
||||
Reference in new issue
Block a user