Files
Claude (dev) c707eb4776
checks / unit (pull_request) Successful in 24m55s
infra-pin / fresh (pull_request) Failing after 1s
EV-16: time the Car Why hold on the control cycle, not on page reads
car_cycle ends with _car_why_tick (display only: control writes, never reads);
the Why reads the record. Adds read-gap tests (A, B, cover off/on), a long
guard-None test and a lower bound for the hold.

Co-Authored-By: Claude <noreply@anthropic.com>
2026-11-21 11:23:13 +01:00

558 lines
27 KiB
Python

"""EV-04: the Controller's side of the car's Manual mode.
The writes themselves are `carmode.ManualWriter`'s; this mixin owns the state
(mode, current, phases: runtime state in the store, like OPT-11's modes), the
actions, the background step that never holds up a control cycle, and what the
car means for the peak guard's ALARM PATH. DECISIONS/EV-04-manual-mode.md.
"""
import asyncio
import dataclasses
import logging
from datetime import timezone
from . import carmode, chargers, messages, peakguard
from .tariff import QUARTER_S
_LOG = logging.getLogger("goodwe")
CAR_PEAK_KEY = "car_peak_q" # {quarter start iso: the car's average W}
CAR_PEAK_MIN_W = 50.0 # a quarter the car hardly touched is not kept
CAR_PEAK_KEEP = 3200 # about a month of quarters
OVER_HOLD_S = peakguard.ALARM_HOLD_S
# EV-11: the card, the row and Why stay on this long after the car stops being
# the cause: longer than the gaps seen on the rig (150 to 250 s at 50 s
# sampling) and shorter than a quarter, or until the session really ends.
OVER_OFF_HOLD_S = 180.0
# EV-15: the longest our own phase change can take (0 A wait, settle, three
# tries of a write at 5 s apart and up to 10 s each, the select's own wait);
# the grace for the alarm never outlasts it, and after the current is set
# again it lasts at most one corroboration window.
OWN_PAUSE_MAX_S = (carmode.ZERO_WAIT_S + carmode.SETTLE_S
+ carmode.MAX_TRIES * 15.0 + 10.0)
OWN_PAUSE_TAIL_S = chargers.CORR_WINDOW_S
# EV-19: the meter's house side (held - car) moved no more than this since the
# last cycle: it has not shown a battery rise the reading already shows.
RISE_STILL_W = 50.0
class CarMixin:
# ------------------------------------------------------------------ state
def car_init(self, opts, store) -> None:
"""Mode, current and phases from the store; `ev_mode_start` says what a
restart does with the mode. A site with no charger keeps defaults and
writes nothing."""
data = getattr(store, "data", None) or {}
self.car_mode = carmode.start_mode(opts, data.get(carmode.KEY_MODE))
if carmode.start_mode(opts, carmode.MANUAL) == carmode.OFF \
and data.get(carmode.KEY_MODE) not in (None, carmode.OFF):
store.set(carmode.KEY_MODE, carmode.OFF)
clamp = carmode.clamp_for(opts, None)
a = carmode.value_a(data.get(carmode.KEY_A, carmode.DEFAULT_A), clamp)
self.car_a = carmode.DEFAULT_A if a is None else a
n = data.get(carmode.KEY_PHASES, carmode.DEFAULT_PHASES)
ok = carmode.allowed_phases(opts)
self.car_n = n if n in ok else ok[0]
self.car_rev = 0
self.car_writer = carmode.ManualWriter()
self._car_task = None
self._car_step_failed = False
self.car_explains = False # the car alone explains the excess
self.car_over = False # ... held: the card and row say so
self._car_over_since = None
self._car_over_gone = None
self._car_why_rec = None # EV-16: [shown over, since, episode]
self._car_over_ep = 0 # EV-16: bumped when car_over ends
self._car_batt_prev = self._car_batt_prev2 = None
self._car_hx_prev = None # EV-19: last cycle's (held, car W)
self._car_need_real = self._car_need_excl = False # EV-10 latches
self._car_need_house = self._car_over_now = False # EV-18 latches
self._car_latch_block = None
self._car_contra_block = None # EV-18: the quarter it was contradicted
self._car_over_notified = None # the session a notice was raised for
self._car_session = 0
self._car_prev_state = None
self._carq = {"key": None, "ws": 0.0, "ws_p": 0.0, "mono": None}
self._peak_proj_real = None
saved = data.get(CAR_PEAK_KEY)
self.car_peak_q = dict(saved) if isinstance(saved, dict) else {}
@property
def car_cover(self) -> bool:
"""Decision 1: do the batteries help cover the car down to the peak
reserve? Default yes."""
v = self.o.get("ev_batt_cover")
return bool(chargers.EV_OPTION_DEFAULTS["ev_batt_cover"]
if v is None else v)
def car_manual(self) -> bool:
return (self.charger.configured()
and self.car_mode == carmode.MANUAL)
def car_clamp(self):
return carmode.clamp_for(self.o, self.car.reading)
def car_writing(self) -> bool:
"""May the add-on write to the charger now? Control runs, shadow mode is
off, no safety stop is latched and the add-on is not shutting down. Shadow mode gates charger
writes exactly as it gates inverter writes."""
latched = (any(i.sign_wd.tripped for i in self.inverters)
or self.site_sign_wd.tripped or self.circ_wd.tripped)
return bool(self.auto and not self.shadow and not latched
and not getattr(self, "stopping", False))
# ---------------------------------------------------------------- actions
def _car_action(self, what, value, now) -> dict:
"""The mode, the current or the phases, from the page or from Home
Assistant. Store state, applied by the next step with no restart."""
if not self.charger.configured():
return {"error": messages.car_refused("off")}
if what == "car_mode":
if value not in carmode.MODES:
return {"error": messages.car_refused("value")}
self.car_mode = value
self.store.set(carmode.KEY_MODE, value)
elif what == "car_current":
clamp = self.car_clamp()
if isinstance(value, bool):
return {"error": messages.car_refused("value")}
a = carmode.value_a(value, clamp)
try:
inside = a is not None and abs(float(value) - a) < 0.5
except (TypeError, ValueError):
inside = False
if not inside:
return {"error": messages.car_refused("value")}
self.car_a = a
self.store.set(carmode.KEY_A, a)
else:
if value not in (1, 3) or isinstance(value, bool):
return {"error": messages.car_refused("value")}
if value not in carmode.allowed_phases(self.o):
return {"error": messages.car_refused("phases")}
self.car_n = value
self.store.set(carmode.KEY_PHASES, value)
self.car_rev += 1
self.car_writer.user_changed()
self.log_event(f"car {what[4:]} set to {value} by operator",
hint=messages.hint(what))
return {"mode": self.car_mode, "current": self.car_a,
"phases": self.car_n}
def car_command_values(self) -> dict:
"""The MQTT state of the three car entities."""
return {"car_mode": carmode.MODE_LABELS[self.car_mode],
"car_current": round(self.car_a),
"car_phases": str(self.car_n)}
# ------------------------------------------------------------- the writer
def car_kick(self) -> None:
"""Start one writer step in the background, unless one is running. A
write waits up to 10 s for the charger's read-back, and a control cycle
never waits for the charger."""
if not self.charger.configured():
return
t = self._car_task
if t is not None and not t.done():
return
self._car_task = asyncio.ensure_future(self._car_run())
async def car_settle(self) -> None:
"""Wait for the writer step in flight (the checks use it)."""
t = self._car_task
if t is not None:
await asyncio.gather(t, return_exceptions=True)
async def _car_run(self) -> None:
try:
await self.car_step()
except asyncio.CancelledError:
raise
except Exception: # noqa: BLE001
# Once at WARNING-and-above, then quietly: a step that fails
# fails every second.
if not self._car_step_failed:
self._car_step_failed = True
_LOG.exception("The car charger step failed")
else:
_LOG.debug("The car charger step failed again", exc_info=True)
else:
self._car_step_failed = False
async def car_shutdown(self) -> None:
"""The add-on stops: no new write, and a phase change in the middle is
undone by giving the car its current back. The current stands
otherwise (Manual's fail state)."""
t, self._car_task = getattr(self, "_car_task", None), None
if t is not None and not t.done():
t.cancel()
await asyncio.gather(t, return_exceptions=True)
if not self.charger.configured() \
or getattr(self, "car_writer", None) is None \
or self.car_writer.seq is None:
return
try:
await asyncio.wait_for(self.car_writer.abandon(
self.charger, self.car_now(), self.car, self.car_clamp()),
15.0)
except Exception: # noqa: BLE001
_LOG.warning("The car could not be given its current back "
"before the add-on stopped: CHARGER_RESTORE.")
async def car_step(self) -> None:
"""One step of Manual. Reads nothing from the world (the cycle's read
did) and writes only through `carmode.ManualWriter`."""
if not self.charger.configured():
return
now = self.car_now()
await self.car_writer.step(
self.charger, self.car.reading, mode=self.car_mode,
want_a=self.car_a, want_phases=self.car_n, rev=self.car_rev,
clamp=self.car_clamp(), now=now, tracker=self.car,
writing=self.car_writing(), shadow=bool(self.shadow),
status=self.car.status(now, True), clock=self.car_now)
# ------------------------------------------- the car and the peak guard
def car_alarm_w(self):
"""The car's power for the guard's alarm path: Manual only, fresh, not
stuck (`CarTracker.car_w_trusted`), and never above what the read-back
allows. None otherwise, and then the normal alarms stand."""
if not self.car_manual():
return None
return self.car.car_w_trusted(self.car_now())
def _car_own_pause(self, mono) -> bool:
"""EV-15: is the car held at 0 A by the add-on's OWN phase change? From
the moment its 0 A write is SENT (the cycle runs beside the write)
until the current is set again, then at most one corroboration window.
No when it was aborted (Off, Stop, shadow, unplug, another writer), a
write was refused, or it ran past its own maximum."""
wr = getattr(self, "car_writer", None)
if wr is None or (wr.seq is None and wr.phase_done_at is None
and wr.zero_sent_at is None) or wr.hold:
return False
r = self.car.reading
if not (self.car_manual() and self.car_writing()
and r is not None and r.available and r.state != "A"):
return False
q = wr.seq
if q is None and wr.zero_sent_at is not None: # sent, not yet back
return 0.0 <= mono - wr.zero_sent_at <= OWN_PAUSE_MAX_S
if q is not None:
return not q.get("failed") and 0.0 <= mono - q["t0"] \
<= OWN_PAUSE_MAX_S
return 0.0 <= mono - wr.phase_done_at <= OWN_PAUSE_TAIL_S
def _car_contradicted(self, mono) -> bool:
"""EV-18 (owner 2026-11-19): did the charger's energy meter answer
and fall short of a fresh, not stuck figure of a charging car
(`CarTracker.contradicted`)? Then that figure stays untrusted for the
alarm to the quarter's end (`car_cycle`). An unknown energy reading
contradicts nothing."""
r = getattr(self.car, "reading", None)
if r is None or not r.available or r.charging is not True \
or not self.car_manual():
return False
return (self.car.car_w(mono) is not None and not self.car.stuck(mono)
and self.car.contradicted(mono))
def _car_idle(self, mono) -> bool:
"""EV-18: is the car known to draw nothing? A fresh reading that says
it is not charging (mode3 A or B) at under `CAR_PEAK_MIN_W`. Not an
unknown figure: the house's own need is graded in such a cycle."""
r = getattr(self.car, "reading", None)
if r is None or not r.available or r.charging is not False:
return False
p = self.car.car_w(mono)
return p is not None and p < CAR_PEAK_MIN_W
def _car_quarter(self, proj, w, mono, wg=None) -> None:
"""The car's energy in the open quarter, for the average the guard's
house leaves out and for the peak line. `wg` (EV-15) is the figure for
grading during our own pause; its energy is kept apart (`ws_p`) so the
guard's input is unchanged."""
q = self._carq
key = None if proj is None else proj.block_start
last = q["mono"]
if key != q["key"]:
self._car_bank(q)
q["key"], q["ws"], q["ws_p"] = key, 0.0, 0.0
if key is not None and last is not None:
dt = min(max(mono - last, 0.0), 5.0)
if w is not None:
q["ws"] += float(w) * dt
elif wg is not None:
q["ws_p"] = q.get("ws_p", 0.0) + float(wg) * dt
q["mono"] = mono
def _car_bank(self, q) -> None:
"""A closed quarter in which the car drew its share goes on the list."""
key = q["key"]
if key is None:
return
avg = q["ws"] / QUARTER_S
if avg < CAR_PEAK_MIN_W:
return
self.car_peak_q[key.astimezone(timezone.utc).isoformat()] = round(avg)
if len(self.car_peak_q) > CAR_PEAK_KEEP:
for k in sorted(self.car_peak_q)[:-CAR_PEAK_KEEP]:
del self.car_peak_q[k]
self.store.set(CAR_PEAK_KEY, dict(self.car_peak_q))
def car_avg_w(self, proj, w, graded=False) -> float:
"""The car's average over the whole open quarter: what it drew so far
and `w` for the rest. `graded` (EV-15) adds what it drew during our
own pause."""
if proj is None or w is None:
return 0.0
left = max(0.0, QUARTER_S - float(proj.elapsed_s))
so_far = self._carq["ws"] if self._carq["key"] == proj.block_start \
else 0.0
if graded and self._carq["key"] == proj.block_start:
so_far += self._carq.get("ws_p", 0.0)
return (so_far + float(w) * left) / QUARTER_S
def car_exclude(self, proj, w):
"""Decision 1 off: the projection the guard sees without the car
(`house - car_w`). Unchanged without a fresh car reading."""
if proj is None or w is None or proj.block_start is None:
return proj
avg = self.car_avg_w(proj, w)
return dataclasses.replace(
proj, projected_w=max(0.0, float(proj.projected_w) - avg),
held_w=max(0.0, float(proj.held_w) - float(w)))
def car_exclude_alarm(self, proj, w):
"""EV-10b: the period as it would be without the car, for grading the
alarm. The house alone, the batteries giving only what the house
would draw from them: the car's share of their power is not charged to
the house. The rest of the period keeps its sign (`held - car`, an
export while the batteries give more than the house uses), so
`misses_aim` adds the batteries back to exactly the house. What is
already done is clipped at 0 Ws: no export is credited for power only
the car asked for. Unchanged without a fresh car reading."""
if proj is None or w is None or proj.block_start is None:
return proj
avg = self.car_avg_w(proj, w, graded=True)
left = max(0.0, QUARTER_S - float(proj.elapsed_s))
held = float(proj.held_w)
done_ws = QUARTER_S * float(proj.projected_w) - max(held, 0.0) * left
car_ws = avg * QUARTER_S - float(w) * left # the car so far
held_x = held - float(w)
return dataclasses.replace(
proj, held_w=held_x,
projected_w=(max(0.0, done_ws - car_ws)
+ max(held_x, 0.0) * left) / QUARTER_S)
def car_cycle(self, real_proj, guard, target_w, now_utc) -> None:
"""After the guard has decided: does the car alone explain the excess?
`real_proj` is the projection WITH the car, whatever the guard saw."""
mono = self.car_now()
w = self.car_alarm_w()
# EV-15: the figure for grading only. Our own phase change holds the
# car at 0 A and the energy meter cannot corroborate it then, so for
# that bounded time its fresh, not stuck figure stands in.
own = (w is None or float(w) <= 0.0) and self._car_own_pause(mono)
wg = w
if w is None and own:
wg = self.car.car_w_paused(mono)
self._car_quarter(real_proj, w, mono, wg)
self._car_session_tick(mono)
# EV-18 (owner 2026-11-19): a figure the meter contradicted grades no
# alarm again in that quarter, not even as our own pause's stand-in.
# The alarm decision only: the car's energy count, the guard's input
# (`car_exclude`) and, with the cover off, the car-over row keep it.
key = None if real_proj is None else real_proj.block_start
if key is not None and not own and self._car_contradicted(mono):
self._car_contra_block = key
contra = key is not None and key == self._car_contra_block
explains = over = False
if real_proj is not None and target_w is not None \
and real_proj.block_start is not None:
# EV-10: every cycle, so the latches do not depend on the option.
# EV-18: a car known to draw nothing counts as 0 W for the latches
# (the house's own need); it and a 0 W figure explain nothing,
# but in our own pause (EV-15).
idle = wg is None and self._car_idle(mono)
graded = self._car_explains_alarm(
real_proj, guard, target_w,
None if contra else 0.0 if idle else wg)
if contra or idle or (w is not None and float(w) <= 0.0
and not own):
graded = False
if self.car_cover:
explains = over = graded
elif w is not None:
ex = float(real_proj.projected_w) - float(target_w)
over = ex > 0.0 and self.car_avg_w(real_proj, w) >= ex
self.car_explains = explains
# EV-11: on once the condition has stood for OVER_HOLD_S, a short gap
# in it not starting that count again; off only after it has been gone
# for OVER_OFF_HOLD_S. `car_explains` (the alarm decision) has no hold.
if over:
self._car_over_gone = None
if self._car_over_since is None:
self._car_over_since = mono
if mono - self._car_over_since >= OVER_HOLD_S:
self.car_over = True
else:
if self._car_over_gone is None:
self._car_over_gone = mono
if mono - self._car_over_gone >= OVER_OFF_HOLD_S:
self.car_over, self._car_over_since = False, None
self._car_over_ep += 1 # EV-16: an episode ends
self._car_over_gone = None
self._car_why_tick(guard, mono)
def _car_why_tick(self, guard, mono) -> None:
"""EV-16, display only: control writes `_car_why_rec`, never reads it.
The Car Why text ("are at" / "give all they can") is held: it changes
only when the other state has stood for `OVER_OFF_HOLD_S` of THIS
cycle's clock (so reads of /status do not matter). State: floor-limited
with the SoC read; a guard of None, or unread SoC, never counts as
floor. Cleared when car_over is off or the cover is off."""
if not (self.car_over and self.car_cover):
self._car_why_rec = None
return
cand = None if guard is None else bool(
getattr(guard, "floor_limited", False)
and getattr(guard, "soc", None) is not None)
ep = self._car_over_ep
r = self._car_why_rec
if r is None or r[2] != ep:
self._car_why_rec = [bool(cand), None, ep]
elif cand is None or cand == r[0]:
r[1] = None
else:
if r[1] is None:
r[1] = mono
if mono - r[1] >= OVER_OFF_HOLD_S:
self._car_why_rec = [cand, None, ep]
def _car_explains_alarm(self, real_proj, guard, target_w, w) -> bool:
"""EV-10: is the alarm's own test true with the car and false without
its fresh, corroborated share (`car_exclude_alarm`), on the same landing? The
tests are the alarms': a saturated guard and a floor with other
batteries left are graded by `load_too_high` on where the period lands
(SAFETY-81 / 87); a floor that leaves nothing is graded by SAFETY-126's
`misses_aim` (the batteries at 0 W from now on), latched for the
quarter (`_car_need_real`, and `_car_need_excl` without the car).
EV-18 (owner 2026-11-19): without the car, the batteries keep giving
what they give now (the lower of two readings), re-checked every cycle;
a miss seen so (`_car_need_house`) never lets the car explain for the
rest of the quarter. The car also explains where the period with it,
on the same batteries, misses (`_car_over_now`). Only a trusted figure
latches: an untrusted car (`w` None) or an unknown battery reading
explains nothing in that cycle only. All reset at a new quarter and
when the guard no longer wants power, whatever the cover option says
(this runs every cycle). DECISIONS/EV-04-manual-mode.md (EV-18)."""
now, prev = self.site_batt_w, self._car_batt_prev
prev2, self._car_batt_prev2 = self._car_batt_prev2, prev
self._car_batt_prev = now
wants = bool(guard is not None and guard.engaged
and guard.blind is None
and (guard.wanted_w or 0.0) > 0.0)
if real_proj.block_start != self._car_latch_block or not wants:
self._car_latch_block = real_proj.block_start
self._car_need_real = self._car_need_excl = False
self._car_need_house = self._car_over_now = False
batt = now
if batt is not None and prev is not None:
batt = min(float(batt), float(prev))
excl = self.car_exclude_alarm(real_proj, w)
# EV-19: the reading can show a rise one cycle before the meter does
# (the batteries pick up the house at the reserve). While the meter's
# house side (held - car; held alone when a car figure is unknown) has
# not moved, a reading above both earlier ones is not yet counted as
# house; a meter that moved shows it (no discount).
held = float(real_proj.held_w)
hp, self._car_hx_prev = self._car_hx_prev, (held, w)
still = False
if hp is not None:
moved = held - hp[0]
if w is not None and hp[1] is not None:
moved -= float(w) - float(hp[1])
still = abs(moved) <= RISE_STILL_W
seen = now
if still and now is not None and prev is not None \
and prev2 is not None:
seen = min(float(now), max(float(prev), float(prev2)))
if wants and batt is not None:
self._car_need_real = self._car_need_real or \
peakguard.misses_aim(real_proj, batt_w=batt,
target_w=target_w)
self._car_over_now = self._car_over_now or \
self._car_lands_over(real_proj, now, batt, target_w)
if w is not None:
self._car_need_excl = self._car_need_excl or \
peakguard.misses_aim(excl, batt_w=batt, target_w=target_w)
self._car_need_house = self._car_need_house or \
self._car_lands_over(excl, seen, batt, target_w)
if w is None or batt is None or not wants \
or not (guard.saturated or guard.floor_limited):
return False
if guard.saturated:
rating = self.site_rating_w
elif (guard.floor_w or 0.0) > 0.0 and guard.able_w is not None:
rating = guard.able_w
else:
return bool(not guard.within_aim and self._car_need_real
and not self._car_need_house
and (self._car_over_now or not self._car_need_excl))
def high(p):
return peakguard.load_too_high(
p, batt_w=batt, ceiling_w=guard.ceiling_w,
achievable_w=rating)
return bool(high(real_proj) and not high(excl))
@staticmethod
def _car_lands_over(p, now, gives, target_w) -> bool:
"""EV-18: does the period end more than `ALARM_MISS_W` over the aim
with the batteries giving `gives` W from now on (`now`: what they gave
in the meter's figure)? Of what is done, only the car's energy counted
since the add-on started is the car's (a restart or a gap leaves the
rest with the house)."""
return peakguard.load_too_high(p, batt_w=now, ceiling_w=target_w,
achievable_w=gives)
def _car_session_tick(self, mono) -> None:
"""A charging session is a plug-in: the state goes from no car to a
car. The notice is raised once per session."""
s = self.car.status(mono, True)
if s in (chargers.NONE_,) and self._car_prev_state not in (
None, chargers.NONE_):
self._car_over_notified = None
# The session is over: that is a real end, with no hold.
self.car_over = False
self._car_over_since = self._car_over_gone = None
self._car_over_ep += 1 # EV-16: an episode ends
if s not in (chargers.NONE_, None) and self._car_prev_state in (
chargers.NONE_, None):
self._car_session += 1
self._car_prev_state = s
async def check_car_over(self) -> None:
"""One grey notice per charging session: the charge you set takes the
15-minute period over the peak limit. Raised nowhere else."""
if not self.car_over or self._car_over_notified == self._car_session:
return
self._car_over_notified = self._car_session
_LOG.info("The car charge you set takes this 15-minute period over "
"the peak limit: CAR_OVER_PEAK.")
await self.hass.call("persistent_notification", "create",
messages.car_over(f"{self.car_a:.0f}").data())
def car_peak_by_car(self, reading, now):
"""`(True, local time)` when the month's peak quarter was one the car
mostly made (it drew half the peak or more), else `(False, None)`."""
if reading is None or not getattr(reading, "is_observed", False) \
or reading.quarter_start is None or not self.car_peak_q:
return False, None
avg = self.car_peak_q.get(
reading.quarter_start.astimezone(timezone.utc).isoformat())
if avg is None or reading.peak_w is None \
or 2.0 * float(avg) < float(reading.peak_w):
return False, None
return True, reading.quarter_start