Files
goodwe-addon/goodwe_controller/DECISIONS/EV-04-manual-mode.md
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

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_current refuses anything above min(ev_max_a, station limit read now, entity range max): it sends nothing, logs CHARGER_CLAMP at 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, use load_too_high on the landing (the batteries give only what they still can). A floor that leaves nothing uses SAFETY-126's misses_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 is None, 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_exclude clipped it at 0 W, misses_aim added 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 period held - car_w, keeping its sign, so misses_aim adds the batteries back to held - car_w + batt = the house; done part max(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 for OVER_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.car says "The car takes {car} and the batteries cover {cov}." without "of it".
  • peak.set_by_car keeps 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.