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>
10 KiB
EV-04 — Manual mode: the first write to a car charger
The design is reports/EV-01-design-report.md (sections 2 to 5), accepted on
2026-11-15 with all eight decisions as recommended. This record keeps what the
code had to decide that the design left open.
What writes, and who may
app/carmode.py ManualWriter is the only caller of write_current and
write_phases (test_ev03.py greps for any other). It runs in a background task
(ctl_car.CarMixin.car_kick), never in the control cycle: a write waits up to
10 s for the charger's read-back, and the cycle must never wait for a charger.
- Off writes nothing. The mode is runtime state in the store (
car_mode,car_current,car_phases), changed on Home or from Home Assistant with no restart. Solar and Night are not accepted (EV-05, EV-02). - Once per user change. A user change sets a flag the writer clears when the charger has what was asked. A difference nobody asked for is the other-writer detector's business, not a reason to write.
- No car or a full car: nothing is written, and the setting waits for a car.
- Shadow mode and a stopped control write nothing; the card says what the add-on would set.
- The clamp is the driver's too. The writer asks for at most the clamp, and
AlfenHaDriver.write_currentrefuses anything abovemin(ev_max_a, station limit read now, entity range max): it sends nothing, logsCHARGER_CLAMPat ERROR (the OUTPUT_CLAMP shape) and answers False. - "Taken" means the read-back followed within 10 s. A write that was not taken is tried again after a minute, three times, then it waits for the user (an amber row). A late read-back is adopted, never called another writer.
The phase sequence
0 A, wait until the charger reports under 100 W or mode3 leaves C (20 s at most),
select the phases, wait 10 s, write the current. One switch per 10 minutes. A
charger that does not take the 0 A never gets the phases select. A sequence that
has begun is finished whatever the mode, because it leaves the car at 0 A
otherwise; a stop of the add-on in the middle gives the car its current back
(car_shutdown).
Another writer
A read-back that differs from what the add-on last wrote (or tried to write, or saw before a refused write) for 30 s is another writer: a grey row, and no write until the user changes the mode or a value. EV-03's detector still serves Off; the tracker mutes its own detector for 15 s after each of our writes, so Manual back to Off does not show the add-on as a second writer.
The peak guard's alarm path
Controller passes the car's power to the guard's alarm path (car_cycle).
The car explains the excess when the house alone would land the period under
the aim: the car's average over the whole period (what it drew so far, and its
power now for the rest, car_avg_w) is at least how far the projected period is
over the aim. With decision 1 on it also needs the guard to be unable to hold
it (saturated or at the peak reserve). Then "Load too high" and "Battery stopped
limiting the peak" are not raised, the rows are not red, and one grey notice per
charging session says so. The claim, the floor and the commands are unchanged.
The brief's wording is car_w >= projected excess over the aim. The
instantaneous form (car_w >= excess_w, the watts to come off the meter now)
stops holding late in a period that the car already pushed over, because
excess_w grows as the seconds run out; the average form does not, and it is the
same test for a steady car.
A stale, stuck or frozen car figure must never hide a real overload. Only
CarTracker.car_w_trusted is used: fresh (the EV-03 rules, which also make an
unavailable reading None at once), not stuck after a write (SAFETY-37's shape),
never above what the read-back allows, and CORROBORATED by the charger's energy
meter (round 2). The rule (CarTracker.corroborated, constants CORR_* in
chargers.py): the charger reports charging (mode3 C) and has an energy entity,
and, looking back over unbroken charging readings to the shortest stretch that
is at least 55 s long and over which the reported power adds up to at least
40 Wh, the meter has gained at least 50 % of that, less 15 Wh (the meter shows
10 Wh steps, so at 40 Wh it must show one step; an honest car can fall one step
short and still passes). Readings are kept 180 s. A gap, a state other than C or
a meter that goes back starts the history again. With no such stretch yet (a
session just began, or the add-on just started) the figure is believed, so a
charge does not raise false alarms for its first minute; a frozen figure is
believed for that long only. No energy entity: never corroborated, so the normal
alarms stand. Bound: a frozen figure of P watts on a car that has really
stopped is caught within max(60 s, 40 Wh / P): 60 s from 2.4 kW up, 104 s at
1.38 kW (6 A, 1 phase, the lowest charge), plus the alarms' own 10 s hold. Below
about 0.8 kW (40 Wh over the 180 s kept) the figure is believed; it cannot hide
an overload that matters. (Round 2 had a 15 Wh slack that cancelled the 50 % rule
up to 1.8 kW; the 40 Wh floor fixes that.)
EV-10, EV-11, EV-12: the rig's three findings (EV-04 test F-1 to F-3)
- The car is the cause when the alarm's own test says so, on the same
landing (EV-10).
car_cycle(_car_explains_alarm) runs the alarm's test on the period as it is and on the period without the car's fresh, corroborated average (car_exclude_alarm, EV-10b below): the car explains the alarm only if it is true with the car and false without it. A saturated guard, and a floor with other batteries left, useload_too_highon the landing (the batteries give only what they still can). A floor that leaves nothing uses SAFETY-126'smisses_aim(the batteries at 0 W from now on), which is latched for the quarter; the add-on keeps that latch twice, with and without the car, from the same readings. Both reset at a new quarter and when the guard stops wanting power, and they run every cycle, so the cover option does not touch them. This holds with the projection still under the aim (rig: 5888 W against 6000 W). A car of 0 W makes the two the same, so it explains nothing; a stale, stuck or uncorroborated figure isNone, sets the latch without the car, and the normal alarms stand. There is no minimum car power: the comparison itself is what separates car from house. - The period without the car is not clipped at 0 W (EV-10b). The rig showed
EV-10 failing: house 3 kW, car 11 kW, batteries 8.1 kW, aim 6 kW. The batteries
give more than the house uses, so the house alone is an export;
car_excludeclipped it at 0 W,misses_aimadded the batteries' full 8.1 kW back, the "house needs the batteries" latch set early in the quarter, and the floor alarm could never be explained.car_exclude_alarm(alarm grading only) builds the house alone as: rest of the periodheld - car_w, keeping its sign, somisses_aimadds the batteries back toheld - car_w + batt= the house; done partmax(0, done - car so far)in Ws (no export is credited that only the car caused); landing(done + max(held, 0) * left) / 900. Without a fresh car reading it is the period as it is.car_exclude(the projection the guard sees with the cover off) is unchanged, with its clip. - Steady row, no hold on the alarm (EV-11). Cause: after the car's own quarter
became the month peak, the aim sat on the grid it made (14.04 kW +-40 W), so
the test crossed the aim every few seconds.
car_over(row, card, notice) now stays on until the test has been false forOVER_OFF_HOLD_S= 180 s (longer than the gaps seen on the rig, 150 to 250 s at 50 s sampling, and shorter than a quarter) and a gap does not restart the 10 s on-count.car_explains, which the alarms read, has no hold. - Our own write is ours until its mute ends (EV-12). The mute of the tracker's own detector opens before the write and runs 15 s from when it returns, because the read-back reaches the cycle while the write still waits for it.
The one write shadow mode allows
When the add-on has paused the car (0 A) for a phase change and has not yet
selected the phases, Off, a stop of control, a safety latch or shadow mode ends
the change. The old current is given back (clamped, _restore_a) in every one of
those cases, shadow mode included. With the shipped shadow_mode: auto, stopping
control turns shadow on, so without this the car would stay at 0 A for as long
as control is stopped, while the design's Manual column says the current
stands. Undoing our own half-done change is not a new command; it is the same
write the shutdown restore makes. Nothing else is written in shadow mode: no
phase switch, and no write afterwards.
Decision 1 (ev_batt_cover)
On (the default): the guard works as it does and the batteries cover the car down
to the peak reserve. Off: the projection the guard sees leaves the car out
(house - car_w, with the car's average so far), so it does not force the
batteries to discharge for it, and the period goes over by the car alone. The
car is never throttled either way. The projection the guard sees is also the
one charge_room_w reads, so with the switch off a grid charge of the batteries
sees the room the car leaves; that is the owner's trade and DOCS says so.
Deviations from the design text
- Titles and setting names follow STYLE.md (at most 5 and 6 words): "Car over the peak limit" (the design: "Car charge over the peak limit"), setting "Batteries help with the peak" (the design: "... while the car charges", which is in its description).
- No "or choose Solar" in the Why or the notice: Solar is not in this card.
- The Why lines are two sentences of at most 12 words, as test_messages.py
asks;
peak.carsays "The car takes {car} and the batteries cover {cov}." without "of it". peak.set_by_carkeeps its first sentence only ("The batteries were at the peak reserve" is not true with decision 1 off). A quarter counts as set by the car when the car drew half the peak or more over it.