Files
goodwe-addon/goodwe_controller/app/ctl_car.py
T
glenn schrooyenandClaude b12776c705
checks / unit (pull_request) Successful in 22m5s
infra-pin / fresh (pull_request) Successful in 2s
EV-10b: grade the alarm on the house alone without the 0 W clip
The period without the car was clipped at 0 W, so batteries covering the car
were charged to the house and the floor alarm fired (rig F-1). New
car_exclude_alarm keeps the sign of the rest of the period; car_exclude (the
cover-off guard input) is unchanged.

Co-Authored-By: Claude <noreply@anthropic.com>
2026-11-16 22:16:29 +01:00

403 lines
19 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
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_batt_prev = None
self._car_need_real = self._car_need_excl = False # EV-10 latches
self._car_latch_block = None
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, "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_quarter(self, proj, w, mono) -> None:
"""The car's energy in the open quarter, for the average the guard's
house leaves out and for the peak line."""
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"] = key, 0.0
if key is not None and w is not None and last is not None:
q["ws"] += float(w) * min(max(mono - last, 0.0), 5.0)
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) -> float:
"""The car's average over the whole open quarter: what it drew so far
and `w` for the rest."""
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
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)
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()
self._car_quarter(real_proj, w, mono)
self._car_session_tick(mono)
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.
graded = self._car_explains_alarm(real_proj, guard, target_w, w)
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_gone = None
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. That latch is kept here twice, on the period as it is
(`_car_need_real`) and without the car (`_car_need_excl`), from the
same `misses_aim` and the same batteries reading. Both reset at a new
quarter and when the guard no longer wants power, whatever the cover
option says (this runs every cycle). A car that is 0 W, or untrusted
(`w` None sets the second latch), makes the two equal and explains
nothing."""
batt, prev = self.site_batt_w, self._car_batt_prev
self._car_batt_prev = batt
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:
self._car_latch_block = real_proj.block_start
self._car_need_real = self._car_need_excl = False
if not wants:
self._car_need_real = self._car_need_excl = False
if batt is not None and prev is not None:
batt = min(float(batt), float(prev))
excl = self.car_exclude_alarm(real_proj, w)
if wants:
if batt is None:
self._car_need_real = self._car_need_excl = True
else:
self._car_need_real = self._car_need_real or \
peakguard.misses_aim(real_proj, batt_w=batt,
target_w=target_w)
self._car_need_excl = self._car_need_excl or w is None or \
peakguard.misses_aim(excl, batt_w=batt, target_w=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_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))
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
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