diff --git a/goodwe_controller/CHANGELOG.md b/goodwe_controller/CHANGELOG.md index d094d02..da70474 100644 --- a/goodwe_controller/CHANGELOG.md +++ b/goodwe_controller/CHANGELOG.md @@ -1,5 +1,126 @@ # Changelog +## 0.22.0 + +**A minor bump: a battery's monthly charge now gets the cheap night, the plan knows about the 7-day wait, a slow meter is followed more gently, and one peak-guard stop no longer costs a night charge its whole period. No option changes.** +No option was added, removed or renamed, and no default changed (86 options). **Existing installs need no option change:** options that start 0.21.0 also start 0.22.0, and the Supervisor form is the same. It is a minor bump because control acts differently in the cases below; every saved setting still starts. + +**A battery's monthly charge gets the cheap night.** While one battery is in the charge part of its monthly cycle, the other battery no longer grid-charges ahead of it, and the charge aims at this month's highest peak, as the peak guard does, not at the lower limit. In a rig test with the live setup (two batteries, one in its monthly charge), the cycling battery charged at about 1.5 kW in every cheap quarter (13.3 kWh in a night) and the other battery bought nothing; before, it charged at about 225 W or not at all. The peak limit was kept. At the start of a month, before a peak above the limit has been seen, this charge is much slower ([[SAFETY-111]]). + +**The plan knows about the 7-day wait.** After a failed monthly cycle, Home no longer shows a cycle every night. It says the cycle waits, and shows the day the wait ends. The cycle tries again at the first start hour after the wait ([[MAINT-26]]). In a rig test no cycle was drawn during the wait, and none started. + +**One peak-guard stop no longer costs the night charge its period.** With battery modes on, a night grid charge that the peak guard stops early in a 15-minute period used to stay stopped until the period ended. It may now start again after a minute, once per period, and not in the last minute. A real overload is cut as fast as before. In a rig test of the 01:00 case the night's charge was 0.45 to 0.46 kWh, against 0.42 to 0.44 kWh before. The status says "grid charge paused, it tries again in a minute" while it waits. + +**A slow meter is followed more gently.** With a meter whose readings come about 4 s or more apart, such as a 5 s meter, control now takes smaller steps after a big change until the meter shows it. With Home Assistant readings 10 s late, less power goes to the grid when loads switch on and off: 44 % less in a simulation and 29 % less in a rig test. Meters of 1 or 2 s are left alone by design (the same commands in 63 simulation runs). With readings 15 s late the gain is smaller (19 % in a simulation), and a rig test sent more to the grid than before; see the known issues. + +**No change in behaviour:** the comments in the main program file are shorter, and the file is split into smaller files by job. A rig test saw the same start-up, stops and commands. + +Contents of this release, in merge order since 0.21.0 (`5e00cbb`): + +| | | +|---|---| +| `56fc41f` | The comments in the main program file are shorter and clearer. There is no change in behaviour ([[MAINT-20]], #224) | +| `8508ac3` | The main program file is split into smaller files by job. There is no change in behaviour; a rig test saw the same start-up, stops and commands ([[MAINT-21]], #243) | +| `a8ecf17` | With a 5 s meter, control follows the meter more gently after a change. With Home Assistant readings 10 s late, less power goes to the grid when loads switch on and off. Meters of 1 or 2 s are left alone ([[SAFETY-136]], #244) | +| `02eac3b` | A night grid charge that the peak guard stops early in a 15-minute period may start again after a minute, once per period, instead of staying stopped until the period ends. A real overload is cut as fast as before. Battery modes only ([[SAFETY-135]], #245) | +| `1b5f7c9` | While a battery's monthly cycle charges, the other battery no longer grid-charges ahead of it, and the charge aims at this month's highest peak, so it gets the cheap night. After a failed cycle, the plan no longer shows a cycle every night and says the cycle waits ([[MAINT-24]], [[MAINT-25]], #246) | +| `f3f9483`, `4c0122a` | History only: MAINT-28 was merged (#247) and then taken out again (#249). The two cancel out and the code is the same as at `1b5f7c9`. MAINT-28 is not in this release ([[MAINT-28]]) | + +### Known issues + +- A false "Battery is not keeping up" can still show when the peak guard pauses a maintenance charge ([[SAFETY-92]]). +- A battery capped at a low limit with a perfectly flat reading can still trip the stale check ([[SAFETY-74]]). +- A battery whose reading at rest is beyond about ±175 W is still not caught when it refuses ([[SAFETY-97]]). +- The peak guard can still back off near the end of a 15-minute period when a meter reading is late, by less than 30 s. This is about the guard's discharge only; a grid charge is cut back since 0.19.2 ([[SAFETY-99]]). +- Two inverters: the maintenance charge can switch on and off while the house is above the peak aim ([[SAFETY-88]]). +- Two inverters: the "circulating" figure counts a battery's reading at rest ([[SAFETY-98]]). +- Two inverters: a drain that starts during a big step in house use can send the other battery to full power, and about 1 kW goes to the grid for about 10 s ([[SAFETY-104]]). +- Two inverters: when a battery comes back during a maintenance charge, the grid can step by several kW at once ([[SAFETY-101]]). +- Two inverters: when a battery drops out during a solar surplus, the others can swing by up to 1.5 kW in a simulation ([[SAFETY-105]]). +- Two inverters: after a drain ends, a change in house use can go unanswered for about 9 s, because some readings are old ([[SAFETY-106]]). +- Two inverters: when one battery's level is missing, both batteries are held at 0 W, and for about 15 s the last command stays on ([[SAFETY-108]]). +- Two inverters: if one battery's level stays missing for 12 h, the other battery's cycle can be marked failed, with a 7-day wait and a notice, though it is healthy. This comes from reading the code; it has not been seen on a site ([[MAINT-17]]). +- When the 15-minute demand forecast sensor counts the battery's own charge, the maintenance charge runs at about half the power the peak limit leaves, so it takes about twice as long (seen on a site: about 1.2 kW instead of 2.5 kW; the peak limit was kept). At the start of a month, before a peak above the limit, that is about 2 kWh a night in a rig test: the cycle can reach its 36 h limit after about 4 nights and fail, and since 0.22.0 the other battery gets no grid charge on those nights ([[SAFETY-111]]). +- One inverter: after a link drop, the battery's own safety stop to 0 W can be taken as a refusal, and the site stays at 0 W for up to 15 min ([[SAFETY-102]]). +- After a Home Assistant restart, control still waits until Home Assistant has finished starting, which can take several minutes, though the readings are already there ([[SAFETY-115]]). +- While Home Assistant is not answering, the page can list inverters as refusing commands and sensors as missing, and send you to Developer Tools, though they are fine ([[UX-37]]). +- If Home Assistant hangs or stops, the page keeps saying "Waiting for Home Assistant" and never turns into an alarm ([[SAFETY-113]]). +- Right after Home Assistant has started, the page can say for about 4 s that an inverter cannot be controlled, and the first command can come late ([[SAFETY-114]]). +- After a Home Assistant restart, the controller status sensor can still say "running" while the add-on cannot control. It was seen once, and the cause is not known ([[SAFETY-116]]). +- Battery modes on: after a planned top-up from the grid, the Batteries screen can say "Enough sun is forecast" ([[UX-32]]). +- Battery modes on: the forecast line "we count on" can show more sun than the plan counts, because the plan takes house use off first ([[UX-33]]). +- Battery modes on: before a planned top-up, the Today list shows a smaller "gives" amount than the plan will use; it grows as the charge happens ([[UX-34]]). +- Two inverters, battery modes on: while the other battery is in its maintenance charge, a battery's card can say it charges from the grid while it stays at 0 W ([[OPT-18]]). +- Two inverters, battery modes on: while a battery refuses to charge in a cheap run, the action log on the page gets about 8 lines an hour for its retries, and the page hint says "waiting for a better price" ([[UX-38]]). +- A battery in a safety stop, or one the add-on cannot reach, can still be started for a cycle, and its drain then waits about 12 h and ends in a failed-cycle notice. This comes from reading the code; it has not been seen on a site ([[MAINT-19]]). +- On the Settings page, the rows of the solar forecast lists are labelled "Phase 1", "Phase 2" instead of "Sensor 1", "Sensor 2" ([[UX-27]]). +- In the solar forecast list, a blank or repeated row makes "source 2 of 2" count differently from the rows on the Settings page ([[UX-28]]). +- The solar forecast message says "has no reading" also when the sensor shows a number that is too old or in the wrong unit ([[UX-29]]). +- If you use only the forecast lists, two Settings notes sit on the single-sensor field, and one of them tells you to set that field ([[UX-30]]). +- After a restart during a price outage, the "No prices" message can say "yet" when prices did come in earlier ([[UX-39]]). +- On the new settings page, you cannot see whether a price service token is set. Check the Configuration tab ([[UX-41]]). +- On the classic settings page, the first click on Save after editing a field can do nothing. Click again ([[UX-42]]). +- A steady overload on a 1 s meter can warn, and send the Home Assistant notification, 2 or 3 times at the start of each 15-minute period instead of once. The peak limit is still kept ([[SAFETY-122]]). +- A fixed tariff is priced once per hour, so a price window that starts or ends at :15, :30 or :45 gets the wrong price for part of that hour. Windows that start and end on the hour are right ([[TARIFF-23]]). +- Step 6 of the setup wizard stays empty because of an error in the page, in English and in Dutch ([[UX-51]]). +- On Dutch pages, refusal texts, the last-event line under the Home buttons, the installer details and the trading status sentences are still English, and a few Dutch texts read badly, such as "1 metingen geweigerd" ([[UX-52]]). +- Some price texts say "hour" where the add-on acts on a 15-minute period, such as "cheapest hour" ([[UX-47]]). +- After the add-on restarts, the Home price chart shows no price for the earlier part of today, and the setup check can say "12 of 24 hours", though the prices are known ([[UX-48]]). +- With battery modes on and only batteries on "Leftover solar", the Home price chart can mark a cheap period where no battery charges ([[UX-49]]). +- On a phone, the bars of the Home price chart are too thin to tap one 15-minute period. The arrow keys work ([[UX-50]]). +- In the last second of a 15-minute period, being a few watts over the aim can make the peak guard ask a battery for full power for one second. When a charge ends on a period edge, the last-second give can fade out over about 10 s, and a rig test exported up to 7.4 kW for about 8 s ([[SAFETY-124]]). +- During the night grid charge, a 15-minute period can end 6 to 14 W over the peak aim, because the battery charges harder than asked. This was seen in simulation; a rig test saw 2 to 8 W ([[OPT-35]]). +- The test rig could not bring back the false peak alarm that [[SAFETY-126]] fixes, so that fix is shown in simulation only. Watch the notifications for a few nights ([[TEST-35]]). +- The night cheap run is sized for the batteries' full charging power, not for what the peak limit leaves. Under a tight limit the run can end before the batteries reach their level, and Home can show a level they do not reach (79.9 % against a shown 95 % in a rig test) ([[OPT-25]]). +- By day, a Leftover solar plan that has only a daily forecast figure counts the sun from now, not from when the figure was read. It counts about 22 % too much for a figure one hour old; the night plan is not affected ([[OPT-30]]). +- The night charge can buy too much in a house that uses more at night than by day, such as one with a car charger or heat pump, and on a sunny day, because spare sun in one expensive hour does not count for the later ones ([[OPT-31]]). +- A cheap run that has already started can overlap a new give run after a re-plan, so a battery can charge from the grid at the dearest price for part of an hour. This was seen in a test case, not on a site. Also in 0.19.2 ([[OPT-32]]). +- If the solar forecast sensors stop updating before 17:00, as in winter or further north, there is no forecast from three hours after their last update until 20:00 ([[OPT-33]]). +- With a forecast that gives only a daily total, the sun is spread an hour off on the two clock-change days after the change. The day's total is right ([[OPT-24]]). +- The add-on learns the house's use only once a solar forecast is set, so a site that adds a forecast later waits one more day for its first plan ([[OPT-26]]). +- Home says "No trading on price yet: no prices have arrived" when every battery is on Solar first, though the prices are shown ([[UX-55]]). +- The Home plan header can say "Charges in the cheapest hour, gives power in the dearest" when Home draws no charge, and it says "hour" for 15-minute prices ([[UX-56]]). +- While the peak guard holds back charging, Home hides the rest of the cheap run and gives no reason. The charge starts again when the guard lets go ([[UX-57]]). +- With battery modes on and selling on, Home can draw a "Sells up to" block when the add-on judges the trade not worth it, and then it will not sell ([[UX-58]]). +- Home, the plan and the Forecast tab stop drawing a battery's give at the trading floor, though control goes on giving down to the battery's cut-out ([[UX-59]]). +- During a price outage, the Batteries screen says "Prices differ too little" and Home says "The price gap is too small" ([[UX-60]]). +- With battery modes on and no meter, or a meter that is a Home Assistant entity, a grid charge is not possible and nothing says so ([[UX-61]]). +- On the Batteries screen, a charge the add-on refused in a cheap run reads as "Saves its power for ...", for up to 15 minutes ([[UX-62]]). +- A Leftover solar battery with no capacity set never charges from the grid when a solar forecast is set, and nothing warns about it ([[UX-63]]). +- The "How the modes work" box on the Batteries screen does not describe Cheap hours only ([[UX-64]]). +- With battery modes on, Settings still shows "Trade on the price spread", which the modes ignore. A site with modes on and no price source starts, and the Batteries screen says "No prices, so it follows the house" without pointing to Settings ([[UX-65]]). +- With battery modes off and several equal prices in a row, Home and the Forecast tab draw one price quarter, while the add-on trades every quarter of the run ([[UX-67]]). +- Late in the day, the Forecast tab's "now" line and last bars sit over the axis labels at the right edge ([[UX-68]]). +- The Forecast tab's level curve charges at each battery's full rating. Under a peak limit the levels it draws are too high and a charge block can end early (54.6 % shown against 39.7 % in a rig test) ([[UX-70]]). +- The peak forecast check says maintenance charging is not kept under the peak limit when no peak forecast is set, but since 0.19.2 it is ([[UX-73]]). +- The peak guard row can show the same figure twice, such as "at this rate 3 500 W, over 3 500 W". Also in 0.19.2 ([[UX-74]]). +- If the inverter's setpoint entity appears in Home Assistant after the add-on has started, the page keeps saying "Inverter control: not found in Home Assistant" and the batteries say "An alarm stopped control" until a restart, though control runs ([[UX-75]]). +- In the last minute of a 15-minute period, with Home Assistant readings 30 s late, the period can end about 80 W over the peak aim and over the limit: 3 530 W against a 3 450 W aim and a 3 500 W limit in a rig test with a 2 kW load added 45 s before the end. The peak guard sees the load too late to hold it back ([[SAFETY-133]]). +- With Home Assistant readings 10 s late, the grid charge in a cheap run can swing by several kW. In a test the add-on asked for an 8.7 kW charge (9.6 kW on 0.20.0) ([[SAFETY-132]]). +- A plan rebuilt while the battery levels are missing for a moment can drop a cheap run that has not started yet, so the battery does not charge that day. Seen in a replay of real prices, where it cost about EUR 0.40 of extra grid use; the Leftover solar change in 0.20.1 no longer triggers it in those replays, but the cause stays ([[OPT-37]]). +- On a 5 s meter, Home Assistant readings 10 s late are still not caught, and readings 15 s late only after about 4 minutes. Control now follows the meter more gently, so less goes to the grid: in a simulation with a changing load, 340 Wh became 189 Wh at 10 s late and 363 Wh became 296 Wh at 15 s late. In a rig test, 15 s late exported 13 to 19 % more than before ([[SAFETY-136]], [[SAFETY-134]]). +- With readings 10 to 15 s late, the hold can end in the middle of the delay and the swing can come back. Seen in rig tests with a 2 s and a 5 s meter ([[SAFETY-134]]). +- With readings 10 s late on a 1 s meter, the grid can still move between -422 and +340 W while the batteries are held. With a very long delay (30 to 90 s) the request can swing by about 900 W every few seconds. Seen in review tests ([[SAFETY-130]]). +- A battery that answers very slowly (10 s or more) can be taken for late Home Assistant readings and held, and the page then blames Home Assistant. A GoodWe battery settles in about 6 s and this has not been seen on one ([[SAFETY-131]]). +- The page row for late readings reads awkwardly in English ("Home Assistant readings show requests about N seconds late, so control holds the batteries"), and the Dutch text misses a word ([[UX-78]]). +- When the add-on stops, a write that takes more than 2 s can still land after the 0 W, and the 30 s safety timer on the ESPHome board then sets 0 W. After the Stop button, a cycle that had already decided can send its share (560 to 670 W) just after the 0 W; the next cycle sends 0 W again ([[SAFETY-138]]). +- In the last hour of a cheap run, Home can draw a battery's grid charge up to an hour past the time control stops charging it. It only draws too much, never too little ([[UX-79]]). +- A tomorrow solar forecast sensor that reports just after midnight with yesterday's value can be used as the new day's forecast for up to 12 hours. This has not been seen on a site ([[OPT-39]]). +- During a cheap-hours charge, at some 15-minute boundaries the add-on sends 0 W for one tick ("no trade (headroom)") and then goes on. Seen in a rig test, in 5 of 8 cases; once, with a frozen battery reading, it left a battery at 0 W until 23:45 ([[OPT-40]]). +- During a real peak, a battery in its maintenance charge can switch between charging and giving, about 400 times in 45 minutes in rig tests. That means more wear, but no higher peak ([[MAINT-28]]). +- While one battery's monthly cycle charges, the other battery's card on Home says "Saves its power for higher prices", and the plan still shows its grid charge in the cheap hours, though it will not charge ([[UX-80]]). +- After a failed monthly cycle, the plan line shows the day the wait ends, such as 18 November, not when the cycle tries again, such as 19 November at 19:00 ([[MAINT-26]]). +- At the start of a cheap window the peak guard can step once although the period is under the aim, and the step can land on a battery in its monthly charge. In a rig test it gave 1.7 to 2.3 kW for 6 s ([[SAFETY-140]]). +- A grid charge at full power in the last seconds of a 15-minute period can run into the next period, where the peak guard cuts it back ([[SAFETY-139]]). + +### If you are crossing from a version older than 0.10.0 + +`## 0.10.0` below can refuse an old config: `slew_w` above its limit, and the +withdrawn `price_provider` ids `engie_dynamic`, `totalenergies_dynamic` and +`eneco_eddy`. Read it before you update. Run `tools/predeploy_check.py` with the +bare options (`jq '.data.options'`) first. + + ## 0.21.0 **A minor bump: control now holds the batteries when Home Assistant readings come late, Home draws the whole night's grid charge, and the shutdown 0 W is sent last. No option changes.** diff --git a/goodwe_controller/DECISIONS/MAIN-orchestration-archive.md b/goodwe_controller/DECISIONS/MAIN-orchestration-archive.md new file mode 100644 index 0000000..18cebc5 --- /dev/null +++ b/goodwe_controller/DECISIONS/MAIN-orchestration-archive.md @@ -0,0 +1,2767 @@ +# MAIN archive - comments cut from app/main.py, word for word + +Written by MAINT-20 part 2. Each section is one comment block or docstring as it +stood in `app/main.py` at release/1.0 `d4c01da`, keyed by its first line number +there; the last heading holds the ones that came in by `16029d7` (keyed +there). It is a record, not a design: the live rule is the one-line comment now +in the code, and the curated reasoning is in [[MAIN-orchestration]]. Comment +blocks have their `#` removed; docstrings their quotes. A pointer in `main.py` +names this file only: find its section by searching here for a phrase of the +comment it ends. + +### L1080 Set by amain() once the transport is built, so the status page can sho + +Set by amain() once the transport is built, so the status page can show +what only the transport knows (homewizard_local's unchanged_s). Stays +None when P1 is off, or under a transport that has no such counter. + +### L2302 TARIFF-24: no forecast now, but a run planned with one is under + +TARIFF-24: no forecast now, but a run planned with one is under +way: it keeps its gap to its end. The wider gap applies from the next +run. OPT-34: a night charge that keeps its level (`_latch_charge()`) +keeps the gap too, run after run, or the next slice of it would be +refused. Pure; Home asks the same (`homeview.trade_verdict()`). + +### L2313 The kept run plan, rebuilt at most once per price slot (15 min) or + +The kept run plan, rebuilt at most once per price slot (15 min) or +when the prices or a battery's choice change; a run under way is +kept to its end (`priceruns.keep_started()`). None with no fresh +firm prices: then no battery holds or trades (design section 5). + +### L2366 OPT-11 P4: the day plan (`dayplan.plan()`) on the runs just made, + +OPT-11 P4: the day plan (`dayplan.plan()`) on the runs just made, +its levels held by the hysteresis (`dayplan.hold()`), then the runs +made again with each battery's shortfall as the charge, so the cheap +run is only as long as the shortfall needs. With no plan (no or stale +forecast, no house profile yet) the levels are dropped: P3 option A. +Returns the runs to keep. + +### L2405 OPT-34, once per cycle after `modetrade.decide()`. A night grid + +OPT-34, once per cycle after `modetrade.decide()`. A night grid +charge that has started keeps its planned level when the forecast goes +mid-charge (the kept figure ends and the sensors are still silent). + +While there is a forecast, fresh or kept, the latch is rebuilt each +cycle from the plan: a battery that charges from the grid in the cheap +run comes in with its planned level, and stays in it at whatever level +the plan gives it, up or down as a fresh figure moves it (also when it +has stopped, at a lowered level), until it leaves the plan. While there +is none, `plan_targets()` gives the latched levels, so the charge goes +on to them, and `weather_held()` keeps the narrow price gap. The latch +lasts through every cheap run on and one price slot after the last +(`CHARGE_LATCH_GRACE_S`), but a run is carried on only if it starts +by the bell start of the night the latch began in (`_night_limit()`; +the run under way then finishes). It is dropped when `now` passes its +end whatever the run state, and a battery that is off or no longer in +a mode with a planned level (`packs`) leaves it. A charge that never +started has none. + +### L2463 OPT-11 P3: each battery's role and range this tick. Grid charging + +OPT-11 P3: each battery's role and range this tick. Grid charging +and selling need a fresh plan that `TariffPlan.arbitrage()` allows +with the MEASURED peak guard (None refuses: nothing measures the +quarter), exactly the gate `arbitrage.decide()` has. + +### L2535 A charge the guard or the headroom stopped stays off this period. + +A charge the guard or the headroom stopped stays off this period. +OPT-15: only a MEASURED stop latches; the first unmeasured headroom +(None) in a quarter stops this tick only, so a gap cannot cost the +whole quarter. A second one latches, so gaps cannot flip the charge. + +### L2565 OPT-11 P3: file the site trade the roles ask for, sized inside the + +OPT-11 P3: file the site trade the roles ask for, sized inside the +modes and the hard limits (the loop bound) and, for a charge, the +billed quarter's headroom (SAFETY-45, aim cap - margin, SAFETY-79). +So no battery that its mode or a refusal holds is asked for watts it +may not give (P1's unmet share). Returns True when a trade is filed. + + +### L2575 OPT-20: the ask carries PROBE_W for exactly the probes whose pin + +OPT-20: the ask carries PROBE_W for exactly the probes whose pin +is filed this tick. `decide()` ran before the pin was (or the +window closed since), so the two can differ by one cycle; left +alone, the allocator takes the pin's watts out of another +battery's share, or hands them to one it can reach. + +### L2631 OPT-11 P3: a mode trade just ended, so the loop takes over from a + +OPT-11 P3: a mode trade just ended, so the loop takes over from a +command no loop chose. Start it at the house's own point E, the +command that brings the grid to its target now (`site battery + grid +- target`, inside the loop bound), instead of at the trade's watts. +OPT-15: then HOLD it at E (`_edge_grid()`) until the meter shows the +step or `EDGE_HOLD_S` passes. The readings still describe the trade for +a second or two (meter and battery lag), and stepping on them sent +E 810 -> 1370 -> 1920 W on TEST-23: -1120 W export at a charge end. +Measured: DECISIONS/OPT-11-battery-modes.md. + + +### L2656 OPT-15: the grid reading the loop acts on this tick. While a run + +OPT-15: the grid reading the loop acts on this tick. While a run +edge is held, the target itself (no error, the command stays at E). +The hold ends when the meter reaches the target in the step's +direction (or passes it), on `end` (a trade started, or another claim +moved the command), or after `EDGE_HOLD_S` - later, up to twice that, +while the battery reading is still moving towards E. + +### L2680 SAFETY-93, N>=2: a charge ends when its battery leaves CHARGE or can + +SAFETY-93, N>=2: a charge ends when its battery leaves CHARGE or can +no longer be placed (stale link, refusal). Kept until the loop runs. +SAFETY-95: a drain likewise; its refusal (SAFETY-73) outranks the pin +without a contradiction, so it is read from the battery (+1, will not +give; a battery that will not take still drains). + +### L2701 SAFETY-93, N>=2: when a battery's maintenance charge ends, the loop + +SAFETY-93, N>=2: when a battery's maintenance charge ends, the loop +starts from what the others stood at plus that battery's new command +(its HOLD pin, or its last discharge if it is free; a charge stops). +Else the charge's watts stay in the site target and land on the +others: B 0 -> -1600 W in one cycle. DECISIONS/SAFETY-93-charge-end.md. + + +### L2724 SAFETY-95, N>=2: when a battery's maintenance drain ends, its + +SAFETY-95, N>=2: when a battery's maintenance drain ends, its +drain leaves the loop's start point, as a charge does (SAFETY-93): the +start is what the others stood at plus its new command (its pin, else +0 W). Where the house needs more, the start is the house's own point +(the live batteries' readings + grid - target), never above last +cycle's start. The loop then moves one slew step a cycle. Else the +drain's floor stays in the target and lands on the others: B 0 -> ++1600 W in one cycle, exporting. DECISIONS/SAFETY-95-drain-end.md. + + +### L2757 SAFETY-95: the grid the loop regulates. While a battery settles + +SAFETY-95: the grid the loop regulates. While a battery settles +from its ended drain (`_held_out_w`: until within the deadband, at +most PLANT_SETTLE_DOWN_S), the meter still shows the drain's tail and +the others' climb, so the loop would chase them (B down, then up +again). Meanwhile the batteries count at the site command: the error +is the house's own point minus the loop's start. + +SAFETY-103: a reading can be up to a register period (10 s) older +than the meter, so the house point is held, and moved only as far as +the meter proves: to the nearest value the batteries can be at (each +between its last changed reading and its commands since; a reading +that changed this cycle, or the side a battery refuses, is taken as +it reads). DECISIONS/SAFETY-103-old-readings-after-a-drain.md. + + +### L2814 SAFETY-96, N>=2: a battery that drops out of the split (stale + +SAFETY-96, N>=2: a battery that drops out of the split (stale +link) leaves the loop's start point, so the others take over at one +slew step a cycle instead of taking its share at once. One that comes +back enters it at its reading, and every battery settles while the +split is made again (`_held_out_w`). +DECISIONS/SAFETY-96-dropped-battery.md. + + +### L2841 SAFETY-96, N>=2: what to add to the site sum so that a battery + +SAFETY-96, N>=2: what to add to the site sum so that a battery +the loop cannot move right now counts at its command, not at its +reading. That is a battery out of the split, one whose writes are +refused, or one settling after a step the loop did not make (a charge +end, a rejoin) until its reading is within the deadband of its +command or PLANT_SETTLE_DOWN_S has passed. Its real power still +reaches the loop through the meter, so it is neither lost nor counted +twice; only the saturation freeze stops seeing it as the loop's. + + +### L2869 OPT-11: say once, per battery, that its mode was dropped as a fault. + +OPT-11: say once, per battery, that its mode was dropped as a fault. + +A mode range without 0 W would force a direction, which no mode may do, +so it is never applied (allocator.unit_interval()). main.py never +builds one; this is the line that says so if it ever does. + + +### L2889 OPT-11: switch one battery on or off, set its mode, or (P3) turn + +OPT-11: switch one battery on or off, set its mode, or (P3) turn +its selling on or off. + +Store state, not an option, so it applies on the next cycle with no +restart. Written to the action log. Switching a battery off also stops +its maintenance cycle (the owner's 2026-09-27 answer). Refused, with a +plain reason, while battery modes are off or for an unknown battery or +value. + + +### L2937 MAINT-11: start or abort the maintenance cycle of ONE named battery. + +MAINT-11: start or abort the maintenance cycle of ONE named battery. + +Returns `{"error", "code", "unit"}` for a refusal and changes nothing. +The site keeps its one maintenance slot: a start while any battery +holds it is refused (no queue), see DECISIONS/MAINT-11. The phase +machine is not touched beyond `force_start()` and `abort()`, the same +two calls the bare button makes. + + +### L2989 OPT-11 P2: one command from a battery's HA switch or mode list. + +OPT-11 P2: one command from a battery's HA switch or mode list. + +It goes through handle_action(), the page's /action path, so the +checks and the store write are the same. A retained command (one the +broker replays on subscribe, e.g. after a restart) is never applied: +the store already holds the last choice. A refusal is logged once per +topic and reason, at most 32, and further refusals are counted in the +log at 1, 10, 100 and so on. Never raises: MQTT must not reach control. + + +### L3069 SAFETY-87: at N>=2, `decision` placed on the batteries that can + +SAFETY-87: at N>=2, `decision` placed on the batteries that can +still give: live, not refusing, above their own reserve. `able_w` is +their rating plus the drain a held battery gives anyway (its +maintenance pin). Unchanged when no battery is held back. +DECISIONS/SAFETY-87-guard-uses-able-batteries.md. + +### L3099 SAFETY-126: `decision` marked `within_aim` while the guard wants + +SAFETY-126: `decision` marked `within_aim` while the guard wants +power but the batteries at 0 W would end the quarter within +`ALARM_MISS_W` of the aim (`peakguard.misses_aim()`). Once a real miss +is seen, the need stands until the guard lets go. The claim and the +commands are unchanged; only the alarms and the "Why" read it. +DECISIONS/SAFETY-126-landing-error-is-not-an-overrun.md. + +### L3128 SAFETY-91, N>=2: the batteries at or under their own peak reserve + +SAFETY-91, N>=2: the batteries at or under their own peak reserve +while another can still give (live, not refusing). They weigh 0 in +every split where the site gives, so they give last (SAFETY-25 +option A: still drawn once the others are full). One held back +stays so until its SoC reads more than 1 point above its reserve, so +a reading flipping across it does not swap the split each cycle. + +### L3153 SAFETY-91, N>=2: while a battery is held back (`_held_back()`), a + +SAFETY-91, N>=2: while a battery is held back (`_held_back()`), a +draining battery's pin becomes a floor at its drain rate, so it rises +towards its rating before the held one gives. A site stop still +decides alone. DECISIONS/SAFETY-91-held-battery-last.md. + +### L3276 SAFETY-87, N>=2: while a battery is held at its peak reserve, a + +SAFETY-87, N>=2: while a battery is held at its peak reserve, a +draining battery that may still give is raised from its drain rate +towards its rating for the peak floor, after the others. Otherwise +the floor's rest lands on the held battery (its weight 0 only orders +the split; the drain pin binds). A site stop still decides alone. + +### L3376 SAFETY-84: a cheap-window charge pulls no more than the quarter's + +SAFETY-84: a cheap-window charge pulls no more than the quarter's +room under the peak aim (`charge_room_w()`), so it yields just enough +to the peak guard; at N>=2 nothing under a site stop (its 0 W would +need the other pack to give). SAFETY-125: at N=1 too, owner +2026-10-29; the stop rule stays N>=2 only. + +### L3653 PRICE-01. A provider with fallbacks gives the maintenance gate + +PRICE-01. A provider with fallbacks gives the maintenance gate +its own prices: the current 15-minute price against today's +average, as the Home Assistant pair did. Still no I/O here - the +series is the one the background refresh stored. + +### L4222 PRICE-01: `cheap`, the gate and the gap from the standing plan. + +PRICE-01: `cheap`, the gate and the gap from the standing plan. + +The gate exists whenever the provider does: no price for now is a +closed gate, so the charge waits and does not run unpriced. The gap +flag stays False until the first refresh has finished, so a start-up +is not a gap. + + +### L4264 MAINT-13: may this pack charge now, for the maintenance timeout? + +MAINT-13: may this pack charge now, for the maintenance timeout? + +True when no price gate is set up (no price entities, no fixed tariff: +nothing holds the charge back), in a cheap window, or while the pack is +really taking charge (sun outside cheap hours). Closed only when a gate +exists, it is shut, and the pack is not charging. + + +### L4277 Gather claims, resolve precedence, write the winner. + +Gather claims, resolve precedence, write the winner. + +Nothing here decides who wins - arbiter.py does, by one rule. This +method's only job is to state honestly what each strategy wants. + + +### L4588 ⚠️ `is_live()` AT ITS OWN DEFAULT WINDOW, which is + +⚠️ `is_live()` AT ITS OWN DEFAULT WINDOW, which is +`LINK_STALE_S` - the SAME call `live_units()` makes for +the allocator. It has to be: what this branch means is +"the allocator has already dropped this unit and said so", +and a different window here would be this check answering +a question about a roster the allocator did not build. +It is the ONE number here with no option behind it, so +"graded at a changed config" is not available for it; +what part 6 grades instead is that WIDENING the window +changes the answer. + +### L4607 ⚠️ THIS UNIT'S OWN CUT-OUT. Not the shipped 10 %, and not + +⚠️ THIS UNIT'S OWN CUT-OUT. Not the shipped 10 %, and not +the site's `peak_soc_floor` either - that one bounds a +money-saving discharge only, and grading a pack against it +explains a wedged unit away in a band an ordinary install +has ten points of. + +### L4650 ⚠️ `any`, NOT the sole unit's. The hold exists so a single missed poll + +⚠️ `any`, NOT the sole unit's. The hold exists so a single missed poll +does not become a fault; a LATCHED inverter must still reach the claim +list below, because its `failsafe` SET is what parks it. One tripped +unit therefore takes the whole roster past the hold, which is the +conservative direction: every other unit's claims are re-filed too. +⚠️ AND SAFETY-30's SITE LATCH TAKES THE ROSTER PAST THE HOLD TOO, for +the same reason: its `sign_site` SET is what parks every inverter, and +a latched site that returned early here would leave each unit's last +share standing for the heartbeat to re-emit - i.e. the trip would stop +acting the moment a poll was missed. + +### L4668 UX-10: the age is rendered when the page asks, not frozen at + +UX-10: the age is rendered when the page asks, not frozen at +this cycle's. With the meter reading gone the grid value +stops changing, so the next cycle is up to cycle_floor_s +away and the line used to read "0 seconds" all that time. + +### L4678 safety limits: these bind EVERY strategy, always + +safety limits: these bind EVERY strategy, always +Defence in depth: write_setpoint() clamps to the device range too. The +duplication is deliberate - one of them is the policy, the other is the +last thing between a bug and the hardware. +⚠️ PER-INVERTER, ONE PAIR PER UNIT, FROM THAT UNIT'S OWN NUMBERS. +This loop is the difference DEV-02 makes to the claim list: the +numbers are ONE inverter's own reported min/max and ONE inverter's own +supervised cap, and there is no such thing as a site rating. Before +this card there was one pair, read from one setpoint entity, filed +once - so a second inverter's rating was never read and never bound. +See arbiter.CLAIM_SCOPE. + +### L4697 OPT-09: WHAT THIS PACK'S STATE OF CHARGE FORBIDS + +OPT-09: WHAT THIS PACK'S STATE OF CHARGE FORBIDS +⚠️ THE POINT OF THE CARD, AND IT IS AN ENVELOPE RATHER THAN A +WEIGHT. Weighting an empty pack down does NOT stop it being +commanded: `allocator._fill()` runs a deliberate last-resort pass +over the zero-weight units when the preferred ones saturate, so +that a preference can never manufacture a standing error at the +meter. Only a closed envelope stops the ask, and `cap` is obeyed +absolutely. So a pack at or under its own BMS cut-out gets +`hi = 0` and a pack at 100 % gets `lo = 0`, and the site target +goes to the sibling instead of being asked of a battery that +cannot answer it. + +⚠️ AT A ROSTER OF ONE THIS IS NEVER FILED, AND THAT IS THE SAME +IDENTITY `sign_site` IS GUARDED BY RATHER THAN A SPECIAL CASE. +`actuator_for()` routes every source to the SITE at N=1 - with one +inverter the fabricated grid reading and the battery setpoint are +the same number - so this interval would bound THE SITE TARGET +there, not a share. That is a behaviour change on the live +single-inverter install and it is the shape SAFETY-25 decided +against on 2026-09-02 (Option A): ordinary self-consumption is not +given an SoC floor by this card. There is also nothing for it to +do at N=1 - no sibling to move the share to - so the whole of AC 4 +("at N=1 allocation is byte-identical to today") is this `if`. + +WHAT IT COSTS, SAID PLAINLY: at N=1 nothing here stops the loop +discharging into the BMS cut-out. That is unchanged, it is +SAFETY-25's deferred Option B, and the BMS itself is what stops it. + +### L4734 safety stops + +safety stops +⚠️ SAFETY-02 is claimed FIRST and unconditionally while latched. It is +a SET at P_SAFETY, so it outranks maintenance, peak shaving and the +loop alike - a controller pushing power the wrong way is wrong +whatever it thinks it is doing. Re-filed EVERY cycle: claims are not +sticky, and one filed once would lapse the next cycle and hand the +actuator silently back to the loop that was driving the wrong way. + +⚠️ AND IT IS PER-INVERTER, THOUGH ITS EVIDENCE IS SITE-WIDE. The +watchdog compares P1 - one meter, one site - against `standing`, THE +COMMAND THIS CONTROLLER PUT ON THIS ACTUATOR, and what it concludes is +"the unit I am driving is pushing power the wrong way". At N>=2 that +evidence cannot be pinned on a sibling this controller never commanded, +so a site-wide stop would park an inverter this watchdog never graded. +See arbiter.CLAIM_SCOPE. + +### L4755 SAFETY-30: THE SITE SIGN TRIP, AND IT IS A SITE SET + +SAFETY-30: THE SITE SIGN TRIP, AND IT IS A SITE SET +⚠️ THE TWIN OF THE LOOP ABOVE, NOT A DUPLICATE OF IT. That loop files +one `failsafe` per unit on the evidence of THAT unit's own measured +power, and parks that unit. This files ONE claim on the SITE, because +what tripped is the SUM of every standing command against the meter - +a fact about the grid connection, whose offending number is the site +target and which no single inverter owns. Parking one unit on it would +leave the rest of the roster pushing the same way with the guard +satisfied. See arbiter.CLAIM_SCOPE, which classifies `sign_site` and +`failsafe` side by side and says why they differ. + +⚠️ AND THE `n_units > 1` GUARD IS NOT REDUNDANT, EVEN THOUGH `cycle()` +never arms this detector at a roster of one. The latch is RESTORED +FROM THE STORE, so an install that ran with two inverters, tripped, +and was then reconfigured back to one would come up with +`site_sign_tripped: true` and would otherwise file a claim on evidence +about a roster it no longer has. Guarded, that install comes up +driving - which is right: the fault it latched on is not a statement +about the site it is now. + +### L4779 SAFETY-31: WHAT "ACTED ON" MEANS, AND WHAT IT HONESTLY CANNOT + +SAFETY-31: WHAT "ACTED ON" MEANS, AND WHAT IT HONESTLY CANNOT +⚠️ A SITE SET AT P_SAFETY: STOP COMMANDING, EVERYWHERE. Read the next +paragraph before changing it, because the obvious objection is right +and is answered rather than ignored. + +THE OBJECTION. HW-01 established that commanding a wedged inverter +achieves nothing - on 2026-09-02 the comms subsystem failed and the +power stage went on executing its last instruction for 6 h 25 m, +through every command this add-on sent it. If the cause of the +circulation is a unit that has stopped listening, then a command is +not a remedy and pretending otherwise is theatre. + +THE ANSWER, AND IT IS WHY THIS IS STILL AN ACTION RATHER THAN A +NOTIFICATION. A circulating loop needs TWO participants. In every +cause on this card's list, exactly one of them is a unit that has +stopped listening and THE OTHER ONE IS THIS CONTROLLER - faithfully +commanding the sibling to a share computed to sum with a number the +wedged unit is not actually producing. Stopping the commanding half +does two things a notification cannot: + + 1. IT HALVES THE LOOP. The unit that is still listening stops being + driven into the one that is not, so the round-tripping stops on + the side this controller owns. That is real energy and real + cycles off a real pack, and it needs no cooperation from the + wedged unit to take effect. + 2. IT MAKES THE RESIDUE VISIBLE. This is the more important half. + Circulating power hides because it NETS TO ZERO AT THE METER. + With this controller's contribution removed, whatever the wedged + unit is still doing stops being cancelled and appears at P1 as a + plain net flow - where SAFETY-02's sign watchdog (which gates on + `abs(grid_w) > 300` and could never open at a netted zero), the + peak guard and the capacity tariff can all see it. The fault + stops being invisible. Measured on the TEST-19 rig: the card's + own scenario reads +0 W at the meter with 6000 W going round, and + the shipped SignWatchdog's predicate is false on every one of + those cycles. + +WHAT IT DOES NOT DO, SAID PLAINLY: it does not stop the wedged +inverter. Nothing this add-on can send will. If the loop persists at +the meter after this trip, the remaining actuator is a human at the +isolator, which is what the notification says in those words. + +⚠️ AND IT IS A SITE CLAIM. `arbiter.CLAIM_SCOPE` carries the argument: +circulating power is defined over the roster and is identically zero +for any one unit, so there is no attribution to file this per-unit on - +and parking the wrong one of the two would leave the loop running with +the guard satisfied. + +### L4831 SITE, both of them, and the two reasons are why. "stopped" is the + +SITE, both of them, and the two reasons are why. "stopped" is the +operator switching control off for the whole site; "inputs missing" is +the SITE's own telemetry gone - the meter this controller regulates +against. Neither is about a pack, and both must stop every inverter. +⚠️ SAFETY-10: `and not self.shadow`, AND IT IS THE ONE FAILSAFE THIS +CARD CHANGES. `P_SAFETY` out-ranks every other claim, so leaving the +stop claim in while shadow mode is engaged would make the recorded +decision "stopped" on every cycle - a shadow run that answers the +wrong question, which is the same as no shadow run. The actuator ends +at the same number either way, and the substitution in `_write_unit()` +that replaces it is STRICTLY STRONGER than this claim: a claim can be +out-ranked by a higher priority, and the wire gate cannot be +out-ranked by anything. + +### L4854 SAFETY-07: the quarter-peak projection guard + +SAFETY-07: the quarter-peak projection guard +ONE `lo` limit at P_PEAK, and peakguard.py carries the whole argument. +What is decided HERE and nowhere else is what the guard is allowed to +see and what it is allowed to ask for: + +⚠️ `frozen` IS EVALUATED ON THIS CYCLE'S STANDING COMMAND, NOT ON +`self.freeze_wd.active`. The watchdog object is advanced at the END of +cycle() (check_meter_frozen), so reading its level here would grade +this quarter against the PREVIOUS cycle's conjunction - one cycle of +lag, in a guard whose entire job is to act inside a 900 s quarter. +`standing` is the value SAFETY-02 already computed above for exactly +this meaning: the command on the wire that this meter reading is a +response to. The predicate itself is freeze.py's shipped +`looks_frozen()`, not a copy of it - see loop_is_following() on what a +transcribed safety predicate costs. + +⚠️ `achievable_w` BOUNDS THE FLOOR SO THIS CLAIM CANNOT CONTRADICT THE +SAFETY LIMITS ABOVE. `lo > hi` in the arbiter is a CONTRADICTION and +resolves to 0 W - the battery parked, in the one minute of the month it +should be discharging hardest. maintenance_charge_w had to learn the +same lesson (config.yaml, validate.py rule 6); this claim is built so +the config cannot express it. + +⚠️ AND IT IS FILED EVERY CYCLE, unconditionally, like SAFETY-02's. A +claim is not sticky. Filed once and skipped next cycle, the floor +lapses and the actuator goes silently back to whatever was pushing the +peak. Which of the higher-priority claims outranks it is arbiter.py's +business, not this block's: a maintenance DRAIN or HOLD owns the +setpoint at P_MAINTENANCE, and a maintenance CHARGE is only ever a +P_MAINT_SHAPE limit (40), bound by this floor. A floor above the drain +rate still wins (SAFETY-78 at N>=2, `_peak_over_drain()` at N=1), and +so does a floor over a HOLD (`_peak_over_hold()`, SAFETY-86). + +⚠️ AND IT IS NOT RUN AT ALL WITHOUT P1. `meter_source: off` is the +legacy single-entity path: there is no telegram stream, so +`p1.averager` has no open block, so the guard would be BLIND on every +cycle forever - and blind means "no charging". That is not a +conservative default, it is a controller that silently stops charging +on every install that has not opted in to P1 yet; test_clamp.py's +export case caught it doing exactly that. The billed quantity simply +is not measured on that path, and the honest report is NOT COVERED - +the same answer, for the same reason, that the status page already +gives for SAFETY-18 on a transport that cannot see `unchanged_s`. +OPT-15: with battery modes on, the quarter `now` is in, even before +its first sample (DECISIONS/OPT-11-battery-modes.md). + +### L4918 ⚠️ THE SITE SUM. The guard sizes a floor from what the battery is + +⚠️ THE SITE SUM. The guard sizes a floor from what the battery is +ALREADY removing from the meter, and the meter sees every +inverter. One unit's power here would size the floor from a +fraction of the discharge already happening. + +### L4926 ⚠️ SUMMED FROM THE PER-UNIT CONJUNCTION, WHICH IS AC 4. Each + +⚠️ SUMMED FROM THE PER-UNIT CONJUNCTION, WHICH IS AC 4. Each +unit contributes `min(its max_w, |its own device bounds|)`, so +inverter B's rating bounds inverter B. Conjoining the SUMS instead +would let one unit's device range cap the whole site. + +### L4931 ⚠️ SAFETY-24. `pack_floor_soc` IS A MEASURED READING AND MAY BE None, + +⚠️ SAFETY-24. `pack_floor_soc` IS A MEASURED READING AND MAY BE None, +and it is handed over as None rather than defaulted here. An early +draft of the stage-5 loop read SoC as `| float(100)` and thereby +invented a full battery (NOTES.md 4.4b); a full battery is +precisely the value that disarms this floor. decide() treats None +as floor-limited, which is the direction that costs a shave rather +than the pack. +⚠️ THE EMPTIEST PACK, not an average - see `pack_floor_soc`. A +floor that grades a discharge permission against the mean lets the +emptier pack be driven below the level this option exists to +protect. None stays None: `decide()` treats it as floor-limited, +which costs a shave rather than a pack. + +### L4944 ⚠️ SAFETY-32. THE SAME OPTION, REDUCED OVER THE PACKS' OWN + +⚠️ SAFETY-32. THE SAME OPTION, REDUCED OVER THE PACKS' OWN +CUT-OUTS. `peak_soc_floor` is still one site-wide EMS floor and is +still read from that one key with CFG-03's one mirror behind it; +what `binding_soc_floor()` adds is the conjunction with each pack's +OWN `bms_soc_floor`, so the floor this site is graded against can +never be below the deepest cut-out on the roster. MAXIMUM here +pairs with the MINIMUM in `pack_floor_soc`: both reductions move +the verdict towards refusing a shave and away from spending a pack. +Under any config rule 8 accepts it IS the option, for every pack - +asserted over the whole schema range in test_peakguard.py part 12 +rather than assumed, because "another rule refuses that" is a claim +about rule ordering and sim/inject.py does not run rule 8 at all. + +### L4960 ⚠️ SAFETY-20. The device range goes in TOO, and this call site is + +⚠️ SAFETY-20. The device range goes in TOO, and this call site is +the one that needed it most: `standing` is `last_write`, i.e. the +value AFTER `clamp_to_rating()` applied `[dev_min, dev_max]`, so +grading it against a rail derived from bare `max_w` compares a +device-clipped number to a ceiling the device cannot reach. + +### L4976 SITE, and peakguard.claim() says so on the object it builds. The + +SITE, and peakguard.claim() says so on the object it builds. The +quantity is the 15-minute average OFFTAKE AT THE GRID CONNECTION, +which is what the capacity tariff bills; there is one quarter-hour +peak per site, not one per pack. ⚠️ IT IS ALSO THE `lo` HALF OF +SAFETY-25 §0c's table - a site `lo` at this stage, which is what the +deferred loop reserve's per-inverter `hi` must never be able to cross. + +### L4986 ⚠️ EDGE-LOGGED, not level-logged. The action log holds 40 lines; a + +⚠️ EDGE-LOGGED, not level-logged. The action log holds 40 lines; a +guard that appended one every 15 s for a whole quarter would push the +cause of the event off the end of the log that is meant to explain it. +SAFETY-03 logs every engagement because a clamp engagement IS the +count that matters there; here the count is the seconds, and the +engagement's own reason line already carries them. + +### L5004 OPT-04: price arbitrage (§10.1 priority 3) + +OPT-04: price arbitrage (§10.1 priority 3) +ONE `set` claim at P_ARBITRAGE, and app/arbitrage.py carries the whole +argument. What is decided HERE and nowhere else is what the strategy +is allowed to see: + +⚠️ IT IS PLACED AFTER THE PEAK BLOCK BECAUSE IT READS ITS CONCLUSION. +`engaged_now` is this cycle's peak verdict, computed ~20 lines up. +Evaluated before it, this would hand the strategy the PREVIOUS cycle's +answer - one cycle of lag on the interlock that implements §9.1's +"peak shaving outranks arbitrage", inside a 900 s quarter. + +⚠️ AND THE THIRD STATE IS NOT A TIDINESS. Without P1 the guard is not +CLEAR, it never RAN, and `None` says so. arbitrage.decide() refuses on +it, because charging at max_w creates the billed quantity while +nothing is measuring the quarter it lands in. `False` here would be +this line asserting a measurement that was never taken - the defect +`PeakReading` and `quarter_ceiling_w()` both exist to remove. + +⚠️ THE THREE-STATE COLLAPSE LIVES IN arbitrage.guard_state(), NOT +HERE, and that is not tidiness. It is the same lesson +`shaping_suspended()` records: inline, this expression was reachable +by no check, and mutating it back to a bare `engaged_now` left every +suite in this repository green while a `meter_source: off` install +traded blind. Read guard_state() before touching this line. + +⚠️ NO FETCH ON THIS PATH. `fresh_tariff_plan()` is an attribute read +and an age comparison; the HTTPS call lives in run_tariff_refresh(). +See TARIFF_REFRESH_S: a supplier's TLS timeout here would be a +supplier able to push this add-on towards layer 1's 30 s veto. + +⚠️ AND THE UNCERTAINTY SET IS NOT EMPTY BY DEFAULT. §11.4's +no-weather row widens the threshold, and this add-on carries no +weather forecast at all - §8.1's PV forecast is not built. Passing +`frozenset()` would be main.py asserting a forecast is healthy when +there is not one, which is exactly what static_tariff's `uncertainty` +argument has no default in order to prevent. +⚠️ TARIFF-11: BOTH ATTRIBUTES, AND `arb_at` IS WHAT MAKES THE ROW +HONEST. Reaching this line is the only proof that this cycle got as +far as the arbitrage step; the early return at the input hold above +leaves BOTH standing at whatever the last completed cycle left, and +`arb_at` is then the age the status row reports rather than a +decision presented as current. + +### L5054 SAFETY-47. HOISTED OUT OF THE CALL, NOT COPIED. One evaluation of + +SAFETY-47. HOISTED OUT OF THE CALL, NOT COPIED. One evaluation of +the shipped expression feeds both the sizing below and +`arbitrage.sized_from_meter()` in `_shadow_settle()`, so the +caveat on the recorded watts can never be answered from a +different cycle's guard than the watts were. +SAFETY-125: a late meter reading's seconds count, as the bill. + +### L5068 SAFETY-45. THE SAME GUARD'S SECOND ANSWER, AND THE CONTINUOUS + +SAFETY-45. THE SAME GUARD'S SECOND ANSWER, AND THE CONTINUOUS +ONE. `guard_state()` is a switch and it was the whole loop: +the guard engaged on a 5 W floor, the trade was refused +outright, the loop took the actuator, the meter fell, the +guard released and the trade came back AT max_w. Measured on +TEST-23 stage 3 at the shipped peak_cap_w/max_w: 28 charge +onsets an hour, grid -456 <-> +3200 W. This is the watts the +billed quarter can still afford, so the buy leg is CLAMPED +instead - the shape control.maintenance_charge_floor() has +always given a maintenance charge, off the MEASURED guard +rather than off the optional peak_forecast_entity. +⚠️ SAME ORDERING ARGUMENT AS THE LINE ABOVE: this reads the +peak block's conclusion, ~50 lines up, so it must stay after +it. Evaluated earlier it would size this quarter's trade from +the previous cycle's quarter. + +### L5093 OPT-09. PER-PACK SIZING. Not `max_w` - the site rating - on + +OPT-09. PER-PACK SIZING. Not `max_w` - the site rating - on +both sides any more: the trade is sized to the packs whose own +state of charge permits that direction, so it can never ask +for more than the roster can take. `trade_power_w()` carries +the argument, including which of the two SoC bounds belongs +here and which belongs on the envelope. ⚠️ AT N=1 BOTH SIDES +ARE `max_w` EXACTLY, whenever the trade is permitted at all: +the one pack that passed the gate is the whole roster. +⚠️ AND ON THE SELL SIDE THIS IS A NO-OP TODAY on any roster, +because `soc=` below is the EMPTIEST pack, so a sell is +refused outright whenever any pack is at or under the floor - +i.e. whenever this sum could be smaller than the site rating. +It becomes reachable the day that gate becomes per-pack; +`test_packshare.py` part 9 grades it directly rather than +letting an unreachable branch go ungraded. + +### L5117 Edge-logged, for the peak guard's reason: the action log holds 40 + +Edge-logged, for the peak guard's reason: the action log holds 40 +lines and a trade lasts a whole hour, so a line per cycle would +flush the context that explains it. The transition is what an +operator needs - "it started buying at 03:00", not 240 copies. + +### L5128 maintenance + +maintenance +⚠️ ONE PASS PER PACK, AND `arbitrate()` IS WHY THE LIST STAYS SHORT. +At most one machine is out of IDLE on any tick, so at most one of +these branches fires and the claim list is the shape it has always +been. The loop is not a widening of what maintenance may ask for; it +is what makes the ONE claim it does file land on the pack that is +actually being recalibrated, whichever roster slot that is. + +### L5137 PER-INVERTER. §12's monthly recalibration is a PACK procedure - + +PER-INVERTER. §12's monthly recalibration is a PACK procedure - +drain THIS pack to its floor, charge THIS pack full, +recalibrate THIS pack's coulomb counter. Two packs recalibrate +on two schedules. See arbiter.CLAIM_SCOPE. + +⚠️ FILED ON THE PACK WHOSE STATE MACHINE PRODUCED IT - `inv`, +the roster entry this `result` was ticked from - and that is +the whole of MAINT-05 at this line. It used to be +`self.maint_unit`, which was `inverters[0]` flatly, because +there was one FSM and its history had nowhere else to live. +Pack B's drain filed on pack A is one pack being commanded for +another's procedure while the pack that is actually draining +stays under the loop: the site would move the right total and +recalibrate nothing. + +⚠️ AND IT STAYS `SCOPE_UNIT`. Two FSMs mean two claims on two +actuators, which the allocator consumes as per-unit intervals; +ARCH-01 is explicit that this must never become a site claim, +because per-inverter constraints filed site-wide are the +cross-inverter `lo > hi` contradiction at arbiter.py:114. + +### L5162 Money outranks the maintenance schedule: while the quarter-hour + +Money outranks the maintenance schedule: while the quarter-hour +projection is over the cap, the charge-only shaping is simply not +claimed, so the loop can discharge and shave the peak. When a +dedicated peak-shaving strategy arrives it will claim SET at +P_PEAK and outrank this limit without any code here changing. +⚠️ AND SAFETY-07 IS THE OTHER HALF OF THIS CONDITION, NOT A +SECOND MECHANISM. The shaping is `hi <= 0`; the peak guard's +claim is `lo >= 0`. Both are limits, arbiter.py applies EVERY +limit at or above the winner's priority, and most restrictive +wins - so a peak event during a maintenance charge window files +`lo > hi`, which is a CONTRADICTION and resolves to 0 W. The +battery would park in the exact quarter it should be shaving. +Priority does not save it: clause 2 has no notion of a +higher-priority limit overriding a lower one, and it should not - +"most restrictive" is what makes the safety bounds unconditional. + +So the higher-priority claimant SUPPRESSES the lower one rather +than out-voting it, which is what this branch already did for +`peak_forecast_entity`. That entity is optional and empty on a +default install, so until now the suspension could not fire on the +site that needed it. `self.peak_guard` is measured from the meter +and is always there. + +⚠️ THE CONJUNCTION LIVES IN peakguard.py, NOT HERE, and that is +not tidiness. It was inline, and a reviewer mutated it back to its +historical broken form - re-gated on `peak_forecast_entity` alone +- and every suite in this repository stayed green while a default +install parked at 0 W in the quarter that sets the month's bill. +Read shaping_suspended() before touching this: both terms are +there, and why neither is sufficient alone. + +⚠️ ONE SUSPENSION FLAG FOR THE SITE, NOT ONE PER PACK, AND THE +INTERLOCK IS WHAT MAKES THAT TRUE. The quantity it edge-logs is +a peak event at the grid connection, and `arbitrate()` allows +at most one pack to be in CHARGE at a time, so this branch can +run at most once per tick. Were two packs ever allowed to +charge together, this flag would have to become per-pack - and +so would the reasoning above it. + +### L5216 ⚠️ CFG-03. `self.maint.cfg.charge_w`, NOT A SECOND READ + +⚠️ CFG-03. `self.maint.cfg.charge_w`, NOT A SECOND READ +OF `self.o`. This line used to re-open the options dict +with its own literal fallback, so the rate the shaping +asked for and the rate the state machine drained at +could be different numbers from the same install - and, +with the key absent, they were. The Controller already +parsed this once in __init__; asking the object that +owns it cannot drift from it. Every pack's machine +holds the same `MaintConfig` instance, so this is the +rate the pack in front of us is charging at. + +### L5239 OPT-11: each battery's mode, a soft unit limit at P_MODE + +OPT-11: each battery's mode, a soft unit limit at P_MODE +Filed only with battery modes on, and never on a battery in any +maintenance phase: maintenance at 60/40 outranks the mode. The range +always holds 0 W (packmode.mode_range()). pre_resolve() keeps it +apart from the hard limits, and it gives way to the peak guard's +site floor (P_PEAK) only as far as the floor needs, so the two never +meet in a `lo > hi` (arbiter._unit_modes()). +P3: the range is the switch's, narrowed by the battery's role in +the price runs this tick (`modetrade.decide()`); both hold 0 W. + +### L5261 the grid-following loop + +the grid-following loop +⚠️ SAFETY-10: `or self.shadow`. The loop is the leg a shadow run most +needs and the one that is switched off by `auto_start: false`, so +without this an install in `auto` shadow mode would record every +strategy's decision and a permanent silence where the grid-following +loop should be. It is safe because the loop's `prev_w` is +`self.target`, which the end of this method re-seeds to what is +actually standing on the wire. +SAFETY-52: a refusal learned while control ran does not survive a +stop or a start (shadow mode keeps the loop running when stopped). + +### L5285 SAFETY-73: each refusing unit's own P_SAFETY claim + +SAFETY-73: each refusing unit's own P_SAFETY claim +A hard unit limit that always intersects (OPT-11's P_MODE layer sits +inside it): closed in the refused direction, so the allocator hands +the share to the others within their own limits. During its probe it +is a pin at PROBE_W and the others carry the rest. Filed here, before +the loop, so OPT-11's loop bound sees it. Unit claims only, and still +the last unit claims filed, so every unit's claim order is as before. + +### L5343 ⚠️ prev is the ARBITER's last output, not the loop's own last + +⚠️ prev is the ARBITER's last output, not the loop's own last +wish. If something outranked the loop, that is what the hardware +actually did, and the controller must track reality or it jumps +the moment it regains control. + +⚠️ The integrator has to track the same reality, and it is no +longer prev_w, so it needs saying out loud: if the arbiter did not +give the loop what it asked for last cycle, the loop's +accumulated error belongs to a command that never happened. +Re-seed from what the hardware was actually told. This is the +failsafe case too - every layer-1 stop resolves to 0 W, so +entering failsafe re-seeds the integrator to zero and the first +cycle after release starts from zero instead of dumping the whole +stale period as power. + +### L5366 SAFETY-52: another writer overrode the loop, so a refusal learned + +SAFETY-52: another writer overrode the loop, so a refusal learned +against the loop's own ask may no longer describe the wire. A gap +(`loop_w` None: blind or stopped) keeps it: the stale-reading stop +is what seeds it, and dropping it there restarts the ~70 s cycle. +SAFETY-107: it ends only if compute() no longer finds it against +that writer's ask (`_refusal_update()`). A held refusal makes the +loop ask 0 W, so any claim that binds differs from it every cycle. + +### L5388 ⚠️ `actual_w` IS THE SITE SUM AND THAT IS DEV-02's OTHER HALF. + +⚠️ `actual_w` IS THE SITE SUM AND THAT IS DEV-02's OTHER HALF. +The anti-windup test inside compute() is +`abs(prev_w - actual_w) > saturation_w`, and `prev_w` is the SITE +target. Handed ONE inverter's power at a roster of two it compares +a site number against a unit number, permanently trips the +saturation freeze and leaves a standing grid error - measured on +admin/goodwe's two-master rig at up to 510 W of split-dependence +(gain 0.2; 250 W at 0.4, 50 W at 0.6) while the allocator's shares +summed to S in every run. With the sum, every split is +bit-identical at every gain the schema accepts. That is why the +per-unit readings became per-instance and THIS one became site +level: the two halves of §6.2's identity break in opposite +directions. See `site_batt_w` and test_alloc.py part 8. + +### L5408 TEL-10. ⚠️ ONE NAME FOR THE COMMAND THE LOOP WAS MEASURED + +TEL-10. ⚠️ ONE NAME FOR THE COMMAND THE LOOP WAS MEASURED +AGAINST. `self.target` is reassigned further down this method, so +a `decision.i_w - self.target` written at publish time would +subtract a DIFFERENT cycle's command and call the answer a lead. +The published lead is built from the value `compute()` was +actually handed, on the line that hands it over. + +### L5459 TEL-10 + +TEL-10 +⚠️ THE INTEGRATOR HAS NEVER LEFT THIS PROCESS, AND THAT IS WHAT +THE CARD IS. `self.i_w` is carried between cycles and published +nowhere - no entity, no attribute, no log line - so the only way +anyone has ever asked what it was doing is to RECONSTRUCT it from +the grid trace and a replay. That reconstruction reproduced about +a third of the engagements it was checked against and was thrown +away; a card that has to be argued from a discarded reconstruction +is a card that cannot be argued. + +Three rows, and the third is not derivable from the first two by +anyone reading the dashboard afterwards: + + `loop_i` the integrator AFTER this cycle - `Decision.i_w`, + which its own docstring says is the value BEFORE + the output clamp, the slew limit and quantisation. + It is therefore NOT `setpoint` and must never be + published from it. + `loop_lead` how far the integrator stands AHEAD of the command + it was computed against. This is the quantity + SAFETY-48 bounds, and `integrator_max_w / slew_w` + is the number of cycles it takes to unwind. + `loop_reason` `compute()`'s OWN reason string - `deadband`, + `i-clamped`, `clamped`, `slew-limited`, + `saturated-freeze`, `freeze-released`, `tracking`. + +⚠️ AND `loop_reason` IS NOT `self.reason`. `self.reason` is the +ARBITER's sentence (`resolution.explain()`, e.g. "loop -> 1200 W") +and it does not carry the loop's own word at all: the Claim filed +below takes `decision.reason` and `Resolution.explain()` prints the +winner's NAME, not the winner's reason. The status page's "Why" +row is the arbiter's sentence and stays that way. + +### L5494 SAFETY-03 + +SAFETY-03 +⚠️ READ THE BOOLEANS, NOT `decision.reason`. On a default install +the integrator bound is what bites and the output clamp is +unreachable (control.py says so), and `reason` is then overwritten +by whichever of slew-limiting or the saturation freeze ran after +it - so a string test is silent on the two cases a winding loop +most often presents as. These flags are set where the clamp +happens and nothing downstream touches them. +SAFETY-40: every number comes from THIS decision, at clamp time, +never from `self.target` after slew/freeze/arbiter rewrote it. + +### L5512 SITE. compute() regulates `grid_w` - the P1 measurement - to + +SITE. compute() regulates `grid_w` - the P1 measurement - to +zero. Its subject is the meter, and §6.2's architecture is ONE +integrator on P1 whose output is then SPLIT. This is the claim the +allocator exists to divide. + +### L5543 ⚠️ `weights=` IS OPT-09, AND ITS ABSENCE WAS THE CARD. ARCH-01 left th + +⚠️ `weights=` IS OPT-09, AND ITS ABSENCE WAS THE CARD. ARCH-01 left the +allocator one free parameter and ALLOC-01 built the machinery that +consumes it (`allocator._fill`); this line is the first thing that has +ever passed one. Without it every unit weighed 1.0 and the split was +a fixed 50/50 regardless of what either pack could do. + +⚠️ A METHOD, NOT A DICT. The weighting is by ENERGY HEADROOM and is +therefore direction-dependent, and the direction is the sign of the +site target - which stage 2 chooses inside `resolve()`. See +`pack_weights()` and `packshare.weights()`; the arbiter calls it once, +between stage 2 and stage 3. + +⚠️ AND IT IS A PREFERENCE, NOT A PERMISSION. Nothing about the site's +ability to DELIVER rests on this argument - a weight cannot stop a +unit being commanded and cannot move a failing unit's load to its +sibling. The `pack` claim filed above is the half that constrains. + +### L5564 SAFETY-73: a probe pin stands only while the resolved site target + +SAFETY-73: a probe pin stands only while the resolved site target +asks at least PROBE_W its way. Below that a sibling would carry +the opposite direction (circulation), so the pin goes back to the +closed limit and the split is resolved once more. + +### L5581 THE TWO REFUSALS, AND THEY ARE NOT THE SAME REFUSAL + +THE TWO REFUSALS, AND THEY ARE NOT THE SAME REFUSAL +Both do the same thing - REPLACE the resolution with a 0 W failsafe +which is then written like any other cycle at +`write_setpoint(self.target)` below. Nothing is skipped. 0 W is the +fail-toward-inaction direction: the setpoint is commanded to zero +rather than left wherever the last cycle put it. They differ in WHO +refused and therefore in what an operator should do about it, so they +are two branches with two messages and not one with a vague one. + +⚠️ AND NEITHER MAY BE LEFT UNGRADED. PR #40's reviewer replaced the +first of these with `if False:` and the whole 17-file suite stayed +green, because at the shipped roster of one it was unreachable. +test_peakguard.py part 10h grades both, on real cycles. + +1. THE ALLOCATOR REFUSED. Before ALLOC-01 this fired on every N>=2 + cycle, because there was no allocator and the obvious placeholder - + hand the site target to each inverter - IS the ARCH-01 fault. There + is an allocator now and that trigger is gone; the branch is not, + because refusing is still right when no safe split exists at all: a + mis-routed claim (so the number to divide may itself be wrong), no + inverter left in the envelope set, or a split that could only be + made by commanding one pack to charge while another discharges. + `allocator.plan()` carries the argument for each. + +### L5614 2. THE ALLOCATOR SUCCEEDED AND THIS CONTROLLER CANNOT DELIVER IT. + +2. THE ALLOCATOR SUCCEEDED AND THIS CONTROLLER CANNOT DELIVER IT. + ⚠️ RE-AIMED BY DEV-02, NOT DELETED, AND THE DIFFERENCE MATTERS. + Under ALLOC-01 this fired whenever the split named any inverter but + the single one this controller could write, because there was one + `setpoint_entity`. There is a writer per inverter now, so that + trigger is gone - and the INSTINCT is not, because a roster entry + can still have no writer: an inverter configured with no + `setpoint_entity` of its own is an inverter this controller cannot + put a number on. Writing the site target to the ones it CAN reach + would over-command them by exactly the missing unit's share - + not the broadcast fault, but the same shape of over-command. + Commanding a partial site is a worse instruction than commanding + nothing, and "nothing" here means 0 W and says so. + + ⚠️ IT IS NOT THE SAME EVENT AS A DEAD LINK, WHICH IS WHY IT IS NOT + FOLDED INTO `live_units()`. A unit whose writes are being rejected + is DROPPED and its share is carried by the survivors - a real, and + announced, change in what the site can deliver. A unit with no + writer configured at all is a CONFIGURATION that cannot be + delivered, and the site stops rather than silently running at part + strength on a roster somebody wrote down wrong. + +### L5643 ⚠️ `shares={}`, NOT THE SHARES IT REFUSED TO DELIVER, AND SINCE + +⚠️ `shares={}`, NOT THE SHARES IT REFUSED TO DELIVER, AND SINCE +DEV-02 THAT IS LOAD-BEARING RATHER THAN TIDY. The write loop below +commands each inverter `shares.get(name, 0.0)`, so carrying the +split through a refusal would write the very numbers this branch +just declined - and, worse, would write NOTHING at all when they +equal what is already standing, because an unchanged value is not +re-sent. The record the operator needs survives on +`self.allocation`, which is assigned above and untouched here. + +### L5658 3. AC 6: A DROPPED INVERTER IS NEVER SILENT. The survivors carry its + +3. AC 6: A DROPPED INVERTER IS NEVER SILENT. The survivors carry its + share, which is a real change in what the site can deliver, and an + operator who is not told reads a working site. Edge-triggered on + the SET of dropped units, not level-triggered, because the action + log is a log of events (§15) and a stale link would otherwise write + a line every second for as long as it lasts. + +### L5676 3b. OPT-09 / IF-04: WATTS NOBODY COULD TAKE ARE NEVER SILENT EITHER. + +3b. OPT-09 / IF-04: WATTS NOBODY COULD TAKE ARE NEVER SILENT EITHER. + `unmet_w` is the site target the envelopes could not absorb. It is + NOT a broken allocation - `Allocation`'s own docstring says why + fusing it with `ok` would let one saturated inverter park the whole + site - but it IS the site failing to deliver what the loop asked + for, and before this card nothing anywhere reported it. It is the + state a closed envelope produces when BOTH packs are at their + limits: the ask has nowhere left to go, and an operator watching a + standing grid error needs the reason rather than the symptom. + Edge-triggered on the VALUE, for `_dropped` reason. + +### L5698 A claim reached the arbiter on an actuator its source's scope does + +A claim reached the arbiter on an actuator its source's scope does +not permit. It is a BUG in the filing site, not a state to survive: +a per-inverter constraint in the site list is the `lo > hi` this +card removes, and a site constraint on one unit is a bound the +other unit never gets. Loud, every cycle, and it does not change +the resolution - the arbiter already routed by `actuator`. + +### L5709 SAFETY-02's arming gate + +SAFETY-02's arming gate +Was the number about to go on the wire chosen by the grid-following +loop, or by a strategy that commands against the meter on purpose? +Only the former is expected to agree in sign with P1 - without this, +every maintenance grid charge trips the failsafe within three minutes. + +⚠️ THE EXPRESSION LIVES IN watchdog.py, NOT HERE, and that is not +tidiness. It was inline, test_watchdog.py held a transcription of it, +and the P_PEAK case meant to force whoever lands peak shaving to come +and change an expectation did not: editing this line alone to +`winner in ("loop", "peak")` left every suite green while the watchdog +went blind for every peak event. Read loop_is_following() before +touching the gate - the forward hazard and the reasoning are there. + +### L5725 UX-08: the same answer in plain words, for the page's "Why" line. + +UX-08: the same answer in plain words, for the page's "Why" line. +`reason` stays the technical record the log and the checks read. +UX-10: `why_key()` maps a safety winner to its claim's reason, and +every key it can return has words in messages.WHY_WINNER. + +### L5739 DEV-02: EACH INVERTER IS TOLD ITS OWN SHARE + +DEV-02: EACH INVERTER IS TOLD ITS OWN SHARE +⚠️ ITS OWN SHARE, NEVER THE SITE TARGET. `resolution.shares` is the +allocator's answer and `sum(shares) + unmet_w == round(target_w)` is +an integer identity, so handing each unit its entry is what makes the +gain at the meter a CONVEX COMBINATION of the per-unit gains. Handing +each unit `self.target` is the ARCH-01 fault: each supplies it in +full, the gain becomes N times the per-unit gain, and on the +two-master rig that is 4000 W peak-to-peak forever at gain 1.0 with +not one guard firing. + +⚠️ AT N=1 THIS IS BYTE-IDENTICAL. The allocator's pass-through returns +`{inverter-a: target_w}` as an unrounded float, so the number written +is `self.target` exactly, as it always was. + +⚠️ AND A UNIT NOT IN `shares` IS COMMANDED 0 W, not left standing. +That is the dropped-link case: the inverter holds its last command +FOREVER, so "not in the split" must mean zero on the wire, not +silence. The write is the same clamped, budgeted path as every other. +SAFETY-85, before the writes: the wire still holds last cycle's. + +### L5765 SAFETY-03, and its boundary is the WRITE + +SAFETY-03, and its boundary is the WRITE +⚠️ NOT THE SAME BOUNDARY AS SAFETY-18's BELOW, THOUGH THE CALLS ABUT. +This one reads `self.clamp_last`, which is None until write_setpoint() +has actually run, so it has to follow the write. The one below grades +`self.target`, which is assigned further up - see check_output_clamp() +and check_meter_frozen() for each. Two guards, two orderings, adjacent +lines: do not "tidy" them into one rule. + +Moving it BELOW the other guards is harmless - nothing between here and +the end of cycle() writes `self.clamp_last`. Moving it above the write +is not, and test_clamp.py part 6 fails on exactly that: it grades the +evidence, not the line number, so a rename or a move into a helper that +still runs after the write keeps it green. (TEST-11.) + +### L5780 SAFETY-18, and its boundary is the ASSIGNMENT + +SAFETY-18, and its boundary is the ASSIGNMENT +⚠️ THE BOUNDARY IS `self.target = resolution.target_w` ABOVE, NOT +write_setpoint(). This comment used to say "the command that has just +gone on the wire", which is wrong twice over and was corrected by +TEST-06's reviewer: `check_meter_frozen()` grades `self.target` - the +arbiter's resolved intent - and `write_setpoint()` clamps only a local +`value` and can skip the write entirely, so that number may never have +gone anywhere. + +What both terms of the conjunction must describe is the SAME moment: +the command this cycle resolved, against how long the meter that chose +it has been standing still. Evaluated before +`self.target = resolution.target_w` it would grade the PREVIOUS +cycle's command against THIS cycle's meter - the one combination that +was true of neither moment. Moving it between the assignment and +write_setpoint() is therefore harmless; moving it above the assignment +is not, and test_freeze.py part 5 fails on exactly that. + +### L5805 SAFETY-31's alarm, and its boundary is the LATCH, not a number + +SAFETY-31's alarm, and its boundary is the LATCH, not a number +Unconstrained where the two above are not: it grades +`self.circ_wd.tripped`, which was advanced near the top of this method +beside SAFETY-02 and which nothing since has touched. It is called on +EVERY cycle rather than only on the cycle that trips, because its +second job is re-raising the alarm after a restart into an existing +trip - see its docstring on why that shares one code path with the +fresh trip instead of getting its own. + +### L5815 SAFETY-42's alarm, and its boundary is the LATCH, like SAFETY-31's + +SAFETY-42's alarm, and its boundary is the LATCH, like SAFETY-31's +It grades `inv.delivery_wd.tripped`, which was advanced near the top +of this method beside SAFETY-02 and SAFETY-31 and which nothing since +has touched. Called on EVERY cycle rather than only on the cycle that +trips, because its second job is re-raising the alarm after a restart +into an existing trip - see its docstring on why that shares one code +path with the fresh trip instead of getting its own. + +### L5829 SAFETY-24's alarm, and it is the OTHER way the money gets spent + +SAFETY-24's alarm, and it is the OTHER way the money gets spent +Same boundary argument as check_peak_saturated(): it grades +`self.peak_guard`, which cycle() assigned above and nothing since has +touched. Kept as its own method rather than folded into that one, +because the two states are mutually exclusive and want OPPOSITE +operator actions - saturation says "shed load, the inverter is already +flat out"; this says "the pack is at its floor and this quarter is not +being shaved at all". + +### L5839 TARIFF-01, and it is LAST on purpose + +TARIFF-01, and it is LAST on purpose +Banking a quarter is bookkeeping about a moment that has already +happened; a slow SD card must never sit between the meter and the +setpoint. Its position is unconstrained in the way SAFETY-03's and +SAFETY-18's are not - it grades neither `target` nor `standing` and +reads only `self.p1`, which no line in this method writes. + +### L5847 SAFETY-10, AND IT IS LAST FOR A REASON THAT IS NOT TIDINESS + +SAFETY-10, AND IT IS LAST FOR A REASON THAT IS NOT TIDINESS +Every guard above has now read `self.target` - the resolved intent - +and SAFETY-18 in particular grades exactly that. Re-seeding before +them would hand each one a 0 W that no decision produced. Re-seeding +AFTER them hands the NEXT cycle, and the sign watchdogs, what is +actually standing on the wire. See `_shadow_settle()`. + +### L5856 SAFETY-10. Record the decision, then re-seed the carried command. + +SAFETY-10. Record the decision, then re-seed the carried command. + +TWO JOBS, AND THEY ARE IN THIS ORDER BECAUSE THE SECOND DESTROYS THE +FIRST'S EVIDENCE. + +1. THE RECORD. A shadow run is only worth running if it answers "what +would it have done, and why". `self.shadow_would_w` and +`Resolution.explain()` are that answer, and the action log gets one +line per CHANGE OF DECISION rather than one per cycle - the log +holds 40 rows, and a level-logged shadow run would flush the context +of its own findings inside four minutes at a 15 s cycle floor. The +same edge rule the peak guard and the arbitrage strategy already +use, for the same reason. + +2. THE RE-SEED. `self.target` and each `inv.target` are set back to +`shadow.WIRE_W` - what the write gate actually put on the wire. + +⚠️ WHY THE RE-SEED IS A SAFETY PROPERTY AND NOT BOOKKEEPING. Three +machines read the carried command as a statement about the HARDWARE: + +* `compute(prev_w=self.target, ...)` - the loop's slew limiter and +its integrator. Left holding a shadow decision, the first cycle +after shadow mode is turned off would slew from a base that never +existed: up to a full `slew_w` step onto a battery sitting at 0 W. +Re-seeded, the exit is safe BY CONSTRUCTION and needs no separate +transition code - the carried command already equals the standing +one. +* `Inverter.standing_w()`, which is what SAFETY-02/30's sign +watchdogs grade. Fed a shadow decision they would compare a number +against a meter that never saw it, disagree for as long as the +decision asked for power, and LATCH A TRIP THAT SURVIVES INTO LIVE +OPERATION AND A RESTART. Shadow mode would manufacture the failsafe +it exists to help debug. ⚠️ THIS ONE IS ALREADY HELD BY THE WIRE +GATE - `standing_w()` prefers `last_write`, and that is the 0.0 W +the gate accepted - so the re-seed is the SECOND rung, covering +the fallback before any write has been accepted. Two rungs +answering one question is MUTATION.md's masking shape, and the +mutation that reproduces the hazard has to defeat BOTH: driven +singly, dropping this line leaves the detector inert and names +nothing about the latch. Measured. +* SAFETY-42's delivery watchdog compares `inv.target` against what +the pack is producing. A share nothing was told to produce is a +delinquency report on every cycle of every shadow run. + +⚠️ AND EVERY CYCLE'S DECISION IS THEREFORE COMPUTED FROM WHERE THE +PLANT REALLY IS, not from a counterfactual plant that drifts further +from reality every tick. "What would this controller command NOW, +given this meter and a battery at 0 W" is a true statement about the +present; "what would the eleventh cycle of a run that never happened +have commanded" is not a statement about anything. + + +### L5909 ⚠️ `first` EXISTS SO A LIVE INSTALL'S FIRST CYCLE IS SILENT. The + +⚠️ `first` EXISTS SO A LIVE INSTALL'S FIRST CYCLE IS SILENT. The +edge is against `None` on cycle one, and an install that comes up +CONTROLLING has nothing to report - a "shadow mode off" line at +every start is one more row of boilerplate in a 40-row log, and +it was measured pushing a real clamp episode's context out of +test_clamp.py part 2's ring. Coming up IN shadow mode is the +other direction and it is always worth a line: it is the log an +operator reads to find out why nothing is being commanded. + +### L5945 SAFETY-47. ⚠️ NO LOGIC HERE, DELIBERATELY. All three rungs - the + +SAFETY-47. ⚠️ NO LOGIC HERE, DELIBERATELY. All three rungs - the +arbiter's winner, the leg being a CHARGE, and the headroom having +been MEASURED - live inside `arbitrage.sized_from_meter()`, which +says why, including why it is NOT keyed on whether the trade was +capped. A rung written at a call site is a rung no check can reach +with the other two clear, which is TEST-16's rule. + +### L5953 ⚠️ THE WINNER AND THE ROUNDED WATTS, NOT THE WATTS ALONE. A decision + +⚠️ THE WINNER AND THE ROUNDED WATTS, NOT THE WATTS ALONE. A decision +that moves from the loop to the peak guard at the same number is a +different decision and the operator needs the line; a loop target +that wanders by a watt is not, and 15 s of those would be the whole +log. +⚠️ SAFETY-47 ADDS THE CAVEAT FLAG TO THE EDGE. The same winner at the +same watts with and without the caveat are two different claims about +the same number, and an edge key blind to that would print the first +one and silently keep it standing. It cannot flood: the flag only +moves when arbitrage starts or stops owning the resolution, or when +the guard starts or stops measuring the quarter, and both of those +move the winner or the watts as well on every cycle measured. + +### L5979 SAFETY-85. The loop's clamp counts only on a cycle the loop decided + +SAFETY-85. The loop's clamp counts only on a cycle the loop decided +(a rating may cut it). A battery another owner set to discharge counts +when it gave less than it was told for `saturation_cycles` cycles in a +row. DECISIONS/SAFETY-85-no-false-not-keeping-up.md. + +### L6025 SAFETY-119: does the loop's bound on this cycle count? Not within + +SAFETY-119: does the loop's bound on this cycle count? Not within +a settle after another owner handed the wire back: its integrator is +re-seeded from that owner's command and kicked by a meter that does +not show it yet. SAFETY-121: the settle is HANDBACK_CYCLES cycles and +SHORT_SPAN_S after the hand-back, so a bound that outlasts it counts +at any cycle length; losing the wire restarts it. Across all +hand-backs the bound is hidden on at most ROLLING_BOUND_CYCLES cycles +in any ROLLING_S, so a bound that never outlasts a settle is counted +too. DECISIONS/SAFETY-121-bound-every-quarter.md. + +### L6060 SAFETY-03. Alarm whenever a clamp actually engaged this cycle. + +SAFETY-03. Alarm whenever a clamp actually engaged this cycle. + +Runs AFTER write_setpoint() for the same reason SAFETY-18 does: the +clamp is arithmetic done inside the write, so before the write there is +nothing yet to report. + +⚠️ PUBLISHING IS NOT IN THE WRITE PATH. The clamp itself is synchronous +inside write_setpoint(); this - the awaits, the notification, anything +that can block on Home Assistant - is out here. A stalled supervisor must +never be able to delay or drop a frame. + +⚠️ THIS IS NOT A TRIP. No claim is filed, nothing is latched, 0 W is not +commanded and `publish()` still reports "running". §11.2's action for +this row is "clamp and alarm", and the clamped value is written and the +loop keeps running. Turning this into a trip means coming here and +changing that deliberately, not discovering it in the field. + + +### L6077 ⚠️ THE EVIDENCE IS PER UNIT AND THE ALARM IS NOT. `clamp_last` moved + +⚠️ THE EVIDENCE IS PER UNIT AND THE ALARM IS NOT. `clamp_last` moved +onto the Inverter because a clamp on B says nothing about A; the +ClampWatchdog stayed one per controller because clamp.py's own +docstring says so - it is an anti-flood counter over an EVENT BUS, not +a property of a device, and one notification per inverter per cycle is +the flood it exists to remove. So: any unit that clamped is an +engagement, and the reason NAMES the unit. + +### L6107 THE ACTION LOG, AND IT IS COALESCED PER EPISODE + +THE ACTION LOG, AND IT IS COALESCED PER EPISODE +Every engagement is recorded, but consecutive ones are recorded by +UPDATING one row's count rather than inserting a row each. + +⚠️ THAT IS NOT COSMETIC, AND IT WAS FOUND THE HARD WAY. `log_event()` +keeps 40 rows; a winding loop clamps on every cycle, so a row per +engagement flushes the whole ring within 40 cycles - and the first +thing it evicted, in test_freeze.py, was SAFETY-18's "METER FROZEN?" +row. A guard whose log drowns out the other guards' logs has moved the +flood rather than removed it. The count here is `clamp_wd.engagements`, +so nothing is lost: the row says exactly how many, and the number is +read off the counter rather than off the number of rows. + +This lives here rather than only in write_setpoint() because on a +default install the actuator-side clamp is unreachable - compute() has +already bounded the integrator - so the only engagements that exist are +loop-side ones. Measured: 60 cycles of the §10.3 runaway produce 0 +write-path engagements and 2 loop-side ones. + +### L6162 A fixed notification_id, for the reason check_meter_frozen() gives - + +A fixed notification_id, for the reason check_meter_frozen() gives - +and a DIFFERENT one from every other alarm this add-on raises, because +a clamp is not a frozen meter and neither is a saturation freeze. +UX-08: the words are messages.output_clamp()'s; the numbers are the +ones `reason` was written from (ClampWatchdog.facts), asked first. + +### L6172 SAFETY-07. Alarm ONLY when the guard has run out of inverter. + +SAFETY-07. Alarm ONLY when the guard has run out of inverter. + +⚠️ AN ENGAGEMENT IS NOT AN ALARM, AND THE DIFFERENCE IS §10.3's DOCTRINE +READ CAREFULLY. "Treat an out-of-range computed setpoint as a bug signal +- clamp it, then alarm" is SAFETY-03's rule and it is right there: the +loop computing 14 768 W is a WINDING INTEGRATOR, a defect, and clipping +it silently is what let it keep climbing behind a dashboard full of legal +numbers. A peak floor above the inverter's rating is not a defect. It is +a house load bigger than the inverter - 2026-08-20 15:45 ran ~5900 W +against a 5000 W unit - and alarming on the ordinary case is how an +operator learns to dismiss the notification that matters. So an +engagement is an ordinary control action: it goes to the §15 action log +and the status page, and no further. + +What DOES earn the operator's attention is saturation: the guard asked +for more discharge than the inverter can give, so the quarter is going +over the ceiling anyway and the controller has already done everything +available to it. That is the one state where the money is going to be +spent and a human is the only remaining actuator. + +SAFETY-81: `g.saturated` alone is not enough. It is graded against the +aim, and a 1 s meter spike, noise or the last seconds of a quarter set +it while the quarter lands on target; `peakguard.load_too_high()` must +agree too, for `ALARM_HOLD_S`. The battery reading it gets is the lower +of this cycle's and the last one's - see there. + +Edge-triggered, and de-asserting arms it again - the same shape as +FreezeWatchdog's `evaluate()`, and for the same reason: one notification +per episode, not one per cycle. SAFETY-81: the notification and action +log line at most once per quarter; the ERROR line once per episode. + + +### L6254 SAFETY-24. Alarm when the EMS SoC floor stops the guard shaving. + +SAFETY-24. Alarm when the EMS SoC floor stops the guard shaving. + +⚠️ FAILING TO SHAVE MUST NOT BE SILENT, AND THAT IS THE WHOLE POINT. +The guard exists for one euro figure - the capaciteitstarief bills the +month's single worst quarter - so a cycle in which it CHOSE not to shave +is a cycle in which money is being spent on purpose. Under-shaving +quietly would leave the operator with a bill and a status page full of +green. + +The distinction from check_peak_saturated() is the operator's action, +which is why these are two notifications and not one: + +saturated the guard asked for everything the inverter has and it +was not enough. SHED LOAD - the controller has already +done all it can, and it is still discharging. +floor-limited the guard asked for NOTHING, because the pack is at or +under the EMS floor, or its SoC could not be read. +Nothing is being discharged for this quarter at all. +(SAFETY-87, N>=2: or the batteries above their +reserve give all they can and it is not enough.) + +They cannot both be true: peakguard.decide()'s floor-limited branch +returns before the `achievable_w` clamp that sets `saturated`. + +⚠️ SAFETY-25 - AND THE MESSAGE SAYS WHAT THE FLOOR IS NOT. Read on its +own, "the capacity-peak guard has run out of battery" invites exactly +one wrong inference: that the pack is now being held at +`peak_soc_floor`. It is not. `peak_soc_floor` bounds THIS GUARD only; +the grid-following loop has no SoC floor at all and, on the committed +2026-08-20 replay, is being granted discharge in EVERY cycle that raises +this notification. An operator who reads the alarm and relaxes because +"the EMS has a 20 % reserve" has been misled by us, so the alarm carries +the correction itself rather than leaving it to DOCS.md. + +Edge-triggered, and de-asserting arms it again - FreezeWatchdog's shape, +for FreezeWatchdog's reason: one notification per episode, not one per +cycle for a quarter of an hour. + + +### L6304 No prefix: `reason` already opens with PEAK_GUARD_FLOOR_LIMITED, and + +No prefix: `reason` already opens with PEAK_GUARD_FLOOR_LIMITED, and +a second copy is the kind of stutter that makes a 40-line action log +read like boilerplate. The saturated path needs its prefix because its +reason carries the word in the middle of a sentence, not at the front. + +### L6313 A fixed notification_id, and a DIFFERENT one from every other alarm + +A fixed notification_id, and a DIFFERENT one from every other alarm +here - check_meter_frozen() gives the reasoning. A battery at its +energy floor is not a saturated inverter and is not a frozen meter, +and an operator who has to dismiss three identical-looking cards +learns to dismiss the one that mattered. +⚠️ SAFETY-25's sentence must render on the unreadable-SoC branch too, +where `soc_floor` is a number but naming it would invite the reader to +think the pack is AT it. `decide()` guards its own reason string the +same way; a f-string that formats a None here would turn the one +notification that matters into a traceback. +SAFETY-32/87: which battery is at its reserve, each graded on its own +floor (`g.held`). At a roster of one no battery is named. +⚠️ SAFETY-25's sentence (the reserve binds the peak guard only) is +part of messages.peak_reserve() on every branch, the unreadable-SoC +one included. + +### L6360 SAFETY-31 + SAFETY-34. The alarm, and it must survive a restart. + +SAFETY-31 + SAFETY-34. The alarm, and it must survive a restart. + +⚠️ THE LATCH IS NOT THE ALARM. `circ_tripped` in `/data/state.json` +survives everything, but nothing looks at a JSON file at 3 a.m. What the +operator sees is a `persistent_notification`, and THAT IS IN MEMORY: a +Home Assistant restart deletes it while the fault runs on. This is not a +hypothetical - it is precisely how the 2026-09-02 outage went unseen for +6 h 25 m with the detector correct the whole time (SAFETY-34). + +So the durable half and the visible half are joined HERE, and the join +is `_circ_announced`: a per-PROCESS flag, deliberately not persisted. +The latch says "this site is tripped"; the flag says "this process has +put that in front of a human". A restart clears the flag and keeps the +latch, so the notification is RE-RAISED on the first cycle after every +add-on start. A Core-only restart does NOT restart the add-on, so it is +also re-asserted every REANNOUNCE_S (SAFETY-34). + +⚠️ ONE CODE PATH FOR BOTH, ON PURPOSE. A fresh trip and a restart into +an existing trip raise the alarm through these same lines. Two paths +would be two chances for the restart one to rot unnoticed, and the +restart one is the case nobody exercises by hand. + + +### L6386 Set BEFORE the await. `hass.call()` can raise or hang, and a retry + +Set BEFORE the await. `hass.call()` can raise or hang, and a retry +every cycle for a broker that is down would be an alarm storm on the +event bus on top of a site that is already stopped. The latch is +already durable and the log line above already fired; this surface is +best-effort by design. + +### L6410 SAFETY-42 + SAFETY-34. The alarm, and it must survive a restart. + +SAFETY-42 + SAFETY-34. The alarm, and it must survive a restart. + +⚠️ THE LATCH IS NOT THE ALARM, and this guard has nothing BUT the alarm. +`unit//delivery_tripped` in `/data/state.json` survives everything, +but nothing looks at a JSON file at 3 a.m. What the operator sees is a +`persistent_notification`, and THAT IS IN MEMORY: a Home Assistant +restart deletes it while the fault runs on. That is precisely how the +2026-09-02 outage went unseen for 6 h 25 m with the detector correct the +whole time (SAFETY-34), and it matters more here than anywhere else in +this file, because SAFETY-02 and SAFETY-31 at least leave a stopped site +for somebody to notice. This one leaves a site that looks like it is +working and is quietly delivering one unit less than it has. + +So the durable half and the visible half are joined HERE, and the join +is `_delivery_announced`: a per-PROCESS set of unit names, deliberately +not persisted. The latch says "this unit is tripped"; membership says +"this process has put that in front of a human". A restart empties the +set and keeps the latch, so the notification is RE-RAISED on the first +cycle after every add-on start, and re-asserted every REANNOUNCE_S +because a Core-only restart does not restart the add-on (SAFETY-34). + +⚠️ ONE CODE PATH FOR BOTH, ON PURPOSE - `check_circulating()`'s +argument. A fresh trip and a restart into an existing trip raise the +alarm through these same lines; two paths would be two chances for the +restart one to rot unnoticed, and the restart one is the case nobody +exercises by hand. + +⚠️ AND ONE NOTIFICATION ID PER UNIT. Every other alarm in this file has +a single fixed id because its subject is the site; this one's subject is +a named box, and two wedged inverters must produce two cards rather than +one replacing the other. The id is built from the same `unit_slugs()` +TEL-07 announces the MQTT entities under, so the card and the entity an +operator correlates it with carry the same token. + + +### L6452 Added BEFORE the await, for `check_circulating()`'s reason: + +Added BEFORE the await, for `check_circulating()`'s reason: +`hass.call()` can raise or hang, and a retry every cycle for a +broker that is down would be an alarm storm on the event bus. The +latch is already durable and the log line already fired; this +surface is best-effort by design. + +### L6463 PRICE-01. One notification when no price covers now, gone when one doe + +PRICE-01. One notification when no price covers now, gone when one does. + +`price_gap` is worked out on the tick from the stored plan. A gap +raises the notification once: the flag is set BEFORE the await, for +`check_circulating()`'s reason (a Home Assistant call can raise or +hang, and a retry every cycle would be a storm). When the gap ends the +same notification is taken down. Control is not touched either way: the +maintenance charge waits because its gate is shut (`_provider_gate`), +and nothing here decides that. + + +### L6483 PRICE-01 G1. At the first cycle only: one INFO line when a + +PRICE-01 G1. At the first cycle only: one INFO line when a +`static_profile` is set beside `price_service` (it is the plan's last +fallback, not a fault, so no notification), and a dismiss of the card an +earlier build raised, which is harmless when absent. + +### L6507 SAFETY-18. Alarm on a meter that answers forever without changing. + +SAFETY-18. Alarm on a meter that answers forever without changing. + +Notification only - no claim, no latch, no 0 W. freeze.py carries the +reasoning and the euro figure; DOCS.md carries the exposure this does +NOT close. + +⚠️ getattr, not an attribute access: `unchanged_s` exists only on +`homewizard_local`, and `p1_source` is None until amain() builds the +transport. Every other meter_source hands the predicate None and gets +False, which is the honest answer - see the transport note in freeze.py. + + +### L6551 The stored plan if it is still current, else None. NEVER a stale one. + +The stored plan if it is still current, else None. NEVER a stale one. + +⚠️ THIS IS THE ONE PLACE THE AGE IS JUDGED, and it is public for +`loop_is_following()`'s reason: a check has to be able to assert on the +shipped expression rather than on a transcription that drifts. Both +terms are required - a plan with no timestamp is one nothing stored, and +a timestamped plan older than TARIFF_MAX_AGE_S is a reading from a task +that has stopped answering. + + +### L6567 Resolve the tariff off the control path, forever. NEVER on the tick. + +Resolve the tariff off the control path, forever. NEVER on the tick. + +⚠️ IT CATCHES EVERYTHING AND KEEPS GOING, for MqttPublisher's reason: +a supplier's outage, a certificate expiry, a malformed feed - all of it +is pricing, and the battery does not care. What it must never do is +raise out of here and take the task down, because then the plan freezes +at its last value and looks current forever. That is what +`fresh_tariff_plan()`'s age bound is the backstop for, and this is the +half that keeps the task alive. ⚠️ THE BOUND IS NO LONGER A BACKSTOP +ONLY: since TARIFF-12 it is also the serve-stale window an outage runs +on, and it is consulted below on every refresh. + +⚠️ AND A FAILURE DOES NOT CLEAR THE PLAN - WHICH IS A CLAIM ABOUT WHAT +`resolve_tariff()` RETURNS, NOT ABOUT WHAT IT RAISES (TARIFF-12). This +paragraph was enforced by the `except` below alone, and the `except` +below is the one path a supplier outage never takes. `load_prices()` +says so in its own words - it "RETURNS, NEVER RAISES, for every failure +a site can actually have" - because a degradation arriving as a +traceback into the planning tick would stop the controller regulating +over an expired certificate. So a dead feed is a RETURN: the `try` +succeeds, `_degrade()` hands back a §11.4 plan, and the assignment used +to overwrite the good one unconditionally. Measured in a 40 h soak with +`static_profile` unset (the shipped default, and the normal state of a +dynamic-tariff site): the FIRST failed fetch replaced a complete 48 h +plan with `TariffPlan(no_data, None, "none")` - 0 points - 27 minutes +after the last good one, and `TARIFF_MAX_AGE_S` governed nothing. A +transient blip cost the same as a 90-minute outage. + +⚠️ SO THE QUESTION IS ASKED ONCE, AFTER THE ATTEMPT, FROM THE EVIDENCE +THAT EXISTS - FCST-06's answer, in this file. The evidence is +`plan.from_feed` (did this attempt observe the feed) and +`fresh_tariff_plan(now)` (is an observation still current). A +degradation replaces a standing observation only once that observation +has aged out, so `TARIFF_MAX_AGE_S` is now the serve-stale window it +reads like rather than a bound nothing could reach. + +⚠️ AND A §11.4 STATIC FALLBACK DOES NOT REPLACE A FRESH PROVIDER PLAN +EITHER, although it carries real prices. Every point `_degrade()` +builds is `provisional=True`, so `firm_points()` is empty, +`arbitrage()` refuses and `cheap_now()` is False - everything a +consumer may act on is already off. A day-ahead price for a given hour +does not change once published, so a plan fetched half an hour ago is +exactly as true about that hour as one fetched now. The fallback is +less actionable and no more current; it takes over when the observation +retires, which is what §11.4 is for. The reverse is not symmetrical: a +standing plan that is ITSELF a degradation is replaced by a fresh one, +or an outage would freeze the operator's static profile at the window +it was generated for. + +⚠️ AND NOTHING HERE READS `arbitrage_enabled`, WHICH TARIFF-10 MAKES +WORTH SAYING. Since that card this task also runs on a site with a +provider configured and trading DISARMED, so "keep the plan" is a +decision about what the add-on has LOOKED UP, not about what it may +trade on. It is also strictly downstream of `resolve_tariff()`: the +§8.3 carry into `price_history` happens on the `series` branch inside +that call, before this decision exists, so which of two plans is kept +cannot add or lose a recorded day. + +⚠️ AND `tariff_at` DOES NOT MOVE ON A KEPT PLAN. It is the moment the +fetch that produced the standing plan happened, and +`fresh_tariff_plan()` judges the age from it - re-stamping it here +would be this task asserting the feed answered when it did not, and the +plan would "freeze at its last value and look current forever", which +is the hazard the paragraph above this one names. An unmoved +`tariff_at` is also the only thing that tells a kept plan from a +freshly fetched one, so it is what the check asserts. + + +### L6658 ⚠️ NOT THE OUTAGE PATH - see the docstring. `load_prices()` + +⚠️ NOT THE OUTAGE PATH - see the docstring. `load_prices()` +returns on every failure a site can have, so what reaches +here is something nobody expected, and the plan is kept for +the same reason and on the same terms. + +### L6672 ⚠️ EACH INVERTER'S RATING FROM ITS OWN ENTITY, WHICH IS AC 4. There + +⚠️ EACH INVERTER'S RATING FROM ITS OWN ENTITY, WHICH IS AC 4. There +was one read of one `setpoint_entity` here, so a second inverter's +rating was never read at all and its clamp, its freeze rail and the +peak guard's `achievable_w` were all the first one's numbers. +Concurrently, for `read_inputs()`'s reason: a slow ESPHome on one unit +must not delay the controller's start on every other. + +### L6684 ⚠️ THIS USED TO WARN AND CARRY ON, and that was the bug CFG-01 + +⚠️ THIS USED TO WARN AND CARRY ON, and that was the bug CFG-01 +exists to remove: a max_w above the device's rating meant +write_setpoint() silently clamped and the configured ceiling was +never the real one. + +amain() already ran this gate before anything started. It runs +AGAIN here for one case the gate cannot cover: ESPHome is often +not up yet when the add-on boots, so hass.limits() returned +(None, None) and the range checks were skipped rather than +guessed at. This is the first moment the device's real rating is +known. If it conflicts, refuse now - stopping deterministically +through the normal shutdown, which commands 0 W on the way out. + +⚠️⚠️ AND THE `if entity:` THAT USED TO WRAP THE WHOLE BLOCK WAS A +READER THAT FAILED PERMISSIVE - CFG-04's own hazard, in this file. +`entity` is the FLAT `setpoint_entity`, which a per-inverter config +leaves blank (validate rule 9(e) requires it), so on the very config +this add-on now supports the entire re-check was SKIPPED: no +inverter's `max_w` was ever graded against the device it is written +to, and the skip was silent. The flat gate still guards the flat +rules, because they read flat options and one device's range; the +per-unit rule runs unconditionally, off the roster, and grades each +unit against ITS OWN ESPHome. At one inverter `validate_unit_ranges()` +skips the unit the flat call already graded, so nothing is reported +twice and the N=1 path is unchanged. + +### L6729 ⚠️ SAFETY-12. The floor is a DEADLINE ON THE GAP BETWEEN CYCLES, not a + +⚠️ SAFETY-12. The floor is a DEADLINE ON THE GAP BETWEEN CYCLES, not a +second scheduler running alongside the arrival trigger. Every cycle +resets it, whichever trigger fired, so on a healthy changing meter it +never elapses and not one existing cycle moves - and therefore no +change to the per-cycle gain the tuning was measured against. + +That is true twice over, and the second reason is the sturdier one: +the combined cycle rate is max(arrival rate, 1/floor), never the sum. +At the defaults 1/15 s is strictly slower than the ~1/5 s arrival +rate, so even a floor that raced the arrivals could not push the loop +past its nominal healthy rate. The re-tune is unreachable by +construction, not merely by the reset. ⚠️ That argument holds only +while floor > the meter's update interval - which is why the schema +minimum of 5 s deserves the second look validate.py has not given it +yet: 5 s IS the reference meter's interval, i.e. the one configurable +value that would double the cycle rate. + +Why it has to exist, and it is not only about latency: `self.grid != +last_grid` alone means a meter that repeats a value runs NO control +cycles at all. The heartbeat below keeps re-emitting the last command +and the firmware keeps putting it on the wire, so every indicator +reads healthy - and, worse, the `inputs missing -> 0 W` claim lives +INSIDE cycle(), so on a repeating meter THAT SAFETY CLAIM CANNOT FIRE. +Demonstrated in test_loop.py: constant meter, SoC entity dies at t=4 s, +and the pre-fix controller holds 220 W through the whole outage with +the status line still reading "loop -> 220 W". Layer 1 does not cover +it on a `meter_source: off` install either - no P1 age sensor is +published, so the firmware has nothing to veto on. Measured on the rig +during TEL-05: 70 s at a literally constant 350.0 W, 14 arrivals, zero +cycles. + +This is NOT a freeze detector, and deliberately so - see +HomeWizardLocalSource.unchanged_s for why one cannot be built here (at +the converged -10 W target a 1 Wh register needs ~6 minutes to move, +so any freeze threshold false-trips at the exact operating point we +run at). Nothing here decides whether a repeated reading is true. It +only stops "the number is the same" from meaning "do not think". + +⚠️ THE 15 s DEFAULT HAS A CEILING IT DOES NOT OWN. It is under +validate.FIRMWARE_INGEST_VETO_S (30 s) and under meter_max_age_s on +purpose, so the loop re-decides at least twice inside any window in +which layer 1 might otherwise be the only thing deciding. If the +firmware's veto ever moves, this default moves with it - it is not +independently justified at 15. + +### L6784 ⚠️ The FULL cycle, not a degraded one. A floor cycle runs the + +⚠️ The FULL cycle, not a degraded one. A floor cycle runs the +same law on the same inputs as an arrival cycle, because in P1 +mode the freshness question is already answered upstream and +answered harder: past `meter_max_age_s` (30 s) p1.net_w is +None, which is "inputs missing", which becomes a P_SAFETY 0 W +claim. So a floor cycle cannot run the PI on a 60 s old +figure, because at 60 s there is no figure. + +⚠️ THAT GUARANTEE IS TRANSPORT-CONDITIONAL, and saying so +matters more than the guarantee: with `meter_source: off`, +read_inputs() takes self.grid straight from hass.number() with +NO age gate at all, so a Home Assistant entity that has gone +quiet reads as a current value on that path with or without +this change. Running the full law is still the right choice +there - the alternative is a degraded second law reasoning +about an age nobody measured - but the floor does not make +that path fresh, and nothing here should be read as claiming +it does. And the integrator +advances per CYCLE, not per second (control.py), so bounding +the gap bounds the accumulation: at most one extra +gain x error per floor interval, under the same +integrator_max_w as every other cycle. A second, gentler +control law for floor cycles would be a second set of +dynamics nobody can test on this hardware. + +### L6809 ⚠️ The heartbeat is not an optimisation. The ESP32 treats silence + +⚠️ The heartbeat is not an optimisation. The ESP32 treats silence +longer than ~30 s as "the controller is gone" and zeroes the +inverter. Refreshing the SAME value is what proves we are alive. + +⚠️ ONE DEADLINE PER INVERTER, AND THE REFRESHES GO OUT TOGETHER. +This was ONE `last_beat` and ONE serialised write, so a hung +`hass.call()` to inverter A consumed inverter B's ~30 s layer-1 +budget and the firmware zeroed a healthy sibling. Now each unit +owns its own deadline, each write is dispatched CONCURRENTLY and +each is bounded by WRITE_BUDGET_S - so the worst a hung A can do +to B is delay B's NEXT beat by the budget, which is why the budget +plus the schema's largest `heartbeat_s` has to stay under layer +1's veto. That inequality is graded, not asserted. + +⚠️ AND EACH UNIT REFRESHES ITS OWN SHARE, `inv.target`, never the +site target. A heartbeat that re-emitted the site number would be +the broadcast fault arriving through the back door, once every +`heartbeat_s`, on a path with no allocator in it. + +### L6834 Refresh every inverter whose own deadline has come. AC 6 lives here. + +Refresh every inverter whose own deadline has come. AC 6 lives here. + +⚠️ IT IS A METHOD RATHER THAN FIVE LINES INSIDE `run_control()` FOR ONE +REASON: the acceptance criterion is "a hung write to A cannot consume +B's layer-1 budget - verified by injecting the hang", and a check cannot +inject a hang into the middle of a `while not self.stopping` loop that +also sleeps, reads inputs and cycles. Inline, the only thing a test +could grade was its OWN gather of `write_setpoint()` calls - which is a +check on the fixture, and a serialised shipped loop survived it. +Measured: the mutation that replaced the concurrent dispatch with a +`for` loop passed the whole suite while this block was inline. + +`loop_now` is the caller's monotonic clock, the same discipline every +watchdog in this add-on takes its clock by. + + +### L6853 ⚠️ THE DEADLINE MOVES BEFORE THE WRITE, NOT AFTER IT. Moved after, a + +⚠️ THE DEADLINE MOVES BEFORE THE WRITE, NOT AFTER IT. Moved after, a +unit whose write hangs would have its deadline advanced late every +time and would drift into being re-sent on every tick; and a unit +whose write RAISED would never have it advanced at all. + +### L6859 ⚠️ CONCURRENTLY. In series, every inverter behind a hung one waits out + +⚠️ CONCURRENTLY. In series, every inverter behind a hung one waits out +that one's whole budget before its refresh is even attempted - and +before this card, with no budget at all, it waited out the HTTP +stack's timeout. That is one inverter's transport fault pushing a +healthy sibling towards layer 1's ~30 s veto. + +### L6869 ⚠️ SITE TOTALS, AND THE KEYS DO NOT MOVE. These entities are already + +⚠️ SITE TOTALS, AND THE KEYS DO NOT MOVE. These entities are already +discovered and already on every dashboard (TEL-07 keeps their +`unique_id`s), so `battery` stays the number the meter sees the +battery doing - the SUM - and `soc` stays the one a floor is graded +against - the EMPTIEST pack. At the shipped roster of one both are +inverter A's own readings, unchanged. Per-inverter entities are +TEL-07's, not a key rename here. + +### L6882 ⚠️ SAFETY-02's alarm surface, and it is deliberately an existing + +⚠️ SAFETY-02's alarm surface, and it is deliberately an existing +one. IF-01/IF-02 own `ems/event/failsafe` and the `failsafe active` +binary sensor and neither is built yet; inventing a bespoke topic +here would be a surface to migrate later. This sensor is already +discovered, already on every dashboard, and "failsafe" is +additive to its vocabulary rather than a change to it. +SAFETY-30 adds the site sign latch to the same vocabulary, for +the reason the note above gives: "failsafe" is additive to a +sensor that already exists and is already on every dashboard, and +a P_SAFETY stop that did not reach it would be a site at 0 W +reporting "running". + +### L6898 SAFETY-10: "shadow" is its own value and not a + +SAFETY-10: "shadow" is its own value and not a +flavour of "stopped". A fleet dashboard reporting a +shadow install as `running` would be calling a +battery nobody is controlling healthy; one reporting +it as `stopped` would lose the fact that the decision +path is live and being recorded. ⚠️ BELOW `failsafe`: +a latch that is up is up, and shadow does not clear it. + +### L6907 SAFETY-31. ⚠️ MEASURED, not the allocation record - see + +SAFETY-31. ⚠️ MEASURED, not the allocation record - see +`site_circulating_w`. `publish()` drops None values, so a cycle +with a missing per-unit reading leaves the last figure standing +rather than publishing a zero that would read as health. + +### L6913 TEL-10. The loop's own three, written from the fields `cycle()` + +TEL-10. The loop's own three, written from the fields `cycle()` +recorded and not re-derived here - the page and the publisher run +on their own tasks and `self.target` has moved on by the time +either of them looks (SAFETY-47's note on `sized_from_meter`, one +field up, is the same hazard). + +### L6922 TEL-11 + +TEL-11 +⚠️ THE KEY IS PRESENT WITH THE VALUE `None` WHEN THERE IS NO READING, +AND ABSENT ENTIRELY WHEN THERE IS NO SOURCE. Those are two different +states and the publisher treats them as two: `mqtt.ABSENT_AS_UNKNOWN` +turns the first into HA's own `None` payload, so the entity's state +goes to `unknown` and the recorder records a GAP - which is how a +reader of a week of history tells "no PV reported" from "PV reported +0 W". The second never reaches the broker at all, because an install +that never set `pv_entity` or `pv_entities` has no such entity +announced. ⚠️ TEL-12: AND THE ROW IS STILL ONE NUMBER. At a roster of +three it is the SITE total, `None` unless EVERY entity answered - see +`pv.total()`, whose note is where the decision not to publish a +partial sum is argued. This line did not have to change for that, and +that is the point: TEL-11's `None`-is-an-absence rule already covered +it, one layer up. + +⚠️ AND THE GATE IS `optional_keys()`, THE SAME EXPRESSION THE +ANNOUNCEMENT USES. Written as a second predicate here the two could +disagree, and both directions are bad - an announced entity nothing +feeds, or a topic nothing declared. `announced_units()` two blocks +down is the same discipline for the roster. + +### L6946 ⚠️ ONLY when P1 ingestion is actually running. The ESP32's stale-input + +⚠️ ONLY when P1 ingestion is actually running. The ESP32's stale-input +watchdog subscribes to sensor.goodwe_p1_sample_age - see the entity-id +note in mqtt.py; the composed name is not the object_id - and forces layer-1 +failsafe once it reaches max_age_s. With meter_source off there is no +ingester feeding it, so published_age_s would be time-since-startup +climbing without bound - i.e. every existing install would cross the +threshold within 30 s and pin its inverter at 0 W forever. Publishing +nothing leaves the entity non-existent, which is the status quo and +what has_state() in the firmware is checking for. + +### L6958 TEL-07. THE PER-UNIT ROWS, AND THE EMPTY LIST IS THE GATE. + +TEL-07. THE PER-UNIT ROWS, AND THE EMPTY LIST IS THE GATE. + +⚠️ THERE IS NO `if len(self.inverters) > 1` HERE, DELIBERATELY. +`announced_units()` answers `[]` at a roster of one, `zip` then yields +nothing, and the values dict comes out byte-identical to what shipped - +so the condition that decides what is ANNOUNCED is the same expression +that decides what is PUBLISHED. Written as a second predicate, the two +could disagree, and both directions are bad: an announced entity +nothing feeds (the hazard `omit` exists for) or, at N=1, a published +topic nothing announced, which AC 4 forbids outright. + +⚠️ AND THE SITE ROWS ABOVE DO NOT MOVE. `battery` stays the SUM and +`soc` stays the EMPTIEST pack; these are additions beside them, not a +re-pointing of them, because those two ids are on the live install's +dashboards and in its automations. + +### L6992 Every inverter to 0 W, and every inverter's TARGET to 0 W with it. + +Every inverter to 0 W, and every inverter's TARGET to 0 W with it. + +⚠️ THE SECOND HALF IS NOT BOOKKEEPING, AND IT IS A HAZARD DEV-02 +CREATED. Before this card the heartbeat re-emitted `self.target`, so +zeroing that one scalar was enough: the stop button set it and the next +refresh carried the zero. The heartbeat now re-emits `inv.target` - it +has to, or it would broadcast the site number - so a stop that zeroed +only `self.target` would leave each unit's LAST SHARE standing, and the +very next heartbeat (up to `heartbeat_s` later, and before any cycle has +run) would put it back on the wire. The operator would have pressed +stop, watched the inverter go to zero, and seen it resume seconds later. +Both must move together, which is why this is one method with a reason +and not two lines repeated at three call sites. + +⚠️ AND 0 W IS THE ONE VALUE THAT MAY BE WRITTEN SITE-WIDE. It means the +same thing to every inverter; a non-zero site-wide write is the ARCH-01 +broadcast fault, and `write_setpoint()` refuses it. + + +### L7017 The status rows. `when` is the reference time for anything billed by + +The status rows. `when` is the reference time for anything billed by +the calendar - today's month when it is None, which is what the live +page means; `status_payload()` calls this with no argument. + +⚠️ IT EXISTS SO THE PEAK ROW CAN BE GRADED (TEST-17). Every other peak +query already takes it - `PeakStore.peak()`, `PeakTracker.peak()`, +`headroom_w()`, `warning_frac()` - and the row built from them was the +one thing that could only be read against `datetime.now()`. A suite +that banks an August quarter then asks this page what the peak is goes +green in August and red in September, which is what happened at 00:00 +on 2026-09-01: TARIFF-01's own section 10, red on a calendar boundary, +on a commit nobody had touched for a day. + + +### L7058 UX-10: no reading yet since the start, still inside the + +UX-10: no reading yet since the start, still inside the +limit. Amber, not red: it is not a fault yet, but control +waits for it. Red at 0 s contradicted the limit the row +prints. Past the limit it is the red row below, as before. + +### L7071 ⚠️ unchanged_s is REPORTED, never thresholded and never folded + +⚠️ unchanged_s is REPORTED, never thresholded and never folded +into the age - see HomeWizardLocalSource.unchanged_s for why +(at the converged -10 W this controller aims for, a 1 Wh +register needs ~6 minutes to move, so any limit false-trips at +the exact operating point we target). The whole argument for +leaving it unthresholded is that a human interprets it, which +requires a human being able to see it - so here it is. getattr: +only homewizard_local has one, and p1_source is None until +amain() builds the transport. + +### L7085 SAFETY-18. Reported in both states, for the reason SAFETY-02 is: + +SAFETY-18. Reported in both states, for the reason SAFETY-02 is: +a detector nobody can see is armed is a detector nobody trusts +when it fires. ok=False/warn=False so the banner goes red - this +is an alarm, and the banner is the loudest surface we own. It +changes NOTHING about control; see check_meter_frozen(). + +### L7104 SAFETY-20, and THE SECOND REASON TO USE THIS ROW RATHER THAN A + +SAFETY-20, and THE SECOND REASON TO USE THIS ROW RATHER THAN A +NEW MECHANISM. The transport case above and this one are the +same statement - "the conjunction cannot be evaluated here" - +and an operator does not need to learn two vocabularies for +it. What differs is only which term is missing: there, +`unchanged_s`; here, a rail the command could ever stand at. + +### L7116 ⚠️ SAFETY-20. THE RAIL PRINTED HERE IS THE RAIL THE PREDICATE + +⚠️ SAFETY-20. THE RAIL PRINTED HERE IS THE RAIL THE PREDICATE +USES, device range included. This row used to interpolate +`rail_w(max_w)` while `looks_frozen()` graded a command the +device had already clipped below it, so on any install whose +inverter is smaller than its configured ceiling the page named +a number the command could never reach and called it `armed`. +Both the row and the predicate now read the same three inputs. + +### L7126 And when the device is what set that number, SAY SO - the + +And when the device is what set that number, SAY SO - the +operator configured `max_w` and is owed the reason the guard +is armed somewhere else. +⚠️ Either bound may be None on its own - `hass.limits()` +reads `min` and `max` independently and returns None for +whichever attribute is missing or unparseable - so this +renders whatever is there rather than formatting a None. +UX-08: "the inverter's own limit" says the device set it; which +inverter and its range are DOCS and the settings, not entity ids. + +### L7140 TARIFF-01. The month's billed peak, and - the load-bearing half - + +TARIFF-01. The month's billed peak, and - the load-bearing half - +a DIFFERENT row when the store could not answer. "no peak yet" is +a normal state on the 1st; "unreadable" is a broken instrument, and +a status page that spelled them the same way would let a 0 W read +look like a quiet month right up until SAFETY-07 shaved nothing. +UX-08: in plain words. The store's state at start is on the INFO +line `capacity-tariff peak store: ...` and `_pk.explain()` on the +log; the coverage figure (TARIFF-13) is a row of its own. + +### L7168 SAFETY-07. Three rows, not one, because "idle" and "cannot see" + +SAFETY-07. Three rows, not one, because "idle" and "cannot see" +are opposite states and a page that spelled them the same way +would show a green line over a guard that is switched off. `None` +is a fourth state on purpose: before the first cycle the guard has +concluded nothing, and saying "idle" then would be a claim about a +decision that has not been taken. + +### L7185 SAFETY-24. NOT ok, like saturation: in both states the money + +SAFETY-24. NOT ok, like saturation: in both states the money +is going to be spent and a human is the only actuator left. A +separate row from saturation because the two ask for opposite +things - see check_peak_floor_limited(). + +⚠️ SAFETY-25. THE SCOPE SENTENCE IS PART OF THE ROW, NOT A +DOCS FOOTNOTE. This is the one line an operator reads at the +exact moment the guard stops discharging, and read alone it +says "the battery is being held at peak_soc_floor" - which is +false, and measurably so: on the committed evening replay the +loop goes on discharging in EVERY cycle this row is showing. +A floor that binds one consumer and not the other is worse +than no floor if the page does not say which. + +⚠️ AND IT CARRIES ITS OWN `banner`. status_payload() renders +the FIRST not-ok/not-warn row as the page's headline, so +without this the loudest element on the page would be a +550-character paragraph that the row three lines below +repeats verbatim. The banner is the short form; the row keeps +the whole sentence, because the row is where an operator +reads what the floor does and does not bound. Shortening the +ROW instead would be weakening AC 3. +UX-08: the same three branches, and the same pack naming, as +check_peak_floor_limited()'s notification. The figures stay in +`_pg.reason`, on the log and the event list. +SAFETY-87: `runs`, control goes on (status_payload()). + +### L7248 ⚠️ OUTSIDE the `p1_enabled` block, and that placement is the point. + +⚠️ OUTSIDE the `p1_enabled` block, and that placement is the point. +SAFETY-07 is NOT COVERED on the legacy single-entity path - the +quarter-hour average is measured from P1 telegrams and this path +has none - and a row that only rendered where the guard runs would +leave the one install that is unprotected showing nothing at all. +Same answer, same reason, as the freeze detector's NOT COVERED row +a few lines up. + +### L7258 ⚠️ ONE PAIR OF ROWS PER INVERTER, NAMED. A single "battery SoC" row on + +⚠️ ONE PAIR OF ROWS PER INVERTER, NAMED. A single "battery SoC" row on +a site with two packs is a page that shows one pack and calls it the +site. The label keeps its exact wording at a roster of one, because +that is what an existing install reads. + +### L7280 ⚠️ SAFETY-56. THIS ROW ASSERTED A FALSE FACT ABOUT A NAMED + +⚠️ SAFETY-56. THIS ROW ASSERTED A FALSE FACT ABOUT A NAMED +ENTITY, WHICH IS THE WORST THING A DIAGNOSTIC CAN DO. It read +" is missing or not numeric" for ANY None, and one of +the ways this value becomes None is SAFETY-37's freshness gate +withholding a reading that is present, numeric and updating - +`Freshness.reading()` returns None BY DESIGN there. On the +live site on 2026-09-21 the operator opened Developer Tools on +the entity this row named, found it working, and had every +reason to conclude the diagnostics were broken. + +⚠️ AND IT IS FIXED BY SAYING LESS, NOT BY LOOKING HARDER. The +row could ask `inv.batt_fresh.stale` - it is on the same +object at the same moment - but this loop also renders the +grid and SoC rows, which have no gate, and a branch per row +would be a second place where "why is this None" is decided. +The gate already has a surface of its own: `stale_note()` +rides `liveness_notes()` a few rows below with the whole +STALE_READING sentence in it, so the operator's discriminator +is "is that row there?" and this row's job is only to stop +pre-empting the answer. Same reason the wording is not shared +with `freshness._grade()`: that one is a log line about a +BEHAVIOUR, this one is a banner about an ENTITY. + +### L7322 DEV-02. Whether this controller can still put a number on each + +DEV-02. Whether this controller can still put a number on each +inverter, and it is reported in the ONE state that matters: a unit +`live_units()` has stopped listing has had its share handed to its +siblings, or - at a roster of one - has taken the site to 0 W. A +dropped link that shows nothing on the page reads as a healthy site. +Red only for a unit that is no longer live; the rest are amber. +The same notes, in the same order, as `liveness_notes()`. + +### L7337 SAFETY-03. Red while an over-rating clamp is engaged (amber for the + +SAFETY-03. Red while an over-rating clamp is engaged (amber for the +integrator bound, SAFETY-40), and the engagement COUNT is shown even +after it clears - a row that vanishes with the condition takes the +evidence with it. Reported only when there is something to report: +unlike the freeze detector this guard has no "not covered" state, it +runs on every write on every transport. +UX-07 item 1 / UX-08: each count is shown under ITS alarm's name - +over-rating cuts as "Power request too high", integrator-bound cycles +as "Battery is not keeping up" - never the two summed under one. + +### L7380 SAFETY-02. Reported in both states: a watchdog nobody can see is armed + +SAFETY-02. Reported in both states: a watchdog nobody can see is armed +is a watchdog nobody trusts when it fires. +⚠️ ONE ROW PER INVERTER, because there is one watchdog per inverter +and a trip on B leaves A commanding. A single row would have to pick +one of them to describe, and the honest answer at a roster of two is +both. At a roster of one the wording is unchanged. +⚠️ AND SINCE SAFETY-30 THE ROW SAYS WHAT THE UNIT WAS COMPARED +AGAINST, because at a roster of two that is no longer the meter and a +row that still said "the command opposed the meter" would send an +operator to look at P1 for a fault that is visible only on one +inverter's own power sensor. `sign_wd.against` is the same string the +trip sentence uses, so the two cannot drift apart. + +### L7394 ⚠️ ADDED ONLY WHEN THERE IS SOMETHING TO DISAMBIGUATE. At the + +⚠️ ADDED ONLY WHEN THERE IS SOMETHING TO DISAMBIGUATE. At the +shipped roster of one the two sentences below are the ones that +have always been on the page, word for word - AC 8 is about what +an operator sees as much as about what the detector computes, and +"opposed a meter reading" would be a gratuitous change to a line +somebody has learned to recognise. At N>=2 the noun is load- +bearing: the row would otherwise send them to look at P1 for a +fault that is visible only on one inverter's own power sensor. +UX-08: at N>=2 `unit` is set, and the row says "its own power". +The figures stay in `sign_wd.reason`, on the log and event list. + +### L7413 SAFETY-30: the SITE row + +SAFETY-30: the SITE row +⚠️ ONLY AT N>=2, and the absence at N=1 is the honest report rather +than a missing row. With one inverter the site comparison and the row +above are the same sentence about the same actuator; printing it twice +would advertise two guards where there is one, which is how an +operator learns to skim the list. + +### L7429 SAFETY-31 + +SAFETY-31 +⚠️ SITE-LEVEL, WHERE THE ROWS ABOVE ARE PER-INVERTER, and the row says +so. There is one circulating figure for the site; naming an inverter +here would invite the operator to clear "the other one". + +### L7450 SAFETY-42 + +SAFETY-42 +⚠️ PER INVERTER, AND WARN RATHER THAN BAD, WHICH IS THE ONE PLACE THE +"reports, does not act" DECISION IS VISIBLE TO AN OPERATOR. Every +other latched row in this list means the site is at 0 W and a red +cross is the truth. This one means the site is STILL RUNNING and is +quietly short by one unit's share; rendering it as a hard failure +would say the controller had stopped, which it has not. It is not "ok" +either - `ok: False` with `warn: True` is this list's caution, and a +caution is what a fault nobody is acting on actually is. + +### L7471 AC 5, and the same honesty `circulating power: n/a` uses one block + +AC 5, and the same honesty `circulating power: n/a` uses one block +up. At one inverter the reduction this check is has no proper +subset to find, for EVERY input, so "armed" would be a claim to be +watching something that cannot happen. + +### L7505 TEL-11 + +TEL-11 +⚠️ NO ROW AT ALL WHEN THE ROSTER IS EMPTY, AND THAT IS A DELIBERATE +DIFFERENCE FROM THE PEAK-FORECAST CAUTION DIRECTLY ABOVE. That one +nags because an unset forecast entity leaves a MONEY GUARD without an +input; this one is pure instrumentation, and a permanent caution on +every install that never asked for a PV channel is exactly the +"no warning spam, no degraded status row" the card forbids. + +⚠️ AND WHEN IT IS SET, A FAILED READ IS `ok=False, warn=True` - a +CAUTION, never `bad`. `status_payload()` builds "NOT READY" from rows +that are neither ok nor warn, and a telemetry channel that could put a +battery site into NOT READY would be observability with a foot in the +control path. The reason comes from `pv.watts()` rather than being +re-derived here, so the page cannot disagree with the reading. + +TEL-12 kept 0.11.0's single-entity sentences word for word. UX-08 +replaced them on purpose (DECISIONS/UX-08-short-notifications.md), so +a `tools/tel11_pv_trace.py` compare against a pre-UX-08 tree shows +these rows as changed telemetry; the control documents stay equal. + +### L7547 ⚠️ AND WHEN BOTH KEYS ARE SET, WHICH ONE WON IS STATED. `pv.py`'s + +⚠️ AND WHEN BOTH KEYS ARE SET, WHICH ONE WON IS STATED. `pv.py`'s +`entities()` makes `pv_entities` REPLACE `pv_entity`, which is the +rule an operator upgrading from 0.11.0 is most likely to trip +over. A CAUTION and never a `bad` row: telemetry must not stop +control. + +### L7578 SAFETY-10, AND IT IS FIRST IN THE CASCADE + +SAFETY-10, AND IT IS FIRST IN THE CASCADE +"The battery is NOT being controlled" is the one sentence on this +page that may never be displaced by another condition. A banner that +can be out-ranked does not STATE a thing plainly; it states it +whenever nothing else is happening, which is the half of the time +nobody needs telling. + +⚠️ AND IT CARRIES A STANDING LATCH RATHER THAN HIDING ONE. The three +`bad` branches below all say some version of "held at 0 W", which is +still true in shadow mode - but an operator who turns shadow mode off +with a latch up gets a battery that will not move and a page that +never mentioned it. `shadow.banner()` names the latch and goes red +for it, so nothing this cascade would have said is lost. + +### L7596 ⚠️ ABOVE THE SIGN FAILSAFE, and the order is a decision. Both are + +⚠️ ABOVE THE SIGN FAILSAFE, and the order is a decision. Both are +latched P_SAFETY stops, so the site is at 0 W either way and the +banner can only carry one sentence. This one goes first because it +is the fault the operator has NO OTHER WAY of learning about: a +sign disagreement is visible at the meter and on every dashboard +in the house, and circulating power is visible nowhere at all. + +### L7604 SAFETY-30's site half, ABOVE the per-unit rows below and below + +SAFETY-30's site half, ABOVE the per-unit rows below and below +circulating power above, and the ordering is the same argument +both times: the banner carries one sentence, so it carries the one +that says the widest true thing. A site sign trip means EVERY +inverter is parked and the fault is in what the site was asking +for, not in one device - naming a unit here would send an operator +to swap the wrong box. + +### L7613 Outranks "Not ready": nothing is missing, something went wrong. + +Outranks "Not ready": nothing is missing, something went wrong. +At a roster of one the unit was graded against the meter; at N>=2 +against its own power, so the banner says so - see checks() on +why the noun is load-bearing rather than cosmetic. + +### L7620 ⚠️ `banner` IF THE ROW OFFERS ONE, `text` OTHERWISE. A row may + +⚠️ `banner` IF THE ROW OFFERS ONE, `text` OTHERWISE. A row may +need to say more to an operator reading the checks list than fits +in the one line at the top of the page - SAFETY-25's floor-limited +row is the case that forced this - and a headline that is a full +paragraph, repeated verbatim by the row underneath it, is a +headline nobody reads. UX-08: without the key, the banner takes +the row's first sentence, so it stays a headline. + +### L7639 ⚠️ SAFETY-42, AND IT IS A `warn` BANNER RATHER THAN A `bad` ONE, + +⚠️ SAFETY-42, AND IT IS A `warn` BANNER RATHER THAN A `bad` ONE, +WHICH IS THE WHOLE "reports, does not act" DECISION IN ONE LINE. +Every `bad` banner above means the site is at 0 W; this one means +the site is STILL RUNNING and quietly short by one unit's share, +and a red headline would say the controller had stopped. + +⚠️ BUT IT MUST DISPLACE "Running — holding grid at zero", AND THAT +IS NOT COSMETIC. That sentence is a claim the site cannot make +while a unit is absent - the loop is saturated and the meter is +short - and "the page reads healthy while the fault runs" is +precisely the shape this whole card exists to remove. It sits +BELOW "Stopped" because a stopped site is the more urgent fact and +the banner carries one sentence. + +### L7655 ⚠️ THE PACK IS NAMED ONLY WHEN THERE IS MORE THAN ONE. At a roster + +⚠️ THE PACK IS NAMED ONLY WHEN THERE IS MORE THAN ONE. At a roster +of one this is the string it has always been, character for +character; at two, "Maintenance: drain" without a name is a +banner an operator cannot act on, because the remedy is at one +device and the site has two. + +### L7669 ⚠️ THE EARLIEST ACROSS THE PACKS, NOT THE FIRST PACK'S. One date on a + +⚠️ THE EARLIEST ACROSS THE PACKS, NOT THE FIRST PACK'S. One date on a +site with two schedules has to be the one that comes first, or the row +says "2026-10-01" while a pack recalibrates tomorrow. `None` means +"never run, due now" and has to win over any date, so it is tested for +rather than sorted with. At a roster of one this is that pack's own +date, unchanged. + +### L7682 SAFETY-31, and it belongs DIRECTLY UNDER the two figures it is not + +SAFETY-31, and it belongs DIRECTLY UNDER the two figures it is not +derivable from. "Grid 0 W, Battery 0 W, Circulating 6000 W" is the +whole card in three rows: both of the numbers an operator normally +reads say the site is idle, and the third says 6 kW is going round +between the packs. Only shown at N>=2 - at one inverter it is +identically zero and a permanent "0 W" row would be noise. + +### L7690 TEL-11, and ONLY when a source is configured - see `checks()`. + +TEL-11, and ONLY when a source is configured - see `checks()`. +`w(None)` renders "—", which is how this row says "no reading" +rather than "0 W". It sits beside Grid and Battery because the +question it answers is the one those two cannot: at "Grid 0 W, +Battery 0 W" the site is either becalmed or throwing away every +watt it makes, and only this row separates them. + +### L7735 FCST-04. WHAT §8.3 HAS TO CARRY FORWARD, which is the difference + +FCST-04. WHAT §8.3 HAS TO CARRY FORWARD, which is the difference +between a 48-hour plan and a 12-hour one on a weekday morning. +It is its own row rather than a clause of "Tariff" because it +answers a different question: "Tariff" says what the plan IS, and +this says what the plan could still be filled from if the feed is +late again tomorrow. + +### L7742 OPT-04. The strategy's own sentence, not a re-derivation of it - + +OPT-04. The strategy's own sentence, not a re-derivation of it - +every refusal it can make already carries a reason a human can +act on, and "Arbitrage: no" would throw all of them away. + +⚠️ TARIFF-10 RE-READ THIS STRING AND LEFT IT ALONE UNDER A +COMMENT THAT WAS FALSE, AND TARIFF-11 IS THAT CORRECTION. The +claim was that `self.arb is None` **if and only if** +`arbitrage.enabled(self.o)` was False. Only the forward direction +holds: `cycle()` returns at the input hold (`bad_for < +stale_input_s`, default 15 s) BEFORE it reaches `self.arb = None` +at all, so on an armed site `self.arb` is `__init__`'s None at +startup and the PREVIOUS cycle's decision during a later hold - +and the row rendered `off (arbitrage_enabled)` on a site whose +`arbitrage_enabled` is `true`. `arbitrage_row()` reads the option +instead of inferring it, and separates "trading is off" from "no +decision was reached this cycle"; `cycle_at` and `arb_at` are what +make the second one an observation rather than a guess. +OPT-11 P3: with battery modes on the modes trade, whatever the +switch says, so the row reports their decision. + +### L7768 UX-46. The rows were built in English with their Dutch beside them + +UX-46. The rows were built in English with their Dutch beside them +(`messages.Bi`); the page's language is chosen once, here, for the +Home sentences, the checks list, the rows that carry one and the +banner. A plain str (no Dutch twin) stays as it is. + +### L7778 The action log itself, newest first. The page does not show it + +The action log itself, newest first. The page does not show it +(UX-08 2d), but an installer can still read it in the `status` +JSON, because several events (a dropped inverter's reason, the +peak guard's projection) are written nowhere else. + +### L7827 ⚠️ THE ONLY WAY OUT OF A SIGN-DISAGREEMENT TRIP, on purpose. + +⚠️ THE ONLY WAY OUT OF A SIGN-DISAGREEMENT TRIP, on purpose. +It clears on a deliberate human start, not on the condition +going away - the condition ALWAYS goes away, because the trip +commands 0 W and a 0 W command cannot disagree with anything. +An operator pressing start has, at minimum, looked at the +banner that says why. + +⚠️ IT CLEARS EVERY INVERTER'S LATCH, AND SAYS SO PER INVERTER. +One button is what the UI has and one button is what §15's +banner tells the operator to press; what must not happen is a +press that clears A while B stays latched with nothing on the +page changing. Each latch is cleared under its OWN key, so an +install that had only B tripped comes back with only B's +history cleared. + +### L7851 ⚠️ AND THE PRE-DEV-02 FLAT KEYS GO WITH THEM, UNCONDITIONALLY. + +⚠️ AND THE PRE-DEV-02 FLAT KEYS GO WITH THEM, UNCONDITIONALLY. +This is what makes `flat True + namespaced False` MEAN +something, and it is the reason `_grade_store_migration()` can +run on every start instead of only on the start that migrates. + +Without it the flat key is a fossil that says `true` forever +on any install that ever tripped, so a guard comparing against +it would re-arm the failsafe on every restart for the rest of +the install's life - which is why that guard used to be gated +on `rep.ran`, and why the gate then swallowed the rollback +ROUND TRIP: migrate, downgrade, trip during the downgrade +window (the old code writes only the flat key), upgrade again +-> `rep.ran` is False, the guard never runs, and the +controller comes up UNLATCHED while /data/state.json says +`sign_tripped: true`. That is store.py's own header sentence, +rebuilt by the version marker. + +Cleared here, the two spellings can only disagree one way: the +flat key is newer than the namespaced one, which means it was +written by a version that did not know about namespaces - i.e. +a trip inside a downgrade window. Unconditional rather than +inside the loop because an operator pressing START is +declaring the whole site clear, and the fossil belongs to no +unit in particular. + +### L7877 SAFETY-30's SITE latch, cleared by the SAME press and for the + +SAFETY-30's SITE latch, cleared by the SAME press and for the +same reason the per-unit ones are: the condition always goes +away on its own, because the trip commands 0 W everywhere and +a site commanding zero cannot oppose anything. Only a human +who has read the banner can say the site is clear. + +⚠️ UNCONDITIONAL, LIKE THE FLAT PAIR ABOVE, AND NOT GUARDED ON +THE ROSTER. An install that ran with two inverters, tripped, +and was then reconfigured back to one would otherwise carry +`site_sign_tripped: true` in its file forever, with no roster +that can reach the code which clears it - and would re-arm the +moment a second inverter was configured again. + +### L7896 SAFETY-31, cleared by the SAME press and for the same reason: + +SAFETY-31, cleared by the SAME press and for the same reason: +the condition always goes away on its own, because the trip +commands 0 W everywhere and two inverters at zero cannot +oppose. Only a human who has read the banner can say the site +is clear. + +⚠️ AND `_circ_announced` GOES WITH IT. It is the "has a human +been shown this" flag; leaving it True through a clear would +mean the NEXT trip in this process latched, stopped the site, +and raised no notification at all. + +### L7913 SAFETY-42, cleared by the SAME press, and for a reason that is + +SAFETY-42, cleared by the SAME press, and for a reason that is +NOT the one above. The other three latches are cleared here +because their trip removed its own evidence - a site commanding +0 W cannot oppose anything - so only a human can say the fault +is gone. This one commands nothing, so its evidence is still +standing and it could in principle clear itself. It does not: +a unit that stopped delivering for minutes and then resumed is +an INTERMITTENT fault, and a detector that erased its own +record of that would be the least useful thing in this file. +⚠️ AND `_delivery_announced` GOES WITH IT, like +`_circ_announced`: leaving a name in it through a clear would +mean the NEXT trip on that unit latched and raised no +notification at all. + +### L7938 ⚠️ THE WHOLE SITE, TARGETS INCLUDED - see command_site_zero(). + +⚠️ THE WHOLE SITE, TARGETS INCLUDED - see command_site_zero(). +Zeroing `self.target` alone would leave each unit's last share +standing for its next heartbeat to re-emit, which an operator +would read as the stop button not working. + +### L7949 ⚠️ WHICH PACK, BECAUSE THERE ARE NOW SEVERAL AND THE BUTTON HAS + +⚠️ WHICH PACK, BECAUSE THERE ARE NOW SEVERAL AND THE BUTTON HAS +ONE LABEL. `_maint_button()` answers it: the pack that holds the +site's maintenance slot if one does - which is what "start" +already meant at a roster of one, where pressing it mid-drain +re-entered DRAIN - and otherwise the pack that has gone longest +without a cycle, which is the same pack `arbitrate()` would have +picked on its own. At N=1 both branches are `maints[0]` and this +is the shipped call, byte for byte. + +This is the bare request (no unit). A request naming a battery +was handled above by `_maint_unit_action()` (MAINT-11). + +### L7991 OPT-11 P2: `(modes, retract)` for the MQTT publisher at start-up. + +OPT-11 P2: `(modes, retract)` for the MQTT publisher at start-up. + +The config topics announced are kept in the store, so turning modes off +removes exactly those (`mqtt.mode_configs()`). An install that never +turned modes on gets nothing, and its store is not written. + + +### L8025 `{slug, ha_version}` from the Supervisor, each None when unreadable. + +`{slug, ha_version}` from the Supervisor, each None when unreadable. + +`GET /addons/self/info` and `GET /info` are on the Supervisor's bypass +list for an add-on's own token, so they need no role (see selfconfig.py). +Asked together with a 3 s budget: a link may never hold up control start. + + +### L8117 Startup self-check: prove we can actually reach the Core API before + +Startup self-check: prove we can actually reach the Core API before +anything tries to control an inverter with it. A 401 here is a +permissions/token problem, not a configuration mistake, and saying so +explicitly saves an installer from re-checking entity ids for an hour. + +### L8134 UX-09: the Details link in every notification needs this add-on's + +UX-09: the Details link in every notification needs this add-on's +slug and Home Assistant's version (see messages.docs_url()). Both +are best effort: without them the link falls back to the hostname, +or to naming the section only. + +### L8140 ⚠️ THE STARTUP GATE (CFG-01). Nothing below this line may run on a + +⚠️ THE STARTUP GATE (CFG-01). Nothing below this line may run on a +configuration validate.py rejects - specs §1.5: a config the system +cannot honour is refused at startup, not survived at runtime. + +It sits HERE, before the broker, before the web server and before any +task exists, so a refusal cannot leave half a controller running with +a UI in front of it. Reading the device range is the one thing the +validator cannot do for itself; (None, None) when ESPHome has not come +up yet is not a refusal - run_control() re-checks once the real rating +is known. See validate.py for where the line is drawn and why. + +### L8156 UX-15: a new install names no inverter. When that is the ONLY + +UX-15: a new install names no inverter. When that is the ONLY +refusal it serves the setup wizard in setup-only mode, which builds +nothing that commands and returns when stopped. Any other refusal +still exits 78 (DECISIONS/UX-15-setup-only-mode.md). + +### L8169 ⚠️ Status publishing must NEVER be able to stop the controller. A + +⚠️ Status publishing must NEVER be able to stop the controller. A +broken broker, a missing library, an API change in paho - all of it is +observability, and the battery does not care. Caught broadly and on +purpose: this crashed the add-on once already (paho 1.x vs 2.x) and +took the control loop down with it. + +### L8186 TEL-11. ⚠️ THE SHIPPED PREDICATE, NOT A SECOND READING OF THE + +TEL-11. ⚠️ THE SHIPPED PREDICATE, NOT A SECOND READING OF THE +OPTION - `Controller.publish()` gates the row on this same +call. An install with no PV roster announces exactly +what it announced before: no topic, no entity, no row. + +### L8191 TEL-07. ⚠️ THE NAMES, NOT A ROSTER. `build_roster()` here + +TEL-07. ⚠️ THE NAMES, NOT A ROSTER. `build_roster()` here +would construct a SECOND set of `Inverter`s off the same +Store, minutes before `Controller.__init__` constructs the +real ones; `roster_names()` is the naming rule on its own and +is what `build_roster()` itself reads. At a roster of one this +announces nothing new - see `announced_units()`. + +### L8231 OPT-04. The tariff refresh runs as its OWN long-lived task, for the + +OPT-04. The tariff refresh runs as its OWN long-lived task, for the +reason P1 ingestion does and then some: `resolve_tariff()` may open an +HTTPS connection to a supplier, and the control tick is what feeds the +ESP32 heartbeat. A fetch on that path is a supplier's TLS timeout able +to push this add-on towards layer 1's 30 s veto. See TARIFF_REFRESH_S. + +⚠️ STARTED FOR A PROVIDER, FOR ARMED TRADING OR FOR BATTERY MODES: +see `tariff_refresh_wanted()` above and DECISIONS/TARIFF-10 and +TARIFF-24 for why each term is there. + +⚠️ IT DOES NOT ARM ANYTHING. Fetching a price and trading on one are +two decisions; this is the first, and `cycle()`'s +`if arbitrage.enabled(self.o):` is still the only gate on the second. + +### L8282 ⚠️ No traceback, on purpose. The banner refuse() already printed says + +⚠️ No traceback, on purpose. The banner refuse() already printed says +everything an operator needs, and a stack trace on top of it would say +"this crashed" - the exact confusion AC3 is about. 78 is sysexits(3) +EX_CONFIG, so even a script reading the exit status can tell a bad +config from a bug. + +## Added at release/1.0 `16029d7` (SMA-2, SMA-10, SAFETY-128, SAFETY-137) + +Same form, keyed by the first line number in `app/main.py` at `16029d7`. + +### L143 SMA-10. The same bound for handing a unit back (`driver.release()`). I + +SMA-10. The same bound for handing a unit back (`driver.release()`). It is the +time the shutdown path already allows one 0 W write, and the units are +released CONCURRENTLY, so one slow or hung unit costs the wind-down no more +than a hung GoodWe write does today: the Supervisor's kill window is not lost +to it. A release still running at the bound is abandoned, not awaited. + +### L150 SMA-10 round 2. The one fallback write after a failed release (default + +SMA-10 round 2. The one fallback write after a failed release (default 0 W, +`Driver.release_fallback()`). Worst case for a unit whose release hangs: +RELEASE_BUDGET_S + FALLBACK_BUDGET_S = 6 s, against the Supervisor's 10 s. + +### L156 SAFETY-137. How long a LAST write (the Stop 0 W, the shutdown 0 W, a r + +SAFETY-137. How long a LAST write (the Stop 0 W, the shutdown 0 W, a release) +waits for a write already on its way to the same unit. Half the release +budget, as `_release_last` always waited. For a GoodWe unit that is +SETTLE_BUDGET_S + WRITE_BUDGET_S = 6 s at worst, which is HAND_BACK_WORST_S: +the wind-down is no slower than SMA-10's worst case. + +### L586 SMA-10. Which units hand back decides what the page says about Stop, + +SMA-10. Which units hand back decides what the page says about Stop, +restart and shadow mode. A GoodWe-only roster adds nothing. + +### L3152 SAFETY-128: update the answer gate; seconds the late verdict has + +SAFETY-128: update the answer gate; seconds the late verdict has +stood, or None. Readings found late are logged once per episode. +DECISIONS/SAFETY-128-late-readings.md. + +### L3805 `inv`'s driver, wired to this Controller's Home Assistant on first use + +`inv`'s driver, wired to this Controller's Home Assistant on first use. + +SMA-2. Bound HERE rather than when the roster is built, so a unit added +to `self.inverters` afterwards is wired too, and the driver follows +whatever `self.hass` is at the time (a check may swap it). + +### L3835 SMA-2. The driver reads, in the order this method always did: SoC, + +SMA-2. The driver reads, in the order this method always did: SoC, +then power. `extra` is whatever else the driver learned; nothing +consumes it yet. + +### L4074 Wait, at most `budget_s`, for the writes already on their way to + +Wait, at most `budget_s`, for the writes already on their way to +`inv` (SAFETY-137: every driver, GoodWe too). A write still running at +the bound is left alone, not cancelled: its own WRITE_BUDGET_S ends it. + +### L4082 `release()`, after a write already on its way to `inv` has finished + +`release()`, after a write already on its way to `inv` has finished +(at most half the budget is spent waiting for it), so the release is the +LAST thing the unit hears and a late write cannot undo it. + +### L4089 SMA-10. Give ONE unit back: exactly one `release()`, then nothing. + +SMA-10. Give ONE unit back: exactly one `release()`, then nothing. + +True when the unit is handed back (now, or already). Never raises: a +driver that raises or hangs is logged and the unit is tried again on the +next idle write, and it cannot stop a sibling being released or zeroed. + +⚠️ `released` IS SET BEFORE THE FIRST AWAIT. A second caller (the +heartbeat while the Stop button is mid-release) then sees it and does +nothing, so a unit gets one `release()` and not two. If the release +did not take, the flag goes back down and the unit stays un-handed +until a later idle write tries again. + +⚠️ IT IS NOT A WRITE: no `note_write`, no `last_write`, so a hand-back +cannot be read as a link that answered. `last_write` is cleared so the +first write after control starts again is always sent. + +### L4109 After a failure the next try waits one heartbeat, so a hung release + +After a failure the next try waits one heartbeat, so a hung release +costs a cycle its 4 s once per heartbeat, not on every cycle. The +Stop button and shutdown (`force`) always try. + +### L4146 ⚠️ ONCE. The unit must not keep carrying its last command, but a + +⚠️ ONCE. The unit must not keep carrying its last command, but a +0 W re-sent on every try would reset the inverter's own fallback +timer for ever. The driver says what the one write is. + +### L4162 --- SMA-10: A UNIT THAT HANDS BACK IS NOT WRITTEN WHILE THE ADD-ON IS + +--- SMA-10: A UNIT THAT HANDS BACK IS NOT WRITTEN WHILE THE ADD-ON IS +IDLE. Idle is: shutting down, control stopped, or shadow mode. The +unit is released once and then nothing is written to it - not the +heartbeat, not the cycle's "stopped" 0 W - so its own controller keeps +it. This is the passive half; `command_site_release()` is the active +one, for the moment the add-on goes away. + +⚠️ A SAFETY STOP IS NOT IDLE. It happens while control runs (`auto`, +not shadow), so it falls through to the 0 W write below: the add-on's +own decision to hold 0 W is never turned into a hand-back. + +⚠️ AND CONTROL STARTING AGAIN RE-ARMS THE UNIT: the flag drops and +`last_write` is cleared, so the first write goes out whatever it is. +`stopping` never re-arms: a shutdown in progress stays handed back. + +### L4181 Control has the unit again: forget the hand-back, and any + +Control has the unit again: forget the hand-back, and any +failed streak with it, so the next Stop starts clean (its own +one 0 W, its own error line and event). + +### L4302 --- SAFETY-137: THE 0 W THAT ENDS THINGS IS THE LAST WRITE THE UNIT + +--- SAFETY-137: THE 0 W THAT ENDS THINGS IS THE LAST WRITE THE UNIT +HEARS. `last` is the Stop 0 W and the shutdown 0 W (and nothing else). +It first waits, bounded, for a write already on its way to this unit, +so that write cannot land after it. And once shutdown has begun every +other write (cycle, heartbeat, a safety stop) is dropped here: the +check sits right before the write is created with no await between, +so a write that starts after it cannot exist, and one that started +before is in `inflight` for the wait above. The idle gate for a +hand-back unit is higher up and does the same for those. + +### L4328 SMA-10 / SAFETY-137: kept for every driver, so a release or a last + +SMA-10 / SAFETY-137: kept for every driver, so a release or a last +0 W can wait for it (`_await_inflight`). + +### L6948 Signal, then return WITHOUT entering the loop. amain() wakes + +Signal, then return WITHOUT entering the loop. amain() wakes +on this, runs the normal wind-down (which commands 0 W, or hands +back a unit whose driver does: SMA-10) and re-raises +ConfigRefused afterwards, so the exit code is 78 and the +inverter is left at zero rather than latched. + +### L7222 SMA-10. The add-on is going away (Stop, shutdown, restart, task + +SMA-10. The add-on is going away (Stop, shutdown, restart, task +death, a config refusal): every unit that hands back is given back, and +every other unit is held at 0 W exactly as `command_site_zero()` does. + +⚠️ THE SAFETY STOPS AND REFUSALS DO NOT COME HERE. A sign trip, a +refused write, a missing reading, another writer: those are the add-on's +own decisions and hold 0 W through `write(0)` for EVERY unit, handed-back +drivers included. `command_site_zero()` is that, and it is unchanged. A +unit the add-on has just declared it cannot trust must not be handed to +something else that will then do what it likes with the battery. + +⚠️ A ROSTER WITH NO HAND-BACK UNIT IS `command_site_zero()`, line for +line: GoodWe's release is its 0 W write, so Stop keeps today's write +and today's heartbeat. + +⚠️ ONE UNIT'S FAILURE IS ITS OWN. `_hand_back()` never raises and is +bounded by RELEASE_BUDGET_S; the units run concurrently, so the whole +call takes no longer than its slowest bound. + +### L8207 SMA-10: the Stop button is the add-on going quiet, so a unit + +SMA-10: the Stop button is the add-on going quiet, so a unit +that hands back is given back; every other unit is zeroed. + +### L8254 SMA-10. `await awaitable`, but give up after `budget_s` and do NOT wai + +SMA-10. `await awaitable`, but give up after `budget_s` and do NOT wait +for it to wind down. `asyncio.wait_for` waits for the cancelled task to +finish, so a driver that ignores its cancellation would hold the whole +shutdown; this abandons it. Raises `asyncio.TimeoutError` at the bound. + +### L8434 SMA-2. The flat options are the one-inverter shape, so it is the + +SMA-2. The flat options are the one-inverter shape, so it is the +GoodWe driver's, asked without a Controller (none exists yet). diff --git a/goodwe_controller/DECISIONS/MAIN-orchestration.md b/goodwe_controller/DECISIONS/MAIN-orchestration.md new file mode 100644 index 0000000..33b716f --- /dev/null +++ b/goodwe_controller/DECISIONS/MAIN-orchestration.md @@ -0,0 +1,53 @@ +# MAIN - why app/main.py is built the way it is + +**Status: SHIPPED.** Written down by MAINT-20 part 2 from the long comments and +docstrings of `app/main.py`, so the module can keep one line and a pointer. The +comments that were shortened but not rewritten here are kept word for word in +[[MAIN-orchestration-archive]], by their line in `app/main.py` at release/1.0 +`d4c01da`. Since MAINT-21 the Controller's methods are split by job into +`app/main.py` and `app/ctl_*.py`; a comment keeps its text and moves with its code. Related: [[SAFETY-07-peak-guard]], [[FCST-04-the-day-that-is-carried]], +[[SAFETY-30-per-unit-sign]], [[SAFETY-73-refusal-per-inverter]], +[[SAFETY-121-bound-every-quarter]], [[TARIFF-10-fetching-is-not-trading]], +[[TARIFF-24-modes-need-the-tariff-task]], [[OPT-34-the-night-charge-keeps-its-level]]. + +## Controller construction + +- **Per-write budget (DEV-02).** Each write is dispatched concurrently and bounded, so one hung `hass.call()` cannot eat a sibling's layer-1 budget (the ESP32 zeroes after about 30 s, and a fault on A could zero a healthy B). The number is derived: `heartbeat_s` max 25 s, layer-1 veto `validate.FIRMWARE_INGEST_VETO_S` 30 s, so 25 + 4 < 30. test_inverter.py grades the inequality, so raising the heartbeat ceiling goes red instead of taking an inverter to zero. Below hass.py's 10 s HTTP timeout on purpose: abandon the write and re-issue it next tick, since `last_write` moves only on an accepted write. +- **Tariff refresh (OPT-04).** `resolve_tariff()` may do an HTTPS fetch. The tick feeds the ESP32 heartbeat, so a supplier's TLS timeout on the tick would push the add-on into layer 1. The tick never awaits a fetch. The 30 min cadence is not about price change (day-ahead publishes once at 14-16 h CET and 8.3's carried hours go firm then); it picks the switch up within the hour at 48 fetches a day. The age bound answers another question: a failed refresh still stores a plan (the 11.4 static fallback), the bound covers the refresh task dying while a plan from hours ago stands as current. Three missed refreshes, for `p1.max_age_s`'s reason. +- **Status rows (TARIFF-11).** The Tariff row used to be `static_status()`'s sentence alone and never saw the provider plan (read 'no static profile' at all 802 samples of a 40 h soak with a live feed). `tick_words` and `plan` are two clocks and the row says so; the plan is stamped with its own age from `tariff_at` (TARIFF-12 does not move it on a kept plan), and `age_s` is the caller's measurement. The Arbitrage row used to be `"off (arbitrage_enabled)" if self.arb is None`, under a comment saying `arb is None` iff trading was off; false, since `cycle()` returns at the input hold before `self.arb = None`: `arbitrage_enabled: true` plus a sensor answering None rendered 'off (arbitrage_enabled)', naming an option that is on, and past the first cycle the previous decision stood as current. Three states: off, armed with no decision this cycle, a decision with its age (always printed: a row that reports staleness only once stale cannot be told from one that never does). +- **`stop` is required (review catch).** `stop=None` made a Controller that cannot stop itself the default: on the late-refusal path in `run_control()` it logged the banner, returned and left the process alive forever with no loop and no output. +- **Action log first.** The store migration can log to it (15: how an operator finds a latch was re-armed); an AttributeError on the way to saying so would stop the add-on booting. +- **Roster and migrations (DEV-02, SAFETY-44, MAINT-05).** Every per-device value lives on the roster objects (app/inverter.py); a `Tuning` and an integrator are deliberately not per device (6.2: one integrator on P1 above the split; a second regulating the same meter is the two-writers failure). The SAFETY-02 key migration runs before the first `Inverter` reads its latch, else a tripped install comes up armed with a green banner. SAFETY-44: it is handed `roster_names(opts)[0]`, never `UNIT_A` (on a declared roster the flat latch landed under `unit/inverter-a/`, read back under the name it was handed, stamping the marker); `roster_names()` returns `[UNIT_A]` on the flat shape so today's path is byte-identical. `misdirected` is unreachable from that call site (`unit` is a roster member by construction; dropping the `roster` argument survives 28/28), so the claim that the call site buys the refusal is gone; the argument stays for new callers and is graded in test_maintenance.py. The maintenance migration targets `self.inverters[0].name`, not `UNIT_A`: with `UNIT_A` the history would sit under a name on no roster (a nameless entry falls back to a positional `inverter-1`). Every two-pack fixture once named its first entry `inverter-a`, so swapping them left 19 files green; `migrate_maint_keys()` now grades the namespace it wrote against the names the machines read, and test_maintenance.py sections 9 and 11 use `["garage", "shed"]`. +- **CFG-04 disclosure.** A declared `inverters:` roster ignores `soc_entity`, `batt_entity`, `batt_invert` and `max_w`, which the UI still shows. Rule 9(e) refuses the dangerous one (a flat `setpoint_entity`); the rest cannot be refused (the schema has no blank value) so one action-log line at every start names the roster and the ignored keys. +- **Site bound.** Summed from the roster, not `opts["max_w"]`: it is the integrator bound and rail of the site loop, then split. Identical at N=1; a per-unit `max_w` binds each share through its `supervised` claim. +- **SAFETY-39 slew fallback** is 0 ("follow the rail"); it was 1000, a stale third copy. `control.slew_limit_w()` is the one reader. +- **CFG-03 in main.py.** Eight `opts.get(key, )` calls used to live in the maintenance setup and two disagreed with config.yaml (2500 against 2000). `MaintConfig.from_options()` reads them. A ninth key goes in config.yaml `options:`/`schema:` and `maintenance.MAINT_OPTION_DEFAULTS` only. +- **Watchdog thresholds (SAFETY-30).** The per-unit pair is re-derived at two inverters, not carried (it grades a command against one unit's own power). The site pair is used only at N>=2: the 300 W threshold carries (meter noise, deadband), the window does not (110 s at one inverter, 215 s at two, against a 180 s hold). +- **Latches (SAFETY-02, -31, -34, -42, -18).** SAFETY-02: one per actuator, restored from namespaced keys; graded on every start (a latch that failed to move namespace, or was taken by an older add-on in a rollback, is a disarmed guard, so a disagreement re-arms by hand and shouts). SAFETY-31: site-level, flat keys (circulating power is defined over the roster), restored because it acts. SAFETY-42's delivery latch does not act, so it is restored only so the ALARM survives (the 2026-09-02 outage went unseen 6 h 25 m with the detector correct). SAFETY-18 is not restored (does not act). SAFETY-30's site check is armed only at N>=2. +- **PV (TEL-11).** Instrumentation only; wiring it in would be an unrequested behaviour change and would destroy the measurement. +- **Peak guard setup (SAFETY-07, TARIFF-01, FCST-04).** See SAFETY-07-peak-guard.md and FCST-04. The windowing caveat for FCST-04: hours already elapsed leave the spread, so a cheap night that has gone no longer sets the day's cheapest hour. + +## Cycle state and latch repair + +- **Allocation record (SAFETY-28).** The tick that mints a record increments once per resolution, not per loop iteration. A cycle with no resolution (the "inputs missing, not yet stale" hold) must not bump it: that hold returns before the allocator so one missed poll does not zero the inverter, and the heartbeat re-affirms `self.target` through the write path; bumping would make that heartbeat unauthorised and drop the site to 0 W. The record is superseded, never expired. +- **`self.arb` (TARIFF-11).** See "Status rows" above; `arb_at < cycle_at` is the derived "the latest cycle did not reach the arbitrage step". +- **Shadow (SAFETY-10, SAFETY-47).** `shadow_would_w` is what a live controller would have put on the wire; `self.target` is what is standing on the wire (held at `shadow.WIRE_W`, re-seeded each shadow cycle). Folding them shows an operator a number nothing is doing. The "sized from the billed-quarter meter" flag is recorded where the decision was taken (the page runs on its own task); False, not None, before the first shadow cycle. +- **ARB-03.** `units` is a property derived from the roster so a site cannot claim two actuators while holding one writer. At N=1 (6.2) the grid connection and the only inverter are one actuator; a second entry makes per-inverter claims stop being site claims (ALLOC-01). +- **DEV-02 latch guard (`_check_sign_latch...`).** Runs on every start: gating on `rep.ran` swallowed store.py's rule-2 round trip (upgrade, downgrade with a trip in the window, upgrade; the controller came up untripped while state.json said `sign_tripped: true`; a firmware rollback path was performed on this site on 2026-09-02). The gate could go because `handle_action()` clears the flat keys with the namespaced ones and the trip mirrors them. SAFETY-44 second half: the question is whether a namespaced latch THAT A MACHINE READS is set. An earlier version accepted any `unit/*/sign_tripped`, which blinded the guard on exactly the installs the broken migration had put the latch under `unit/inverter-a/` (a key nothing reads). The first blunt fix (every off-roster latch is litter) re-armed a healthy A off B's mirrored flat key (test_inverter.py DEV-02 restart case). `UNIT_A` is the discriminator: the only name the broken migration wrote. A single flag written for two intents was defeated by one removed unit's key (roster ['garage','shed'] with `unit/old-shed/sign_tripped` drove on a state file reading `sign_tripped: true`; `tools/rehearse_roster.py` exit 1); the fixtures now hold both arrangements. Residual: a first unit really named `inverter-a`, latched and removed from the roster is re-armed on `inverters[0]` (conservative). The printed reason is the flat mirror's (whatever tripped last), so on a multi-unit site one inverter's evidence may appear under another's name; test_maintenance.py's check that the reason is not the removed unit's depends on that fixture's flat string, not on this code. +- **Maintenance views (MAINT-05).** `maints` is one FSM per roster entry; `maint`, `maint_unit` and the button target are views of the one that holds the slot (`maintenance.arbitrate()` allows at most one out of IDLE). validate.py rule 6 grades `maintenance_charge_w` against the weakest cap on the roster. +- **N=1 views.** Properties, not fields, and they refuse at N>=2 (6.2's identity is false there). Nothing inside main.py may read them (test_inverter.py AST scan). +- **`_arm_sign_watchdogs` (SAFETY-30).** Called every cycle because fixtures append an `Inverter` after construction; a detector frozen at construction would be graded against the meter at a roster of two. `arm()` touches no timer or latch. +- **Per-inverter refusal (SAFETY-73).** The probe ask is PROBE_W, not `saturation_w`: a unit's share is often small (a 400 W night load split two ways) and SAFETY-43 would name the empty battery as not delivering. The site target is restarted from the watts on the wire when a unit reopens (phase A: -1059 W). + +## Write path and cycle + +- **The write gate (SAFETY-28).** specs 1.5 makes two writers on one actuator a non-goal. `len(validate.ACTUATOR_WRITE_KEYS) == 1` is a fact about the options schema, not the writes, and goes false when CFG-04 adds per-inverter config. So the enforcement is on the write: a number reaches the wire only if the single allocator placed it, on this tick, for this unit (`Allocation.authorises()`); a second writer must file a Claim. 0 W is always authorised and the test for zero comes first and reads nothing: the failsafe branches write 0 W while the allocator has refused (`Allocation.ok` False, no shares), and a gate asking its permission would deadlock the failsafe behind the component it answers; at S = 0 broadcast and allocation coincide, so there is no over-command (the hazard is N-times loop gain from broadcast, TEST-19's `N=2 gain 1.0` limit cycle). The predicate is `value == 0.0`, not a `failsafe=True` flag, which a second writer would pass; -0.0 == 0.0 and a nan never gets here. DEV-02: the unit is an argument, not the N=1 view; the default refuses at N>=2. The refusal sits above the clamp and below the non-finite coercion. +- **Clamp (SAFETY-03)** is on the only path to the wire, so no optimizer, maintenance or manual path routes around it. A non-finite value is loss of input (11.1), coerced to 0 W. Every engagement goes to the action log undeduplicated; the notification is deduplicated. +- **Shadow (SAFETY-10)** suppresses in the same method, below the gate and the clamp, as a substitution not a return. It is not a second writer. +- **Reads (DEV-02, TEL-12).** Each inverter's readings are gathered concurrently across units and sequentially within one; PV entities ride in the same gather (a slow sensor must not push a healthy battery toward layer 1's veto). P1 has no inverter-side fallback: the inverter's AC power correlates 0.998 with battery power and 0.09 with the real meter. +- **Stale reading (SAFETY-37/56/57).** The power reading goes through the freshness gate, the SoC does not (the power feeds the sign and delivery checks, which a frozen register fools). SAFETY-57 rewrote the escape clause: "it clears itself when the register reports a different value" was false for the state announced, because the 0 W it announces is what stops the value changing. The release is reported, never silent (it withdraws a SITE STOP). +- **TARIFF-03.** The one shiftable load is the maintenance cycle's cheap-window top-up; the static window is synchronous and I/O-free, and validate.py refuses `static_profile` together with the price entities. +- **Cycle ordering (SAFETY-02/31/42).** The watchdog evaluations run every cycle, before the input hold, so a run of held cycles cannot leave their timers resuming from a start that predates the gap. Reason first, flag second (each `set` writes the file): a crash between persists a reason nothing reads, not a latch with no explanation. The per-unit trip mirrors the legacy flat keys (store.py rule 2 covered only the latch present at migration time). The site check is flat-keyed, armed only at N>=2. SAFETY-31's input is MEASURED power (`inv.batt`), never the allocation record, which has sign-coherence by construction. +- **Maintenance FSMs (MAINT-05).** Each pack is ticked with its own SoC (a minimum would abort a cycle on a sibling's state, an average would declare a pack full that is not); `arbitrate()` runs first. A deferral is carried to the status page because the edge-logged line scrolls out of the 40-row log. +- **Aggregates.** SUM for the site bound, achievable rating and the battery power the site loop regulates against (`compute()`'s saturation test compares against the site target; one unit's power trips the freeze permanently, up to 510 W of split-dependence at gain 0.2, test_alloc.py part 8). MINIMUM for the discharge permission (the emptiest pack). MEASURED power for circulating power. Unknown bounds stay unknown when any unit is silent. +- **Trade sizing (OPT-09).** `trade_sizing` uses arbitrage's own SoC bounds, not the BMS cut-out (SAFETY-25): sizing is the trade's business, the pack envelope is the pack's. Weights are a preference, so a pack between its arbitrage floor and its cut-out can still take part of a sell; fixing it needs a per-pack envelope depending on which claim won the tick. diff --git a/goodwe_controller/DECISIONS/MAINT-24-charge-first.md b/goodwe_controller/DECISIONS/MAINT-24-charge-first.md new file mode 100644 index 0000000..240da11 --- /dev/null +++ b/goodwe_controller/DECISIONS/MAINT-24-charge-first.md @@ -0,0 +1,72 @@ +# MAINT-24 - a started maintenance charge gets the cheap night + +**Status: for review.** Tests: `test_maint24.py` (`test_opt20.py`'s `ch_ch_maint` digest moved with it). No option added; the MAINT-13 +timeout numbers are unchanged. Folds in SAFETY-80. SAFETY-111 stays on its card (section 3). + +**What happened (live 0.21.0, A, 2026-11-08..11).** A sat in its maintenance +CHARGE phase for more than 75 h and stalled at 49-50 %. At night B's battery-mode +grid charge took the cheap run: A is not idle, so `modetrade.chargers()` never +lists it, B is the only charger, and the allocator hands the whole negative +target to B. A's own shaping then paused or shrank (the check compared the peak +forecast with `cap - margin` = 3450 W, while B's trade and the guard aim at this +month's peak, about 4.9 kW), and A gave power back on guard stops against a peak +that B's own charge made. The timeout (MAINT-13) counted that starved time as +charging time and ended the cycle. Report: `reports/MAINT-24-investigation-report.md`. + +## 1. The maintenance charge goes first in the cheap run + +`modetrade.decide(maint_charging=)`, set in `_mode_roles()` when any pack is in +its maintenance CHARGE phase. It is the mirror of `draining` (SAFETY-78): no +grid-charge trade for the other packs, why `cycle`, the same Tick. The other +packs keep their solar roles, so they may still take spare solar. A refusal probe +(SAFETY-73, PROBE_W alone, OPT-20) still goes on: it places no charge on the +pack in maintenance, and `test_opt20.py` g7 pins it. The drain still blocks it. B's night +charge waits for the nights A needs. At N=1 the only pack is the one in +maintenance, so nothing changes. + +## 2. The shaping aims where the guard aims (SAFETY-80) + +The pause (`shaping_suspended()`) and the floor (`maintenance_charge_floor()`) +get `peakguard.quarter_target_w(cap, margin, month reading)` instead of +`peak_cap_w - peak_margin_w`. With no banked peak above the cap that is the same +number. SAFETY-63 (no forecast: no pause, configured rate) and SAFETY-125 (late +reading: `charge_room_w`) are untouched. `peak_aim_w()` stays for the day plan. + +## 3. SAFETY-111 is not folded in + +`peak_fc` holds the pack's own charge, so the floor `aim - peak_fc` settles at +(aim - house) / 2, here 1475 W instead of 2000 W. Taking the own charge off the +forecast was tried: it lifts A to 2000 W, but it changes the N=1 charge that +`test_safety119.py` pins (a static 800 W forecast then no longer shapes the +charge), so it is a change of its own. 1475 W fills a 10 kWh pack inside the +night (sim below). It stays on its card. + +## 4. A gives nothing while no real peak exists + +With 1 and 2 no grid charge of B makes a peak against the lower aim, and the pause +comes only when the forecast is over the month aim, so A is not made the only +battery that gives while B charges. A guard stop on a real peak +still lands on A (SAFETY-07 / MAINT-02, unchanged). + +## Numbers (sim, house 3000 W, cap 3500, margin 50, month peak 6000 W) + +| | base 02eac3b | MAINT-24 | +|---|---|---| +| A charge | 0 W (B charges 2500 W) | 1475 W = (5950 - 3000) / 2 | +| B grid trade | yes, quarters 5500 W | none, why `cycle` | +| quarter peak | 5500 W | 4475 W (aim 5950 W) | +| A at house 3800 W | 0 W | 1075 W, quarters 4876 W | + +Whole night (sim, `tools`-style replay, N=2, cheap 21:00-06:00, A from 10 %, B +from 30 %, 9 h): base A takes 1.41 kWh (10 -> 23 %), B takes 6.84 kWh by grid +trade; MAINT-24 A takes 9.47 kWh and is full (100 %) inside the night, B takes +no grid charge. Worst 15-minute average 5500 W on base, 4475 W now, A never +gives. + +## Not changed + +The MAINT-13 timeout, the peak aim itself, the month peak, `P_MAINT_SHAPE` and +`P_ARBITRAGE`. The Home card for B does not say "the other battery is cycling" +for a CHARGE phase (`other_cycle` reads "emptying"); that is a wording card. + +MAINT-25 (the Home plan and the back-off) has its own note: `MAINT-25-plan-backoff.md`. diff --git a/goodwe_controller/DECISIONS/MAINT-25-plan-backoff.md b/goodwe_controller/DECISIONS/MAINT-25-plan-backoff.md new file mode 100644 index 0000000..c2e7c6a --- /dev/null +++ b/goodwe_controller/DECISIONS/MAINT-25-plan-backoff.md @@ -0,0 +1,10 @@ +# MAINT-25 - the Home plan honours the 7-day back-off + +**Status: for review.** Added to the MAINT-24 PR by the owner (2026-11-12). +Tests: `test_maint25.py`. After a failed cycle `wants_start()` waits 7 days +(MAINT-13, `backoff_until()`), but `homeview.maintenance_runs()` only asked +`due()`, so the plan drew a cycle at the start hour every night of the wait. +During the back-off it now draws no run for that battery and shows one line +instead: "Battery A: the monthly cycle waits until 19 November." (Dutch: "... +wacht tot 19 november."). A cycle completed after the failure ends it, as in +`backoff_until()`. The other battery is planned as before. diff --git a/goodwe_controller/DECISIONS/SAFETY-128-late-readings.md b/goodwe_controller/DECISIONS/SAFETY-128-late-readings.md index 6b9e644..e2751f6 100644 --- a/goodwe_controller/DECISIONS/SAFETY-128-late-readings.md +++ b/goodwe_controller/DECISIONS/SAFETY-128-late-readings.md @@ -71,7 +71,8 @@ The fits run all the time; the pull request has the counts. **What it costs.** - Found 36-68 s after a lag starts at 1-2 s meters; at a 5 s meter 30 s late is found within 100 s after it starts (88 s measured) (the loop first moves 100 W after 60 s, - SAFETY-129) with the export above -200 W, and 10 s late is not found. Until + SAFETY-129) with the export above -200 W, and 10 s late is not found (SAFETY-136 calms + the loop at a slow meter instead). Until then control is as before. In a quiet house the "readings late" row stays about 2 minutes longer after the lag ends (126 s against 32 s on base); no harm measured, and it clears as early as on base when the load changes. diff --git a/goodwe_controller/DECISIONS/SAFETY-135-young-period.md b/goodwe_controller/DECISIONS/SAFETY-135-young-period.md new file mode 100644 index 0000000..4f8d6aa --- /dev/null +++ b/goodwe_controller/DECISIONS/SAFETY-135-young-period.md @@ -0,0 +1,116 @@ +# SAFETY-135 - one guard stop does not cost the night charge the whole period + +**Status: for review, round 2.** Code: `Controller._mode_roles()` and +`Controller._give_falling()` (`app/ctl_trade.py`), `modetrade.decide(wait=)`, +`RESTART_S`, `YOUNG_S`, `GAVE_S`, `WAIT_WORDS` (`app/modetrade.py`). Tests: +`test_safety135.py`. Battery modes only. No option, no change to the peak +guard. + +**Problem.** A grid charge the peak guard stops stays off to the period's end +(the OPT-11 latch). Three cases seen on TEST-23: +- *A spike at a period's start* (UX-77 I-1, x10): a 1-3 s spike, or a charge + still at full power from the end of the last period, makes the guard project + 4.3-6.6 kW and cut the charge. The cut is right, but one 2 s spike cost 15 + minutes of charge, about 0.16 kWh per trip on the rig. +- *A start at the tariff edge* (sim, 5 s meter): a give ends at 01:00 and the + cheap run starts. The battery reading drops at once, the meter a few + seconds later. In between, grid + batteries reads the house too low, the + room too big: the charge starts and the guard cuts it within seconds. +- *An oven cycling under a cheap-hours charge* (SAFETY-136 rig run C/s5b, x1): + the charge started at 01:00:32 in an oven pause and the guard cut it at + 01:01:31 when the oven came back on (5.3 kW projected). The cut is right, + but the charge stayed off to 01:15. + +**Decision.** +1. *The first guard stop in a period does not latch.* A charge the peak guard + stops (or a measured headroom stops in the period's first `YOUNG_S` = 60 s) + may start again `RESTART_S` = 60 s after that stop, + under the normal start rule (guard clear, headroom over `START_W`), but not + in the period's last 60 s: there the room is the deficit times 900/s left, + and a restart overshot by 15 W in the owner-shape night (N=2, 01:00). A + second stop latches to the period's end, so there is at most one restart + per period and the OPT-11 flip guard keeps its job. A measured headroom + stop later in the period latches at once, and an unmeasured headroom + (OPT-15) on its second stop, as before. Why only guard stops later on: all + three rig cases are guard stops, while a headroom that falls to 0 W mid + period is the slow loss of room the OPT-11 latch was made for (the + 2026-09-09 flips), so freeing it buys no case and risks that flip. + Three existing checks pinned "one start per period" and move with this: + `test_modes_p3.py` (a house swinging 2.0/3.9 kW each minute: now at most + two starts per period), `test_price_run_fixes.py` 1c (a 1-minute 3.7 kW + load: one restart after 60 s), and the `n1_ch` digest in + `test_modes_p4.py` (only the waiting reason word moved, "(peak)" for + "(headroom)"; with this card off it is OPT-15's pin again). +2. *No start while a give is still falling.* In a period's first `YOUNG_S`, + while the batteries give over `START_W` less than they did in the + last `GAVE_S` = 15 s, no charge starts: the meter may not show that drop + yet. A smaller drop does not hold the start. + +The guard is not touched (claim, floor, projection), so a real over-aim load +is cut on the same cycle as before, and a running charge is never held. While +a start waits, the status row says "grid charge paused, it tries again in a +minute" or "grid charge waits for the meter to catch up". + +**Options weighed.** +- *Round 1: only a stop in the first 60 s does not latch.* Missed the rig + oven case, cut at 91 s (review M-1). +- *Re-evaluation each cycle with no latch*: brings back the 13 flips in 4 + minutes the latch was made for (2026-09-09 replay). +- *Restart at once after the first stop*: two flips in 20 s with spikes at + 0/20 s (`test_safety135.py` part 5 fails on it). +- *No start in a young period within 60 s of a give or a guard action*: + 0.018 kWh (N=1) and 0.003 kWh (N=2) less than base on the owner night. +- *Cutting the young room by the recent give*: double-counts once the meter + catches up and flapped on a 1 s meter where base did not. +- *A hysteresis band*: the edge error is the readings' age, not a small room. + +**Numbers** (`scratch/SAFETY-135/dev/s135_sim.py`, real `cycle()`, TEST-23-like +lag, 1 s cycle, two 2.5 kW batteries unless said, cap 3 500 W, aim 3 450 W; +the sim's grid average per period): + +| Scenario | Base: paused s, kWh, flaps, top period | Head | +|---|---|---| +| (a) 4 s spike at 01:30 and 01:45, house 2.8 kW | 1 197 s, 0.330 kWh, 1, 3 458 W | 139 s, 0.537 kWh, 0, 3 458 W | +| (b) 01:00 edge after a give, 5 s meter, house 3.0 kW | 882 s, 0.006 kWh, 1, 3 009 W | 21 s, 0.119 kWh, 0, 3 464 W | +| (b) the same, house 2.4 kW | 0 s, 0.266 kWh, 0, 3 461 W | 11 s, 0.266 kWh, 0, 3 461 W | +| Rig s5b (5 kW + 4.6 kW, oven), 1 s / 5 s meter | 838 / 886 s, 0.054 / 0.035 kWh, 2 224 / 2 123 W | 793 / 793 s, 0.075 / 0.084 kWh, 2 299 / 2 286 W | +| (c) +4 kW for 5 min from 01:30:20 | cut 01:30:22, 0.387 kWh | cut 01:30:22, 0.492 kWh | +| Owner-shape night, N=1 / N=2 | 5.510 / 6.048 kWh, top 3 454 / 3 453 W | 5.510 / 6.169 kWh, 3 454 / 3 453 W | +| Owner-shape day, N=1 / N=2 | top 331 / 145 W | the same | + +In s5b the restart at 01:02:32 is cut again by the oven at 01:03:17 and then +latches: one restart, as designed. A +4 kW load from second 30, 57, 59, 60 or +61 (N=1 and N=2) is cut on the same cycle as base, the charge restarts only +after the load ends, and the period lands at 3 450.0 W (base 3 037-3 350 W). +The add-on's own period averages in `test_safety135.py` are at or under the +aim + 2 W in every part. + +**Sensitivity** (one constant moved, the others as shipped; head): + +| Constant | Spike (a): paused s, kWh | Edge (b) 5 s meter 3.0 kW: paused s, flaps | Rig s5b 1 s: kWh, period W | Owner night N=2: kWh, top W | +|---|---|---|---|---| +| `RESTART_S` 30 | 79, 0.541 | 21, 0 | 0.082, 2 321 | 6.206, **3 459** | +| `RESTART_S` 60 (shipped) | 139, 0.537 | 21, 0 | 0.075, 2 299 | 6.169, 3 453 | +| `RESTART_S` 90 | 199, 0.532 | 21, 0 | 0.061, 2 250 | 6.169, 3 453 | +| `RESTART_S` 120 | 259, 0.528 | 21, 0 | 0.085, 2 338 | 6.169, 3 453 | +| `GAVE_S` 5 | - | 75, **1** | 0.075, 2 299 | 6.170, 3 453 | +| `GAVE_S` 10 | - | 15, 0 | 0.075, 2 299 | 6.169, 3 453 | +| `GAVE_S` 15 (shipped) | - | 21, 0 | 0.075, 2 299 | 6.169, 3 453 | +| `GAVE_S` 30 | - | 35, 0 | 0.073, 2 290 | 6.168, 3 453 | +| `YOUNG_S` 30 / 90 | - | 21, 0 | 0.075, 2 299 | 6.169, 3 453 | + +`RESTART_S` 30 restarts the owner night in a period's last 30 s and lands +9 W over base's top period; 60 is the shortest value without that. In s5b +the value only moves where the restart meets the oven cycle. `GAVE_S` 5 s is +shorter than a 5 s meter's age and flaps again; 10-30 s only move the wait. +`YOUNG_S` does not move these runs: the give falls in the first seconds. + +On the synthetic night where the house alone is 950 W over the aim (N=1, +heat pump 4.4 kW), head's top period is 4 403 W against base's 4 401 W: a +charge restarted in the period before runs into the heat pump's start (the +carry-over below). Base charges 1.142 kWh there, head 1.560 kWh. + +**Not changed.** With battery modes off, `arbitrage.decide()` has no period +latch and sizes the charge to the headroom each cycle (SAFETY-45). A charge at +full power in a period's last seconds still runs into the next period (the +charge side of SAFETY-124); with rule 1 that costs 60 s, not the period. diff --git a/goodwe_controller/DECISIONS/SAFETY-136-slow-meter-settle.md b/goodwe_controller/DECISIONS/SAFETY-136-slow-meter-settle.md new file mode 100644 index 0000000..4818202 --- /dev/null +++ b/goodwe_controller/DECISIONS/SAFETY-136-slow-meter-settle.md @@ -0,0 +1,81 @@ +# SAFETY-136 - a slow meter gets a gentler loop until the last move shows + +**Status: for review.** Code: `app/settle.py`, a call in `Controller.cycle()` +(`app/ctl_cycle.py`). Tests: `test_safety136.py`. No option, no text change. + +**Problem.** On a 5 s meter, Home Assistant readings 10-15 s late are not +found (SAFETY-129): they look like a slow battery (R2-1), and a hold does not +help (a perfect one cut the export of the oven by 7 %, SAFETY-129 review). +With moving loads the loop answers the same stale error at each cycle and +overshoots: an oven, a kettle and hob, the owner's day or a step export 3-10 +times what they do with no lag. The fix is a calmer loop, not a detector. + +**Decision.** After a move of 150 W or more, a loop on a slow meter runs at half +its gain until the meter has fallen by half of that move, or for 2 cycles. +Slow is judged from the readings that arrive: the usual gap +between them, over the last 60 s and at least 5 readings, is over 3.75 s (the +limit of SAFETY-128's fast meter fit). It counts arrivals, not changes of +value: on the recorded day at 1-2 s the value-based test (`MeterFit.slow()`) +called 24 % of the cycles slow, because the recorded house repeats a value +for 5 s or more, and the commands then differed from base. So there is no +option. At a meter with a usual gap of 3.75 s or less (1-3 s) it is false, the tuning is never touched and the +commands are those of the tree before. A meter that Home Assistant passes on +only when its value changes looks as slow as its changes are far apart, as it +does to SAFETY-128's fits: a 1-2 s meter with a value that holds for 5 s or +more is then treated as slow, and the loop is gentler for it (the cost below). +With no lag the meter shows a move at the next reading, so the wait ends at +once. + +**Candidates** (SAFETY-129 sim, real `cycle()`, 5 s meter, sum over oven, +kettle and hob, owner shape over the oven and over the heat pump, step down, +step up, flat; export Wh, lag 0 / 10 s / 15 s; base 64 / 340 / 363): + +| Candidate, only at a slow meter | 0 s | 10 s | 15 s | Import Wh, 0 / 10 / 15 s | +|---|---|---|---|---| +| gain 0.4 | 97 | 201 | 299 | 97 / 224 / 301 | +| gain 0.3 | 128 | 185 | 322 | 132 / 232 / 293 | +| step limit 500 W | 118 | 285 | 293 | 110 / 325 / 324 | +| cut fast, raise slowly (0.6 / 0.3) | 55 | 140 | 226 | 140 / 332 / 345 | +| ignore 1 cycle after a move | 93 | 216 | 325 | 90 / 240 / 291 | +| ignore 2 cycles after a move, unless the meter showed half | 69 | 206 | 277 | 62 / 240 / 354 | +| **half gain for 2 cycles after a move, unless the meter showed half** | **67** | **189** | **296** | **62 / 223 / 288** | + +A lower gain for good, a step limit and a fixed ignore all make a 5 s meter +with no lag worse (export +30-110 Wh, quarter peak up to 150 W): that is the +common case. Cutting fast and raising slowly moves export to import and peak. +Waiting only while the last move has not shown costs nothing with no lag. +Ignoring the meter (the 2-cycle line) was worse than half gain where the plant +is slow, not the readings late: a 12 s dead time with one inverter went from +250 to 841 Wh import and a quarter peak of 206 to 1 509 W, so the loop keeps +following at half gain. + +**What it gives** (5 s meter; the pull request and the report have each +scenario). Export summed over the seven houses: 10 s late 340 -> 189 Wh +(-44 %, import 363 -> 223), 15 s late 363 -> 296 Wh (-19 %, import 281 -> +288), together -31 %. At 15 s the oven and the owner's oven are not better +(92 / 39 Wh against 91 / 37), the kettle and the steps are. No lag: export +64.4 -> 66.5 Wh (kettle +2), import and peak the same. + +**What it costs.** The loop follows a real step more slowly: half gain for up +to two cycles after each move of 150 W or more. Of the 136 sim runs (every +SAFETY-129 review scenario and its 15 harm runs), 56 at 4-10 s meters differ +from base. Together their export is 10 363 -> 9 559 Wh (-8 %) and import +8 389 -> 7 835 Wh (-7 %). Only 5 export more than 1 Wh and 14 import more: +export by at most 11.5 Wh (a 10 s battery lag, +10 %), import by at most +17 Wh (a 12 s dead time, one inverter, +7 %), and the quarter average by at +most 35 W, except two import quarters: +73 W (10 s meter, 10 s dead time, +export -59 Wh) and +40 W (`dead10_p6`, -6 to 34 W, export -68 Wh). Slow +batteries with a dead time of 8-10 s export 5-39 % less; a 12 s dead time is +the same. `READINGS_LATE` holds are the same seconds in every run. + +**Live, a 1-2 s meter can be judged slow.** Through Home Assistant on change, +a value that holds for 4-10 s makes a 1 s meter slow. In 20 rig scenarios the +commands were those of base. On the recorded day (1 s, N=1, 1 day, repeats +dropped; its values hold about 5 s) it was slow in 33 % of cycles, half gain +in 83 cycles, 15 422 commands in both trees, 4 016 with another value (at +most 190 W apart), cost 0.61 EUR in both (review of SAFETY-136). + +**Does not change.** Meters of 1-2 s: the same commands in all 63 runs (34 +at 1 s, 29 at 2 s), and the recorded-day digests (see the report). The late +verdict, the hold and the freeze tests. 15 s late is only partly helped, and +30 s late is the hold's (SAFETY-129). diff --git a/goodwe_controller/DECISIONS/SAFETY-32-per-pack-bms-floor.md b/goodwe_controller/DECISIONS/SAFETY-32-per-pack-bms-floor.md index d9a5dce..9e4553e 100644 --- a/goodwe_controller/DECISIONS/SAFETY-32-per-pack-bms-floor.md +++ b/goodwe_controller/DECISIONS/SAFETY-32-per-pack-bms-floor.md @@ -709,7 +709,7 @@ rather than smuggled in. **Also still not in this card, and named by the shipped code already:** the charge *ceiling* is the mirror image — `pack_floor_soc` is the wrong reduction for it, because a ceiling is the **fullest** pack and `arbitrage`'s `soc_ceiling` -takes one number. `main.py:932-936` says so, and it belongs to CFG-04/SPIKE-04's +takes one number. The `Controller.pack_floor_soc` docstring in `app/main.py` says so, and it belongs to CFG-04/SPIKE-04's per-pack bound. Nothing here touched it. ## 6. What was changed, and one thing that was found on the way diff --git a/goodwe_controller/app/ctl_alarms.py b/goodwe_controller/app/ctl_alarms.py new file mode 100644 index 0000000..d7eabc0 --- /dev/null +++ b/goodwe_controller/app/ctl_alarms.py @@ -0,0 +1,461 @@ +"""Controller methods that raise and clear the alarms. + +Moved unchanged from app/main.py (MAINT-21). DECISIONS/MAIN-orchestration.md.""" + +import logging +from datetime import datetime, timedelta, timezone + +from . import allocator +from . import control as _ctl +from .circulation import opposing +from .clamp import ( + REASON_CODE as CLAMP_REASON, delivery_short, shortfall_note, + write_clamp_note, +) +from . import messages +from .mqtt import unit_slugs +from . import peakguard +from .price import brussels +from .price_chain import fixed_tariff_beside_service +from .ctl_writes import REFUSED_SPAN_S +from .ctl_inputs import _mono + +_LOG = logging.getLogger("goodwe") + + +# SAFETY-34: a Core-only restart wipes persistent_notification without +# restarting this add-on, so a latched alarm is re-asserted this often. +REANNOUNCE_S = 300.0 + + +# SAFETY-85: a battery another owner set is graded against the least it was +# told over the plant's settle time, so a battery still settling is not short. +SHORT_CYCLES, SHORT_SPAN_S = _ctl.SETTLE_CYCLES, REFUSED_SPAN_S + + +# SAFETY-119/121: after a hand-back the loop's bound is hidden for +# HANDBACK_CYCLES / SHORT_SPAN_S, and across hand-backs on at most +# ROLLING_BOUND_CYCLES cycles per ROLLING_S +# (DECISIONS/SAFETY-121-bound-every-quarter.md). Without a monotonic clock the +# budget never refills. +HANDBACK_CYCLES = 4 + + +ROLLING_S = 900.0 + + +ROLLING_BOUND_CYCLES = 11 + + +class AlarmsMixin: + def _loop_alarm_input(self, resolution) -> None: + """SAFETY-85. The loop's clamp counts only on a cycle the loop decided + (a rating may cut it). A battery another owner set to discharge counts + when it gave less than it was told for `saturation_cycles` cycles in a + row. DECISIONS/SAFETY-85-no-false-not-keeping-up.md""" + d = self._loop_decision + if d is None: + self._short_run = 0 + self._asked_hist = {} + self._wire_lost, self._handback = False, None + return + unmet = self.allocation.unmet_w if self.allocation is not None else 0 + cut = (resolution.bound_by or "").split("(")[0] + owns = (resolution.winner == "loop" and not d.held and not unmet + and (resolution.target_w == d.target_w + or cut in ("device", "supervised"))) + # Graded against the least that stood on the wire (0 W in shadow + # mode) over SHORT_CYCLES cycles and SHORT_SPAN_S seconds. + now, asked = self._now_mono, {} + for inv in self.inverters: + h = self._asked_hist.setdefault(inv.name, []) + h.append((now, inv.standing_w())) + while len(h) > SHORT_CYCLES and ( + now is None or h[0][0] is None + or now - h[0][0] > SHORT_SPAN_S): + h.pop(0) + asked[inv.name] = min(w for _t, w in h) + others = [inv for inv in self.inverters if not owns + or allocator.pin_w(resolution.unit_bounds.get(inv.name)) + is not None] + short = [(inv, asked[inv.name], inv.batt) for inv in others + if inv.batt is not None + and delivery_short(asked[inv.name], inv.batt, + self.tuning.saturation_w)] + self._short_run = self._short_run + 1 if short else 0 + settling = self._settling(owns, now) + if owns and self.loop_clamped[0] and not ( + settling and not self.loop_clamped[2]): + return + engaged = self._short_run >= self.tuning.saturation_cycles + named = len(self.inverters) > 1 + self.loop_clamped = (engaged, shortfall_note( + [(inv.name if named else None, a, g) for inv, a, g in short]) + if engaged else "", False) + self.loop_clamp_facts = () + + def _settling(self, owns, now) -> bool: + """SAFETY-119: does the loop's bound on this cycle count? Not within a + settle (HANDBACK_CYCLES cycles and SHORT_SPAN_S) after another owner + handed the wire back; across all hand-backs the bound is hidden on at + most ROLLING_BOUND_CYCLES cycles in any ROLLING_S. + DECISIONS/SAFETY-121-bound-every-quarter.md""" + def aged(t0, span): + return now is None or t0 is None or now - t0 >= span + + if not owns: + self._wire_lost, self._handback = True, None + return False + if self._wire_lost: + self._wire_lost, self._handback = False, (now, 0) + if self._handback is None: + return False + tc, n = self._handback + n += 1 + self._handback = (tc, n) + if aged(tc, SHORT_SPAN_S) and n >= HANDBACK_CYCLES: + self._handback = None + return False + if self.loop_clamped[0] and not self.loop_clamped[2]: + kept = tuple(t for t in self._hidden if now is None or ( + t is not None and now - t < ROLLING_S)) + if len(kept) >= ROLLING_BOUND_CYCLES: + self._hidden = kept + return False + self._hidden = kept + (now,) + return True + + async def check_output_clamp(self) -> None: + """SAFETY-03. Alarm whenever a clamp actually engaged this cycle. Runs + AFTER write_setpoint() (the clamp is arithmetic done inside the write). + ⚠️ PUBLISHING IS NOT IN THE WRITE PATH: a stalled supervisor must never + delay or drop a frame. ⚠️ THIS IS NOT A TRIP: no claim, no latch, 0 W + is not commanded (§11.2: clamp and alarm); turning it into one is a + deliberate change. (DECISIONS/MAIN-orchestration-archive.md)""" + # ⚠️ THE EVIDENCE IS PER UNIT AND THE ALARM IS NOT: `clamp_last` is on + # the Inverter, `ClampWatchdog` is one per controller (an anti-flood + # counter), so any unit that clamped is an engagement and the reason + # names it. (DECISIONS/MAIN-orchestration-archive.md) + clamped_units = [inv for inv in self.inverters + if inv.clamp_last is not None and inv.clamp_last.engaged] + engaged_write = bool(clamped_units) + engaged_loop, loop_note, loop_bug = self.loop_clamped + engaged = engaged_write or engaged_loop + # SAFETY-40: only an over-rating is a bug; the integrator bound is not. + bug = engaged_write or loop_bug + if engaged_write: + _named = len(self.inverters) > 1 + reason = write_clamp_note([(inv.name if _named else None, + inv.clamp_last) + for inv in clamped_units]) + facts = [messages.Clamp(inv.name if _named else None, + inv.clamp_last.requested_w, + inv.clamp_last.applied_w, + inv.clamp_last.bound) + for inv in clamped_units] + else: + reason = loop_note if engaged else "" + facts = self.loop_clamp_facts if engaged else () + fired = self.clamp_wd.note(engaged, reason, datetime.now(timezone.utc), + bug=bug, facts=facts) + + # THE ACTION LOG IS COALESCED PER EPISODE: consecutive engagements + # update one row's count. ⚠️ NOT COSMETIC: the log keeps 40 rows and a + # winding loop clamps every cycle, so a row each flushed SAFETY-18's + # "METER FROZEN?" row. Here as well as in write_setpoint() because on a + # default install the actuator-side clamp is unreachable. + # (DECISIONS/MAIN-orchestration-archive.md) + if engaged and not engaged_write: + tag = f"{CLAMP_REASON} episode {self.clamp_wd.episodes}" + row = (f"{tag}: " + f"{messages.count(self.clamp_wd.engagements, 'engagement')}" + f" - {reason}") + if self.events and tag in self.events[0]: + stamp = self.events[0].split(" ", 1)[0] + self.events[0] = f"{stamp} {row}" + else: + self.log_event(row, hint=messages.hint( + "power_too_high" if bug else "not_keeping_up")) + if not fired: + return + if not self.clamp_wd.bug: + # SAFETY-40: the integrator bound is anti-windup, not a bug - a + # WARNING and a plainly titled notice, same cadence. Its OWN id, so + # it can never replace a BUG SIGNAL notice still on screen. + _LOG.warning("The battery gives less than asked: %s. Held back %s " + "so far.", messages.reason_code(self.clamp_wd.reason), + messages.times(self.clamp_wd.engagements)) + _LOG.debug("Evidence: %s.", self.clamp_wd.reason) + _LOG.debug("A short hold after a large load or solar step is " + "normal. If it lasts, check that the battery follows " + "its commands.") + await self.hass.call("persistent_notification", "create", + messages.loop_bound().data()) + return + _LOG.error( + "Power request too high, a software fault: %s. Cut back %s so " + "far, control runs on.", messages.reason_code(self.clamp_wd.reason), + messages.times(self.clamp_wd.engagements)) + _LOG.debug("Evidence: %s.", self.clamp_wd.reason) + _LOG.debug( + "SAFETY-03: silently clipping this is how a winding integrator " + "reached 14 768 W on this project before. The clamp makes every " + "dashboard read a legal number while the thing producing it goes " + "on climbing. This is an alarm, not a trip.") + # A fixed notification_id, for the reason check_meter_frozen() gives - + # and a DIFFERENT one from every other alarm this add-on raises, + # because a clamp is not a frozen meter and neither is a saturation + # freeze. (DECISIONS/MAIN-orchestration-archive.md) + await self.hass.call("persistent_notification", "create", + messages.output_clamp(self.clamp_wd.facts, + shadow=self.shadow).data()) + + async def check_peak_saturated(self) -> None: + """SAFETY-07. Alarm ONLY when the guard has run out of inverter. ⚠️ An + engagement is not an alarm: a peak floor above the rating is a house + load bigger than the inverter, not a defect (unlike SAFETY-03's winding + integrator). SAFETY-81: `g.saturated` must agree with + `peakguard.load_too_high()` for `ALARM_HOLD_S`. Edge-triggered: one + notification per episode, at most once per quarter. + (DECISIONS/MAIN-orchestration-archive.md)""" + g = self.peak_guard + batt, prev = self.site_batt_w, self._peak_batt_prev + if batt is None: + # Unknown, not "fine": the hold below neither grows nor restarts. + return + self._peak_batt_prev = batt + if prev is not None: + batt = min(float(batt), float(prev)) + p = self._peak_proj + # OPT-15 x SAFETY-81: until the new quarter's first sample the old + # projection read "no seconds left" (not high), which restarted the + # hold; a rolled one (battery modes on) is not graded then, so a + # persistent overload is still notified once per quarter. + high = bool( + g is not None and g.saturated and p is not None + and p.block_start is not None and not self._peak_rolled + and peakguard.load_too_high( + p, batt_w=batt, ceiling_w=g.ceiling_w, + achievable_w=self.site_rating_w)) + # SAFETY-81: and for ALARM_HOLD_S, on the projection's clock. + saturated = False + if high: + t = p.block_start + timedelta(seconds=float(p.elapsed_s)) + if self._peak_high_since is None: + self._peak_high_since = t + saturated = ((t - self._peak_high_since).total_seconds() + >= peakguard.ALARM_HOLD_S) + else: + self._peak_high_since = None + was, self._peak_saturated = self._peak_saturated, saturated + if not saturated or was: + return + _LOG.error( + "Switch off large loads, the battery alone cannot keep this " + "15-minute period under the peak limit: %s.", + messages.reason_code(g.reason)) + _LOG.debug("Evidence: %s.", g.reason) + # SAFETY-81: notified once per quarter; a later episode is logged only. + if p.block_start == self._peak_alarm_block: + return + self._peak_alarm_block = p.block_start + self.log_event("PEAK_GUARD_SATURATED - " + g.reason, + hint=messages.hint("peak_saturated")) + # A fixed notification_id, and a DIFFERENT one from every other alarm + # here - check_meter_frozen() gives the reasoning. A saturated peak guard + # is not a frozen meter and is not an out-of-range setpoint. + await self.hass.call("persistent_notification", "create", + messages.peak_saturated( + g.ceiling_w, shadow=self.shadow).data()) + + async def check_peak_floor_limited(self) -> None: + """SAFETY-24. Alarm when the EMS SoC floor stops the guard shaving. ⚠️ + FAILING TO SHAVE MUST NOT BE SILENT (the capacity tariff bills the + month's worst quarter). Not check_peak_saturated(): that is shed-load, + this is nothing discharged; never both. ⚠️ SAFETY-25: the message says + the floor binds this guard only; the loop has no SoC floor and goes on + discharging. Edge-triggered. (DECISIONS/MAIN-orchestration-archive.md)""" + g = self.peak_guard + limited = bool(g is not None and g.floor_limited) + if limited and (g.floor_w or 0.0) > 0.0: + limited = self._reserve_short(g) + else: + self._reserve_batt_prev = self._reserve_high_since = None + # SAFETY-126: nothing can give, so it alarms at once, but only + # when the quarter really misses the aim (`_peak_landing()`). + limited = limited and not g.within_aim + was, self._peak_floor_limited = self._peak_floor_limited, limited + if not limited or was: + return + # No prefix: `reason` already opens with PEAK_GUARD_FLOOR_LIMITED, and + # a second copy is the kind of stutter that makes a 40-line action log + # read like boilerplate. (DECISIONS/MAIN-orchestration-archive.md) + self.log_event(g.reason, hint=messages.hint("peak_reserve")) + _LOG.error( + "Switch off large loads, the peak guard may not draw the battery " + "lower: %s.", messages.reason_code(g.reason)) + _LOG.debug("Evidence: %s.", g.reason) + # A fixed notification_id, and a DIFFERENT one from every other alarm + # here - check_meter_frozen() gives the reasoning. ⚠️ SAFETY-25's + # sentence (the reserve binds the peak guard only) is in + # messages.peak_reserve() on every branch, unreadable SoC included. + # (DECISIONS/MAIN-orchestration-archive.md) + await self.hass.call("persistent_notification", "create", + messages.peak_reserve( + g.ceiling_w, soc_unread=g.soc is None, + floor_unknown=(g.soc is not None + and g.soc_floor is None), + packs=(g.held if len(self.inverters) > 1 + else ()), + others=(g.floor_w or 0.0) > 0.0).data()) + + def _reserve_short(self, g) -> bool: + """SAFETY-87: the batteries that can still give, at full power, miss + the limit (`load_too_high()` on `g.able_w`), for ALARM_HOLD_S, as + SAFETY-81 grades 'Load too high'.""" + p, batt = self._peak_proj, self.site_batt_w + if batt is None: + return self._peak_floor_limited + prev, self._reserve_batt_prev = self._reserve_batt_prev, batt + if prev is not None: + batt = min(float(batt), float(prev)) + if not (p is not None and p.block_start is not None + and peakguard.load_too_high(p, batt_w=batt, + ceiling_w=g.ceiling_w, + achievable_w=g.able_w)): + self._reserve_high_since = None + return False + t = p.block_start + timedelta(seconds=float(p.elapsed_s)) + if self._reserve_high_since is None: + self._reserve_high_since = t + return ((t - self._reserve_high_since).total_seconds() + >= peakguard.ALARM_HOLD_S) + + async def check_circulating(self) -> None: + """SAFETY-31 + SAFETY-34. The alarm, and it must survive a restart. ⚠️ + THE LATCH IS NOT THE ALARM: the notification is in memory, so + `_circ_announced` (per-PROCESS, not persisted) makes a restart re-raise + it, and REANNOUNCE_S re-asserts it after a Core-only restart. ⚠️ ONE + CODE PATH for a fresh trip and a restart into one. + (DECISIONS/MAIN-orchestration-archive.md)""" + if not self.circ_wd.tripped: + return + if self._circ_announced and not self._reannounce_due("goodwe_circulating_power"): + return + # Set BEFORE the await. `hass.call()` can raise or hang, and a retry + # every cycle for a broker that is down would be an alarm storm on the + # event bus on top of a site that is already stopped. + # (DECISIONS/MAIN-orchestration-archive.md) + self._circ_announced = True + self._announced_mono["goodwe_circulating_power"] = _mono() + names = self.units + pos, neg = opposing([inv.batt for inv in self.inverters], + min_w=self.circ_wd.cfg.min_w / 2.0) + # A fixed notification_id, and a DIFFERENT one from every other alarm + # this add-on raises - check_meter_frozen() gives the reasoning. + await self.hass.call("persistent_notification", "create", + messages.circulating( + [names[i] for i in pos] if pos and neg else (), + [names[i] for i in neg] if pos and neg else (), + ).data()) + + def _reannounce_due(self, notification_id: str) -> bool: + """SAFETY-34: has this latched alarm gone REANNOUNCE_S without being re-asserted?""" + t = self._announced_mono.get(notification_id) + return t is None or _mono() - t >= REANNOUNCE_S + + async def check_not_delivering(self) -> None: + """SAFETY-42 + SAFETY-34. The alarm, and it must survive a restart. ⚠️ + THE LATCH IS NOT THE ALARM: the notification is in memory, so + `_delivery_announced` (a per-PROCESS set of unit names, not persisted) + makes a restart re-raise it, and REANNOUNCE_S re-asserts it. ⚠️ ONE + CODE PATH for a fresh trip and a restart into one. ⚠️ ONE ID PER UNIT + (`unit_slugs()`): two wedged inverters give two cards. + (DECISIONS/MAIN-orchestration-archive.md)""" + names = self.units + slugs = unit_slugs(names) + for inv, slug in zip(self.inverters, slugs): + nid = f"goodwe_not_delivering_{slug}" + if not inv.delivery_wd.tripped: + continue + if inv.name in self._delivery_announced and not self._reannounce_due(nid): + continue + # Added BEFORE the await, for `check_circulating()`'s reason: + # `hass.call()` can raise or hang, and a retry every cycle for a + # broker that is down would be an alarm storm on the event bus. + # (DECISIONS/MAIN-orchestration-archive.md) + self._delivery_announced.add(inv.name) + self._announced_mono[nid] = _mono() + await self.hass.call("persistent_notification", "create", + messages.not_delivering(inv.name, slug).data()) + + async def check_price_gap(self) -> None: + """PRICE-01. One notification when no price covers now, gone when one + does. (DECISIONS/MAIN-orchestration-archive.md)""" + if self.price_gap and not self._price_gap_announced: + self._price_gap_announced = True + await self.hass.call("persistent_notification", "create", + messages.no_prices(*self._gap_args()).data()) + elif not self.price_gap and self._price_gap_announced: + self._price_gap_announced = False + await self.hass.call("persistent_notification", "dismiss", + messages.prices_back().data()) + + async def check_fixed_note(self) -> None: + """PRICE-01 G1. First cycle only: one INFO line when `static_profile` + sits beside `price_service` (the plan's last fallback, not a fault, so + no notification). (DECISIONS/MAIN-orchestration-archive.md)""" + if self._fixed_note_said: + return + self._fixed_note_said = True + if fixed_tariff_beside_service(self.o): + _LOG.info(messages.FIXED_TARIFF_LOG) + try: + await self.hass.call("persistent_notification", "dismiss", + messages.fixed_tariff_card_gone().data()) + except Exception: # noqa: BLE001 - housekeeping never stops a cycle + _LOG.debug("Could not take down the old fixed-tariff card.") + + def _gap_args(self) -> tuple: + """`(since, now)` in Brussels time for the gap's words. `since` is None + when no price was ever published.""" + now = brussels(datetime.now(timezone.utc)) + if self.price_gap_since is None: + return None, now + return brussels(self.price_gap_since), now + + async def check_meter_frozen(self) -> None: + """SAFETY-18. Alarm on a meter that answers forever without changing. + Notification only: no claim, no latch, no 0 W (freeze.py carries the + reasoning). getattr, not an attribute access: `unchanged_s` exists only + on `homewizard_local`, and `p1_source` is None until amain() builds the + transport. (DECISIONS/MAIN-orchestration-archive.md)""" + unchanged = getattr(self.p1_source, "unchanged_s", None) + # SITE, all three inputs: one meter, the SITE target the arbiter + # resolved, and the rail the SITE could stand at - which is the summed + # per-unit conjunction, so a small inverter B lowers the site rail rather + # than being graded against inverter A's. + fired = self.freeze_wd.evaluate(unchanged, self.target, + self.site_max_w, + datetime.now(timezone.utc), + dev_min=self.site_dev_bound("dev_min"), + dev_max=self.site_dev_bound("dev_max")) + if not fired: + return + self.log_event("METER FROZEN? " + self.freeze_wd.reason, + hint=messages.hint("meter_frozen")) + _LOG.error( + "The meter shows the same value while the battery is asked for " + "full power, and control still follows it, so check the meter: " + "%s.", messages.reason_code(self.freeze_wd.reason)) + _LOG.debug("Evidence: %s.", self.freeze_wd.reason) + _LOG.debug( + "SAFETY-18: nothing else stops this. The meter still answers, so " + "its age is fresh, the firmware watchdog is fed and the arbiter " + "only bounds the magnitude. Kept up for a quarter of an hour, it " + "sets the month's billed capacity peak.") + # ⚠️ A fixed notification_id, so a second episode REPLACES the first + # rather than stacking. An operator who has to dismiss eleven identical + # notifications learns to dismiss the twelfth without reading it. + await self.hass.call("persistent_notification", "create", + messages.meter_frozen(unchanged).data()) diff --git a/goodwe_controller/app/ctl_cycle.py b/goodwe_controller/app/ctl_cycle.py new file mode 100644 index 0000000..873e746 --- /dev/null +++ b/goodwe_controller/app/ctl_cycle.py @@ -0,0 +1,1125 @@ +"""Controller.cycle(): one control cycle, whole. + +Moved unchanged from app/main.py (MAINT-21). DECISIONS/MAIN-orchestration.md.""" + +import asyncio +import logging +import math +from datetime import datetime, timedelta, timezone + +from . import arbitrage +from .arbiter import ( + Claim, P_LOOP, P_MAINTENANCE, P_MAINT_SHAPE, P_MODE, P_SAFETY, Resolution, + resolve, +) +from . import packmode +from . import control as _ctl +from .control import compute, maintenance_charge_floor +from .delivery import UnitDelivery, account as delivery_account, delinquent +from .clamp import loop_clamp_note +from . import messages +from .freeze import looks_frozen +from .maintenance import ( + FAIL_BACKOFF_DAYS, IDLE, MaintResult, arbitrate as maint_arbitrate, +) +from .mqtt import unit_slugs +from . import peakguard +from . import packshare +from . import shadow +from .price import Uncertainty +from .tariff import next_quarter +from .watchdog import loop_is_following +from .ctl_trade import pack_energy_of +from .rows import why_key, why_raised + +_LOG = logging.getLogger("goodwe") + + +def _refused_interval(sign: int) -> tuple: + """SAFETY-73: the (lo, hi) a refusing unit may be asked: 0 W that way.""" + return (-math.inf, 0.0) if sign > 0 else (0.0, math.inf) + + +class CycleMixin: + async def cycle(self) -> None: + """Gather claims, resolve precedence, write the winner. Nothing here + decides who wins (arbiter.py does, by one rule); this method only + states what each strategy wants. + (DECISIONS/MAIN-orchestration-archive.md)""" + now = datetime.now(timezone.utc) + # BEFORE the first `return` of this method on purpose (TARIFF-11): it + # stamps that a cycle RAN, a different fact from the decisions it may + # reach. + self.cycle_at = now + + # Each pack on ITS OWN reading, not "the SoC": 12's recalibration + # drains and refills ONE pack and grades ONE coulomb counter; a minimum + # would abort on a sibling's state and an average would declare a pack + # full that is not. `arbitrate()` runs first, once, over all of them. + _off = ({inv.name for inv in self.inverters + if not self.pack_mode(inv).use} if self.modes_on else set()) + for inv, machine in zip(self.inverters, self.maints): + if inv.name in _off: + self._maint_stop_off(machine, now) + _on = [m for inv, m in zip(self.inverters, self.maints) + if inv.name not in _off] + _plan_on = iter(maint_arbitrate(_on, now) if _off + else maint_arbitrate(self.maints, now)) + maint_plan = [None if inv.name in _off else next(_plan_on) + for inv, _m in zip(self.inverters, self.maints)] + maint_results = [] + for inv, machine, blocked in zip(self.inverters, self.maints, maint_plan): + if blocked is None: + maint_results.append(MaintResult(IDLE, False, None, False, [])) + continue + # MAINT-13: the charge timeout counts only the minutes the pack was + # allowed to charge (see `_charge_gate_open`). + res = machine.tick(now, inv.soc, blocked_by=blocked, + gate_open=self._charge_gate_open(inv)) + for msg in res.events: + self.log_event(msg, hint=messages.hint( + "maint_failed" if res.failed else "maintenance", + phase=machine.phase)) + if res.failed: + # Said once: only the tick that failed carries `res.failed`. + multi = len(self.inverters) > 1 + slug = (unit_slugs(self.units)[self.inverters.index(inv)] + if multi else "battery") + await self.hass.call( + "persistent_notification", "create", + messages.maint_failed( + res.failed, FAIL_BACKOFF_DAYS, + unit=inv.name if multi else "", slug=slug).data()) + maint_results.append(res) + # Carried to the status page, not left in the 40-line action log: the + # deferral is edge-logged, and a pack that is due, idle and WAITING + # must be able to say so when looked at (12's failure mode is a + # schedule that silently stops firing). + self._maint_deferred = [(m.name, r.deferred) + for m, r in zip(self.maints, maint_results) + if r.deferred] + + # SAFETY-02, and it runs BEFORE the early return below: evaluated every + # cycle, else a run of held cycles leaves `disagree_since` untouched + # and the timer resumes from a start time that predates the gap. One + # watchdog per inverter on that inverter's own reading; what it is + # compared against is decided by the roster (SAFETY-30). + self._arm_sign_watchdogs() + n_units = len(self.inverters) + standing = {} + for inv in self.inverters: + was_tripped = inv.sign_wd.tripped + # `Inverter.standing_w()`, not the expression it replaces: + # SAFETY-37's freshness gate arms off the same method. + stood = inv.standing_w() + standing[inv.name] = stood + against = self.grid if n_units <= 1 else inv.batt + if inv.sign_wd.evaluate(stood, against, self.following, now) \ + and not was_tripped: + # REASON first, FLAG second (each `set` writes the file): a + # crash between the two persists a reason nothing reads, not a + # latch with no explanation. Both keys are namespaced to this + # unit. + inv.store_set("sign_reason", inv.sign_wd.reason) + inv.store_set("sign_tripped", True) + # The legacy flat keys are MIRRORED, the other half of store.py + # rule 2: that rule only covered the latch existing at + # migration time, so a trip after it wrote nothing flat and a + # rollback would find no latch. + self.store.set("sign_reason", inv.sign_wd.reason) + self.store.set("sign_tripped", True) + self.log_event(f"FAILSAFE {inv.name}: " + inv.sign_wd.reason, + hint=messages.hint("direction", unit=inv.name)) + _LOG.error("%s is set to 0 W until control is started, " + "because its power went the wrong way: %s.", + inv.name, messages.reason_code(inv.sign_wd.reason)) + _LOG.debug("Evidence for %s: %s.", inv.name, + inv.sign_wd.reason) + # The site's own standing command is the SUM of the units': SAFETY-07 + # and SAFETY-18 grade a SITE quantity (the quarter average at the grid + # connection; a meter not moving while the site pushes near its rail). + # Same number at a roster of one. + site_standing = float(sum(standing.values())) + + # SAFETY-30: the site half of the sign check: the TOTAL standing on the + # wire against the meter, catching a fault no per-unit check sees + # (every unit faithfully executing the wrong total). Only at N>=2 (at + # one inverter it would duplicate `inverters[0].sign_wd`; AC 8). Flat + # keys, not namespaced. + if n_units > 1: + was_site = self.site_sign_wd.tripped + if self.site_sign_wd.evaluate(site_standing, self.grid, + self.following, now) and not was_site: + # REASON first, FLAG second, as the per-unit trip and + # SAFETY-31. The keys are flat, not namespaced, and not the + # per-unit pair (store.py). + self.store.set("site_sign_reason", self.site_sign_wd.reason) + self.store.set("site_sign_tripped", True) + self.log_event("FAILSAFE site: " + self.site_sign_wd.reason, + hint=messages.hint("site_direction")) + _LOG.error("Every inverter is set to 0 W until control is " + "started, because the total power went the wrong " + "way: %s.", + messages.reason_code(self.site_sign_wd.reason)) + _LOG.debug("Evidence for the site: %s.", + self.site_sign_wd.reason) + + # SAFETY-31, beside SAFETY-02 for the same reason: evaluated EVERY + # cycle, unconditionally, above the input hold (else `over_since` + # resumes from a start that predates the gap). The input is MEASURED + # power, never commanded: a unit ignoring or lagging its share, a stale + # share still executing. + circ_w = self.site_circulating_w + was_circ = self.circ_wd.tripped + if self.circ_wd.evaluate(circ_w, now) and not was_circ: + # REASON first, FLAG second (each `set` writes the file): a crash + # between must not persist a latch with no explanation. + self.store.set("circ_reason", self.circ_wd.reason) + self.store.set("circ_tripped", True) + self._circ_announced = False + self.log_event("CIRCULATING POWER - " + self.circ_wd.reason, + hint=messages.hint("circulating")) + _LOG.error( + "Every inverter is set to 0 W until control is started, " + "because the inverters worked against each other: %s.", + messages.reason_code(self.circ_wd.reason)) + _LOG.debug("Evidence for the site: %s.", self.circ_wd.reason) + + # SAFETY-42, for SAFETY-02's and SAFETY-31's reason: evaluated every + # cycle above the input hold. The operands are `standing` and + # `inv.batt`, the pair SAFETY-30 uses. `delinquent()` is called once + # over the whole roster, and every number is the configured one, never + # a literal that could drift (`self.delivery_cfg`, not + # `DeliveryConfig()`: part 4b grades a hold that is not the shipped 185 + # s). + for inv in self.inverters: + # `self.delivery_cfg`, not `DeliveryConfig()`: the window is + # `delivery_hold_s`, and part 4b grades a hold that is not the + # shipped 185 s. + inv.delivery_wd.arm(self.delivery_cfg) + _delinquent = delinquent( + [UnitDelivery( + inv.name, standing[inv.name], inv.batt, + delivery_account( + # ⚠️ `is_live()` AT ITS OWN DEFAULT WINDOW, which is + # `LINK_STALE_S` - the SAME call `live_units()` makes for + # the allocator. (DECISIONS/MAIN-orchestration-archive.md) + live=inv.is_live(now)[0], + # SAFETY-73: a refusing unit is asked 0 W on purpose, and + # one asked under PROBE_W that gives under 100 W is a + # refusal too small to call (its sibling covers the meter). + parked=inv.sign_wd.tripped or bool(inv.refused) or ( + n_units > 1 and inv.batt is not None + and abs(float(standing[inv.name])) <= _ctl.PROBE_W + and abs(float(inv.batt) - inv.idle_w) + < _ctl.REFUSED_BELOW_W), + # ⚠️ THIS UNIT'S OWN CUT-OUT (`bms_floor`): not the shipped + # 10 % and not the site's `peak_soc_floor`, which bounds a + # money-saving discharge only. + # (DECISIONS/MAIN-orchestration-archive.md) + soc=inv.soc, bms_floor=inv.bms_soc_floor)) + for inv in self.inverters], + self.tuning.saturation_w) + for inv in self.inverters: + was_short = inv.delivery_wd.tripped + if inv.delivery_wd.evaluate(_delinquent.get(inv.name), now) \ + and not was_short: + # REASON FIRST, FLAG SECOND, and each `set` writes the file (as + # the three trips above): a crash between must not persist a + # latch with no explanation. ⚠️ NO FLAT MIRROR OF THIS PAIR, + # unlike SAFETY-02: store.py's rule 2 keeps flat keys so a + # rollback finds its latch, but the version rolled back TO + # drives one actuator, where this check is inert; a mirror + # would hand it a latch about a roster it cannot have. + # DECISIONS/MAIN-orchestration.md. + inv.store_set("delivery_reason", inv.delivery_wd.reason) + inv.store_set("delivery_tripped", True) + self._delivery_announced.discard(inv.name) + self.log_event(f"NOT DELIVERING {inv.name}: " + + inv.delivery_wd.reason, + hint=messages.hint("not_delivering", + unit=inv.name)) + _LOG.error( + "%s is not delivering while control keeps running, and " + "only stopping and starting control clears this: %s.", + inv.name, messages.reason_code(inv.delivery_wd.reason)) + _LOG.debug("Evidence for %s: %s.", inv.name, + inv.delivery_wd.reason) + _LOG.debug( + "SAFETY-42 reports and does not act: commanding a unit " + "that is not listening achieves nothing (HW-01), and the " + "only re-allocation the add-on can express would throw " + "away a partly delivering unit's output.") + + stale_after = float(self.o.get("stale_input_s", 15)) + late_s = self._readings_late(site_standing) # SAFETY-128 + self._late_zero = late_s is not None and late_s >= stale_after + # ⚠️ `any`, NOT the sole unit's. The hold exists so a single missed + # poll does not become a fault; a LATCHED inverter must still reach the + # claim list below, because its `failsafe` SET is what parks it. + # SAFETY-30's site latch takes the roster past the hold too (its + # `sign_site` SET parks every inverter): the trip would stop acting the + # moment a poll was missed. (DECISIONS/MAIN-orchestration-archive.md) + if not self.inputs_ok and not any(i.sign_wd.tripped + for i in self.inverters) \ + and not (n_units > 1 and self.site_sign_wd.tripped): + bad_for = (now - self.inputs_bad_since).total_seconds() if self.inputs_bad_since else 0.0 + if bad_for < stale_after: + # A single missed poll is not a fault. Hold, keep the heartbeat + # going, and give it a few seconds to come back. + self.reason = f"inputs missing {bad_for:.0f}s" + # UX-10: the age is rendered when the page asks, not frozen at + # this cycle's. (DECISIONS/MAIN-orchestration-archive.md) + self.why_words = messages.why_waiting(bad_for) + self._why_waiting_since = now - timedelta(seconds=bad_for) + return + if late_s is not None and late_s < stale_after and self.inputs_ok \ + and (self.auto or self.shadow) \ + and not any(i.sign_wd.tripped for i in self.inverters) \ + and not (n_units > 1 and self.site_sign_wd.tripped): + self.reason = f"readings late {late_s:.0f}s" # SAFETY-128: hold + self.why_words = messages.why_late() + return + + claims = [] + + # safety limits: these bind EVERY strategy, always. Defence in depth: + # write_setpoint() clamps to the device range too, and the duplication + # is deliberate. ⚠️ PER-INVERTER, ONE PAIR PER UNIT from THAT unit's + # own min/max and supervised cap: there is no site rating + # (arbiter.CLAIM_SCOPE). (DECISIONS/MAIN-orchestration-archive.md) + for inv in self.inverters: + if inv.dev_min is not None and inv.dev_max is not None: + claims.append(Claim.limit("device", P_SAFETY, inv.dev_min, inv.dev_max, "rating", + actuator=self.actuator_of("device", inv))) + # `max_w` is the supervised cap on what may be WRITTEN to one + # setpoint entity (§11.3), not a bound on the grid connection. + claims.append(Claim.limit("supervised", P_SAFETY, -inv.max_w, inv.max_w, "max_w", + actuator=self.actuator_of("supervised", inv))) + # OPT-09: WHAT THIS PACK'S STATE OF CHARGE FORBIDS. ⚠️ AN ENVELOPE, + # NOT A WEIGHT: a zero weight does not stop `allocator._fill()` + # commanding a pack (at or under its BMS cut-out `hi = 0`, at 100 % + # `lo = 0`). ⚠️ NEVER FILED AT N=1 (it would bound the site target: + # SAFETY-25 Option A), so there nothing here stops the loop + # discharging into the BMS cut-out; the BMS does. + # (DECISIONS/MAIN-orchestration-archive.md) + if n_units > 1: + _pe = packshare.envelope(pack_energy_of(inv)) + if _pe.binding: + claims.append(Claim.limit("pack", P_SAFETY, _pe.lo, _pe.hi, + _pe.why, + actuator=self.actuator_of("pack", inv))) + # The SITE bound, for the site-level consumers below. It is the roster + # sum: what this site can deliver, not what one of its inverters can. + max_w = self.site_max_w + + # safety stops. ⚠️ SAFETY-02 is claimed FIRST and unconditionally while + # latched, a SET at P_SAFETY, and re-filed EVERY cycle (claims are not + # sticky). ⚠️ AND IT IS PER-INVERTER, THOUGH ITS EVIDENCE IS SITE-WIDE: + # at N>=2 the evidence cannot be pinned on a sibling this controller + # never commanded (arbiter.CLAIM_SCOPE). + # (DECISIONS/MAIN-orchestration-archive.md) + for inv in self.inverters: + if inv.sign_wd.tripped: + claims.append(Claim.set("failsafe", P_SAFETY, 0.0, + "sign disagreement", + actuator=self.actuator_of("failsafe", inv))) + + # SAFETY-30: THE SITE SIGN TRIP, A SITE SET: the SUM of every standing + # command against the meter, which no single inverter owns; parking one + # unit on it would leave the rest pushing the same way. ⚠️ The `n_units + # > 1` guard is not redundant: the latch is restored from the store, + # and an install reconfigured back to one inverter must come up + # driving. (DECISIONS/MAIN-orchestration-archive.md) + if n_units > 1 and self.site_sign_wd.tripped: + claims.append(Claim.set("sign_site", P_SAFETY, 0.0, + "site sign disagreement", + actuator=self.actuator_of("sign_site"))) + + # SAFETY-31: ⚠️ A SITE SET AT P_SAFETY: STOP COMMANDING, EVERYWHERE. A + # circulating loop needs two participants and one is this controller: + # stopping it halves the loop and makes the residue visible at P1. It + # does NOT stop a wedged inverter (HW-01); the remaining actuator is a + # human at the isolator. A site claim: circulating power is zero for + # any one unit (arbiter.CLAIM_SCOPE). + # (DECISIONS/MAIN-orchestration-archive.md) + if self.circ_wd.tripped: + claims.append(Claim.set("circulation", P_SAFETY, 0.0, + "circulating power", + actuator=self.actuator_of("circulation"))) + + # SITE, both of them: "stopped" (the operator switching control off) + # and "inputs missing" (the meter gone) are not about a pack. ⚠️ + # SAFETY-10: `and not self.shadow` is the one failsafe this card + # changes (a stop claim would record "stopped" on every shadow cycle); + # the wire gate in `_write_unit()` is stronger. + # (DECISIONS/MAIN-orchestration-archive.md) + if not self.auto and not self.shadow: + claims.append(Claim.set("safety", P_SAFETY, 0.0, "stopped", + actuator=self.actuator_of("safety"))) + elif not self.inputs_ok: + if self.target != 0.0: + self.log_event("inputs missing - commanding 0 W", + hint=messages.hint("inputs_missing")) + claims.append(Claim.set("safety", P_SAFETY, 0.0, "inputs missing", + actuator=self.actuator_of("safety"))) + elif late_s is not None: + claims.append(Claim.set("safety", P_SAFETY, 0.0, "readings late", + actuator=self.actuator_of("safety"))) + + # SAFETY-07: the quarter-peak projection guard: ONE `lo` limit at + # P_PEAK; peakguard.py carries the argument. ⚠️ `frozen` is evaluated + # on THIS cycle's standing command, not `self.freeze_wd.active` (a + # cycle behind). ⚠️ `achievable_w` keeps the floor from filing `lo > + # hi` (0 W). ⚠️ Filed EVERY cycle (claims are not sticky). ⚠️ NOT RUN + # WITHOUT P1: it would be blind, and blind means "no charging"; the + # report is NOT COVERED. (DECISIONS/MAIN-orchestration-archive.md) + self._peak_proj = (None if not self.p1_enabled + else self.peak.project(self.p1.averager, now, + roll=self.modes_on)) + # OPT-15 x SAFETY-81: see `check_peak_saturated()`. + self._peak_rolled = (self._peak_proj is not None + and self._peak_proj.block_start is not None + and self._peak_proj.block_start + != self.p1.averager.block_start) + _reading = self.peak.peak(now) if self.p1_enabled else None + # SAFETY-90: seconds a meter gap left uncounted are counted, so the + # guard goes on after the readings return. + self._peak_proj = self._fill_peak_gaps(self._peak_proj, now, _reading) + # SAFETY-91: at N>=2 the quarter's edge is graded on the next quarter, + # so a HOLD's ceiling does not lapse for a cycle onto a held battery. + if self._peak_proj is not None and len(self.inverters) > 1: + self._peak_proj = next_quarter(self._peak_proj, + self.p1.averager.max_hold_s) + self.peak_guard = None if not self.p1_enabled else peakguard.decide( + self._peak_proj, + # ⚠️ THE SITE SUM. The guard sizes a floor from what the battery is + # ALREADY removing from the meter, and the meter sees every + # inverter. (DECISIONS/MAIN-orchestration-archive.md) + batt_w=self.site_batt_w, + cap_w=float(self.o.get("peak_cap_w", 3500)), + margin_w=self.peak_margin_w, + reading=_reading, + # ⚠️ SUMMED FROM THE PER-UNIT CONJUNCTION, WHICH IS AC 4. Each unit + # contributes `min(its max_w, |its own device bounds|)`, so + # inverter B's rating bounds inverter B. + # (DECISIONS/MAIN-orchestration-archive.md) + achievable_w=self.site_rating_w, + # ⚠️ SAFETY-24. `pack_floor_soc` IS A MEASURED READING AND MAY BE + # None, and it is handed over as None rather than defaulted (a + # defaulted 100 % is a full battery, the value that disarms this + # floor); `decide()` treats None as floor-limited. + # (DECISIONS/MAIN-orchestration-archive.md) + soc=self.pack_floor_soc, + # ⚠️ SAFETY-32. THE SAME OPTION, REDUCED OVER THE PACKS' OWN + # CUT-OUTS: `binding_soc_floor()` takes the MAXIMUM with each + # pack's `bms_soc_floor`, pairing with the MINIMUM in + # `pack_floor_soc` (both move towards refusing a shave). + # "Unreachable" is a claim about rule ordering, and sim/inject.py + # does not run rule 8: asserted over the whole schema range in + # test_peakguard.py part 12. + # (DECISIONS/MAIN-orchestration-archive.md) + soc_floor=peakguard.binding_soc_floor(self.packs, float(self.o.get( + "peak_soc_floor", + peakguard.PEAK_OPTION_DEFAULTS["peak_soc_floor"]))), + max_hold_s=self.p1.averager.max_hold_s, + # ⚠️ SAFETY-20. The device range goes in TOO: `standing` is + # `last_write`, the value AFTER `clamp_to_rating()`, so a rail from + # bare `max_w` is a ceiling the device cannot reach. + # (DECISIONS/MAIN-orchestration-archive.md) + frozen=looks_frozen(getattr(self.p1_source, "unchanged_s", None), + site_standing, max_w, self.freeze_wd.cfg, + dev_min=self.site_dev_bound("dev_min"), + dev_max=self.site_dev_bound("dev_max")), + ) + # SAFETY-87: at N>=2 a battery at or under its own reserve gives + # nothing for the peak, and the others carry the guard's need. + if self.peak_guard is not None: + self.peak_guard = self._peak_on_able(self.peak_guard, + maint_results) + self.peak_guard = self._peak_landing(self.peak_guard) + self.peak_guard = peakguard.cap_floor( # SAFETY-128 + self.peak_guard, self.answer.peak_cap(site_standing)) + # SITE, and peakguard.claim() says so on the object it builds: the + # quantity is the 15-minute average OFFTAKE AT THE GRID CONNECTION, + # which the capacity tariff bills (one quarter-hour peak per site, not + # per pack). ⚠️ It is also the `lo` half of SAFETY-25 §0c's table: a + # site `lo` that the deferred loop reserve's per-inverter `hi` must + # never cross. (DECISIONS/MAIN-orchestration-archive.md) + peak_claim = (peakguard.claim(self.peak_guard) + if self.peak_guard is not None else None) + if peak_claim is not None: + claims.append(peak_claim) + # ⚠️ EDGE-LOGGED, not level-logged: the action log holds 40 lines, and + # a line every 15 s for a quarter would push the cause off the end. + # (DECISIONS/MAIN-orchestration-archive.md) + engaged_now = self.peak_guard is not None and self.peak_guard.engaged + if engaged_now != self._peak_engaged: + self._peak_engaged = engaged_now + if self.peak_guard is not None: + _pg = self.peak_guard + self.log_event(_pg.explain(), hint=messages.hint( + "peak_off" if not _pg.engaged else + "peak_blind" if _pg.blind else + "peak_on" if _pg.within_aim else + "peak_reserve" if _pg.floor_limited else + "peak_saturated" if _pg.saturated else "peak_on")) + + # OPT-04: price arbitrage (§10.1 priority 3): ONE `set` claim at + # P_ARBITRAGE; arbitrage.py carries the argument. ⚠️ AFTER THE PEAK + # BLOCK BECAUSE IT READS ITS CONCLUSION (`engaged_now`). ⚠️ The + # three-state collapse lives in arbitrage.guard_state(), NOT here (None + # = the guard never ran, without P1). ⚠️ NO FETCH ON THIS PATH. ⚠️ The + # uncertainty set is NOT empty (no weather forecast is built). + # TARIFF-11: `arb_at` keeps the status row honest. + # (DECISIONS/MAIN-orchestration-archive.md) + self.arb, self.arb_at = None, now + self.arb_headroom_w = None + self.room_charge = False + # OPT-11 P3: with battery modes on, each battery's mode decides who + # trades (`_mode_roles()`, `_mode_trade()`, below, which read the + # same headroom), and this site-wide trade is not run. + site_trade = arbitrage.enabled(self.o) and not self.modes_on + if site_trade or self.modes_on: + # SAFETY-47. HOISTED OUT OF THE CALL, NOT COPIED: one evaluation + # feeds both the sizing below and `arbitrage.sized_from_meter()`, + # so the caveat on the recorded watts is never answered from a + # different cycle's guard. + # (DECISIONS/MAIN-orchestration-archive.md) + self.arb_headroom_w = peakguard.charge_room_w(self.peak_guard, + self._peak_proj) + if site_trade: + floor_pct, ceiling_pct = arbitrage.soc_bounds(self.o) + charge_w, discharge_w = self.trade_power_w(floor_pct, ceiling_pct) + self.arb = arbitrage.decide( + self.fresh_tariff_plan(now), now, + peak_guard_active=arbitrage.guard_state(self.peak_guard), + # SAFETY-45. THE SAME GUARD'S SECOND ANSWER, AND THE CONTINUOUS + # ONE: the watts the billed quarter can still afford clamp the + # buy leg (a switch alone gave 28 charge onsets an hour on + # TEST-23). ⚠️ It reads the peak block's conclusion, so it must + # stay after it. (DECISIONS/MAIN-orchestration-archive.md) + charge_headroom_w=self.arb_headroom_w, + # The emptiest pack again, and for the sell side that is the + # right reduction. ⚠️ THE BUY SIDE WANTS THE FULLEST, and there + # is one `soc` argument - `pack_floor_soc` names that residual + # rather than hiding it; a per-pack charge ceiling is CFG-04's, + # and at the shipped roster of one the two reductions are the + # same number. + soc=self.pack_floor_soc, + min_spread_eur_kwh=arbitrage.threshold_eur_kwh(self.o), + uncertainty=frozenset({Uncertainty.NO_WEATHER}), + # OPT-09. PER-PACK SIZING, not `max_w`: the trade is sized to + # the packs whose own state of charge permits that direction + # (`trade_power_w()`). ⚠️ At N=1 both sides are `max_w` + # exactly. ⚠️ On the sell side this is a no-op today (`soc=` + # below is the EMPTIEST pack); test_packshare.py part 9 grades + # it. (DECISIONS/MAIN-orchestration-archive.md) + charge_w=charge_w, discharge_w=discharge_w, + soc_floor_pct=floor_pct, soc_ceiling_pct=ceiling_pct) + # SITE, and arbitrage.claim() says so on the object it builds. It + # buys and sells at the grid against a day-ahead price: the price is + # a property of the connection and the energy crosses the meter. + arb_claim = arbitrage.claim(self.arb) + if arb_claim is not None: + claims.append(arb_claim) + self.room_charge = self.arb.action == arbitrage.CHARGE + # Edge-logged, for the peak guard's reason: the action log holds 40 + # lines and a trade lasts a whole hour, so a line per cycle would + # flush the context that explains it. + # (DECISIONS/MAIN-orchestration-archive.md) + if self.arb.action != self._arb_action: + self._arb_action = self.arb.action + self.log_event(self.arb.explain(), hint=messages.hint( + "trade_charge" if self.arb.action == arbitrage.CHARGE else + "trade_give" if self.arb.action == arbitrage.DISCHARGE + else "trade_off")) + + # maintenance ⚠️ ONE PASS PER PACK, AND `arbitrate()` IS WHY THE LIST + # STAYS SHORT. (DECISIONS/MAIN-orchestration-archive.md) + for inv, result in zip(self.inverters, maint_results): + if result.owns_setpoint: + # PER-INVERTER: §12's recalibration is a PACK procedure, filed + # on the pack whose state machine produced it (`inv`, + # MAINT-05). ⚠️ IT STAYS `SCOPE_UNIT`, never a site claim + # (ARCH-01: per-inverter limits filed site-wide are the + # cross-inverter `lo > hi`). + # (DECISIONS/MAIN-orchestration-archive.md) + claims.append(Claim.set("maintenance", P_MAINTENANCE, + float(result.setpoint_w or 0.0), result.phase, + actuator=self.actuator_of("maintenance", inv))) + self.sat_count = 0 + elif result.charge_only: + # Money outranks the maintenance schedule: while the projection + # is over the cap the charge-only shaping is not claimed, so + # the loop can shave. ⚠️ Shaping is `hi <= 0` and the peak + # claim `lo >= 0`; both filed give `lo > hi`, which resolves to + # 0 W in the quarter that sets the bill, so the higher claimant + # SUPPRESSES the lower. ⚠️ THE CONJUNCTION LIVES IN + # peakguard.shaping_suspended(), NOT HERE. One suspension flag + # per SITE (`arbitrate()` allows one pack in CHARGE). + # (DECISIONS/MAIN-orchestration-archive.md) + # MAINT-24: the guard's aim, month peak included (SAFETY-80). + # DECISIONS/MAINT-24-charge-first.md + maint_aim = peakguard.quarter_target_w( + float(self.o.get("peak_cap_w", 3500)), + self.peak_margin_w, _reading) + if peakguard.shaping_suspended( + self.peak_guard, self.peak_fc, maint_aim): + # Edge-logged: level-logging here would write one line per + # cycle for as long as the event lasts and flush the 40-line + # action log of the very context that explains it. + if not self._maint_shape_suspended: + self._maint_shape_suspended = True + self.log_event("peak at risk - maintenance charge shaping " + "suspended so the peak claim is not " + "contradicted", + hint=messages.hint("maint_paused")) + else: + self._maint_shape_suspended = False + hi = 0.0 + reason = "charge-only" + if self.cheap: + # ⚠️ CFG-03. `self.maint.cfg.charge_w`, NOT A SECOND + # READ OF `self.o`: a literal fallback here let the + # shaping and the state machine use different rates + # from the same install. + # (DECISIONS/MAIN-orchestration-archive.md) + floor = maintenance_charge_floor( + self.maint.cfg.charge_w, + self.peak_fc, maint_aim) + floor = self._charge_headroom(floor, claims) + if floor > 0: + hi, reason = -floor, "cheap-window charge" + # PER-INVERTER, like the SET above and for the same reason - + # the shaping is about the pack being charged, which is `inv`. + claims.append(Claim.limit("maintenance", P_MAINT_SHAPE, hi=hi, + reason=reason, + actuator=self.actuator_of("maintenance", + inv))) + + # OPT-11: each battery's mode, a soft unit limit at P_MODE. Filed only + # with battery modes on, and never on a battery in any maintenance + # phase (maintenance outranks the mode). The range always holds 0 W + # (packmode.mode_range()) and gives way to the peak floor only as far + # as needed, so the two never meet in `lo > hi` + # (arbiter._unit_modes()). (DECISIONS/MAIN-orchestration-archive.md) + if self.modes_on: + tick = self._mode_roles(now, maint_results) + for inv, result in zip(self.inverters, maint_results): + if result.phase != IDLE: + continue + pm = self.pack_mode(inv) + lo, hi = packmode.mode_range(pm, inv.max_w) + rlo, rhi = tick.ranges.get(inv.name, (lo, hi)) + lo, hi = max(lo, rlo), min(hi, rhi) + claims.append(Claim.limit("mode", P_MODE, lo, hi, pm.key, + actuator=self.actuator_of("mode", + inv))) + + # the grid-following loop. ⚠️ SAFETY-10: `or self.shadow`: the loop is + # the leg a shadow run most needs; it is safe because the loop's + # `prev_w` is `self.target`, re-seeded to what is on the wire. + # SAFETY-52: a refusal learned while control ran does not survive a + # stop or a start. (DECISIONS/MAIN-orchestration-archive.md) + if bool(self.auto) != self._refusal_auto: + self._refusal_auto = bool(self.auto) + self._refusal_end("control started" if self.auto + else "control stopped") + for inv in (self.inverters if len(self.inverters) > 1 else ()): + self._unit_refusal_end(inv, "control started" if self.auto + else "control stopped") + # SAFETY-73: each unit's own refusal, engaged and ended on its own + # reading, before the loop reads `self.target` (an end reseeds it). + _probing = {} + if len(self.inverters) > 1 and self.inputs_ok: + self._unit_refusals() + _probing = {inv.name: self._unit_probe(inv) + for inv in self.inverters if inv.refused} + # SAFETY-73: each refusing unit's own P_SAFETY claim: a hard unit limit + # that always intersects (OPT-11's P_MODE sits inside it), closed in + # the refused direction, so the allocator hands the share to the others + # within their own limits; a pin at PROBE_W during its probe. Filed + # before the loop so OPT-11's loop bound sees it. + # (DECISIONS/MAIN-orchestration-archive.md) + for inv in self.inverters: + if not inv.refused: + continue + if _probing.get(inv.name): + claims.append(Claim.set("refused", P_SAFETY, + inv.refused * _ctl.PROBE_W, + _ctl.PROBING, + actuator=self.actuator_of("refused", + inv))) + else: + claims.append(Claim.limit("refused", P_SAFETY, + *_refused_interval(inv.refused), + _ctl.REFUSED, + actuator=self.actuator_of("refused", + inv))) + # --- SAFETY-78: a pinned drain is a floor under the site target ----- + # After every unit claim, so the floor is what the pin really places. + drain = self._drain_floor(claims, maint_results) + if drain is not None: + claims.append(Claim.limit("drain", P_MAINTENANCE, lo=drain, + reason="maintenance drain", + actuator=self.actuator_of("drain"))) + self._peak_over_drain(claims, maint_results) + # --- SAFETY-86: while a HOLD gives, the site stays at the peak floor -- + # So the loop never asks for watts the hold keeps back. + hold_hi = self._peak_over_hold(claims, maint_results) + if hold_hi is not None: + claims.append(Claim.limit("hold", P_MAINTENANCE, hi=hold_hi, + reason="maintenance hold", + actuator=self.actuator_of("hold"))) + # --- SAFETY-91: a drain rises before a held battery gives ------------ + self._drain_rise(claims, maint_results) + # --- SAFETY-84: a cheap-window charge is a ceiling over the site ---- + charge = self._charge_ceiling(claims) + if charge is not None: + claims.append(Claim.limit("charge", P_MAINT_SHAPE, hi=charge, + reason="maintenance charge", + actuator=self.actuator_of("charge"))) + # --- OPT-11 P3: the site trade, after every unit claim -------------- + # Sized from what the batteries may place with their modes and hard + # limits (the loop bound), so none is asked for watts it may not give. + mode_trade, trade_was = False, self._mode_trade_was + if self.modes_on: + mode_trade = self._mode_trade(claims, now) + self.room_charge = self.room_charge or ( + mode_trade and self.arb.action == arbitrage.CHARGE) + self._mode_trade_was = mode_trade + self._charge_track(claims, maint_results) + _live96 = set(self.live_units()) + self._loop_start = {} + if (self.auto or self.shadow) and self.inputs_ok: + # ⚠️ prev is the ARBITER's last output, not the loop's own wish: if + # something outranked the loop, that is what the hardware did. The + # integrator re-seeds from the same (entering failsafe re-seeds it + # to zero). (DECISIONS/MAIN-orchestration-archive.md) + moved = self.loop_w is None or self.target != self.loop_w + if moved: + self.i_w = self.target + # OPT-11 P3: a run edge (a mode trade ended) reseeds the loop, and + # OPT-15 holds it there until the meter shows the step. + if trade_was and not mode_trade: + self._reseed_run_edge(claims, now) + moved = False + loop_grid = self._edge_grid(mode_trade or moved, now) + # SAFETY-52: another writer overrode the loop, so a refusal learned + # against the loop's own ask may no longer describe the wire. + # (DECISIONS/MAIN-orchestration-archive.md) + rejudged = 0 + if self.loop_w is not None and self.target != self.loop_w: + rejudged = self.batt_refused + # SAFETY-96: a battery that dropped out of the split leaves the + # loop's start point (SAFETY-93's own if its charge ended too). + self._reseed_drop(_live96) + # SAFETY-93: a charge that ended leaves the loop's start point. + self._reseed_charge_end(maint_results) + # SAFETY-95: then a drain that ended, last (it reads the start + # the others left). + self._reseed_drain_end(maint_results, _live96) + # No probe while it is judged afresh (the loop does not hold the wire). + probe = False if rejudged else self._refusal_probe() + if len(self.inverters) > 1: + probe = any(_probing.values()) + # ⚠️ `actual_w` IS THE SITE SUM AND THAT IS DEV-02's OTHER HALF. + # The anti-windup test in compute() is `abs(prev_w - actual_w) > + # saturation_w` and `prev_w` is the SITE target; one inverter's + # power at N=2 would trip the saturation freeze permanently. + # (DECISIONS/MAIN-orchestration-archive.md) + site_batt = self.site_batt_w + # SAFETY-103: what each battery can be doing (its reading may be + # older than the meter). + self._track_reads() + # SAFETY-96: a battery the loop cannot move counts at its command, + # so its own power does not freeze the loop (the meter has it). + site_batt += self._held_out_w(_live96) + # TEL-10. ⚠️ ONE NAME FOR THE COMMAND THE LOOP WAS MEASURED + # AGAINST. (DECISIONS/MAIN-orchestration-archive.md) + loop_prev = self.target + # SAFETY-95: a drain's tail is not the loop's to chase. + # OPT-15: `loop_grid` is the grid, or the target while a run + # edge is held. + grid_in = (self._drain_grid_w(_live96) if self._drain_tail + else loop_grid) + # SAFETY-136: on a slow meter, a gentler loop until the last move + # shows. + slow_meter = self.settle.slow() + if moved or mode_trade: + self.settle.reset() + decision = compute( + prev_w=loop_prev, + grid_w=grid_in, + actual_w=site_batt, + tuning=self.settle.tuning(self.tuning, grid_in, slow_meter), + sat_count=self.sat_count, + i_w=self.i_w, + # SAFETY-52 at one inverter only: with several, OPT-09's pack + # limit already closes an empty battery's discharge end. + # SAFETY-73: at N>1 the site law holds 0 W only while every + # unit refuses the same way. Otherwise None, the old law. + refused=(0 if rejudged else self.batt_refused) + if len(self.inverters) == 1 + else self._site_refused(), + probe=probe, + # SAFETY-94: at N=1 the engage also needs the reading to have + # given nothing for the whole span, as at N>1. + gave_nothing=(bool(self._gave_nothing(self.inverters[0])) + if len(self.inverters) == 1 else None), + # SAFETY-97: "gives nothing" is centred on the idle reading. + idle_w=self._site_idle_w(), + hold=self.answer.hold, hold_w=self.answer.hold_w, # SAFETY-128 + # OPT-11: None unless battery modes are on. SAFETY-85: or while + # maintenance holds a battery at N>=2, so the loop does not + # wind past what the others can give and jump when it ends. + bound=(self.loop_bound(claims) if self.modes_on or ( + len(self.inverters) > 1 + and any(r.phase != IDLE for r in maint_results)) + else None), + ) + if decision.frozen and self.sat_count < self.tuning.saturation_cycles: + self.log_event(f"saturation freeze ({self.target:.0f} W vs " + f"{site_batt:.0f} W)", + hint=messages.hint("not_keeping_up")) + self.settle.moved(grid_in, loop_prev, decision.target_w, slow_meter) + self.sat_count = decision.sat_count + self.i_w = decision.i_w + self.loop_w = decision.target_w + self._loop_decision = decision + if len(self.inverters) == 1: + self._refusal_update(decision, loop_prev, site_batt, probe, + rejudged) + # TEL-10. ⚠️ THE INTEGRATOR HAS NEVER LEFT THIS PROCESS: `loop_i` + # is `Decision.i_w`, the value BEFORE the clamp, slew and + # quantisation, so it is NOT `setpoint` and must not be published + # from it; `loop_lead` is how far it stands ahead of the command; + # `loop_reason` is `compute()`'s own word and NOT `self.reason`. + # (DECISIONS/MAIN-orchestration-archive.md) + self.loop_i_w = decision.i_w + self.loop_i_lead = decision.i_w - loop_prev + self.loop_reason = decision.reason + # SAFETY-03. ⚠️ READ THE BOOLEANS, NOT `decision.reason`: `reason` + # is overwritten by slew-limiting or the saturation freeze after + # the clamp, so a string test is silent on the cases a winding loop + # most often presents as. SAFETY-40: every number comes from THIS + # decision, at clamp time. + # (DECISIONS/MAIN-orchestration-archive.md) + self.loop_clamped = ( + decision.i_clamped or decision.clamped, + loop_clamp_note(decision), + decision.clamped, + ) + self.loop_clamp_facts = ( + (messages.Clamp(None, decision.requested_w, decision.clamped_w, + "rating"),) if decision.clamped else ()) + # SITE. compute() regulates `grid_w` - the P1 measurement - to + # zero. Its subject is the meter, and §6.2's architecture is ONE + # integrator on P1 whose output is then SPLIT. + # (DECISIONS/MAIN-orchestration-archive.md) + claims.append(Claim.set("loop", P_LOOP, decision.target_w, decision.reason, + actuator=self.actuator_of("loop"))) + else: + # Stopped or blind: no accumulation may survive the outage. + self.i_w = 0.0 + self.settle.reset() + self.loop_w = None + self._live_was = frozenset(_live96) + # TEL-10, and it is the same zero the line above writes rather than + # a second opinion about it. ⚠️ `not-running` rather than a stale + # `tracking`: a reason row that keeps repeating the last word the + # loop said while the loop is not running is a row that reads as + # health, which is the failure `publish()`'s own None-dropping note + # is about one field over. + self.loop_i_w = 0.0 + self.loop_i_lead = 0.0 + self.loop_reason = "not-running" + # A loop that is not running cannot be winding. Clearing this here + # rather than letting the last value stand is what makes the alarm + # de-assert when control is stopped. + self.loop_clamped = (False, "", False) + self.loop_clamp_facts = () + self._loop_decision = None + + # SAFETY-28. A new resolution is a new tick, and the previous record is + # stale from this line onwards. Incremented BEFORE resolve() so that the + # record resolve() builds is stamped with the tick it is for. + self.alloc_tick += 1 + # ⚠️ `weights=` IS OPT-09, AND ITS ABSENCE WAS THE CARD. A METHOD, NOT + # A DICT: the weighting is by ENERGY HEADROOM, so it depends on the + # direction (the sign of the site target, chosen inside `resolve()`; + # see `pack_weights()`). ⚠️ A PREFERENCE, NOT A PERMISSION: a weight + # cannot stop a unit being commanded. + # (DECISIONS/MAIN-orchestration-archive.md) + _live = self.live_units() + while True: + resolution = resolve(claims, units=self.units, live=_live, + weights=self.pack_weights, tick=self.alloc_tick, + reserve=self._held_back()) + # SAFETY-73: a probe pin stands only while the resolved site target + # asks at least PROBE_W its way; below that a sibling would carry + # the opposite direction (circulation), so the pin goes back to the + # closed limit. (DECISIONS/MAIN-orchestration-archive.md) + _void = [k for k, c in enumerate(claims) + if c.source == "refused" and c.kind == "set" + and c.value * resolution.target_w < _ctl.PROBE_W ** 2] + if not _void: + break + for k in _void: + claims[k] = Claim.limit( + "refused", P_SAFETY, + *_refused_interval(1 if claims[k].value > 0 else -1), + _ctl.REFUSED, actuator=claims[k].actuator) + self.allocation = resolution.allocation + if self.modes_on: + self._mode_fault_log(resolution) + # THE TWO REFUSALS ARE NOT THE SAME REFUSAL: both REPLACE the + # resolution with a 0 W failsafe, written like any other cycle; they + # differ in WHO refused, hence two branches and two messages. ⚠️ + # NEITHER MAY BE LEFT UNGRADED (test_peakguard.py part 10h). + # (DECISIONS/MAIN-orchestration-archive.md) + if not resolution.allocated: + self.log_event("ARBITER: " + resolution.allocation.explain(), + hint=messages.hint("split")) + resolution = Resolution(0.0, "failsafe", None, False, + resolution.considered, + unit_bounds=resolution.unit_bounds, + shares={}, allocated=False, + scope_errors=resolution.scope_errors, + allocation=resolution.allocation, + winner_priority=resolution.winner_priority) + # 2. THE ALLOCATOR SUCCEEDED AND THIS CONTROLLER CANNOT DELIVER IT. ⚠️ + # RE-AIMED BY DEV-02, NOT DELETED: a roster entry with no writer would + # have the site target written to the others (over-command by its + # share); "nothing" here means 0 W. Not folded into `live_units()`: a + # dead link is dropped and announced, an undeliverable roster stops the + # site. (DECISIONS/MAIN-orchestration-archive.md) + elif {u for u in resolution.shares if not self._can_write(u)}: + undeliverable = ", ".join( + sorted(u for u in resolution.shares if not self._can_write(u))) + self.log_event( + f"ARBITER: the site target was allocated across " + f"{len(resolution.shares)} inverters and this controller has no " + f"setpoint entity for {undeliverable} - refusing to command a " + f"partial site", hint=messages.hint("no_setpoint")) + # ⚠️ `shares={}`, NOT THE SHARES IT REFUSED TO DELIVER, AND SINCE + # DEV-02 THAT IS LOAD-BEARING: the write loop commands + # `shares.get(name, 0.0)`, so carrying the split through would + # write the numbers this branch declined, or nothing at all when + # they equal what stands (an unchanged value is not re-sent). + # (DECISIONS/MAIN-orchestration-archive.md) + resolution = Resolution(0.0, "failsafe", None, False, + resolution.considered, + unit_bounds=resolution.unit_bounds, + shares={}, allocated=True, + scope_errors=resolution.scope_errors, + allocation=resolution.allocation, + winner_priority=resolution.winner_priority) + # 3. AC 6: A DROPPED INVERTER IS NEVER SILENT. The survivors carry its + # share, a real change in what the site can deliver, and an operator + # who is not told reads a working site. Edge-triggered on the SET of + # dropped units (the action log is a log of events, §15). + # (DECISIONS/MAIN-orchestration-archive.md) + _dropped = tuple(u for u, _why in (self.allocation.dropped + if self.allocation else ())) + if _dropped != self._dropped_last: + for _u, _why in (self.allocation.dropped if self.allocation else ()): + self.log_event(f"ALLOCATOR: {_u} dropped from the split " + f"({_why}) - the remaining inverter(s) now carry " + f"its share of the site target", + hint=messages.hint("unit_dropped", unit=_u)) + if self._dropped_last and not _dropped: + self.log_event("ALLOCATOR: every inverter is back in the split", + hint=messages.hint("units_back")) + self._dropped_last = _dropped + # 3b. OPT-09 / IF-04: WATTS NOBODY COULD TAKE ARE NEVER SILENT EITHER. + # `unmet_w` is the site target the envelopes could not absorb; not a + # broken allocation (fusing it with `ok` would let one saturated + # inverter park the site), but the site failing to deliver what the + # loop asked. Edge-triggered on the VALUE. + # (DECISIONS/MAIN-orchestration-archive.md) + _unmet = int(self.allocation.unmet_w if self.allocation else 0) + if _unmet != self._unmet_last: + if _unmet: + self.log_event( + f"ALLOCATOR: {_unmet:+d} W of the site target could not be " + f"placed on any inverter - {self.allocation.explain()}", + hint=messages.hint("unmet", w=_unmet)) + else: + self.log_event("ALLOCATOR: the whole site target fits again", + hint=messages.hint("unmet_gone")) + self._unmet_last = _unmet + if resolution.scope_errors: + # A claim reached the arbiter on an actuator its source's scope + # does not permit: a BUG in the filing site, not a state to survive + # (a per-inverter constraint in the site list is the `lo > hi` this + # card removes). Loud, every cycle; the resolution is unchanged. + # (DECISIONS/MAIN-orchestration-archive.md) + _LOG.error("A limit was filed on the wrong inverter, which is a " + "software fault. %s.", " / ".join(resolution.scope_errors)) + if resolution.contradiction: + self.log_event("ARBITER CONTRADICTION - commanding 0 W, see the log", + hint=messages.hint("clash")) + # SAFETY-02's arming gate: was the number chosen by the grid-following + # loop, or by a strategy that commands against the meter on purpose? + # Only the former is expected to agree in sign with P1. ⚠️ THE + # EXPRESSION LIVES IN watchdog.py, NOT HERE: read loop_is_following() + # before touching the gate. (DECISIONS/MAIN-orchestration-archive.md) + self.following = loop_is_following(resolution, self.loop_w) + self.target = resolution.target_w + self.reason = resolution.explain() + # UX-08: the same answer in plain words, for the page's "Why" line; + # `reason` stays the technical record the log and the checks read. + # UX-10: every key `why_key()` can return has words in + # messages.WHY_WINNER. (DECISIONS/MAIN-orchestration-archive.md) + _why = why_key(resolution.winner, claims) + if _why == "inputs missing" and not resolution.contradiction: + # UX-11: past the hold, say which reading is missing. + self.why_words = messages.why_missing(self.missing_reading(), + stale_after) + else: + self.why_words = messages.why( + _why, resolution.target_w, resolution.bound_by, + contradiction=resolution.contradiction, + raised=why_raised(resolution, claims)) + # DEV-02: EACH INVERTER IS TOLD ITS OWN SHARE, NEVER THE SITE TARGET + # (handing each unit `self.target` is the ARCH-01 fault: each supplies + # it in full and the gain at the meter becomes N times the per-unit + # gain). At N=1 this is byte-identical. ⚠️ A unit not in `shares` is + # commanded 0 W, not left standing: an inverter holds its last command + # for ever. (DECISIONS/MAIN-orchestration-archive.md) + self._loop_alarm_input(resolution) + writes = [] + for inv in self.inverters: + inv.target = float(resolution.shares.get(inv.name, 0.0)) + writes.append(self.write_setpoint(inv.target, unit=inv)) + await asyncio.gather(*writes) + + # SAFETY-03, and its boundary is the WRITE. ⚠️ NOT THE SAME BOUNDARY AS + # SAFETY-18's BELOW, THOUGH THE CALLS ABUT: this one reads + # `self.clamp_last`, None until write_setpoint() has run, so it must + # follow the write (test_clamp.py part 6). Two guards, two orderings: + # do not "tidy" them into one rule. + # (DECISIONS/MAIN-orchestration-archive.md) + await self.check_output_clamp() + + # SAFETY-18, and its boundary is the ASSIGNMENT. ⚠️ THE BOUNDARY IS + # `self.target = resolution.target_w` ABOVE, NOT write_setpoint(): both + # terms of the conjunction must describe the SAME moment, so moving it + # above the assignment grades the previous cycle's command against this + # cycle's meter (test_freeze.py part 5). + # (DECISIONS/MAIN-orchestration-archive.md) + await self.check_meter_frozen() + + # --- PRICE-01: no price for now, said once and taken down once -------- + # Not a safety check, so it is one of the cheap ones: an attribute test + # and, on a change only, one Home Assistant call. + await self.check_price_gap() + await self.check_fixed_note() + + # SAFETY-31's alarm, and its boundary is the LATCH, not a number: it + # grades `self.circ_wd.tripped`, advanced near the top of this method. + # Called on EVERY cycle, not only the one that trips, because its + # second job is re-raising the alarm after a restart. + # (DECISIONS/MAIN-orchestration-archive.md) + await self.check_circulating() + + # SAFETY-42's alarm, and its boundary is the LATCH, like SAFETY-31's: + # it grades `inv.delivery_wd.tripped`, and is called on EVERY cycle + # because its second job is re-raising the alarm after a restart. + # (DECISIONS/MAIN-orchestration-archive.md) + await self.check_not_delivering() + + # --- SAFETY-07's alarm, and it is NOT the engagement ------------------ + # Its boundary is unconstrained: it grades `self.peak_guard`, which this + # method assigned above and nothing since has touched. + await self.check_peak_saturated() + + # SAFETY-24's alarm, and it is the OTHER way the money gets spent. Same + # boundary argument as check_peak_saturated(); kept as its own method + # because the two states are mutually exclusive and want OPPOSITE + # operator actions (saturated: shed load; this: the pack is at its + # floor and the quarter is not being shaved). + # (DECISIONS/MAIN-orchestration-archive.md) + await self.check_peak_floor_limited() + + # TARIFF-01, and it is LAST on purpose: banking a quarter is + # bookkeeping about a moment that has passed, and a slow SD card must + # never sit between the meter and the setpoint. It grades neither + # `target` nor `standing`. (DECISIONS/MAIN-orchestration-archive.md) + self.peak.sync(self.p1) + + # SAFETY-10, AND IT IS LAST FOR A REASON THAT IS NOT TIDINESS: every + # guard above has read `self.target`, the resolved intent (SAFETY-18 + # grades exactly that); re-seeding before them would hand each a 0 W no + # decision produced. See `_shadow_settle()`. + # (DECISIONS/MAIN-orchestration-archive.md) + self._shadow_settle(resolution) + + def _shadow_settle(self, resolution) -> None: + """SAFETY-10. Record the decision, then re-seed the carried command + (`self.target`, each `inv.target`) to `shadow.WIRE_W`, in this order + because the second destroys the first's evidence. ⚠️ THE RE-SEED IS A + SAFETY PROPERTY: compute's slew base, the sign watchdogs + (`standing_w()`) and SAFETY-42 read the carried command as a statement + about the HARDWARE; a shadow decision there would latch a trip that + survives into live operation. One log line per CHANGE of decision. + (DECISIONS/MAIN-orchestration-archive.md)""" + engaged = self.shadow + if engaged != self._shadow_was: + # ⚠️ `first` EXISTS SO A LIVE INSTALL'S FIRST CYCLE IS SILENT (a + # "shadow mode off" line at every start pushed a clamp episode out + # of the 40-row log); coming up IN shadow mode always gets a line. + # (DECISIONS/MAIN-orchestration-archive.md) + first = self._shadow_was is None + self._shadow_was = engaged + if engaged: + self.log_event( + "SHADOW MODE ON - " + shadow.why( + self.o, control_started=self.auto) + + f"; inverter held at {shadow.WIRE_W:.0f} W", + hint=messages.hint("shadow_on")) + # UX-10: INFO. It follows a setting or a button press, and + # no person has to act on it. + _LOG.info( + "Shadow mode is on, so every inverter stays at %.0f W and " + "nothing the add-on decides is sent. %s.", shadow.WIRE_W, + shadow.why(self.o, control_started=self.auto)) + elif not first: + self.log_event( + "Shadow mode off: the add-on controls the battery again, " + f"starting from {shadow.WIRE_W:.0f} W", + hint=messages.hint("shadow_off")) + _LOG.info( + "Shadow mode is off, so the add-on controls the battery " + "again, starting from %.0f W.", shadow.WIRE_W) + if not engaged: + self.shadow_would_w = None + self.shadow_sized_from_meter = False + self._shadow_winner = None + return + self.shadow_would_w = float(resolution.target_w) + # SAFETY-47. ⚠️ NO LOGIC HERE, DELIBERATELY: all three rungs live in + # `arbitrage.sized_from_meter()`; a rung written at a call site is one + # no check can reach with the other two clear (TEST-16). + # (DECISIONS/MAIN-orchestration-archive.md) + self.shadow_sized_from_meter = arbitrage.sized_from_meter( + self.arb, self.arb_headroom_w, winner=resolution.winner) + # ⚠️ THE WINNER AND THE ROUNDED WATTS, NOT THE WATTS ALONE (a loop + # target that that wanders by a watt would be the whole log). ⚠️ + # SAFETY-47 ADDS THE CAVEAT FLAG TO THE EDGE: the same winner at the + # same watts with and without the caveat are two different claims. + # (DECISIONS/MAIN-orchestration-archive.md) + edge = (resolution.winner, round(float(resolution.target_w)), + self.shadow_sized_from_meter) + if edge != self._shadow_winner: + self._shadow_winner = edge + self.log_event(shadow.log_line( + would_w=resolution.target_w, reason=resolution.explain(), + sized_from_meter=self.shadow_sized_from_meter), + hint=messages.hint("shadow_decision", + sw=resolution.target_w)) + self.target = shadow.WIRE_W + for inv in self.inverters: + inv.target = shadow.WIRE_W diff --git a/goodwe_controller/app/ctl_inputs.py b/goodwe_controller/app/ctl_inputs.py new file mode 100644 index 0000000..7568dce --- /dev/null +++ b/goodwe_controller/app/ctl_inputs.py @@ -0,0 +1,425 @@ +"""Controller methods that read the inputs: meter, packs, PV, forecast. + +Moved unchanged from app/main.py (MAINT-21). DECISIONS/MAIN-orchestration.md.""" + +import asyncio +import logging +import time +from datetime import datetime, timezone + +from .arbiter import actuator_for +from . import solarfc +from . import freshness +from . import lateness +from . import messages +from . import pv as pv_read +from .price import brussels, price_option, provider_configured +from .price_chain import uses_chain +from .static_tariff import static_status +from .rows import tariff_plan_row + +_LOG = logging.getLogger("goodwe") + + +# UX-11: a quiet meter logs at most one WARNING this often (on `ha_signed` a +# healthy meter can go 42-97 s between changes). +METER_QUIET_REPEAT_S = 600.0 + + +_mono = time.monotonic # patched by the checks; asyncio keeps the real one + + +# OPT-04: the background tariff refresh. The tick NEVER awaits a fetch: it +# reads `self.tariff_plan`, which the refresh task assigns. +# DECISIONS/MAIN-orchestration.md. +TARIFF_REFRESH_S = 1800.0 + + +# The age bound covers the refresh task dying: three missed refreshes. +# DECISIONS/MAIN-orchestration.md. +TARIFF_MAX_AGE_S = 3 * TARIFF_REFRESH_S + + +# OPT-27: the forecast sensors' last fresh readings (`solarfc.Hold`), so an +# evening restart keeps the night plan's figure. +FC_HOLD_KEY = "solar_fc_hold" + + +FORECAST_READ_S = 60.0 + + +class InputsMixin: + def _readings_late(self, standing_w): + """SAFETY-128: update the answer gate; seconds the late verdict has + stood, or None. DECISIONS/SAFETY-128-late-readings.md.""" + a = self.answer + if self._now_mono is None: + return None + a.observe(self._now_mono, standing_w, self.site_batt_w, + grid_w=self.grid, exempt=bool(self.batt_refused) or any( + i.refused or ( + i.batt is not None + and abs(i.standing_w()) >= lateness.ANSWER_W + and abs(i.batt - i.idle_w) < lateness.ANSWER_W) + for i in self.inverters), + idle_w=self._site_idle_w()) + if a.late_seen != self._late_logged: + self._late_logged = a.late_seen + if a.late_seen: + self.log_event("readings late - holding", + hint=messages.hint("readings_late")) + _LOG.warning("Home Assistant readings arrive late, so control " + "holds the batteries: READINGS_LATE.") + _LOG.debug("READINGS_LATE: the readings show a power request " + "%.0f s after it is sent.", a.delay_s) + else: + self.log_event("readings on time", hint=messages.hint( + "readings_back")) + _LOG.info("Home Assistant readings are on time again.") + return a.late_s(self._now_mono) + + @property + def inputs_ok(self) -> bool: + """The site meter, and EVERY pack's own two readings: every pack, not + the live ones. A unit whose SoC did not answer cannot be graded for + the maintenance FSM or the pack floor, and 11.1 rule 1 for a missing + input is command zero and keep commanding.""" + if self.grid is None or not self.inverters: + return False + return all(inv.soc is not None and inv.batt is not None + for inv in self.inverters) + + def missing_reading(self) -> str: + """UX-11: the first reading `inputs_ok` finds missing, in words.""" + if self.grid is None or not self.inverters: + return "meter" + for inv in self.inverters: + of = "" if len(self.inverters) == 1 else f" from {inv.name}" + if inv.batt is None: + return f"battery power{of}" + if inv.soc is None: + return f"battery level{of}" + return "input" + + # -- io ------------------------------------------------------------------ + @property + def pv_roster(self) -> tuple: + """Every configured PV production entity, or `()` (TEL-11/TEL-12). ONE + reading of the options, `pv.entities()`, the same call + `mqtt.optional_keys()` makes, so what is ANNOUNCED, READ and CHECKED + cannot disagree; it replaced a `pv_entity` property.""" + return pv_read.entities(self.o) + + async def _read_pv(self) -> None: + """This cycle's SITE PV production, or an ABSENCE with a reason + (TEL-11/12). `pv.total()` makes "one of three absent" an absence of + the SITE figure. It assigns on EVERY call including failing ones (a + stale value must not survive a failure), and uses `hass.state()` not + `hass.number()` because the UNIT is half of the answer.""" + # TEL-12: every entity in ONE gather. Read serially, three slow sensors + # would add three 10 s timeouts to a cycle that feeds the ESP32 + # heartbeat; telemetry must have no foot in the control path. + roster = self.pv_roster + states = await asyncio.gather( + *(self.hass.state(entity) for entity in roster)) + self.pv_w, self.pv_why, self.pv_parts = pv_read.total( + list(zip(roster, states)), pv_read.inverted(self.o)) + # UX-54: kept for the Forecast tab only. It must never cost a cycle. + try: + self.solar_today.add(datetime.now(timezone.utc), self.pv_w) + except Exception: # noqa: BLE001 + _LOG.debug("measured solar not kept", exc_info=True) + + def _peak_fc_unit_log(self, fault) -> None: + """SAFETY-118. One WARNING when the peak forecast's unit cannot be read + in watts, and again only if the unit changes; the unit is on DEBUG.""" + if fault == self._peak_fc_fault: + return + self._peak_fc_fault = fault + if fault is None: + _LOG.info("The 15-minute demand forecast is used again.") + elif fault == "": + _LOG.warning("The 15-minute demand forecast has no unit, so it " + "is not used.") + else: + _LOG.warning("The 15-minute demand forecast is not in a power " + "unit, so it is not used.") + _LOG.debug("The 15-minute demand forecast reads in %r.", fault) + + async def _read_forecast(self) -> None: + """OPT-11 P4: the solar forecast sensors (`solarfc.read()`). A + failed or stale read is no forecast, never a zero.""" + # OPT-17: every member of both days in one gather. + ents = self.fc_entities + self.fc_tomorrow_entities + states = await asyncio.gather(*(self.hass.state(e) for e in ents)) + n = len(self.fc_entities) + now = datetime.now(timezone.utc) + fc, why, gaps = solarfc.read_sum( + list(zip(self.fc_entities, states[:n])), + list(zip(self.fc_tomorrow_entities, states[n:])), now, + hold=self.fc_hold) + if self.fc_hold.changed: + self.fc_hold.changed = False + self.store.set(FC_HOLD_KEY, self.fc_hold.dump()) + # A member is named only in a sum of several; one entity reads as + # before. Logged once per episode: on a change, never every read. + gaps = tuple(g for g in gaps if len( + self.fc_entities if g[0] == "today" + else self.fc_tomorrow_entities) > 1) + was_kept = bool(self.solar_fc is not None and self.solar_fc.kept) + if (fc is None) != (self.solar_fc is None) \ + or why != self.solar_fc_why or gaps != self.solar_fc_gaps \ + or bool(fc is not None and fc.kept) != was_kept: + self.log_event( + "solar forecast: " + ( + "none (" + str(why) + ")" if fc is None else + f"read, kept from {brussels(fc.at):%H:%M}" if fc.kept + else "read") + + "".join(f", {d} {e} not usable ({w})" + for d, _i, e, w in gaps), + hint=messages.hint( + "forecast_none" if fc is None else + "forecast_no_tomorrow" if gaps else "forecast_read")) + self.solar_fc, self.solar_fc_why = fc, why + self.solar_fc_gaps = gaps + + async def read_inputs(self, now_mono: float | None = None) -> None: + """Every input this cycle needs, and SAFETY-37's freshness verdict. + `now_mono` is defaulted rather than read inside `_read_unit()` so + ONE instant covers every unit in a gather.""" + o = self.o + now_mono = freshness.monotonic() if now_mono is None else float(now_mono) + self._now_mono = now_mono + if self.p1_enabled: + # P1 is the only authoritative measurement of what the utility sees + # (5.1); when stale this is None -> "inputs missing -> command 0 + # W". NO fallback to an inverter-side figure: its AC power + # correlates 0.998 with battery power and 0.09 with the real meter + # (a controller would regulate against its own output). + self.grid = self.p1.net_w + self.settle.arrive(now_mono, self.p1.samples) # SAFETY-136 + else: + self.grid = await self.hass.number(o.get("meter_entity", ""), + bool(o.get("meter_invert"))) + # DEV-02: each inverter's own two readings from its own entities, + # CONCURRENTLY across units and sequentially within one (a slow entity + # must not delay the heartbeat path). The PV reads ride in the same + # gather and an empty PV roster appends nothing (no coroutine). + # DECISIONS/MAIN-orchestration.md. + _reads = [self._read_unit(inv, now_mono) for inv in self.inverters] + if self.pv_roster: + _reads.append(self._read_pv()) + # OPT-11 P4: the solar forecast, in the same gather (a slow sensor must + # not delay control), at most once per FORECAST_READ_S. + if self.fc_entity is not None and ( + self._fc_read_mono is None + or now_mono - self._fc_read_mono >= FORECAST_READ_S + or now_mono < self._fc_read_mono): + self._fc_read_mono = now_mono + _reads.append(self._read_forecast()) + await asyncio.gather(*_reads) + if o.get("peak_forecast_entity"): + # SAFETY-118: read in its own unit like the PV path, one state + # read. No unit or a non-power unit: not used, as if the option + # were empty. + st = await self.hass.state(o["peak_forecast_entity"]) + self.peak_fc, _why = pv_read.watts(st) + # A missing reading leaves the unit-fault state as it was. + if pv_read.has_reading(st): + self._peak_fc_unit_log(pv_read.unit_fault(st)) + else: + self.peak_fc = None + self._peak_fc_fault = None + + now_e, avg_e = o.get("price_now_entity"), o.get("price_avg_entity") + if now_e and avg_e: + now_p = await self.hass.number(now_e) + avg_p = await self.hass.number(avg_e) + self.cheap = (now_p is not None and avg_p is not None and now_p <= avg_p) + self._price_gated = True + self.tariff_words = "Prices from Home Assistant entities" + elif uses_chain(o): + # PRICE-01. A provider with fallbacks gives the maintenance gate + # its own prices: the current 15-minute price against today's + # average, as the Home Assistant pair did. No I/O here: the series + # is the one the background refresh stored. + # (DECISIONS/MAIN-orchestration-archive.md) + self._provider_gate(datetime.now(timezone.utc)) + else: + # TARIFF-03: 9.2 makes a static day/night tariff a first-class + # product and its EMS handling TIME-WINDOW SHIFTING; the one + # shiftable load is the maintenance cycle's cheap-window grid + # top-up. Synchronous and I/O-free on purpose (the provider-backed + # plan is the background task's); validate.py refuses + # `static_profile` with the price entities, so the two cannot both + # be set. + _now = datetime.now(timezone.utc) + self.cheap, self.tariff_words = static_status(o, _now) + self._price_gated = self._static_gated(o, _now) + + # TARIFF-11: the provider plan reaches the *Tariff* row here, the only + # place the two sources meet. `fresh_tariff_plan()` is an attribute + # read and an age comparison against TARIFF_MAX_AGE_S: still no fetch + # on this path. + _tick = datetime.now(timezone.utc) + _standing = self.fresh_tariff_plan(_tick) + self.tariff_words = tariff_plan_row( + _standing, self.tariff_words, + age_s=(None if _standing is None + else (_tick - self.tariff_at).total_seconds()), + horizon_h=float(price_option(o, "price_horizon_h")), + provider=provider_configured(o), max_age_s=TARIFF_MAX_AGE_S) + + # UX-11: the red meter row says "the add-on log shows why", so a quiet + # meter gets one WARNING per episode (at most one per + # METER_QUIET_REPEAT_S; the rest DEBUG). Log only: no notification, + # decides nothing. + if self.p1_enabled: + if (self.p1.stale and not self._meter_quiet_logged + and self.p1.published_age_s > self.p1.max_age_s): + self._meter_quiet_logged = True + now = _mono() + self._meter_quiet_loud = ( + self._meter_quiet_warned is None + or now - self._meter_quiet_warned >= METER_QUIET_REPEAT_S) + if self._meter_quiet_loud: + self._meter_quiet_warned = now + _LOG.warning("No meter reading for over %s, so control " + "waits and then sets the battery to 0 W.", + messages.seconds(self.p1.max_age_s)) + else: + _LOG.debug("No meter reading for over %s again.", + messages.seconds(self.p1.max_age_s)) + elif not self.p1.stale and self._meter_quiet_logged: + self._meter_quiet_logged = False + if self._meter_quiet_loud: + _LOG.info("Meter readings are back.") + else: + _LOG.debug("Meter readings are back.") + + self.answer.watch(now_mono, [(inv.name, inv.standing_w(), inv.batt) + for inv in self.inverters], # SAFETY-128 + sum(inv.standing_w() for inv in self.inverters), + self.grid) + if self.inputs_ok: + if self.inputs_bad_since is not None: + self.log_event("inputs recovered", + hint=messages.hint("inputs_back")) + self.inputs_bad_since = None + elif self.inputs_bad_since is None: + self.inputs_bad_since = datetime.now(timezone.utc) + + def _driver(self, inv): + """`inv`'s driver, wired to this Controller's Home Assistant on first use + (SMA-2: bound here, so a unit added later and a swapped `self.hass` are + followed). DECISIONS/SMA-2-driver-seam.md.""" + drv = inv.driver + if not drv.bound(): + drv.bind_getter(lambda: self.hass) + return drv + + async def _read_unit(self, inv, now_mono: float) -> None: + """One inverter's own SoC and battery power, from ITS OWN entities. + SAFETY-37: the POWER reading goes through the freshness gate and the + SoC does not, deliberately: `batt` feeds SAFETY-30's per-unit sign + check and the delivery check, which a frozen register would fool. + The standing command is asked of the unit, not recomputed.""" + # SMA-2: the driver reads SoC, then power, as this method always did. + # DECISIONS/SMA-2-driver-seam.md. + inv.soc, raw, _extra = await self._driver(inv).read() + was_stale = inv.batt_fresh.stale + was_releases = inv.batt_fresh.releases + inv.batt_fresh.submit(raw, inv.standing_w(), now_mono) + # `inv.batt` is the GATED value: a stale register is a MISSING input, + # so the site holds for `stale_input_s` then commands 0 W and keeps + # commanding (11.1 rule 1). + inv.batt = inv.batt_fresh.reading() + # SAFETY-97: learn this unit's idle reading, only while control runs + # and nothing says the unit is refusing, stale or faulty. + if inv.idle.observe( + inv.batt, inv.standing_w(), now_mono, + bool(self.auto) and inv.batt is not None + and not inv.batt_fresh.stale and not inv.refused + and not self.batt_refused and not inv.sign_wd.tripped): + inv.store_set("idle_w", round(inv.idle.value, 1)) + if inv.batt_fresh.stale and not was_stale: + self.log_event(f"STALE {inv.name}: " + inv.batt_fresh.reason, + hint=messages.hint("battery_stuck", unit=inv.name)) + self._refusal_from_stale(inv, now_mono) + # SAFETY-56/57: the stale-reading line names two explanations once, + # in `%s`. The escape clause "clears itself when the register + # reports a different value" was false for the state this line + # announces (the 0 W it announces is what stops the value + # changing), so SAFETY-57 rewrote it and SAFETY-56 the diagnosis. + # DECISIONS/SAFETY-57-the-exit-from-a-stale-verdict.md. + _LOG.error("%s: battery power reading stopped changing, set to " + "0 W until it changes, or %.0f s after the command " + "drops below %.0f W: %s.", + inv.name, inv.batt_fresh.bound.release_s, + inv.batt_fresh.bound.move_w, + messages.reason_code(inv.batt_fresh.reason)) + _LOG.debug("Evidence for %s: %s.", inv.name, inv.batt_fresh.reason) + _LOG.debug("%s: the limits are unchanged for %.0f s while asked " + "to move: a command over %.0f W that moved over %.0f W.", + inv.name, + inv.batt_fresh.bound.unchanged_s, + inv.batt_fresh.bound.move_w, + inv.batt_fresh.bound.move_w) + elif inv.batt_fresh.releases > was_releases: + # SAFETY-57: reported, never silent: a latch that lets go on a + # timer and says nothing cannot be audited, and this one withdraws + # a SITE STOP. `release_note()` says nothing has been learned about + # the register. + self.log_event(f"STALE WITHDRAWN {inv.name}", + hint=messages.hint("battery_back", unit=inv.name)) + # Not "recovered": nothing is known about the reading yet, so the + # line gives the value it holds and the window it is rechecked over + # (SAFETY-57). + _LOG.warning("%s: the command stayed below %.0f W for %.0f s, so " + "battery power reading %+.0f W is used again and " + "rechecked over %.0f s.", inv.name, + inv.batt_fresh.bound.move_w, + inv.batt_fresh.bound.release_s, inv.batt_fresh.held, + inv.batt_fresh.bound.unchanged_s) + _LOG.debug("SAFETY-57: %s", inv.batt_fresh.release_note(inv.name)) + + # -- the cycle ----------------------------------------------------------- + def actuator_of(self, source: str, inv=None) -> str: + """Which actuator a claim from `source` is filed on this cycle. `inv` + is the roster entry the claim is ABOUT; left out it is the first + inverter (what every per-inverter claim meant at N=1). The + classification is not here: `arbiter.CLAIM_SCOPE` decides.""" + return actuator_for(source, (inv or self.inverters[0]).name, self.units) + + def live_units(self) -> tuple: + """Which inverters may be commanded THIS TICK, for the allocator. The + allocator DROPS what this does not list and the survivors carry the + whole site target, so it is reported (`Allocation.dropped`). + Answered per tick, never cached (a master goes stale). It answers + ONE question: can this controller put a number on this unit's wire. + Deliberately not "its sensors are missing". At a roster of ONE, + False is a 0 W site.""" + now = datetime.now(timezone.utc) + live = [] + for inv in self.inverters: + ok, why = inv.is_live(now) + if ok: + live.append(inv.name) + else: + # Level-logged at DEBUG only: `Allocation.dropped` is the + # operator-facing surface (edge-logged in cycle()); a line + # every second would flush the 40-row action log. + _LOG.debug("%s is not commandable this tick: %s", inv.name, why) + return tuple(live) + + def liveness_notes(self) -> list: + """Why each unit is or is not commandable, for the status page. + SAFETY-37's stale-reading line rides here too: a different fault, a + different remedy (a dropped unit is carried by the survivors; a + stale power register is a missing input).""" + now = datetime.now(timezone.utc) + return [n for n in + [x for inv in self.inverters + for x in (inv.link_note(now), inv.stale_note(), + inv.refusal_note())] + if n] diff --git a/goodwe_controller/app/ctl_status.py b/goodwe_controller/app/ctl_status.py new file mode 100644 index 0000000..74ad3f3 --- /dev/null +++ b/goodwe_controller/app/ctl_status.py @@ -0,0 +1,927 @@ +"""Controller methods that build the status page, rows and MQTT output. + +Moved unchanged from app/main.py (MAINT-21). DECISIONS/MAIN-orchestration.md.""" + +import logging +import time +from datetime import datetime, timezone + +from . import arbitrage +from . import packmode +from .clamp import is_commandable +from . import dayview, homeview +from . import messages +from .freeze import rail_unreachable, rail_w +from .hass import OUTAGE +from .maintenance import IDLE +from .mqtt import ( + announced_units, optional_keys, parse_command, unit_slugs, unit_state_key, +) +from . import peakguard +from . import pv as pv_read +from . import shadow +from .price import brussels +from .validate import FIRMWARE_INGEST_VETO_S +from .rows import arbitrage_row + +_LOG = logging.getLogger("goodwe") + + +class StatusMixin: + async def mqtt_command(self, topic, payload, retained) -> None: + """OPT-11 P2: one command from a battery's HA switch or mode list, + through handle_action(). A retained command is never applied (the store + already holds the last choice). Never raises: MQTT must not reach + control. (DECISIONS/MAIN-orchestration-archive.md)""" + try: + slug, action, value, why = parse_command( + topic, payload, retained, packmode.MODES) + if why is None: + names = [inv.name for inv in self.inverters] + unit = dict(zip(unit_slugs(names), names)).get(slug) + result = await self.handle_action(action, unit=unit, + value=value) + if not (isinstance(result, dict) and "error" in result): + self.mqtt.publish(self.mode_values()) + return + why = result["error"] + else: + why = messages.pack_refused(why) + # Printable only: a topic is sender-chosen, so no log injection. + topic_s = "".join(c if c.isprintable() else "?" + for c in str(topic)[:128]) + _LOG.debug("Home Assistant command %s %s refused: %s", topic_s, + repr(payload)[:48], why) + if (topic_s, why) in self._mqtt_refused \ + or len(self._mqtt_refused) >= 32: + # Not logged again, but counted: 1, 10, 100... stay visible. + self._mqtt_refused_more += 1 + more = self._mqtt_refused_more + if str(more).rstrip("0") == "1": + _LOG.warning("Home Assistant commands still ignored: %d " + "more so far.", more) + return + self._mqtt_refused.add((topic_s, why)) + _LOG.warning("Home Assistant command on %s ignored: %s", topic_s, + why) + except Exception: # noqa: BLE001 + _LOG.exception("Home Assistant command could not be handled") + + @property + def why_words(self) -> str: + """The page's "Why" line. While control waits for a missing reading + the age is counted when the page asks (UX-10), not frozen at the age + the last cycle saw.""" + if self._why_waiting_since is not None: + return messages.why_waiting(max(0.0, ( + datetime.now(timezone.utc) + - self._why_waiting_since).total_seconds())) + return self._why_words + + @why_words.setter + def why_words(self, text: str) -> None: + self._why_words = text + self._why_waiting_since = None + + def publish(self) -> None: + # ⚠️ SITE TOTALS, AND THE KEYS DO NOT MOVE: `battery` stays the SUM and + # `soc` the EMPTIEST pack (their `unique_id`s are on live dashboards); + # per-inverter entities are TEL-07's. + # (DECISIONS/MAIN-orchestration-archive.md) + values = { + "setpoint": self.target, + "grid": self.grid, + "battery": self.site_batt_w, + "soc": self.pack_floor_soc, + "phase": self.maint.phase, + # ⚠️ SAFETY-02's alarm surface, and it is deliberately an existing + # one: "failsafe" is additive to a sensor already on every + # dashboard, and a P_SAFETY stop that did not reach it would be a + # site at 0 W reporting "running". + # (DECISIONS/MAIN-orchestration-archive.md) + "status": ("failsafe" if any(i.sign_wd.tripped + for i in self.inverters) + or (self.site_sign_wd.tripped + and len(self.inverters) > 1) + or self.circ_wd.tripped + # SAFETY-10: "shadow" is its own value and not a flavour + # of "stopped". ⚠️ BELOW `failsafe`: a latch that is up + # is up, and shadow does not clear it. + # (DECISIONS/MAIN-orchestration-archive.md) + else "shadow" if self.shadow + else "running" if self.auto else "stopped"), + # SAFETY-31. ⚠️ MEASURED, not the allocation record - see + # `site_circulating_w`. `publish()` drops None values, so a missing + # per-unit reading leaves the last figure standing rather than + # publishing a zero that would read as health. + # (DECISIONS/MAIN-orchestration-archive.md) + "circulation": (None if self.site_circulating_w is None + else round(self.site_circulating_w)), + # TEL-10. The loop's own three, written from the fields `cycle()` + # recorded and not re-derived (the page and the publisher run on + # their own tasks, and `self.target` has moved on). + # (DECISIONS/MAIN-orchestration-archive.md) + "loop_i": round(self.loop_i_w, 1), + "loop_lead": round(self.loop_i_lead, 1), + "loop_reason": self.loop_reason, + } + # TEL-11. ⚠️ THE KEY IS PRESENT WITH `None` WHEN THERE IS NO READING + # AND ABSENT WHEN THERE IS NO SOURCE: two states + # (`mqtt.ABSENT_AS_UNKNOWN` makes the first an `unknown`, a gap in the + # recorder). TEL-12: still ONE number, the SITE total, None unless + # EVERY entity answered. ⚠️ THE GATE IS `optional_keys()`, THE SAME + # EXPRESSION THE ANNOUNCEMENT USES. + # (DECISIONS/MAIN-orchestration-archive.md) + if "pv" in optional_keys(self.o): + values["pv"] = (None if self.pv_w is None + else round(self.pv_w, 1)) + # ⚠️ ONLY when P1 ingestion is running: the ESP32's stale-input + # watchdog subscribes to sensor.goodwe_p1_sample_age and forces layer-1 + # failsafe at max_age_s, so with meter_source off a published age would + # climb unbounded and pin every existing install at 0 W within 30 s. + # Publishing nothing leaves the entity non-existent (firmware + # has_state()). (DECISIONS/MAIN-orchestration-archive.md) + if self.p1_enabled: + # Recomputed here, once a second, on purpose - see P1Ingest. + values["p1_age"] = round(self.p1.published_age_s, 1) + # TEL-07. THE PER-UNIT ROWS, AND THE EMPTY LIST IS THE GATE: ⚠️ no `if + # len(self.inverters) > 1` here, deliberately: `announced_units()` + # answers [] at N=1, so what is announced and what is published come + # from one expression. ⚠️ The site rows do not move: `battery` stays + # the SUM and `soc` the EMPTIEST pack (live dashboards use those ids). + # (DECISIONS/MAIN-orchestration-archive.md) + names = announced_units([inv.name for inv in self.inverters]) + for inv, slug in zip(self.inverters, unit_slugs(names)): + values[unit_state_key(slug, "setpoint")] = inv.target + values[unit_state_key(slug, "battery")] = inv.batt + values[unit_state_key(slug, "soc")] = inv.soc + values[unit_state_key(slug, "sign_latch")] = ( + "tripped" if inv.sign_wd.tripped else "clear") + # OPT-11 P2: each battery's mode and switch; nothing while modes are off. + values.update(self.mode_values()) + self.mqtt.publish(values) + + # -- UI ------------------------------------------------------------------ + def checks(self, when: datetime | None = None) -> list: + """The status rows. `when` is the reference time for anything billed by + the calendar - today's month when it is None, which is what the live + page means. ⚠️ IT EXISTS SO THE PEAK ROW CAN BE GRADED (TEST-17): a + suite that banks an August quarter went red at the September boundary. + (DECISIONS/MAIN-orchestration-archive.md)""" + o = self.o + out = [] + # SAFETY-61. First, so a stalled loop is the headline: the heartbeat is + # sent from this loop, so past layer 1's veto the inverter is at 0 W. + if self.loop_pass_mono is None: + out.append({"ok": True, "warn": False, "id": "controller", + "text": messages.row_controller_starting()}) + else: + _pass_age = time.monotonic() - self.loop_pass_mono + if _pass_age > FIRMWARE_INGEST_VETO_S: + out.append({"ok": False, "warn": False, "id": "controller", + "text": messages.row_controller_stalled( + _pass_age, FIRMWARE_INGEST_VETO_S)}) + else: + out.append({"ok": True, "warn": False, "id": "controller", + "text": messages.row_controller_ran(_pass_age)}) + # SAFETY-112. The headline unless control has stalled: while the + # Supervisor gives 502 (Home Assistant not yet RUNNING) no reading or + # write gets through, and the rows below that need it follow from it. + if OUTAGE.waiting(): + out.insert(1 if out[0]["ok"] is False else 0, + {"ok": False, "warn": False, "id": "home_assistant", + "banner": messages.banner_ha_waiting(), + "text": messages.row_ha_waiting()}) + if self.p1_enabled: + age = self.p1.published_age_s + if (self.p1.stale and self.p1.age_s() is None + and age <= self.p1.max_age_s): + # UX-10: no reading yet since the start, still inside the + # limit. Amber, not red: it is not a fault yet, but control + # waits for it. Red at 0 s contradicted the limit the row + # prints. (DECISIONS/MAIN-orchestration-archive.md) + out.append({"ok": False, "warn": True, "id": "meter", + "text": messages.row_meter_waiting( + self.p1.max_age_s)}) + elif self.p1.stale: + # The last error is on the add-on log's WARNING line (p1.py). + out.append({"ok": False, "warn": False, "id": "meter", + "text": messages.row_meter_stale( + age, self.p1.max_age_s)}) + else: + # ⚠️ unchanged_s is REPORTED, never thresholded and never + # folded into the age - see HomeWizardLocalSource.unchanged_s + # for why (at the converged -10 W this controller aims for, a 1 + # Wh register needs ~6 minutes to move, so any limit + # false-trips at the exact operating point we target). + # (DECISIONS/MAIN-orchestration-archive.md) + unchanged = getattr(self.p1_source, "unchanged_s", None) + out.append({"ok": True, "warn": False, "id": "meter", + "text": messages.row_meter( + self.p1.net_w, age, self.p1.parse_errors, + unchanged)}) + # SAFETY-18. Reported in both states (a detector nobody can see is + # armed is not trusted when it fires). ok=False/warn=False so the + # banner goes red; it changes NOTHING about control (see + # check_meter_frozen()). (DECISIONS/MAIN-orchestration-archive.md) + if self.freeze_wd.active: + # The figures are in `freeze_wd.reason`, on the log and the + # event list (check_meter_frozen()). + out.append({"ok": False, "warn": False, "id": "meter_frozen", + "text": messages.row_meter_frozen()}) + elif getattr(self.p1_source, "unchanged_s", None) is None: + # Not "armed". Every transport but homewizard_local is invisible + # to this check, and saying "armed" there would be a lie the + # status page tells on behalf of a guard that cannot run. + out.append({"ok": False, "warn": True, "id": "freeze_check", + "text": messages.row_freeze_off("source")}) + elif rail_unreachable(self.site_max_w, + dev_min=self.site_dev_bound("dev_min"), + dev_max=self.site_dev_bound("dev_max")): + # SAFETY-20: the same row as the transport case above (the + # check cannot be evaluated here); only the missing term + # differs. (DECISIONS/MAIN-orchestration-archive.md) + _no_rating = (not self.site_max_w + or not is_commandable(self.site_max_w)) + out.append({"ok": False, "warn": True, "id": "freeze_check", + "text": messages.row_freeze_off( + "rating" if _no_rating else "range")}) + else: + # ⚠️ SAFETY-20. THE RAIL PRINTED HERE IS THE RAIL THE PREDICATE + # USES, device range included. + # (DECISIONS/MAIN-orchestration-archive.md) + _rail = rail_w(self.site_max_w, + dev_min=self.site_dev_bound("dev_min"), + dev_max=self.site_dev_bound("dev_max")) + # And when the device set that number, SAY SO: the operator + # configured `max_w`. ⚠️ Either bound may be None on its own + # (`hass.limits()` reads min and max independently), so render + # what is there. (DECISIONS/MAIN-orchestration-archive.md) + out.append({"ok": True, "warn": False, "id": "freeze_check", + "text": messages.row_freeze_on( + self.freeze_wd.cfg.hold_s, _rail, + own_limit=_rail < rail_w(self.site_max_w))}) + + # TARIFF-01. The month's billed peak, and a DIFFERENT row when the + # store could not answer: "no peak yet" is normal on the 1st, + # "unreadable" is a broken instrument. + # (DECISIONS/MAIN-orchestration-archive.md) + _pk = self.peak.peak(when) + if _pk.is_unreadable: + out.append({"ok": False, "warn": True, "id": "month_peak", + "text": messages.row_month_peak_unreadable()}) + else: + # §9.1's "warning entity at 80 %", as a status row rather than + # a second entity - see the constructor on not doubling up. + _frac = self.peak.warning_frac(when) or 0.0 + _ok = _frac < 0.8 + out.append({"ok": _ok, "warn": not _ok, "id": "month_peak", + "text": (messages.row_month_peak_none() + if not _pk.is_observed else + messages.row_month_peak( + _pk.peak_w, + brussels(_pk.quarter_start), + _frac))}) + out.append({"ok": True, "warn": False, "id": "periods_measured", + "text": messages.row_periods_measured( + self.peak.recorded)}) + + # SAFETY-07. Three rows, not one, because "idle" and "cannot see" + # are opposite states and a page that spelled them the same would + # show a green line over a guard that is switched off. `None` is a + # fourth state on purpose: before the first cycle nothing has been + # concluded. (DECISIONS/MAIN-orchestration-archive.md) + _pg = self.peak_guard + if _pg is None: + out.append({"ok": True, "warn": True, "id": "peak_guard", + "text": messages.row_peak_guard_waiting()}) + elif _pg.saturated and not _pg.within_aim: + out.append({"ok": False, "warn": False, "id": "peak_guard", + "runs": True, + "text": messages.row_peak_saturated(_pg.ceiling_w)}) + elif _pg.floor_limited and ( + not ((_pg.floor_w or 0.0) > 0.0 or _pg.within_aim) + or self._peak_floor_limited): + # SAFETY-24. NOT ok, like saturation (the money is being spent + # and a human is the only actuator left); a separate row + # because the remedy is opposite. ⚠️ SAFETY-25: the scope + # sentence (the floor binds the guard, not the loop) is part of + # the row, which carries its own short `banner`; shortening the + # ROW would weaken AC 3. + # (DECISIONS/MAIN-orchestration-archive.md) + out.append({"ok": False, "warn": False, "id": "peak_guard", + "runs": True, + "banner": messages.banner_peak_reserve(), + "text": messages.row_peak_reserve( + _pg.ceiling_w, soc_unread=_pg.soc is None, + floor_unknown=(_pg.soc is not None + and _pg.soc_floor is None), + packs=(_pg.held if len(self.inverters) > 1 + else ()), + others=(_pg.floor_w or 0.0) > 0.0)}) + elif _pg.blind: + out.append({"ok": False, "warn": True, "id": "peak_guard", + "text": messages.row_peak_guard_blind( + peakguard.blind_kind(_pg.blind))}) + elif self.peak_unmeasured_s > 0.0: + # SAFETY-90: the start of this quarter came before the first + # reading, and the guard counts it as high use. + out.append({"ok": False, "warn": True, "id": "peak_guard", + "text": messages.row_peak_guard_unmeasured()}) + elif _pg.engaged: + out.append({"ok": False, "warn": True, "id": "peak_guard", + "text": messages.row_peak_guard_on( + _pg.floor_w or 0.0, _pg.ceiling_w, + shadow=self.shadow)}) + elif _pg.projected_w is not None: + # SAFETY-125: "under" only when it is; over the limit at this + # rate, a grid charge is cut back to the quarter's room. + out.append({"ok": True, "warn": False, "id": "peak_guard", + "text": messages.row_peak_guard_idle( + _pg.projected_w, _pg.ceiling_w, + month_peak=(_pg.ceiling_from + == peakguard.CEILING_MONTH_PEAK), + cut=self.room_charge and not self.shadow)}) + else: + out.append({"ok": True, "warn": False, "id": "peak_guard", + "text": _pg.explain()}) + else: + # ⚠️ OUTSIDE the `p1_enabled` block, and that placement is the + # point: SAFETY-07 is NOT COVERED on the legacy single-entity path + # (no telegrams), and a row that rendered only where the guard runs + # would leave the unprotected install showing nothing. + # (DECISIONS/MAIN-orchestration-archive.md) + out.append({"ok": False, "warn": True, "id": "peak_guard", + "text": messages.row_peak_guard_off()}) + + # ⚠️ ONE PAIR OF ROWS PER INVERTER, NAMED. A single "battery SoC" row + # on a site with two packs is a page that shows one pack and calls it + # the site. (DECISIONS/MAIN-orchestration-archive.md) + rows = [] + for inv in self.inverters: + unit = None if len(self.inverters) == 1 else inv.name + rows.append((messages.LABEL_SOC, unit, inv.soc, + inv.driver.soc_source())) + rows.append((messages.LABEL_BATTERY, unit, inv.batt, + inv.driver.batt_source())) + if not self.p1_enabled: + # In P1 mode the check above replaces this one; leaving both in + # would report "no entity configured" for a meter_entity that is + # correctly unused, i.e. a permanent false NOT READY. + rows.insert(0, (messages.LABEL_GRID, None, self.grid, + o.get("meter_entity"))) + # UX-08: the rows name the setting, never the entity id (STYLE.md). + for label, unit, value, entity in rows: + if not entity: + out.append({"ok": False, "warn": False, "id": "sensor", + "text": messages.row_sensor_unset(label, unit)}) + elif value is None: + # ⚠️ SAFETY-56. THIS ROW ONCE ASSERTED A FALSE FACT ABOUT A + # NAMED ENTITY: `Freshness.reading()` returns None BY DESIGN + # while the gate withholds a numeric reading. ⚠️ FIXED BY + # SAYING LESS: the gate has its own surface (`stale_note()` in + # `liveness_notes()`). + # (DECISIONS/MAIN-orchestration-archive.md) + out.append({"ok": False, "warn": False, "id": "sensor", + "text": messages.row_sensor_unusable(label, unit)}) + else: + out.append({"ok": True, "warn": False, "id": "sensor", + "text": messages.row_sensor(label, value, unit)}) + + for inv in self.inverters: + unit = None if len(self.inverters) == 1 else inv.name + if not inv.driver.configured(): + out.append({"ok": False, "warn": False, "id": "control", + "text": messages.row_control_unset(unit)}) + elif inv.dev_max is None: + out.append({"ok": False, "warn": False, "id": "control", + "text": messages.row_control_missing(unit)}) + else: + out.append({"ok": True, "warn": False, "id": "control", + "text": messages.row_control(inv.dev_min, + inv.dev_max, unit)}) + + # DEV-02. Whether this controller can still put a number on each + # inverter: a dropped link that shows nothing on the page reads as a + # healthy site. Red only for a unit no longer live; the rest amber. The + # same notes, in the same order, as `liveness_notes()`. + # (DECISIONS/MAIN-orchestration-archive.md) + _now = datetime.now(timezone.utc) + for inv in self.inverters: + for note, red in ((inv.link_note(_now), not inv.is_live(_now)[0]), + (inv.stale_note(), False), + (inv.refusal_note(), False)): + if note: + out.append({"ok": False, "warn": not red, "text": note}) + if self.answer.late_seen: # SAFETY-128 + out.append({"ok": False, "warn": True, "id": "late", + "text": messages.row_readings_late( + self.answer.shown_s, self._late_zero)}) + + # SAFETY-03. Red while an over-rating clamp is engaged (amber for the + # integrator bound, SAFETY-40), and the engagement COUNT stays shown + # after it clears. Each count is shown under ITS alarm's name, never + # the two summed (UX-07/UX-08). + # (DECISIONS/MAIN-orchestration-archive.md) + _cw = self.clamp_wd + if _cw.active and _cw.bug: + out.append({"ok": False, "warn": False, "id": "power_too_high", + "banner": messages.banner_power_too_high(), + "text": messages.row_power_too_high( + _cw.facts, _cw.over_rating, shadow=self.shadow)}) + elif _cw.active: + # SAFETY-40: the integrator bound alone is amber, not red. + out.append({"ok": False, "warn": True, "id": "not_keeping_up", + "text": messages.row_not_keeping_up( + _cw.bound_episodes)}) + # No over-rating in THIS episode (`bug` would be set), so any count + # is from an earlier one: keep that software-fault evidence shown. + if _cw.over_rating: + out.append({"ok": False, "warn": True, "id": "power_too_high", + "text": messages.row_before( + messages.T_OUTPUT_CLAMP, _cw.over_rating)}) + else: + if _cw.over_rating: + out.append({"ok": False, "warn": True, "id": "power_too_high", + "text": messages.row_before( + messages.T_OUTPUT_CLAMP, _cw.over_rating)}) + if _cw.bound_episodes: + out.append({"ok": False, "warn": True, "id": "not_keeping_up", + "text": messages.row_before( + messages.T_LOOP_BOUND, _cw.bound_episodes)}) + + for inv in self.inverters: + if inv.last_write_ok is False: + out.append({"ok": False, "warn": False, "id": "write", + "text": messages.row_write_refused( + None if len(self.inverters) == 1 + else inv.name)}) + + # SAFETY-02. Reported in both states. ⚠️ ONE ROW PER INVERTER: a trip + # on B leaves A commanding. Since SAFETY-30 the row says what the unit + # was compared against (`sign_wd.against`, the string the trip sentence + # uses); at N=1 the wording is unchanged. + # (DECISIONS/MAIN-orchestration-archive.md) + for inv in self.inverters: + unit = None if len(self.inverters) == 1 else inv.name + # ⚠️ ADDED ONLY WHEN THERE IS SOMETHING TO DISAMBIGUATE: at N=1 the + # two sentences below are the ones that have always been on the + # page, word for word (AC 8); at N>=2 the noun is load-bearing, so + # the row does not send an operator to P1 for a fault visible only + # on one inverter's own power. + # (DECISIONS/MAIN-orchestration-archive.md) + if inv.sign_wd.tripped: + out.append({"ok": False, "warn": False, "id": "direction", + "text": messages.row_direction_trip(unit)}) + else: + held = inv.sign_wd.held_s(datetime.now(timezone.utc)) + out.append({"ok": True, "warn": False, "id": "direction", + "text": messages.row_direction_check( + held, inv.sign_wd.cfg.hold_s, unit)}) + + # SAFETY-30: the SITE row. ⚠️ ONLY AT N>=2, and the absence at N=1 is + # the honest report: with one inverter the site comparison and the row + # above are the same sentence about the same actuator. + # (DECISIONS/MAIN-orchestration-archive.md) + if len(self.inverters) > 1: + if self.site_sign_wd.tripped: + out.append({"ok": False, "warn": False, "id": "site_direction", + "text": messages.row_site_direction_trip()}) + else: + _sheld = self.site_sign_wd.held_s(datetime.now(timezone.utc)) + out.append({"ok": True, "warn": False, "id": "site_direction", + "text": messages.row_site_direction_check( + _sheld, self.site_sign_wd.cfg.hold_s)}) + + # SAFETY-31. ⚠️ SITE-LEVEL, WHERE THE ROWS ABOVE ARE PER-INVERTER, and + # the row says so: there is one circulating figure for the site, and + # naming an inverter would invite clearing "the other one". + # (DECISIONS/MAIN-orchestration-archive.md) + _circ = self.site_circulating_w + if self.circ_wd.tripped: + out.append({"ok": False, "warn": False, "id": "circulating", + "text": messages.row_circulating_trip()}) + elif len(self.inverters) <= 1: + # AC 5. At the shipped roster the quantity is identically zero for + # every value of every reading, so "armed" would be a claim to be + # watching something that cannot happen. Say what is true instead. + out.append({"ok": True, "warn": False, "id": "circulating", + "text": messages.row_one_inverter( + messages.CHECK_CIRCULATING)}) + else: + held = self.circ_wd.held_s(datetime.now(timezone.utc)) + out.append({"ok": True, "warn": False, "id": "circulating", + "text": messages.row_circulating_check( + _circ, held, self.circ_wd.cfg.hold_s)}) + + # SAFETY-42. ⚠️ PER INVERTER, AND WARN RATHER THAN BAD, WHICH IS THE + # ONE PLACE THE "reports, does not act" DECISION IS VISIBLE: every + # other latched row means the site is at 0 W, this one means it is + # STILL RUNNING and quietly short by one unit's share; `ok: False` with + # `warn: True` is this list's caution. + # (DECISIONS/MAIN-orchestration-archive.md) + if len(self.inverters) > 1: + for inv in self.inverters: + if inv.delivery_wd.tripped: + out.append({"ok": False, "warn": True, "id": "delivery", + "text": messages.row_not_delivering(inv.name)}) + else: + _dheld = inv.delivery_wd.held_s(datetime.now(timezone.utc)) + out.append({"ok": True, "warn": False, "id": "delivery", + "text": messages.row_delivery_check( + inv.name, _dheld, + inv.delivery_wd.cfg.hold_s)}) + else: + # AC 5: at one inverter this check has nothing to find, so it is + # not called "armed" (as `circulating power: n/a` above). + # (DECISIONS/MAIN-orchestration-archive.md) + out.append({"ok": True, "warn": False, "id": "delivery", + "text": messages.row_one_inverter("Delivery check")}) + + if not o.get("estop_fitted", False): + out.append({"ok": False, "warn": True, "id": "estop", + "text": messages.row_no_estop()}) + else: + out.append({"ok": True, "warn": False, "id": "estop", + "text": messages.row_estop_fitted()}) + + if not o.get("peak_forecast_entity"): + # ok=False + warn=True renders as a caution, not a pass. A check that + # is both is a check nobody reads. + out.append({"ok": False, "warn": True, "id": "peak_forecast", + "text": messages.row_no_peak_forecast()}) + elif getattr(self, "_peak_fc_fault", None) is not None: + out.append({"ok": False, "warn": True, "id": "peak_forecast", + "text": messages.row_peak_forecast_unit( + self._peak_fc_fault)}) + # OPT-17: a forecast summed from several entities names, by position, + # each member with no usable reading. A caution: control goes on. + gaps = getattr(self, "solar_fc_gaps", ()) + for day, ents in (("today", getattr(self, "fc_entities", ())), + ("tomorrow", + getattr(self, "fc_tomorrow_entities", ()))): + gone = [i for d, i, _e, _w in gaps if d == day] + if gone: + out.append({"ok": False, "warn": True, "id": "solar_forecast", + "text": messages.row_forecast_gap( + day, gone, len(ents))}) + # TEL-11. ⚠️ NO ROW AT ALL WHEN THE ROSTER IS EMPTY (pure + # instrumentation: no warning spam). ⚠️ WHEN IT IS SET, A FAILED READ + # IS `ok=False, warn=True`, a CAUTION never `bad`: telemetry must not + # put a battery site into NOT READY. UX-08 replaced 0.11.0's sentences + # on purpose. (DECISIONS/MAIN-orchestration-archive.md) + roster = self.pv_roster + if roster: + # UX-08: sources are numbered in the order of the settings list, + # never named by entity id (STYLE.md). The per-source figures and + # units are what `pv.total()` returns; they stay in `pv_parts`. + flip = pv_read.inverted(self.o) + n_src = len(roster) + if self.pv_w is None and n_src == 1: + out.append({"ok": False, "warn": True, "id": "pv", + "text": messages.row_pv_none(self.pv_why)}) + elif self.pv_w is None: + # ⚠️ THE ROW THAT SAYS THERE IS NO TOTAL, AND IT SAYS IT IN + # THOSE WORDS - and which sources are missing, by position. + out.append({"ok": False, "warn": True, "id": "pv", + "text": messages.row_pv_partial( + [i + 1 for i, (_e, watt, _y) + in enumerate(self.pv_parts) if watt is None], + n_src)}) + else: + out.append({"ok": True, "warn": False, "id": "pv", + "text": messages.row_pv( + self.pv_w, n_src, + n_src == 1 and roster[0] in flip)}) + # ⚠️ AND WHEN BOTH KEYS ARE SET, WHICH ONE WON IS STATED. `pv.py`'s + # `entities()` makes `pv_entities` REPLACE `pv_entity`, which is + # the rule an operator upgrading from 0.11.0 is most likely to trip + # over. (DECISIONS/MAIN-orchestration-archive.md) + if pv_read.entity_is_ignored(self.o): + out.append({"ok": False, "warn": True, "id": "pv", + "text": messages.row_pv_single_ignored()}) + # TEL-14: a sign that looks reversed, per entity rather than on the + # total - see `pv.NEGATIVE_W` and DECISIONS/TEL-14-pv-sign.md §3. + for i, (ent, watt, _y) in enumerate(self.pv_parts): + if watt is not None and watt < pv_read.NEGATIVE_W: + out.append({"ok": False, "warn": True, "id": "pv", + "text": messages.row_pv_negative( + i + 1, n_src, watt, ent in flip)}) + _inv_list = [str(x or "").strip() + for x in (self.o.get("pv_invert_entities") or [])] + for ent in pv_read.stray_inverts(self.o): + out.append({"ok": False, "warn": True, "id": "pv", + "text": messages.row_pv_stray( + _inv_list.index(ent) + 1)}) + return out + + def status_payload(self, lang: str = "en") -> dict: + checks = self.checks() + bad = [c for c in checks if not c["ok"] and not c["warn"]] + # SAFETY-87: a red row with `runs` (the peak alarms) is an alarm while + # control goes on, so it neither reads "Not ready" nor holds the page. + runs = [c for c in bad if c.get("runs")] + bad = [c for c in bad if not c.get("runs")] + running_alarm = waiting = False + # SAFETY-10, AND IT IS FIRST IN THE CASCADE: "The battery is NOT being + # controlled" may never be displaced by another condition. ⚠️ AND IT + # CARRIES A STANDING LATCH RATHER THAN HIDING ONE: `shadow.banner()` + # names the latch and goes red for it, so nothing the cascade would + # have said is lost. (DECISIONS/MAIN-orchestration-archive.md) + _shadow = shadow.banner(self.o, control_started=self.auto, + latched=self.shadow_latches()) + if _shadow is not None: + level, banner = _shadow + elif self.circ_wd.tripped: + # ⚠️ ABOVE THE SIGN FAILSAFE, and the order is a decision: both are + # latched P_SAFETY stops and the banner carries one sentence; this + # one goes first because it is the fault the operator has NO OTHER + # WAY of learning about (a sign disagreement is visible at the + # meter, circulating power nowhere). + # (DECISIONS/MAIN-orchestration-archive.md) + level, banner = "bad", messages.banner_circulating() + elif self.site_sign_wd.tripped and len(self.inverters) > 1: + # SAFETY-30's site half, ABOVE the per-unit rows below and below + # circulating power above: the banner carries one sentence, so the + # one that says the widest true thing. A site sign trip parks EVERY + # inverter and the fault is in what the site was asking for; naming + # a unit would send an operator to swap the wrong box. + # (DECISIONS/MAIN-orchestration-archive.md) + level, banner = "bad", messages.banner_site_direction() + elif any(i.sign_wd.tripped for i in self.inverters): + # Outranks "Not ready": nothing is missing, something went wrong. + # At N>=2 the unit was graded against its own power, so the banner + # says so (see checks()). (DECISIONS/MAIN-orchestration-archive.md) + level, banner = "bad", messages.banner_direction( + len(self.inverters) > 1) + elif bad: + # ⚠️ `banner` IF THE ROW OFFERS ONE, `text` OTHERWISE: a row may + # say more than fits the headline (SAFETY-25's floor row). + # (DECISIONS/MAIN-orchestration-archive.md) + level, banner = "bad", messages.banner_not_ready(bad[0]) + # SAFETY-112: nothing to do but wait, so Home says that instead + # of "Needs you now". Only when it IS the headline: a safety stop + # above outranks it and still needs a person. + waiting = bad[0].get("id") == "home_assistant" + elif not self.auto: + level, banner = "warn", messages.banner_stopped() + elif runs: + level, running_alarm = "bad", True + banner = runs[0].get("banner") or messages.headline_bi( + runs[0]["text"]) + elif any(i.delivery_wd.tripped for i in self.inverters): + # ⚠️ SAFETY-42, AND IT IS A `warn` BANNER RATHER THAN A `bad` ONE, + # WHICH IS THE WHOLE "reports, does not act" DECISION IN ONE LINE + # (the site is STILL RUNNING, one unit short). ⚠️ BUT IT MUST + # DISPLACE "Running - holding grid at zero": that sentence is a + # claim the site cannot make while a unit is absent. It sits BELOW + # "Stopped". (DECISIONS/MAIN-orchestration-archive.md) + level, banner = "warn", messages.banner_not_delivering( + [i.name for i in self.inverters if i.delivery_wd.tripped]) + elif self.maint.phase != IDLE: + # ⚠️ THE PACK IS NAMED ONLY WHEN THERE IS MORE THAN ONE: at N=1 the + # string is what it has always been, character for character. + # (DECISIONS/MAIN-orchestration-archive.md) + level, banner = "warn", messages.banner_maintenance( + self.maint.phase, + self.maint_unit.name if len(self.inverters) > 1 else "") + else: + level, banner = "ok", messages.banner_running() + + def w(v): + return "—" if v is None else f"{v:,.0f} W".replace(",", " ") + + # ⚠️ THE EARLIEST ACROSS THE PACKS, NOT THE FIRST PACK'S. `None` means + # "never run, due now" and has to win over any date, so it is tested + # for rather than sorted with. At N=1 this is that pack's own date. + # (DECISIONS/MAIN-orchestration-archive.md) + _now = datetime.now(timezone.utc) + _dues = [m.next_due(_now) for m in self.maints] + _waits = [u for u in (m.backoff_until(_now) for m in self.maints) if u] + next_due = None if any(d is None for d in _dues) else min(_dues) + rows = [ + ("Grid", w(self.grid)), + ("Battery", w(self.site_batt_w)), + # SAFETY-31, and it belongs DIRECTLY UNDER the two figures it is + # not derivable from ("Grid 0 W, Battery 0 W, Circulating 6000 W" + # is the whole card in three rows). Only shown at N>=2: at one + # inverter it is identically zero. + # (DECISIONS/MAIN-orchestration-archive.md) + *(() if len(self.inverters) <= 1 + else ((("Circulating", w(self.site_circulating_w)),))), + # TEL-11, and ONLY when a source is configured - see `checks()`. + # `w(None)` renders "-", which is how this row says "no reading" + # rather than "0 W". (DECISIONS/MAIN-orchestration-archive.md) + *(() if not self.pv_roster else ((("Solar production", + w(self.pv_w)),))), + ("Battery level", "—" if self.pack_floor_soc is None + else f"{self.pack_floor_soc:g} %"), + ("Power request", w(self.target)), + # SAFETY-10, and it sits BETWEEN the two rows it reconciles. + # "Commanded 0 W" above and a "Why" below that explains a trade is + # the exact pair an operator would otherwise have to guess at; this + # row is what makes the two of them consistent, and it is rendered + # in EVERY state - including `off`, where it says the battery IS + # being controlled - because a surface whose ABSENCE is how you + # learn something is a surface you have to already know about. + ("Shadow mode", shadow.words( + self.o, control_started=self.auto, + would_w=self.shadow_would_w, + # SAFETY-47. THE FLAG THE CYCLE RECORDED, NOT ONE DERIVED HERE + # - the page runs on its own task and `self.peak_guard` has + # moved on. See `Controller.__init__`. + sized_from_meter=self.shadow_sized_from_meter, + reason=self.why_words)), + ("Why", self.why_words), + ("Maintenance phase", self.maint.phase if len(self.inverters) <= 1 + else f"{self.maint.phase} ({self.maint_unit.name})"), + # ⚠️ ONLY WHEN A PACK IS ACTUALLY WAITING, so a one-inverter status + # page - where `_maint_deferred` is empty on every tick - carries + # exactly the rows it carried before. + *((("Maintenance waiting", "; ".join(f"{n}: {why}" + for n, why in self._maint_deferred)),) + if self._maint_deferred else ()), + # MAINT-13: only while a failed cycle waits, so a site with nothing + # failed carries exactly the rows it carried before. + *((("Maintenance paused", messages.row_maint_waits( + min(_waits).strftime("%Y-%m-%d"))),) if _waits else ()), + ("Maintenance due", "now" if next_due is None else next_due.strftime("%Y-%m-%d")), + ("Cheap window", "yes" if self.cheap else "no"), + ("Tariff", self.tariff_words), + # PRICE-01: only while no price covers now. + *((("Prices", messages.row_no_prices(*self._gap_args())),) + if self.price_gap else ()), + # FCST-04. WHAT §8.3 HAS TO CARRY FORWARD, the difference between a + # 48-hour plan and a 12-hour one on a weekday morning. Its own row: + # "Tariff" says what the plan IS, this says what it could still be + # filled from if the feed is late again. + # (DECISIONS/MAIN-orchestration-archive.md) + ("Price history", self.price_history.words), + # OPT-04. The strategy's own sentence, not a re-derivation: every + # refusal it can make carries a reason a human can act on. ⚠️ + # TARIFF-11: `self.arb is None` is NOT "trading is off" (cycle() + # returns at the input hold first); `arbitrage_row()` reads the + # option, and `cycle_at`/`arb_at` make "no decision this cycle" an + # observation. (DECISIONS/MAIN-orchestration-archive.md) + ("Arbitrage", arbitrage_row( + on=arbitrage.enabled(self.o) or self.modes_on, + decision=self.arb, + decided_at=self.arb_at, cycle_at=self.cycle_at, + now=datetime.now(timezone.utc), why=self.why_words)), + ] + held = level == "bad" and not running_alarm + # UX-46. The page's language is chosen once, here, for the Home + # sentences, checks, rows that carry one and the banner; a plain str + # (no Dutch twin) stays as it is. + # (DECISIONS/MAIN-orchestration-archive.md) + checks = [dict(c, text=messages.pick(c["text"], lang)) for c in checks] + rows = [(k, messages.pick(v, lang)) for k, v in rows] + banner = messages.pick(banner, lang) + out = { + "banner": banner, "level": level, "rows": rows, "checks": checks, + "hint": self.hint, + # The action log itself, newest first: not shown on the page (UX-08 + # 2d) but readable in the `status` JSON, since several events are + # written nowhere else. (DECISIONS/MAIN-orchestration-archive.md) + "events": list(self.events), + } + # UX-13 P1: the Home screen's structured half. Read-only, and it may + # never cost the page its rows: a fault here is logged and the old + # fields are served alone (the page then shows the installer details). + try: + out.update(homeview.build(self, level=level, checks=checks, + lang=lang, held=held, waiting=waiting)) + except Exception: # noqa: BLE001 + # Once per process at ERROR: the page polls every 3 s. + if not getattr(self, "_home_failed", False): + self._home_failed = True + _LOG.exception("Home view could not be built, so the page " + "shows the plain status rows only") + else: + _LOG.debug("Home view failed again", exc_info=True) + out["home_error"] = True + return out + + def forecast_payload(self, lang: str = "en") -> dict: + """UX-54: the Forecast tab's data. Built on request, from what the + control cycle already holds; no Home Assistant call. Today's blocks are + Home's own, so `status_payload()` is built first and read.""" + try: + return dayview.build(self, self.status_payload(lang=lang), + datetime.now(timezone.utc), lang) + except Exception: # noqa: BLE001 + if not getattr(self, "_forecast_failed", False): + self._forecast_failed = True + _LOG.exception("The Forecast tab could not be built") + else: + _LOG.debug("The Forecast tab failed again", exc_info=True) + return {"ok": False} + + async def handle_action(self, what: str, *, unit=None, value=None): + now = datetime.now(timezone.utc) + if what in ("pack_use", "pack_mode", "pack_sell"): + return self._pack_action(what, unit, value, now) + if what == "auto_toggle": + self.auto = not self.auto + self.store.set("auto", self.auto) + self.log_event("control started" if self.auto else "control stopped", + hint=messages.hint("control_started" if self.auto + else "control_stopped")) + if self.auto: + # ⚠️ THE ONLY WAY OUT OF A SIGN-DISAGREEMENT TRIP, on purpose: + # it clears on a deliberate human start, not on the condition + # going away (the condition ALWAYS goes away, because the trip + # commands 0 W). ⚠️ IT CLEARS EVERY INVERTER'S LATCH, AND SAYS + # SO PER INVERTER, each under its OWN key. + # (DECISIONS/MAIN-orchestration-archive.md) + for inv in self.inverters: + if not inv.sign_wd.tripped: + continue + inv.sign_wd.reset() + inv.store_set("sign_tripped", False) + inv.store_set("sign_reason", "") + self.log_event(f"sign-disagreement failsafe cleared by " + f"operator on {inv.name}", + hint=messages.hint("stop_cleared", + unit=inv.name)) + # ⚠️ AND THE PRE-DEV-02 FLAT KEYS GO WITH THEM, + # UNCONDITIONALLY: this is what makes `flat True + namespaced + # False` MEAN something, and why `_grade_store_migration()` can + # run on every start. Left behind, a flat key is a fossil that + # re-arms the failsafe on every restart. + # (DECISIONS/MAIN-orchestration-archive.md) + self.store.set("sign_tripped", False) + self.store.set("sign_reason", "") + # SAFETY-30's SITE latch, cleared by the SAME press for the + # same reason (the trip commands 0 W, so the condition goes + # away on its own). ⚠️ UNCONDITIONAL, NOT GUARDED ON THE + # ROSTER: an install reconfigured back to one inverter would + # otherwise keep `site_sign_tripped: true` for ever. + # (DECISIONS/MAIN-orchestration-archive.md) + if self.site_sign_wd.tripped: + self.log_event("site sign-disagreement failsafe cleared " + "by operator", + hint=messages.hint("site_stop_cleared")) + self.site_sign_wd.reset() + self.store.set("site_sign_tripped", False) + self.store.set("site_sign_reason", "") + # SAFETY-31, cleared by the SAME press and for the same reason. + # ⚠️ AND `_circ_announced` GOES WITH IT: left True, the NEXT + # trip in this process would latch, stop the site and raise no + # notification. (DECISIONS/MAIN-orchestration-archive.md) + if self.circ_wd.tripped: + self.circ_wd.reset() + self.store.set("circ_tripped", False) + self.store.set("circ_reason", "") + self.log_event("circulating-power trip cleared by operator", + hint=messages.hint("site_stop_cleared")) + self._circ_announced = False + # SAFETY-42, cleared by the SAME press, for a reason that is + # NOT the one above: this latch commands nothing, so its + # evidence still stands and it could clear itself. It does not: + # a unit that stopped delivering and resumed is an INTERMITTENT + # fault. ⚠️ AND `_delivery_announced` GOES WITH IT, like + # `_circ_announced`. (DECISIONS/MAIN-orchestration-archive.md) + for inv in self.inverters: + if inv.delivery_wd.tripped: + self.log_event(f"not-delivering report on {inv.name} " + f"cleared by operator", + hint=messages.hint( + "not_delivering_cleared", + unit=inv.name)) + inv.delivery_wd.reset() + inv.store_set("delivery_tripped", False) + inv.store_set("delivery_reason", "") + self._delivery_announced = set() + if not self.auto: + # ⚠️ THE WHOLE SITE, TARGETS INCLUDED - see + # command_site_zero(). SMA-10: Stop gives hand-back units back. + # (DECISIONS/MAIN-orchestration-archive.md) + await self.command_site_release() + return {"auto": self.auto} + if what in ("maint_start", "maint_abort") and unit is not None: + # MAINT-11: the operator named the battery. A request with no unit + # falls through to the branches below, unchanged. + return await self._maint_unit_action(what, unit, now) + if what == "maint_start": + # ⚠️ WHICH PACK, BECAUSE THERE ARE NOW SEVERAL AND THE BUTTON HAS + # ONE LABEL: `_maint_button()` picks the pack that holds the + # maintenance slot, else the one longest without a cycle; at N=1 + # both are `maints[0]`. This is the bare request; a named battery + # is `_maint_unit_action()` (MAINT-11). + # (DECISIONS/MAIN-orchestration-archive.md) + _m = self._maint_button(now) + for msg in _m.force_start(now): + self.log_event(msg, hint=messages.hint("maintenance", + phase=_m.phase)) + return {"phase": self.maint.phase} + if what == "maint_abort": + # Aborts the pack that is actually cycling - `_maint_button()` again + # - and then zeroes the SITE, which is what it always did. + _m = self._maint_button(now) + for msg in _m.abort(now, "operator"): + self.log_event(msg, hint=messages.hint("maintenance", + phase=_m.phase)) + await self.command_site_zero() + return {"phase": self.maint.phase} + return None diff --git a/goodwe_controller/app/ctl_tasks.py b/goodwe_controller/app/ctl_tasks.py new file mode 100644 index 0000000..ea42c4d --- /dev/null +++ b/goodwe_controller/app/ctl_tasks.py @@ -0,0 +1,243 @@ +"""Controller methods that run as background tasks. + +Moved unchanged from app/main.py (MAINT-21). DECISIONS/MAIN-orchestration.md.""" + +import asyncio +import contextlib +import logging +import time +from datetime import datetime, timedelta, timezone + +from . import messages +from .inverter import UNIT_A +from .price import brussels, price_option +from .static_tariff import resolve_tariff +from .validate import refuse, validate_startup_config, validate_unit_ranges +from .ctl_inputs import TARIFF_MAX_AGE_S, TARIFF_REFRESH_S + +_LOG = logging.getLogger("goodwe") + + +class TasksMixin: + def _grade_store_migration(self, store) -> None: + """DEV-02. Did SAFETY-02's latch actually survive the key rename? + Graded, not performed: a latch that silently fails to move is a + DISARMED SAFETY GUARD on an install that believes it is protected. The + pre-DEV-02 flat value is compared with what the roster came up with; a + disagreement re-arms the latch by hand (the fail-safe direction is ON). + It runs on EVERY start, not only the migrating one: gating on `rep.ran` + swallowed store.py's rule-2 round trip (upgrade, downgrade with a trip + in the window, upgrade; performed on this site 2026-09-02). + DECISIONS/MAIN-orchestration.md.""" + rep = self.store_migration + if rep.ran and not rep.ok: + _LOG.error("The saved safety stops did not copy over cleanly, so " + "they are read again from the older saved state: %s.", + rep.explain()) + data = getattr(store, "data", {}) + legacy_tripped = bool(data.get("sign_tripped", False)) + if not legacy_tripped or not self.inverters: + return + # The question is "is any namespaced latch set THAT A MACHINE READS" + # (SAFETY-44), asked of the STORE's keys, not the roster's objects: + # re-arming A off a flat key that B's trip mirrored would latch a + # healthy inverter on every restart. Three cases: on the roster, stop; + # off-roster named `UNIT_A` (the broken migration's fingerprint), + # repair onto `inverters[0]`; off-roster, other name: stop unless a + # stranded `UNIT_A` latch is present. This guard is the ONLY repair for + # sites upgraded before the fix. Residual: a first unit really named + # `inverter-a`, latched and removed, is re-armed on `inverters[0]` + # (conservative). DECISIONS/MAIN-orchestration.md. + on_roster = {inv.name for inv in self.inverters} + stranded, on_roster_latched, other_off_roster = [], False, False + for k, v in data.items(): + if not (k.startswith("unit/") and k.endswith("/sign_tripped")): + continue + if not bool(v): + continue + # `unit_key()` builds `unit//`, so the unit is field 1: + # split through the writer's own spelling. + unit = k.split("/")[1] + if unit in on_roster: + on_roster_latched = True + elif unit == UNIT_A: + stranded.append(k) + else: + other_off_roster = True + if on_roster_latched or any(inv.sign_wd.tripped + for inv in self.inverters): + return + if other_off_roster and not stranded: + # A removed unit's own latch and no misdirected one: the flat key + # is that unit's mirror, so re-arming `inverters[0]` from it would + # latch a healthy pack. + return + if stranded: + _LOG.error( + "A saved safety stop belongs to %s, which is not in the " + "inverter list %s, so it is set again on the first inverter.", + ", ".join(sorted(stranded)), sorted(on_roster)) + first = self.inverters[0] + # The one state this method exists for. + reason = str(data.get("sign_reason", "") or "") + first.sign_wd.tripped = True + first.sign_wd.reason = reason or ( + "SIGN_DISAGREEMENT: latched before this version; the reason was " + "not carried across the per-inverter store migration") + first.store_set("sign_reason", first.sign_wd.reason) + first.store_set("sign_tripped", True) + _LOG.error( + "%s is set to 0 W again because an older saved safety stop was " + "found, so find out why before you start control: %s.", + first.name, messages.reason_code(first.sign_wd.reason)) + _LOG.debug("Evidence for %s: %s.", first.name, first.sign_wd.reason) + _LOG.debug( + "SAFETY-02 latch guard: the pre-DEV-02 flat key says the " + "sign-disagreement failsafe is latched and no inverter came up " + "latched. Either the per-inverter migration lost it, or an older " + "add-on wrote it during a rollback. Both would be a disarmed " + "guard, so the latch is re-armed on %s.", first.name) + self.log_event("FAILSAFE re-armed from the pre-DEV-02 store keys - " + + first.sign_wd.reason, + hint=messages.hint("stop_restored", unit=first.name)) + + # -- tasks --------------------------------------------------------------- + # -- OPT-04: the background tariff refresh ------------------------------- + def fresh_tariff_plan(self, now): + """The stored plan if it is still current, else None. NEVER a stale + one. THIS IS THE ONE PLACE THE AGE IS JUDGED, and it is public for + `loop_is_following()`'s reason: a check has to be able to assert on the + shipped expression rather than on a transcription that drifts. + (DECISIONS/MAIN-orchestration-archive.md)""" + if self.tariff_plan is None or self.tariff_at is None: + return None + if (now - self.tariff_at).total_seconds() > TARIFF_MAX_AGE_S: + return None + return self.tariff_plan + + async def run_tariff_refresh(self) -> None: + """Resolve the tariff off the control path, forever. NEVER on the tick. + ⚠️ IT CATCHES EVERYTHING AND KEEPS GOING: raising out of here would + freeze the plan, looking current for ever (`fresh_tariff_plan()`'s age + bound is the backstop). ⚠️ A FAILURE DOES NOT CLEAR THE PLAN + (TARIFF-12): a degraded plan replaces a standing observation only once + it has aged out; a §11.4 fallback never replaces a fresh provider plan. + ⚠️ `tariff_at` DOES NOT MOVE ON A KEPT PLAN. + (DECISIONS/MAIN-orchestration-archive.md)""" + horizon = float(price_option(self.o, "price_horizon_h")) + while not self.stopping: + now = datetime.now(timezone.utc) + try: + plan = await resolve_tariff( + self.o, now, now + timedelta(hours=horizon), now=now, + history=self.price_history, watch=self.price_watch) + standing = self.fresh_tariff_plan(now) + # Three terms, and each of them is the only false one in some + # check: the feed answered (replace), nothing current stands + # (take the degradation - this is what makes the age bound + # govern), or what stands is itself a degradation (replace). + keep = (not plan.from_feed + and standing is not None and standing.from_feed) + if keep: + _LOG.warning( + "The price update was incomplete, so the plan from %s " + "is kept until it is %s old. The update held %s.", + messages.when(brussels(self.tariff_at)), + messages.duration(TARIFF_MAX_AGE_S), plan.words) + else: + self.tariff_plan, self.tariff_at = plan, now + _LOG.info("tariff refreshed: %s", plan.words) + except Exception as err: # noqa: BLE001 + # ⚠️ NOT THE OUTAGE PATH - see the docstring: `load_prices()` + # returns on every failure a site can have, so what reaches + # here is unexpected, and the plan is kept on the same terms. + # (DECISIONS/MAIN-orchestration-archive.md) + _LOG.warning( + "The price update failed (%s), so the plan from %s is kept " + "until it is %s old, and trading stops then.", + err, messages.when(brussels(self.tariff_at)), + messages.duration(TARIFF_MAX_AGE_S)) + with contextlib.suppress(asyncio.TimeoutError): + await asyncio.wait_for(self.stop_event.wait(), + timeout=TARIFF_REFRESH_S) + + async def run_control(self) -> None: + # ⚠️ EACH INVERTER'S RATING FROM ITS OWN ENTITY, WHICH IS AC 4 (one + # read of one `setpoint_entity` left a second inverter's clamp, freeze + # rail and `achievable_w` on the first one's numbers). Concurrently: a + # slow ESPHome on one unit must not delay the start on the others. + # (DECISIONS/MAIN-orchestration-archive.md) + async def _limits(inv): + if inv.driver.configured(): + inv.dev_min, inv.dev_max = await self._driver(inv).limits() + await asyncio.gather(*(_limits(inv) for inv in self.inverters)) + entity = self.o.get("setpoint_entity", "") + # ⚠️ THIS USED TO WARN AND CARRY ON, the bug CFG-01 exists to remove: a + # max_w above the device's rating was silently clamped. amain() ran + # this gate already; it runs AGAIN because ESPHome is often not up at + # boot (limits None) and this is the first moment the real rating is + # known; a conflict refuses through the normal shutdown (0 W). ⚠️ THE + # `if entity:` THAT WRAPPED THIS BLOCK FAILED PERMISSIVE (CFG-04's + # hazard): a per-inverter config leaves the flat `setpoint_entity` + # blank, so the re-check was skipped; the per-unit rule now runs + # unconditionally. (DECISIONS/MAIN-orchestration-archive.md) + problems = [] + if entity: + _first = self.inverters[0] + problems += validate_startup_config(self.o, _first.dev_min, + _first.dev_max) + problems += validate_unit_ranges(self.inverters, skip_entity=entity) + if problems: + refuse(problems) + self.refused = problems + self.log_event("REFUSED: " + problems[0], + hint=messages.hint("refused")) + # Signal and return WITHOUT entering the loop: amain() runs the + # wind-down (0 W, or a hand-back: SMA-10, see + # DECISIONS/SMA-10-two-idle-states.md) and exits with code 78. + self.stop_event.set() + return + + last_grid = object() + heartbeat = float(self.o.get("heartbeat_s", 10)) + # ⚠️ SAFETY-12. The floor is a DEADLINE ON THE GAP BETWEEN CYCLES, not + # a second scheduler: every cycle resets it, so on a healthy meter it + # never elapses and the per-cycle gain is unchanged. It exists because + # a meter that repeats a value would run NO cycles, and the `inputs + # missing -> 0 W` claim lives inside cycle(). NOT a freeze detector. ⚠️ + # THE 15 s DEFAULT HAS A CEILING IT DOES NOT OWN: it sits under + # validate.FIRMWARE_INGEST_VETO_S (30 s) and `meter_max_age_s` and + # moves with the firmware's veto; the schema minimum of 5 s is the + # reference meter's interval and deserves a second look. + # (DECISIONS/MAIN-orchestration-archive.md) + floor = float(self.o.get("cycle_floor_s", 15)) + last_cycle = None + while not self.stopping: + await self.read_inputs() + now_mono = asyncio.get_running_loop().time() + # A cycle is one meter update, exactly as on the reference install - + # or the floor elapsing, whichever comes first. + overdue = last_cycle is None or (now_mono - last_cycle) >= floor + if self.grid != last_grid or overdue: + last_grid = self.grid + last_cycle = now_mono + # ⚠️ The FULL cycle, not a degraded one: in P1 mode past + # `meter_max_age_s` (30 s) p1.net_w is None ("inputs missing"). + # ⚠️ TRANSPORT-CONDITIONAL: with `meter_source: off`, + # read_inputs() has NO age gate, so a quiet entity reads as + # current; the floor does not make it fresh. The integrator + # advances per CYCLE, so bounding the gap bounds the + # accumulation. (DECISIONS/MAIN-orchestration-archive.md) + await self.cycle() + # ⚠️ The heartbeat is not an optimisation: the ESP32 zeroes the + # inverter after ~30 s of silence, and refreshing the SAME value + # proves we are alive. ⚠️ ONE DEADLINE PER INVERTER, refreshed + # concurrently, each bounded by WRITE_BUDGET_S (budget plus the + # largest `heartbeat_s` stays under layer 1's veto: graded); each + # unit refreshes its own `inv.target`, never the site target. + # (DECISIONS/MAIN-orchestration-archive.md) + await self.send_heartbeats(asyncio.get_running_loop().time(), + heartbeat) + self.publish() + self.loop_pass_mono = time.monotonic() + await asyncio.sleep(1) diff --git a/goodwe_controller/app/ctl_trade.py b/goodwe_controller/app/ctl_trade.py new file mode 100644 index 0000000..09b92f6 --- /dev/null +++ b/goodwe_controller/app/ctl_trade.py @@ -0,0 +1,1281 @@ +"""Controller methods for trading: mode runs, peak floors, pack actions. + +Moved unchanged from app/main.py (MAINT-21). DECISIONS/MAIN-orchestration.md.""" + +import collections +import dataclasses +import logging +from datetime import datetime, timedelta, timezone + +from . import arbitrage +from .arbiter import ( + ACTUATOR_SITE, Claim, P_MAINTENANCE, P_MAINT_SHAPE, P_PEAK, SET, + pre_resolve, +) +from . import allocator +from . import dayplan +from . import modetrade +from . import packmode +from . import priceruns +from . import solarfc +from . import control as _ctl +from . import messages +from .maintenance import CHARGE, DRAIN, HOLD, IDLE, MaintConfig, POWER_MOVING +from .mqtt import MODE_LABELS, USE_OFF, USE_ON, unit_slugs, unit_state_key +from . import peakguard +from . import packshare +from .price import Absence +from .price import required_spread as price_required_spread +from .price import uncertainty_of as price_uncertainty_of +from .price_chain import gate_for +from .static_tariff import static_gated +from .ctl_inputs import TARIFF_MAX_AGE_S + +_LOG = logging.getLogger("goodwe") + + +# OPT-11 P3: how long the last cheap run stays the price stored energy is +# valued at: the rest of that day. +REF_CHEAP_KEEP = timedelta(hours=12) + + +# OPT-15: the longest a run edge holds the loop at E waiting for the meter to +# show the step (control.PLANT_SETTLE_S). +EDGE_HOLD_S = _ctl.PLANT_SETTLE_S + + +# OPT-11 P4: store key of the house profile, and how often the forecast sensors +# are read (hourly at most). +HOUSE_PROFILE_KEY = "house_profile" + + +# OPT-34: the level of a night grid charge that has started, so it does not +# drop when the forecast goes (`Controller._latch_charge()`). +CHARGE_LATCH_KEY = "night_charge_latch" + + +# OPT-34: a latch outlives its last cheap run by one price slot, since the next +# run is planned at the slot edge. +CHARGE_LATCH_GRACE_S = 900.0 + + +def _night_limit(born): + """OPT-34: a run that starts after this cannot carry the latch on: the + first bell start (`solarfc.BELL_FROM_H`, local) after `born`.""" + d0, d1 = solarfc._bounds(born) + bell = solarfc._bell_start(d0) + return bell if bell > born else solarfc._bell_start(d1) + + +def pack_energy_of(inv): + """OPT-09. ONE roster entry as the view `packshare` consumes. + One builder for two callers (`pack_energy` needs the roster, `cycle()` one + entry): written twice they would drift. A module function so inverter.py + need not import `packshare`.""" + return packshare.PackEnergy(inv.name, inv.soc, inv.bms_soc_floor, + inv.capacity_kwh, inv.max_w) + + +# MAINT-13: a battery power reading at or below minus this many W is a pack +# that is taking charge. +MAINT_CHARGING_W = 50.0 + + +class TradeMixin: + def trade_power_w(self, floor_pct, ceiling_pct) -> tuple: + """OPT-09. `(charge_w, discharge_w)`: how hard a trade may be SIZED: + what the site can push AND STILL HAVE SOMEWHERE TO PUT. The bounds are + arbitrage's own (`arbitrage_soc_floor` / `_ceiling`), NOT the BMS + cut-out that `packshare.envelope()` uses (SAFETY-25): different + questions. It sizes the ask, it does not route it. A pack whose SoC did + not read counts on neither side. Neither side may be zero on a trading + tick (`arbitrage.decide()` refuses `IDLE_NO_SIZE`: a 0 W claim is a + park order). DECISIONS/MAIN-orchestration.md.""" + # The reduction lives in `packshare`; `test_packshare.py` part 9 calls + # the SAME function (a transcription in a check is a copy that drifts). + return packshare.trade_power_w(self.pack_energy, floor_pct, ceiling_pct) + + def peak_aim_w(self) -> float: + """SAFETY-79. `peak_cap_w` less `peak_margin_w`: what the forecast + checks aim at. Reports and the bill use the real cap.""" + return float(self.o.get("peak_cap_w", 3500)) - self.peak_margin_w + + @property + def pack_energy(self) -> list: + """OPT-09. Each pack as the FOUR numbers a split needs; the fourth is + `capacity_kwh`, which is why this is not `packs`. EVERY unit, live + or not, for `packs`'s reason (the allocator drops dead ones itself).""" + return [pack_energy_of(inv) for inv in self.inverters] + + def pack_weights(self, target_w): + """OPT-09. The comfort weights for a site target of `target_w`. A + method handed to `resolve()`, not a dict computed before it (energy + headroom depends on the target), and read fresh on every call, never + cached.""" + base = packshare.weights(self.pack_energy, target_w) + if not self.modes_on: + return base + # OPT-11: the solar order. While the site charges, Leftover solar + # batteries weigh 0, so Solar first fill first (comfort, like the rest + # here; permission is the mode claim). + w = packmode.charge_weights(base, self.pack_modes(), target_w) + # P3: in a price run, the batteries whose run it is carry it first. + tick = self.mode_tick + return w if tick is None else modetrade.weights(tick.roles, w, + target_w) + + def pack_mode(self, inv) -> "packmode.PackMode": + """OPT-11. This battery's on/off switch and mode, read from the store.""" + return packmode.read(getattr(self.store, "data", None) or {}, inv.name) + + def pack_modes(self) -> dict: + return {inv.name: self.pack_mode(inv) for inv in self.inverters} + + def loop_bound(self, claims): + """OPT-11. `(lo, hi)`: what the batteries may place if the loop + decides: the sum over live units of each unit's hard limits with its + mode applied (`allocator.loop_bound()`), from THIS cycle's unit + claims. None when no mode is filed (maintenance) or the range leaves + out 0 W (a fault `resolve()` reports).""" + if len(self.inverters) <= 1: + modes = [c for c in claims if c.source == "mode"] + if not modes: + return None + lo = max(c.lo for c in modes) + hi = min(c.hi for c in modes) + return (lo, hi) if lo <= 0.0 <= hi else None + bounds = {u: pre_resolve([c for c in claims if c.actuator == u]) + for u in self.units} + return allocator.loop_bound(bounds, live=self.live_units()) + + # --- OPT-11 P3: price runs, per battery ------------------------------- + def _mode_packs(self, maint_results=None) -> list: + """Each battery as `modetrade.Pack`, in roster order.""" + live = set(self.live_units()) + out = [] + for i, inv in enumerate(self.inverters): + pm = self.pack_mode(inv) + idle = (maint_results is None + or maint_results[i].phase == IDLE) + refused = (inv.refused if len(self.inverters) > 1 + else self.batt_refused) or 0 + # OPT-15: a charge refusal's probe (SAFETY-73, N>1) as it stood + # when last decided; its pin is filed after this, in cycle(). + probing = (len(self.inverters) > 1 and refused < 0 + and inv.probe_from is not None) + out.append(modetrade.Pack( + inv.name, pm.use, pm.mode, pm.sell and pm.can_sell, + float(inv.max_w), inv.soc, inv.capacity_kwh, + live=inv.name in live, idle=idle, refused=int(refused), + probing=probing)) + return out + + def _wx_track(self, now) -> None: + """TARIFF-24, once per cycle, before the plan: with a forecast read, + remember when the run now under way (cheap, give or sell) ends.""" + if self.solar_fc is None: + return + rp = self.mode_runs + ends = [] + if rp is not None and rp.on: + ends = [r.end for r in (rp.cheap, rp.sell) + if r is not None and r.holds(now)] + g = rp.give_at(now) + if g is not None: + ends.append(g.end) + self._wx_free_to = max(ends) if ends else None + + def weather_held(self, now) -> bool: + """TARIFF-24: no forecast now, but a run planned with one is under way: + it keeps its gap to its end (OPT-34: a night charge that keeps its + level too); the wider gap applies from the next run. Pure; Home asks + the same (`homeview.trade_verdict()`). + (DECISIONS/MAIN-orchestration-archive.md)""" + return self.solar_fc is None and ( + (self._wx_free_to is not None and now < self._wx_free_to) + or (self._charge_latch is not None + and now < self._charge_latch[0])) + + def _price_runs(self, now, packs, floor_pct, ceiling_pct): + """The kept run plan, rebuilt at most once per price slot (15 min) or + when the prices or a battery's choice change; a run under way is kept + to its end (`priceruns.keep_started()`). None with no fresh firm + prices: then no battery holds or trades. + (DECISIONS/MAIN-orchestration-archive.md)""" + plan = self.fresh_tariff_plan(now) + if plan is None or not plan.has_prices: + self.mode_runs, self._runs_key = None, None + self.day_plan = None + return None + slot = int(now.timestamp() // 900) + key = (id(plan), slot, tuple((p.name, p.use, p.mode, p.sell) + for p in packs)) + held = self.weather_held(now) + if self.fc_entity is not None: + # P4: a forecast arriving or going rebuilds the plan at once (and + # so does the end of a run that held the gap, TARIFF-24). + key += (self.solar_fc is None, held) + if key != self._runs_key: + done_c = self._run_done.get("charge", (None, set()))[1] + done_s = self._run_done.get("sell", (None, set()))[1] + e = modetrade.energy(packs, floor_pct, ceiling_pct, done_c, + done_s) + required = price_required_spread( + arbitrage.threshold_eur_kwh(self.o), + price_uncertainty_of(plan.read.product) + | arbitrage.weather_uncertainty(True, self.solar_fc, held)) + ref = self._ref_cheap + if ref is not None and now - ref.end > REF_CHEAP_KEEP: + ref = self._ref_cheap = None + new = priceruns.plan( + plan.read.points, now, required_eur_kwh=required, + charge_kwh=e[0], charge_kw=e[1], sell_kwh=e[2], + sell_kw=e[3], + ref_eur_kwh=None if ref is None else ref.mean_eur_kwh) + if self.fc_entity is not None: + new = self._day_plan(now, packs, floor_pct, ceiling_pct, + new, plan, required, ref, done_c, e) + self.mode_runs = priceruns.keep_started(self.mode_runs, new, now) + self._runs_key = key + runs = self.mode_runs + # The cheapest cheap run under way lately is the price the stored + # energy was bought at; it stays the reference for REF_CHEAP_KEEP + # after it ends, unless a cheaper one comes. + ref = self._ref_cheap + if runs is not None and runs.cheap is not None \ + and runs.cheap.holds(now) and ( + ref is None or now - ref.end > REF_CHEAP_KEEP + or runs.cheap.mean_eur_kwh <= ref.mean_eur_kwh): + self._ref_cheap = runs.cheap + return runs + + def _day_plan(self, now, packs, floor_pct, ceiling_pct, runs, plan, + required, ref, done_c, e): + """OPT-11 P4: the day plan (`dayplan.plan()`) on the runs just made, + its levels held by the hysteresis (`dayplan.hold()`), then the runs + made again with each battery's shortfall as the charge. With no plan + (no or stale forecast, no house profile yet) the levels are dropped: P3 + option A. (DECISIONS/MAIN-orchestration-archive.md)""" + dp = dayplan.plan( + self.solar_fc, + None if self.house_profile is None + else self.house_profile.estimator(), + priceruns.keep_started(self.mode_runs, runs, now), now, packs, + trust_pct=self.solar_trust_pct, floor_pct=floor_pct, + ceiling_pct=ceiling_pct, aim_w=self.peak_aim_w(), + slots=priceruns.firm_slots(plan.read.points, now), + spread=required) + self.day_plan = dp + if dp is None: + self._plan_targets = None + return runs + self._plan_targets = dayplan.hold( + self._plan_targets, dp.targets, + {p.name: p.capacity_kwh for p in packs}) + e2 = modetrade.energy(packs, floor_pct, ceiling_pct, done_c, (), + targets=self._plan_targets) + return priceruns.plan( + plan.read.points, now, required_eur_kwh=required, + charge_kwh=e2[0], charge_kw=e2[1], sell_kwh=e[2], sell_kw=e[3], + ref_eur_kwh=None if ref is None else ref.mean_eur_kwh) + + def plan_targets(self): + """P4: each battery's planned level, or None (no day plan). Dropped + at once when the forecast goes (stale or missing), except the level + of a night charge that has started (OPT-34): it keeps that level.""" + if self.solar_fc is None: + lt = self._charge_latch + if lt is None or datetime.now(timezone.utc) >= lt[0]: + return None + return dict(lt[1]) + return self._plan_targets + + def _latch_charge(self, now, runs, targets, packs=None) -> None: + """OPT-34, once per cycle after `modetrade.decide()`: a started night + grid charge keeps its planned level when the forecast goes mid-charge + (`plan_targets()` gives the latched levels, `weather_held()` the narrow + price gap). The latch lasts through every cheap run plus one price slot + (`CHARGE_LATCH_GRACE_S`), is dropped when `now` passes its end or the + battery leaves its mode, and a charge that never started has none. + DECISIONS/OPT-34-the-night-charge-keeps-its-level.md""" + old = lt = self._charge_latch + tick = self.mode_tick + run = None if runs is None else runs.cheap + in_run = run is not None and run.holds(now) + grace = timedelta(seconds=CHARGE_LATCH_GRACE_S) + if lt is not None and now >= lt[0]: + lt = None + if lt is not None and packs is not None: + ok = {p.name for p in packs + if p.use and p.mode in packmode.PLAN_CHARGE_MODES} + lv = {n: v for n, v in lt[1].items() if n in ok} + lt = (lt[0], lv, lt[2]) if lv else None + # A run may carry the latch on only if it starts by the night's bell. + carry = in_run and (lt is None or run.start <= _night_limit(lt[2])) + if in_run and self.solar_fc is not None: + # Rebuilt from the plan: a battery already latched follows its + # level up or down whatever its role this tick (a fresh figure may + # lower it below the SoC), one that left the plan is dropped, and + # a new one comes in only while it charges from the grid. + tg = targets or {} + lv = {n: float(tg[n]) for n in (lt[1] if lt else {}) if n in tg} + if tick is not None and tick.action == modetrade.CHARGE: + lv.update({n: float(tg[n]) for n, r in tick.roles.items() + if r == modetrade.CHARGE and n in tg}) + if not lv: + lt = None + elif lt is None: + lt = (run.end + grace, lv, now) + else: + lt = (max(run.end + grace, lt[0]) if carry else lt[0], lv, + lt[2]) + elif lt is not None and carry: + lt = (max(lt[0], run.end + grace), lt[1], lt[2]) + if lt != old: + self._charge_latch = lt + self.store.set(CHARGE_LATCH_KEY, None if lt is None else { + "until": lt[0].isoformat(), "levels": lt[1], + "born": lt[2].isoformat()}) + + def _mode_roles(self, now, maint_results): + """OPT-11 P3: each battery's role and range this tick. Grid charging + and selling need a fresh plan that `TariffPlan.arbitrage()` allows with + the MEASURED peak guard (None refuses: nothing measures the quarter), + exactly the gate `arbitrage.decide()` has. + (DECISIONS/MAIN-orchestration-archive.md)""" + floor_pct, ceiling_pct = arbitrage.soc_bounds(self.o) + packs = self._mode_packs(maint_results) + self._wx_track(now) + runs = self._price_runs(now, packs, floor_pct, ceiling_pct) + guard = arbitrage.guard_state(self.peak_guard) + plan = self.fresh_tariff_plan(now) + charge_ok = sell_ok = False + trade_why = "not_covered" + + def allowed(active): + return plan.arbitrage( + peak_guard_active=active, + min_spread_eur_kwh=arbitrage.threshold_eur_kwh(self.o), + uncertainty=arbitrage.weather_uncertainty( + True, self.solar_fc, self.weather_held(now)), + now=now).match( + allowed=lambda _v: True, refused=lambda _v: False) + if guard is not None and plan is not None and runs is not None: + # A charge asks the guard (section 9.1 interlock); a sell only + # needs it to have measured the quarter, since discharge is never + # capped by it (a big discharge alone engages it on export). + sell_ok = allowed(False) + charge_ok = sell_ok and allowed(guard) + trade_why = (None if charge_ok else "peak" if sell_ok + else "not_worth") + self.mode_gate = None if charge_ok else trade_why + price_now = None + if plan is not None: + try: + pt = plan.read.match(series=lambda r: r.at(now), + no_data=lambda _r: None) + price_now = (None if pt is None or pt.provisional + else float(pt.eur_per_kwh)) + except Absence: + price_now = None + house = (None if self.grid is None or self.site_batt_w is None + else float(self.grid) + float(self.site_batt_w)) + if self.house_profile is not None and \ + self.house_profile.add(now, house): + self.store.set(HOUSE_PROFILE_KEY, self.house_profile.dump()) + targets = self.plan_targets() + if targets is None: + done_c = self._run_mark("charge", runs and runs.cheap, packs, + lambda p: p.soc is not None + and p.soc >= ceiling_pct) + else: + # P4: out of the run at its planned level. A level the + # hysteresis moved opens the run to it again (a new mark key). + def full(p): + to = modetrade.charge_to(p, ceiling_pct, targets) + return p.soc is not None and (to is None or p.soc >= to) + done_c = self._run_mark("charge", runs and runs.cheap, packs, + full, tuple(sorted(targets.items()))) + done_s = self._run_mark("sell", runs and runs.sell, packs, + lambda p: p.soc is not None + and p.soc <= floor_pct) + quarter = int(now.timestamp() // 900) + was = self.mode_tick is not None and \ + self.mode_tick.action == modetrade.CHARGE + # SAFETY-135: the first guard stop in a period (or measured headroom + # stop in a young one) does not latch; the charge may start again + # RESTART_S after it, but not in the period's last RESTART_S. No + # start in a young period while a give falls. + # DECISIONS/SAFETY-135-young-period.md + st = getattr(self, "_charge_stop", None) + paused = (st is not None and st[0] == quarter + and (now.timestamp() - st[1] < modetrade.RESTART_S + or (quarter + 1) * 900 - now.timestamp() + < modetrade.RESTART_S)) + wait = ("wait" if paused else + "settle" if self._give_falling(now) else None) + self.mode_tick = modetrade.decide( + runs, now, packs, charge_ok=charge_ok, sell_ok=sell_ok, + trade_why=trade_why, price_now=price_now, + headroom_w=self.arb_headroom_w, floor_pct=floor_pct, + ceiling_pct=ceiling_pct, house_w=house, charging_now=was, + blocked=self._charge_blocked_q == quarter, + done_charge=done_c, done_sell=done_s, targets=targets, + draining=any(r.phase == DRAIN for r in maint_results or ()), + wait=wait, + maint_charging=any(r.phase == CHARGE + for r in maint_results or ())) + self._latch_charge(now, runs, targets, packs) + # A charge the guard or the headroom stopped stays off this period. + # OPT-15: only a MEASURED stop latches; the first unmeasured headroom + # in a quarter stops one tick, a second latches. + # (DECISIONS/MAIN-orchestration-archive.md) + if was and self.mode_tick.action != modetrade.CHARGE: + why = self.mode_tick.why + gap = why == "headroom" and self.arb_headroom_w is None + if why == "peak" or (why == "headroom" and not gap) or ( + gap and self._charge_gap_q == quarter): + young = now.timestamp() - quarter * 900 < modetrade.YOUNG_S + if (why == "peak" or (young and not gap)) and ( + st is None or st[0] != quarter): + self._charge_stop = (quarter, now.timestamp()) + else: + self._charge_blocked_q = quarter + elif gap: + self._charge_gap_q = quarter + return self.mode_tick + + def _give_falling(self, now) -> bool: + """SAFETY-135: True in a young period while the batteries give over + START_W less than they did in the last GAVE_S s: the meter may not + show that yet, so a charge room read now is too big. + DECISIONS/SAFETY-135-young-period.md""" + t = now.timestamp() + gave = getattr(self, "_gave", None) + if gave is None: + gave = collections.deque() + self._gave = gave + if gave and t < gave[-1][0]: + gave.clear() # the clock stepped back + if self.site_batt_w is not None: + gave.append((t, max(0.0, float(self.site_batt_w)))) + while gave and t - gave[0][0] >= modetrade.GAVE_S: + gave.popleft() + if self.site_batt_w is None or not gave \ + or t % 900 >= modetrade.YOUNG_S: + return False + drop = max(w for _t, w in gave) - max(0.0, float(self.site_batt_w)) + return drop > modetrade.START_W + + def _run_mark(self, kind, run, packs, out, extra=None) -> set: + """The batteries that left run `run` (full, or at the floor); they + stay out until it ends, so a level edge does not re-arm them. + `extra` (P4: the planned levels) is part of the run's key.""" + key = None if not run else (run.start, run.end) + if key is not None and extra is not None: + key += (extra,) + was_key, done = self._run_done.get(kind, (None, set())) + if key != was_key: + done = set() + if key is not None: + done |= {p.name for p in packs if out(p)} + self._run_done[kind] = (key, done) + return done + + def _mode_trade(self, claims, now) -> bool: + """OPT-11 P3: file the site trade the roles ask for, sized inside the + modes and the hard limits and, for a charge, the billed quarter's + headroom (SAFETY-45, aim cap - margin, SAFETY-79), so no battery that + its mode or a refusal holds is asked for watts it may not give. + (DECISIONS/MAIN-orchestration-archive.md)""" + tick = self.mode_tick + if tick is None: + return False + if tick.action == modetrade.CHARGE: + # OPT-20: the ask carries PROBE_W for exactly the probes whose pin + # is filed this tick (`decide()` ran before the pin, so they can + # differ by one cycle; left alone the allocator moves the pin's + # watts to another battery). + # (DECISIONS/MAIN-orchestration-archive.md) + pins = _ctl.PROBE_W * sum( + 1 for c in claims if c.source == "refused" + and c.kind == "set" and c.value < 0) + if pins != tick.probe_w: + tick = self.mode_tick = dataclasses.replace( + tick, ask_w=tick.ask_w + tick.probe_w - pins, + probe_w=pins) + size = modetrade.size(tick, self.loop_bound(claims) + if tick.action else None, self.arb_headroom_w) + runs = self.mode_runs + if tick.action and (size == 0.0 or runs is None): + # Nothing the batteries may place (a refusal, a hard limit): no + # trade, and the roles say so rather than "charging". + back = {modetrade.CHARGE: modetrade.HOLD, + modetrade.REST: modetrade.HOUSE, + modetrade.SELL: modetrade.GIVE} + tick = self.mode_tick = modetrade.Tick( + tick.ranges, {n: back.get(r, r) for n, r in tick.roles.items()}, + None, 0.0, "size") + if size == 0.0 or runs is None: + reason = ("battery modes: no price run now" if tick.why is None + else modetrade.WAIT_WORDS.get(tick.why) + or f"battery modes: no trade ({tick.why})") + self.arb = arbitrage.ArbitrageDecision( + action=None, power_w=None, reason=reason, + spread_eur_kwh=None, required_eur_kwh=None, + price_now_eur_kwh=None) + else: + charge = tick.action == modetrade.CHARGE + run = runs.cheap if charge else runs.sell + who = ", ".join(n for n, r in sorted(tick.roles.items()) + if r == tick.action) + act = arbitrage.CHARGE if charge else arbitrage.DISCHARGE + self.arb = arbitrage.ArbitrageDecision( + action=act, power_w=size, + reason=(f"{act}: battery modes, " + f"{'cheap' if charge else 'sell'} run " + f"{run.start.isoformat()} to {run.end.isoformat()} " + f"at {run.mean_eur_kwh:.4f} EUR/kWh; " + f"{abs(size):.0f} W on {who}"), + spread_eur_kwh=None, required_eur_kwh=runs.level_eur_kwh, + price_now_eur_kwh=None) + claims.append(arbitrage.claim(self.arb)) + if self.arb.action != self._arb_action: + self._arb_action = self.arb.action + self.log_event(self.arb.explain(), hint=messages.hint( + "trade_charge" if self.arb.action == arbitrage.CHARGE else + "trade_give" if self.arb.action == arbitrage.DISCHARGE + else "trade_off")) + return self.arb.action is not None + + def _reseed_run_edge(self, claims, now) -> None: + """OPT-11 P3: a mode trade just ended, so the loop takes over from a + command no loop chose: it starts at the house's own point E, not at the + trade's watts, and OPT-15 HOLDS it at E (`_edge_grid()`) until the + meter shows the step or `EDGE_HOLD_S` passes. + DECISIONS/OPT-11-battery-modes.md""" + self._edge = None + batt = self.site_batt_w + if batt is None or self.grid is None: + return + want = float(batt) + float(self.grid) - self.tuning.target_grid_w + bound = self.loop_bound(claims) + if bound is not None: + want = max(bound[0], min(bound[1], want)) + want = float(round(max(-self.site_max_w, min(self.site_max_w, want)))) + self.target = self.i_w = want + if want != float(batt): + self._edge = (want, 1.0 if want > float(batt) else -1.0, + now + timedelta(seconds=EDGE_HOLD_S), float(batt)) + + def _edge_grid(self, end, now): + """OPT-15: the grid reading the loop acts on this tick. While a run + edge is held, the target itself (no error, the command stays at E); the + hold ends when the meter reaches the target, on `end`, or after + `EDGE_HOLD_S`. (DECISIONS/MAIN-orchestration-archive.md)""" + e = self._edge + if e is None: + return self.grid + held_w, sign, until, last_b = e + tg, db = self.tuning.target_grid_w, self.tuning.deadband_w + b = self.site_batt_w + moving = (b is not None and sign * (float(b) - last_b) >= db + and sign * (held_w - float(b)) >= db + and now < until + timedelta(seconds=EDGE_HOLD_S)) + if (end or (now >= until and not moving) + or sign * (float(self.grid) - tg) < db): + self._edge = None + return self.grid + self._edge = (held_w, sign, until, last_b if b is None else float(b)) + self.i_w = held_w + return tg + + def _charge_track(self, claims, maint_results) -> None: + """SAFETY-93, N>=2: a charge ends when its battery leaves CHARGE or can + no longer be placed (stale link, refusal). Kept until the loop runs. + SAFETY-95: a drain likewise; its refusal (SAFETY-73) is read from the + battery (+1 = will not give). (DECISIONS/MAIN-orchestration-archive.md)""" + if len(self.inverters) < 2: + return + live = set(self.live_units()) + now = {CHARGE: set(), DRAIN: set()} + for inv, res in zip(self.inverters, maint_results): + u = self.actuator_of("maintenance", inv) + if res.phase in now and u in live and not pre_resolve( + [c for c in claims if c.actuator == u]).contradiction \ + and not (res.phase == DRAIN and (inv.refused or 0) > 0): + now[res.phase].add(inv.name) + self._charge_ended |= self._charging_was - now[CHARGE] + self._charging_was = frozenset(now[CHARGE]) + self._drain_ended |= self._draining_was - now[DRAIN] + self._draining_was = frozenset(now[DRAIN]) + + def _reseed_charge_end(self, maint_results) -> None: + """SAFETY-93, N>=2: when a battery's maintenance charge ends, the loop + starts from what the others stood at plus that battery's new command + (its HOLD pin, or its last discharge if it is free; a charge stops); + else the charge's watts land on the others (B 0 -> -1600 W in one + cycle). DECISIONS/SAFETY-93-charge-end.md""" + ended, self._charge_ended = self._charge_ended, frozenset() + if len(self.inverters) < 2 or not ended: + return + for inv, res in zip(self.inverters, maint_results): + if inv.name not in ended: + continue + now_w = (float(res.setpoint_w or 0.0) if res.owns_setpoint + else max(float(inv.target), 0.0)) + if not inv.is_live(datetime.now(timezone.utc))[0]: + now_w = 0.0 # SAFETY-96: out of the split, it is sent 0 W + self.target += now_w - float(inv.target) + # SAFETY-96: it settles from its charge to that command. + self._loop_start[inv.name] = now_w + self._settle[inv.name] = self._now_mono + self.i_w = self.target + + def _reseed_drain_end(self, maint_results, live) -> None: + """SAFETY-95, N>=2: when a battery's maintenance drain ends, its drain + leaves the loop's start point, as a charge does (SAFETY-93): the start + is what the others stood at plus its new command (its pin, else 0 W), + never above last cycle's start; else the drain's floor lands on the + others (B 0 -> +1600 W, exporting). DECISIONS/SAFETY-95-drain-end.md""" + ended, self._drain_ended = self._drain_ended, frozenset() + if len(self.inverters) < 2 or not ended: + return + hi = self.target + for inv, res in zip(self.inverters, maint_results): + if inv.name not in ended: + continue + now_w = (float(res.setpoint_w or 0.0) + if res.owns_setpoint and res.phase != DRAIN + else min(float(inv.target), 0.0)) + if inv.name not in live: + now_w = 0.0 # SAFETY-96: out of the split, it is sent 0 W + else: + self._drain_tail.add(inv.name) + self.target += now_w - float(inv.target) + self._loop_start[inv.name] = now_w + self._settle[inv.name] = self._now_mono + lo, hi = sorted((self.target, hi)) + # A dropped battery's power is the meter's, like the house's. + here = float(self.grid) - self.tuning.target_grid_w + sum( + float(inv.batt) for inv in self.inverters if inv.name in live) + self.target = self.i_w = min(hi, max(lo, here)) + + def _drain_grid_w(self, live) -> float: + """SAFETY-95: the grid the loop regulates. While a battery settles from + its ended drain (`_held_out_w`, at most PLANT_SETTLE_DOWN_S) the + batteries count at the site command, so the loop does not chase the + drain's tail. SAFETY-103: a reading can be up to a register period (10 + s) older than the meter, so the house point is held and moved only as + far as the meter proves. + DECISIONS/SAFETY-103-old-readings-after-a-drain.md""" + grid = float(self.grid) + self._drain_tail &= set(self._settle) & set(live) + if not self._drain_tail: + self._drain_house = None + return grid + aim = self.tuning.target_grid_w + lo = hi = grid - aim + for inv in self.inverters: + if inv.name not in live: + continue + r = float(inv.batt) + span = self._read_span.get(inv.name) + if (span is None or span[2] != inv.batt_fresh.changed_mono + or span[2] == self._now_mono): + span = (r, r) + # A battery that refuses one way (SAFETY-73) is not heading + # that way, whatever it was asked: that side is its reading. + if (inv.refused or 0) > 0: + span = (min(span[0], r), r) + elif (inv.refused or 0) < 0: + span = (r, max(span[1], r)) + lo, hi = lo + span[0], hi + span[1] + held = (float(self.target) if self._drain_house is None + else self._drain_house) + self._drain_house = min(hi, max(lo, held)) + return self._drain_house - float(self.target) + aim + + def _track_reads(self) -> None: + """SAFETY-103, N>=2: per battery, the range its power can be in now: + its last changed reading and every command on its wire since (a + lagging battery moves from one toward the others, never beyond).""" + if len(self.inverters) < 2: + return + for inv in self.inverters: + if inv.batt is None: + continue + cmd, since = inv.standing_w(), inv.batt_fresh.changed_mono + lo, hi, was = self._read_span.get(inv.name, (0.0, 0.0, None)) + if was is None or since != was: + lo = hi = float(inv.batt) + self._read_span[inv.name] = (min(lo, cmd), max(hi, cmd), since) + + def _reseed_drop(self, live) -> None: + """SAFETY-96, N>=2: a battery that drops out of the split (stale link) + leaves the loop's start point, so the others take over at one slew step + a cycle instead of taking its share at once. + DECISIONS/SAFETY-96-dropped-battery.md""" + was, self._live_was = self._live_was, frozenset(live) + if len(self.inverters) < 2 or was is None or was == live: + return + for inv in self.inverters: + if inv.name in self._charge_ended | self._drain_ended: + continue # SAFETY-93/95's edge: `_reseed_*_end()` + if inv.name in was and inv.name not in live: + now_w = 0.0 + elif inv.name in live and inv.name not in was: + now_w = float(inv.batt) + # The split is made again, so every battery's command steps. + self._settle.update( + {u: self._now_mono for u in live}) + else: + continue + self.target += now_w - float(inv.target) + self._loop_start[inv.name] = now_w + self.i_w = self.target + + def _held_out_w(self, live) -> float: + """SAFETY-96, N>=2: what to add to the site sum so that a battery the + loop cannot move right now counts at its command, not at its reading. + Its real power still reaches the loop through the meter: neither lost + nor counted twice. DECISIONS/SAFETY-96-dropped-battery.md""" + if len(self.inverters) < 2: + return 0.0 + out = 0.0 + for inv in self.inverters: + cmd = self._loop_start.get(inv.name, float(inv.target)) + since = self._settle.get(inv.name) + age = (None if since is None or self._now_mono is None + else self._now_mono - since) + if since is not None and ( + age is None or age >= _ctl.PLANT_SETTLE_DOWN_S + or (age > 0 and abs(float(inv.batt) - cmd) + < self.tuning.deadband_w)): + del self._settle[inv.name] + if (inv.name not in live or inv.rejected_since is not None + or inv.name in self._settle): + out += cmd - float(inv.batt) + return out + + def _mode_fault_log(self, resolution) -> None: + """OPT-11: say once, per battery, that its mode was dropped as a fault. + A mode range without 0 W would force a direction, which no mode may do, + so it is never applied (allocator.unit_interval()); main.py never + builds one. (DECISIONS/MAIN-orchestration-archive.md)""" + alloc = resolution.allocation + now = {u for u, _ in getattr(alloc, "mode_faults", ())} + if resolution.mode_fault is not None and self.inverters: + now.add(self.inverters[0].name) + for inv in self.inverters: + if inv.name in now and inv.name not in self._mode_faults: + _LOG.error("Battery mode ignored for %s. Software fault " + "MODE_RANGE.", inv.name) + self.log_event(f"battery mode ignored on {inv.name}, a " + f"software fault", hint=messages.hint( + "mode_fault", unit=inv.name)) + self._mode_faults = now + + def _pack_action(self, what, unit, value, now) -> dict: + """OPT-11: switch one battery on or off, set its mode, or (P3) turn its + selling on or off. Store state, not an option: it applies next cycle + with no restart. Switching a battery off also stops its maintenance + cycle. (DECISIONS/MAIN-orchestration-archive.md)""" + if not self.modes_on: + return {"error": messages.pack_refused("off")} + inv = next((i for i in self.inverters if i.name == unit), None) + if inv is None: + return {"error": messages.pack_refused("unit")} + if what == "pack_use": + if not isinstance(value, bool): + return {"error": messages.pack_refused("value")} + inv.store_set(packmode.USE_KEY, value) + self.log_event(f"{inv.name} switched {'on' if value else 'off'} " + f"by operator", + hint=messages.hint("pack_on" if value + else "pack_off", unit=inv.name)) + if not value: + self._maint_stop_off(self.maints[self.inverters.index(inv)], + now) + elif what == "pack_sell": + if not packmode.SELLING_ENABLED: + return {"error": messages.pack_refused("sell_off")} + if not isinstance(value, bool): + return {"error": messages.pack_refused("value")} + inv.store_set(packmode.SELL_KEY, value) + self.log_event(f"{inv.name} selling switched " + f"{'on' if value else 'off'} by operator", + hint=messages.hint("pack_sell", unit=inv.name)) + else: + if value not in packmode.MODES: + return {"error": messages.pack_refused("value")} + inv.store_set(packmode.MODE_KEY, value) + self.log_event(f"{inv.name} mode set to {value.replace('_', ' ')} " + f"by operator", + hint=messages.hint("pack_mode", unit=inv.name)) + pm = self.pack_mode(inv) + out = {"unit": inv.name, "use": pm.use, "mode": pm.mode} + if what == "pack_sell": + out["sell"] = pm.sell + return out + + async def _maint_unit_action(self, what, unit, now) -> dict: + """MAINT-11: start or abort the maintenance cycle of ONE named battery. + The site keeps ONE maintenance slot: a start while any battery holds it + is refused (no queue). (DECISIONS/MAIN-orchestration-archive.md)""" + inv = next((i for i in self.inverters if i.name == unit), None) + if inv is None: + return self._maint_refusal("unit") + machine = self.maints[self.inverters.index(inv)] + if what == "maint_start": + holder = next((i for i, m in zip(self.inverters, self.maints) + if m.phase in POWER_MOVING), None) + if holder is not None: + return self._maint_refusal("busy", holder.name) + if self.modes_on and not self.pack_mode(inv).use: + return self._maint_refusal("off", inv.name) + for msg in machine.force_start(now): + self.log_event(msg, hint=messages.hint( + "maintenance", phase=machine.phase)) + return {"unit": inv.name, "phase": machine.phase} + if machine.phase not in POWER_MOVING: + return self._maint_refusal("idle", inv.name) + for msg in machine.abort(now, "operator"): + self.log_event(msg, hint=messages.hint("maintenance", + phase=machine.phase)) + await self.command_site_zero() + return {"unit": inv.name, "phase": machine.phase} + + @staticmethod + def _maint_refusal(code, unit="") -> dict: + return {"error": messages.maint_refused(code, unit), "code": code, + "unit": unit} + + def mode_values(self) -> dict: + """OPT-11 P2: each battery's mode and switch, for their HA state + topics. Read from the store, so they are right after a restart. Empty + while battery modes are off.""" + if not self.modes_on: + return {} + out = {} + names = [inv.name for inv in self.inverters] + for inv, slug in zip(self.inverters, unit_slugs(names)): + pm = self.pack_mode(inv) + out[unit_state_key(slug, "mode")] = MODE_LABELS.get(pm.mode, + pm.mode) + out[unit_state_key(slug, "use")] = USE_ON if pm.use else USE_OFF + return out + + def _drain_floor(self, claims, maint_results): + """SAFETY-78: the site `lo` for a pinned maintenance drain, or None. At + N>=2 the drain pins its pack and the site target is split around the + pin; below the pin a sibling would have to charge (opposite + directions, refused, 0 W, the drain never moves), so the site target + may not go below what the pin places. At N=1 the drain is the site + SET itself: nothing filed. A draining pack with nothing to give adds + no floor (logged once).""" + if len(self.inverters) < 2: + return None + live = set(self.live_units()) + floor, waits = 0.0, set() + for inv, res in zip(self.inverters, maint_results): + if res.phase != DRAIN or not res.owns_setpoint \ + or not (res.setpoint_w or 0.0) > 0.0: + continue + u = self.actuator_of("maintenance", inv) + b = pre_resolve([c for c in claims if c.actuator == u]) + p = (None if u not in live or b.contradiction + or b.pinned_by != "maintenance" else allocator.pin_w(b)) + if p is not None and p > 0.0: + floor += p + else: + waits.add(inv.name) + for name in sorted(waits - self._drain_waits): + self.log_event(f"maintenance: {name} cannot give power now, so " + f"its monthly cycle waits", + hint=messages.hint("maint_waits", unit=name)) + self._drain_waits = waits + return floor if floor > 0.0 else None + + def _peak_on_able(self, decision, maint_results): + """SAFETY-87: at N>=2, `decision` placed on the batteries that can + still give: live, not refusing, above their own reserve. `able_w` is + their rating plus the drain a held battery gives anyway. + DECISIONS/SAFETY-87-guard-uses-able-batteries.md""" + if len(self.inverters) < 2: + return decision + floor = float(self.o.get( + "peak_soc_floor", peakguard.PEAK_OPTION_DEFAULTS["peak_soc_floor"])) + ok, held = peakguard.reserve_split(self.packs, floor) + if not held: + return decision + live = set(self.live_units()) + able = [p for p, inv in zip(self.packs, self.inverters) + if p in ok and inv.name in live and not (inv.refused or 0) > 0] + if not able: + return dataclasses.replace(decision, held=held) + drain = sum(min(float(r.setpoint_w), i.rating_w()) + for i, r in zip(self.inverters, maint_results) + if i.name in held and r.phase == DRAIN + and r.owns_setpoint and (r.setpoint_w or 0.0) > 0.0) + names = {p.name for p in able} + return peakguard.place_on_able( + decision, held, + able_w=drain + sum(i.rating_w() for i in self.inverters + if i.name in names), + soc=min(float(p.soc) for p in able), + soc_floor=peakguard.binding_soc_floor(able, floor)) + + def _peak_landing(self, decision): + """SAFETY-126: `decision` marked `within_aim` while the guard wants + power but the batteries at 0 W would end the quarter within + `ALARM_MISS_W` of the aim (`peakguard.misses_aim()`). The claim and the + commands are unchanged; only the alarms and the "Why" read it. + DECISIONS/SAFETY-126-landing-error-is-not-an-overrun.md""" + batt, prev = self.site_batt_w, self._land_batt_prev + self._land_batt_prev = batt + if not (decision.engaged and decision.blind is None + and (decision.wanted_w or 0.0) > 0.0): + self._peak_needed = False + return decision + if batt is not None and prev is not None: + batt = min(float(batt), float(prev)) + self._peak_needed = self._peak_needed or ( + self._peak_proj is not None and peakguard.misses_aim( + self._peak_proj, batt_w=batt, target_w=decision.target_w)) + return (decision if self._peak_needed + else dataclasses.replace(decision, within_aim=True)) + + def _peak_reserve(self) -> frozenset: + """SAFETY-87: the batteries that give nothing for the peak this + cycle: under their reserve while the others carry a peak floor.""" + g = self.peak_guard + if g is None or g.able_w is None or not (g.floor_w or 0.0) > 0.0: + return frozenset() + return frozenset(g.held) + + def _held_back(self) -> frozenset: + """SAFETY-91, N>=2: the batteries at or under their own peak reserve + while another can still give (live, not refusing). One held back stays + so until its SoC reads more than 1 point above its reserve. + DECISIONS/SAFETY-91-held-battery-last.md""" + if len(self.inverters) < 2: + return frozenset() + floor = float(self.o.get( + "peak_soc_floor", peakguard.PEAK_OPTION_DEFAULTS["peak_soc_floor"])) + ok, held = peakguard.reserve_split(self.packs, floor) + held = set(held) | { + p.name for p in ok if p.name in self._held_was + and float(p.soc) <= peakguard.pack_floor_pct(p, floor) + 1.0} + live = set(self.live_units()) + if not held or not any( + p.name not in held and inv.name in live + and not (inv.refused or 0) > 0 + for p, inv in zip(self.packs, self.inverters)): + self._held_was = frozenset() + else: + self._held_was = frozenset(held) + return self._held_was + + def _drain_rise(self, claims, maint_results) -> None: + """SAFETY-91, N>=2: while a battery is held back (`_held_back()`), a + draining battery's pin becomes a floor at its drain rate, so it rises + towards its rating before the held one gives. A site stop still decides + alone. DECISIONS/SAFETY-91-held-battery-last.md""" + held = self._held_back() + if not held or any(c.kind == SET and c.actuator == ACTUATOR_SITE + and c.priority > P_PEAK for c in claims): + return + live = set(self.live_units()) + for inv, res in zip(self.inverters, maint_results): + u = self.actuator_of("maintenance", inv) + if res.phase != DRAIN or not res.owns_setpoint \ + or inv.name in held or u not in live: + continue + b = pre_resolve([c for c in claims if c.actuator == u]) + p = (None if b.contradiction or b.pinned_by != "maintenance" + else allocator.pin_w(b)) + if p is None or not p > 0.0: + continue + for i, c in enumerate(claims): + if c.source == "maintenance" and c.kind == SET \ + and c.actuator == u: + claims[i] = Claim.limit("maintenance", P_MAINTENANCE, + lo=p, reason=c.reason, + actuator=u) + + def _fill_peak_gaps(self, proj, now, reading): + """SAFETY-90: `proj` with a meter gap's uncounted seconds counted at + `peakguard.gap_w()` of the imports seen just before and just after it, + and those before this run's first reading likewise at the import seen + first (shown as not measured). + DECISIONS/SAFETY-90-peak-guard-after-a-gap.md.""" + self.peak_gap_s = self.peak_unmeasured_s = 0.0 + avg = self.p1.averager + since = avg.held_since + if proj is None or proj.block_start is None or since is None: + return proj + if self._unseen is None and self.p1.last is not None: + self._unseen = [proj.block_start, max(0.0, ( + since - proj.block_start).total_seconds() - avg.elapsed_s), + since, None] + seen = (None if self.grid is None or self.site_batt_w is None + else float(self.grid) + max(0.0, float(self.site_batt_w))) + if proj.block_start != self._gap_block: + self._gap_block, self._gap_w = proj.block_start, None + self._gap_filled_s = self._gap_held_ws = 0.0 + cap = float(self.o.get("peak_cap_w", 3500)) + ceiling = peakguard.quarter_ceiling_w(cap, reading)[0] + unseen_on = (self._unseen is not None + and self._unseen[0] == proj.block_start) + if unseen_on and self._unseen[3] is None and seen is not None: + # While the add-on was down the batteries were at 0 W, so the + # seconds before its first reading count like a gap, at the + # import seen first; a restored reading's held part is topped up. + self._unseen[3] = peakguard.gap_w(ceiling, seen) + if self._run_pre is not None: + s0, g0 = self._run_pre + h = (min(s0 + timedelta(seconds=avg.max_hold_s), + self._unseen[2]) + - max(s0, proj.block_start)).total_seconds() + self._unseen_held_ws = max(0.0, h) * max( + 0.0, self._unseen[3] - max(0.0, g0)) + kw = dict(tail_s=(now - since).total_seconds(), + max_hold_s=avg.max_hold_s, + unseen_s=self._unseen[1] if unseen_on else 0.0, + unseen_w=(self._unseen[3] if unseen_on + and self._unseen[3] is not None else ceiling)) + _p, gap_s, _u = peakguard.fill_gaps(proj, gap_w=0.0, **kw) + if gap_s > self._gap_filled_s + peakguard.GAP_TOL_S: + self._gap_w = peakguard.gap_w(ceiling, self._gap_w, + self._gap_seen_w, seen) + if self._gap_pre is not None: + # The averager credited the gap's first max_hold_s at the + # reading before it; top that part up to gap_w as well. + s0, g0 = self._gap_pre + h = (min(s0 + timedelta(seconds=avg.max_hold_s), since) + - max(s0, proj.block_start)).total_seconds() + self._gap_held_ws += max(0.0, h) * max( + 0.0, self._gap_w - max(0.0, g0)) + self.log_event(f"PEAK_GUARD_GAP: the meter missed {gap_s:.0f} s " + f"of this 15-minute period, counted at " + f"{self._gap_w:.0f} W", + hint=messages.hint("peak_gap")) + self._gap_filled_s = max(self._gap_filled_s, gap_s) + if seen is not None: + self._gap_seen_w = seen + if self.grid is not None: + self._gap_pre = (since, float(self.grid)) + out, self.peak_gap_s, self.peak_unmeasured_s = peakguard.fill_gaps( + proj, gap_w=self._gap_w if self._gap_w is not None else ceiling, + held_ws=self._gap_held_ws + (self._unseen_held_ws if unseen_on + else 0.0), **kw) + return out + + def _peak_over_drain(self, claims, maint_results) -> None: + """SAFETY-83: at N=1 a peak floor above the drain rate outranks it: the + drain is the site SET at P_MAINTENANCE, above P_PEAK, so the floor + did not bind. Refiled at P_MAINTENANCE where it asks for more; + P_SAFETY still outranks. N>=2: the `drain` floor and + `_drain_over_reserve()`.""" + if len(self.inverters) != 1: + self._drain_over_reserve(claims, maint_results) + return + res = maint_results[0] + if res.phase != DRAIN or not res.owns_setpoint: + return + rate = float(res.setpoint_w or 0.0) + for i, c in enumerate(claims): + if c.source == peakguard.SOURCE and c.lo > rate: + claims[i] = dataclasses.replace(c, priority=P_MAINTENANCE) + + def _held_pin(self, claims, u): + """SAFETY-87: what held unit `u` places anyway (its own pin), or None + when that pin charges, so the site is never split both ways.""" + b = pre_resolve([c for c in claims if c.actuator == u]) + p = None if b.contradiction else allocator.pin_w(b) + return None if p is not None and p < 0.0 else max(p or 0.0, 0.0) + + def _drain_over_reserve(self, claims, maint_results) -> None: + """SAFETY-87, N>=2: while a battery is held at its peak reserve, a + draining battery that may still give is raised from its drain rate + towards its rating for the peak floor, after the others. A site stop + still decides alone. DECISIONS/SAFETY-87-guard-uses-able-batteries.md""" + reserve = self._peak_reserve() + floor = max((c.lo for c in claims if c.source == peakguard.SOURCE), + default=0.0) + if not reserve or not floor > 0.0 or any( + c.kind == SET and c.actuator == ACTUATOR_SITE + and c.priority > P_PEAK for c in claims): + return + live = set(self.live_units()) + drains, others = [], 0.0 + for inv, res in zip(self.inverters, maint_results): + u = self.actuator_of("maintenance", inv) + if u not in live: + continue + if inv.name in reserve: + p = self._held_pin(claims, u) + if p is None: + return + others += p + continue + b = pre_resolve([c for c in claims if c.actuator == u]) + if b.contradiction: + continue + p = allocator.pin_w(b) + if p is not None and p < 0.0: + return # a pack pinned to charge: never split both ways + if res.phase == DRAIN and b.pinned_by == "maintenance" \ + and p is not None and p > 0.0: + drains.append((u, p, allocator.hi_w(b))) + others += allocator.hi_w(b) if p is None else p + give = floor - others + for u, p, hi in drains: + if give <= 0.0: + break + up = max(p, min(hi, p + give)) + give -= up - p + for i, c in enumerate(claims): + if c.source == "maintenance" and c.kind == SET \ + and c.actuator == u: + claims[i] = dataclasses.replace(c, value=up) + + def _peak_over_hold(self, claims, maint_results): + """SAFETY-86: a peak floor outranks a maintenance HOLD (0 W). N=1: + refiled at P_MAINTENANCE as for a drain. N>=2: the holding pack's + pin is raised to the floor minus what the others may place, and the + floor is returned as the site `hold` ceiling. A site stop still + decides alone. DECISIONS/SAFETY-86-peak-over-hold.md.""" + hold = {self.actuator_of("maintenance", inv) + for inv, res in zip(self.inverters, maint_results) + if res.phase == HOLD and res.owns_setpoint} + peak = [i for i, c in enumerate(claims) + if c.source == peakguard.SOURCE and c.lo > 0.0] + if not hold or not peak: + return + if len(self.inverters) == 1: + for i in peak: + claims[i] = dataclasses.replace(claims[i], + priority=P_MAINTENANCE) + return + if any(c.kind == SET and c.actuator == ACTUATOR_SITE + and c.priority > P_PEAK for c in claims): + return + live = set(self.live_units()) + reserve = self._peak_reserve() # SAFETY-87: they give nothing + others = 0.0 + for inv in self.inverters: + u = self.actuator_of("maintenance", inv) + if u in hold or u not in live: + continue + if inv.name in reserve: # only its own pin, never both ways + p = self._held_pin(claims, u) + if p is None: + return + others += p + continue + b = pre_resolve([c for c in claims if c.actuator == u]) + if b.contradiction: + continue + p = allocator.pin_w(b) + if p is not None and p < 0.0: + return # a pack pinned to charge: never split both ways + others += allocator.hi_w(b) if p is None else p + floor = max(claims[i].lo for i in peak) + give = floor - others + if give <= 0.0: + return + for i, c in enumerate(claims): + if c.source == "maintenance" and c.kind == SET \ + and c.actuator in hold: + claims[i] = dataclasses.replace(c, value=give) + return floor + + def _charge_headroom(self, floor: float, claims) -> float: + """SAFETY-84: a cheap-window charge pulls no more than the quarter's + room under the peak aim (`charge_room_w()`), so it yields just enough + to the peak guard; at N>=2 nothing under a site stop (its 0 W would + need the other pack to give). SAFETY-125: at N=1 too; the stop rule + stays N>=2 only. + DECISIONS/SAFETY-125-grid-charge-under-the-month-peak.md""" + if len(self.inverters) > 1 and any( + c.kind == SET and c.actuator == ACTUATOR_SITE + and c.priority > P_MAINT_SHAPE for c in claims): + return 0.0 + room = peakguard.charge_room_w(self.peak_guard, self._peak_proj) + floor = floor if room is None else min(floor, room) + self.room_charge = self.room_charge or floor > 0.0 + return floor + + def _charge_ceiling(self, claims): + """SAFETY-84: the site `hi` for a cheap-window charge at N>=2, or None: + the charging pack's own `hi` (P_MAINT_SHAPE) makes it charge; above + that the other pack would have to give (opposite directions, + refused, 0 W). Not filed at N=1.""" + if len(self.inverters) < 2: + return None + live = set(self.live_units()) + ceiling = 0.0 + for inv in self.inverters: + u = self.actuator_of("maintenance", inv) + b = pre_resolve([c for c in claims if c.actuator == u]) + if u in live and not b.contradiction and b.hi < 0.0: + ceiling += allocator.hi_w(b) + return ceiling if ceiling < 0.0 else None + + def _maint_stop_off(self, machine, now) -> None: + """OPT-11: stop this battery's maintenance cycle because it is off.""" + if machine.phase == IDLE: + return + for msg in machine.abort(now, "battery switched off"): + self.log_event(msg, hint=messages.hint("maint_off", + unit=machine.name)) + + def _provider_gate(self, now: datetime) -> None: + """PRICE-01: `cheap`, the gate and the gap from the standing plan. No + price for now is a closed gate, so the charge waits rather than run + unpriced; the gap flag stays False until the first refresh has + finished. (DECISIONS/MAIN-orchestration-archive.md)""" + plan = self.fresh_tariff_plan(now) + published = None if plan is None else plan.published + if published is not None: + self._last_published = published + gate = gate_for(published, now) + self.cheap, self._price_gated = gate.cheap, True + self.tariff_words = gate.words + # Owner, 2026-10-14: the words say 'maintenance waits', so they show + # only while the maintenance charge is on. + self.price_gap = ((not gate.covered) and self.tariff_at is not None + and MaintConfig.from_options(self.o).enabled) + last = self._last_published + if gate.covered or last is None: + self.price_gap_since = None + elif last.covers(now): + # The last series still covers now, but no refresh has made it + # current for TARIFF_MAX_AGE_S: the refresh task has stopped. The + # gap began when the plan was retired. + self.price_gap_since = ( + None if self.tariff_at is None + else self.tariff_at + timedelta(seconds=TARIFF_MAX_AGE_S)) + else: + self.price_gap_since = last.last_end_before(now) + + def _static_gated(self, o: dict, now: datetime) -> bool: + """`static_gated()`, worked out once an hour: it builds the same + month-long plan as `static_status()` (about 20 ms with a profile), and + whether a fixed tariff is set up does not change from tick to tick + (options change only with a restart).""" + key = (id(o), now.strftime("%Y-%m-%d %H")) + if key != self._gated_key: + self._gated_key, self._gated = key, static_gated(o, now) + return self._gated + + def _charge_gate_open(self, inv) -> bool: + """MAINT-13: may this pack charge now, for the maintenance timeout? + Closed only when a price gate exists, it is shut, and the pack is not + really taking charge. (DECISIONS/MAIN-orchestration-archive.md)""" + if not self._price_gated or self.cheap: + return True + batt = inv.batt + return batt is not None and float(batt) <= -MAINT_CHARGING_W diff --git a/goodwe_controller/app/ctl_writes.py b/goodwe_controller/app/ctl_writes.py new file mode 100644 index 0000000..637496c --- /dev/null +++ b/goodwe_controller/app/ctl_writes.py @@ -0,0 +1,613 @@ +"""Controller methods that write to, refuse and hand back the inverters. + +Moved unchanged from app/main.py (MAINT-21). DECISIONS/MAIN-orchestration.md.""" + +import asyncio +import logging +import time +from datetime import datetime, timezone + +from . import control as _ctl +from .clamp import clamp_to_rating, is_commandable +from . import messages +from . import shadow + +_LOG = logging.getLogger("goodwe") + + +# DEV-02: the per-write budget, DERIVED: `heartbeat_s` max 25 s + 4 < +# `validate.FIRMWARE_INGEST_VETO_S` (30 s), graded by test_inverter.py. +# DECISIONS/MAIN-orchestration.md. +WRITE_BUDGET_S = 4.0 + + +# SMA-10: the bound for handing a unit back (`driver.release()`); units are +# released concurrently and one still running at the bound is abandoned. +# DECISIONS/SMA-10-two-idle-states.md. +RELEASE_BUDGET_S = WRITE_BUDGET_S + + +# SMA-10: the one fallback write after a failed release (default 0 W). Worst +# case RELEASE_BUDGET_S + FALLBACK_BUDGET_S = 6 s, inside the Supervisor's 10 s. +# DECISIONS/SMA-10-two-idle-states.md. +FALLBACK_BUDGET_S = 2.0 + + +# SAFETY-137: how long a LAST write waits for a write already on its way to the +# same unit; half the release budget, so a GoodWe unit's worst case is +# HAND_BACK_WORST_S. DECISIONS/SAFETY-137-last-write-is-zero.md. +SETTLE_BUDGET_S = RELEASE_BUDGET_S / 2 + + +# SAFETY-73: the evidence must also span this long, not only SETTLE_CYCLES +# cycles: a 1 s meter makes 12 cycles only 11 s, shorter than a healthy battery +# reading's lag, and both inverters were refused after ordinary load steps. +REFUSED_SPAN_S = (_ctl.SETTLE_CYCLES - 1) * _ctl.LOOP_TICK_S + + +# SAFETY-94: evidence restarts when the reading has moved this far toward the +# ask. A refusing battery reads flat; live readings wander under 25 W at rest; +# a first-order lag gains at most 0.4 tau x 100 W across the band, so the +# evidence cannot span REFUSED_SPAN_S unless the lag is over 54 s. +REFUSED_PROGRESS_W = _ctl.PROBE_ANSWER_W / 2 + + +async def _bounded(awaitable, budget_s: float): + """SMA-10. `await awaitable`, abandoning it after `budget_s` without waiting + for it to wind down (`wait_for` would). Raises `asyncio.TimeoutError`.""" + task = asyncio.ensure_future(awaitable) + done, _ = await asyncio.wait({task}, timeout=budget_s) + if not done: + task.cancel() + # a result or error that arrives later has nobody to read it + task.add_done_callback(lambda t: t.cancelled() or t.exception()) + raise asyncio.TimeoutError + return task.result() + + +class WritesMixin: + # helpers; SAFETY-52: a battery that refuses is asked for 0 W + def _refusal_probe(self) -> bool: + """True while a refused direction may try `PROBE_W` (every 15 min).""" + if (not self.batt_refused or self.batt_refused_at is None + or self._now_mono is None): + return False + held = self._now_mono - self.batt_refused_at + if held >= _ctl.PROBE_EVERY_S + _ctl.PROBE_S: + self.batt_refused_at = self._now_mono + return False + return held >= _ctl.PROBE_EVERY_S + + def _refusal_start(self, sign: int, evidence: str) -> None: + self.batt_refused = sign + self.batt_refused_at = self._now_mono + self.log_event(f"BATTERY REFUSES {evidence}", + hint=messages.hint("battery_refuses")) + _LOG.info("The battery refuses to give power, so the add-on asks 0 W " + "and tries %.0f W every %.0f minutes: BATTERY_REFUSES.", + _ctl.PROBE_W, _ctl.PROBE_EVERY_S / 60) + _LOG.debug("Evidence: BATTERY_REFUSES: %s.", evidence) + + def _refusal_end(self, why: str) -> None: + if not self.batt_refused: + return + self.batt_refused, self.batt_refused_at = 0, None + self.log_event(f"BATTERY REFUSES ENDED: {why}", + hint=messages.hint("battery_gives")) + _LOG.info("The battery refusal ends, control asks for power again: %s.", + why) + + def _refusal_update(self, decision, asked_w, batt_w, probe, + rejudged: int = 0) -> None: + """Follow `compute()`'s carried refused direction, and say so. + `rejudged`: the refusal held while another writer had the wire, so + `compute()` judged it afresh against that writer's ask (SAFETY-107).""" + now = decision.refused or 0 + if rejudged: + if now == rejudged: + # Still refused against the ask on the wire: the same episode. + # The probe clock restarts: a probe is the loop's ask and is + # not on the wire while another writer is. + self.batt_refused_at = self._now_mono + return + gave = (rejudged * (batt_w - self._site_idle_w()) + >= _ctl.PROBE_ANSWER_W) + self._refusal_end("the battery gives power" if gave + else "another writer") + if now and not self.batt_refused: + self._refusal_start(now, f"asked {asked_w:+.0f} W, the battery " + f"gave {batt_w:+.0f} W for " + f"{decision.sat_count} cycles") + elif self.batt_refused and not now: + gave = (self.batt_refused * (batt_w - self._site_idle_w()) + >= _ctl.PROBE_ANSWER_W) + self._refusal_end("the probe was answered" if gave and probe + else "the battery gives power" if gave + else "the grid now asks the other direction") + + def _refusal_from_stale(self, inv, now_mono) -> None: + """A stale-reading stop while the loop is frozen on ~0 W is a refusal. + Only at one inverter: with several, one empty battery must not stop + the site (OPT-09 moves its share).""" + t = self.tuning + standing = inv.standing_w() + if len(self.inverters) > 1: + # SAFETY-73: at N>1 the same trip refuses THIS unit only. + if ((self.auto or self.shadow) and not inv.refused + and inv.ref_count >= t.saturation_cycles + and inv.batt_fresh.held is not None + and abs(inv.batt_fresh.held - inv.idle_w) + < _ctl.REFUSED_BELOW_W + and abs(standing) > _ctl.PROBE_W): + self._now_mono = now_mono + self._unit_refusal_start( + inv, 1 if standing > 0 else -1, + f"stale reading {inv.batt_fresh.held:+.0f} W while asked " + f"{standing:+.0f} W") + return + if (len(self.inverters) == 1 and (self.auto or self.shadow) + and not self.batt_refused + and self.sat_count >= t.saturation_cycles + and inv.batt_fresh.held is not None + and abs(inv.batt_fresh.held - inv.idle_w) + < _ctl.REFUSED_BELOW_W + and abs(standing) > t.saturation_w): + self._now_mono = now_mono + self._refusal_start(1 if standing > 0 else -1, + f"stale reading {inv.batt_fresh.held:+.0f} W " + f"while asked {standing:+.0f} W") + + # SAFETY-73: SAFETY-52's decisions per inverter at N>1: a unit giving < + # REFUSED_BELOW_W for SETTLE_CYCLES while asked > PROBE_W is closed in that + # direction by a P_SAFETY unit limit, so the allocator hands its share on; + # probed at PROBE_W every PROBE_EVERY_S, one unit at a time. The ask is + # PROBE_W, not `saturation_w`: a unit's share is often small and SAFETY-43 + # would name the empty battery as not delivering. + # DECISIONS/SAFETY-73-refusal-per-inverter.md. + def _unit_refusal_start(self, inv, sign: int, evidence: str) -> None: + inv.refused, inv.refused_at = sign, self._now_mono + inv.probe_from, inv.ref_count = None, 0 + self.log_event(f"BATTERY REFUSES {inv.name}: {evidence}", + hint=messages.hint("unit_refuses", unit=inv.name)) + _LOG.info("%s: the battery refuses power, so it is asked 0 W and the " + "other inverters take over: BATTERY_REFUSES.", inv.name) + _LOG.debug("Evidence for %s: BATTERY_REFUSES: %s.", inv.name, evidence) + # Only a refusal to GIVE: a full battery that stops taking charge is + # above its cut-out level by definition. + if (sign > 0 and inv.soc is not None and inv.bms_soc_floor is not None + and float(inv.soc) > float(inv.bms_soc_floor)): + # Owner decision 3: a refusal above the configured cut-out level + # may mean that level is set wrong. One line, no safety stop. + _LOG.warning("%s refuses power above its battery cut-out level, " + "check its cut-out level: REFUSES_ABOVE_CUT_OUT.", + inv.name) + _LOG.debug("Evidence for %s: REFUSES_ABOVE_CUT_OUT: battery level " + "%.0f %%, cut-out level %.0f %%.", inv.name, + float(inv.soc), float(inv.bms_soc_floor)) + + def _unit_refusal_end(self, inv, why: str) -> None: + if not inv.refused: + return + inv.refused, inv.refused_at, inv.probe_from = 0, None, None + inv.ref_count = 0 + self.log_event(f"BATTERY REFUSES ENDED {inv.name}: {why}", + hint=messages.hint("unit_gives", unit=inv.name)) + _LOG.info("%s: the battery refusal ends, it is asked for power again: " + "%s.", inv.name, why) + # The site target may stand above what was placed (the refused share + # was unmet). Restart it from the watts on the wire, or the reopened + # unit gets the parked remainder at once (phase A: -1059 W). + placed = float(sum(i.standing_w() for i in self.inverters)) + self.target = self.i_w = placed + self.sat_count = 0 + + def _unit_probe(self, inv) -> bool: + """True while `inv` may try PROBE_W. One unit probes at a time.""" + now = self._now_mono + if not inv.refused or inv.refused_at is None or now is None: + return False + if inv.probe_from is not None: + if now - inv.probe_from < _ctl.PROBE_S: + return True + inv.probe_from, inv.refused_at = None, now + return False + if now - inv.refused_at < _ctl.PROBE_EVERY_S or any( + i.probe_from is not None for i in self.inverters): + return False + inv.probe_from = now + return True + + def _unit_refusals(self) -> None: + """Engage and end each unit's refusal from its own reading.""" + for inv in self.inverters: + b = inv.batt + if inv.refused: + # SAFETY-97: given and taken are counted from the idle reading. + if (b is not None and inv.refused * (b - inv.idle_w) + >= _ctl.PROBE_ANSWER_W): + self._unit_refusal_end( + inv, "the probe was answered" + if inv.probe_from is not None + else "the battery gives power") + continue + # The other direction: the battery takes PROBE_ANSWER_W or more + # the other way for SETTLE_CYCLES, counted on its own reading + # so one overshoot through zero does not hand its share back. + inv.ref_count = (inv.ref_count + 1 if b is not None and + -inv.refused * (b - inv.idle_w) + >= _ctl.PROBE_ANSWER_W else 0) + if inv.ref_count >= _ctl.SETTLE_CYCLES: + self._unit_refusal_end( + inv, "the battery takes power the other way") + continue + if inv.rejected_since is not None: + # SAFETY-96: its writes are refused, so its board may have gone + # to 0 W on its own; that is no refusal by the battery. The + # count is kept, as across a gap. + continue + sign = self._gave_nothing(inv) + if sign: + self._unit_refusal_start( + inv, sign, + f"asked {inv.standing_w():+.0f} W, the battery gave " + f"{b:+.0f} W for {_ctl.SETTLE_CYCLES} cycles") + + def _gave_nothing(self, inv) -> int: + """The refusal evidence, one cycle of it: the sign `inv` has given + under REFUSED_BELOW_W while asked over PROBE_W, one way, for + SETTLE_CYCLES spanning REFUSED_SPAN_S, else 0. SAFETY-73 at N>1; + SAFETY-94 adds it to the N=1 engage in compute(). SAFETY-97: the + band is centred on the unit's idle reading.""" + b = inv.batt + if b is None: + return 0 # a gap keeps the count: the gate's trip seeds + standing = inv.standing_w() + sign = 1 if standing > 0 else -1 + # One direction throughout: a command that swaps sign every cycle reads + # ~0 through the plant's lag, which is a battery following, not + # refusing (TEST-19). + if (abs(standing) > _ctl.PROBE_W + and abs(b - inv.idle_w) < _ctl.REFUSED_BELOW_W): + # SAFETY-94: a reading still moving towards the ask is a battery + # catching up through its lag: start again. + if (sign != inv.ref_sign or not inv.ref_count + or sign * (b - inv.ref_from) >= REFUSED_PROGRESS_W): + inv.ref_count, inv.ref_since, inv.ref_from = ( + 0, self._now_mono, b) + inv.ref_count = min(inv.ref_count + 1, _ctl.SETTLE_CYCLES) + else: + inv.ref_count = 0 + inv.ref_sign = sign + if inv.ref_count >= _ctl.SETTLE_CYCLES and ( + inv.ref_since is None or self._now_mono is None + or self._now_mono - inv.ref_since >= REFUSED_SPAN_S): + return sign + return 0 + + def _site_idle_w(self) -> float: + """SAFETY-97: the site reading at idle, the sum of the units'.""" + return float(sum(inv.idle_w for inv in self.inverters)) + + def _site_refused(self): + """Owner decision 4: every unit refuses the same way, so the site law + holds 0 W (SAFETY-52's, in compute()). Otherwise None, the old law.""" + signs = {inv.refused for inv in self.inverters} + return signs.pop() if len(signs) == 1 and 0 not in signs else None + + @property + def shadow(self) -> bool: + """SAFETY-10. Is the battery being left alone right now? A property, + not a field (as `self.units`): the cycle, the write and the status + page ask at three moments, and the write gate asks THIS, not a + parameter passed down.""" + return shadow.engaged(self.o, control_started=self.auto) + + def shadow_latches(self) -> tuple: + """The failsafe latches that are UP, named, for the shadow banner: a + standing latch is standing when the controller stops being inert, so + an operator who turns shadow off is not handed a battery that will + not move with no reason shown.""" + out = [] + if self.circ_wd.tripped: + out.append("circulating power") + if self.site_sign_wd.tripped and len(self.inverters) > 1: + out.append("site sign watchdog") + for inv in self.inverters: + if inv.sign_wd.tripped: + out.append(f"{inv.name} sign watchdog") + return tuple(out) + + def write_refusal(self, value: float, inv=None) -> str | None: + """Why `value` may NOT be written to `inv` right now, or None if it + may. SAFETY-28: a number reaches the wire only if THE SINGLE ALLOCATOR + placed it, on this tick, for THIS unit (`Allocation.authorises()`); a + second writer must file a Claim. 0 W is ALWAYS authorised and tested + first, reading nothing: the failsafe writes run while the allocator has + REFUSED, so a gate asking permission to command zero would deadlock the + failsafe. It tests `value == 0.0`, not a flag the caller sets. DEV-02: + the unit is an ARGUMENT (the record holds one share per unit); the + default is for N=1 callers and REFUSES at N>=2. + DECISIONS/MAIN-orchestration.md.""" + if value == 0.0: + return None + inv = self._only() if inv is None else inv + rec = self.allocation + if rec is None: + return ("no allocation record exists yet - nothing has authorised " + f"{value:+.0f} W on {inv.name}") + return rec.authorises(inv.name, value, self.alloc_tick) + + async def write_setpoint(self, value: float, *, force: bool = False, + unit=None, last: bool = False) -> None: + """Put `value` on ONE inverter, or with `unit=None` on all. `unit=None` + is for a number that is not a share (stop button, `shutdown()`, + `maint_abort()`: 0 W means the same to every inverter). Writes are + concurrent, each under its own budget (DEV-02). `last`: + DECISIONS/SAFETY-137-last-write-is-zero.md.""" + if unit is None: + targets = [i for i in self.inverters] + if len(targets) > 1 and is_commandable(value) and float(value) != 0.0: + # Loud, and it commands zero rather than the value asked for: + # fail toward inaction, as every other refusal here. + self.log_event( + f"refusing to broadcast {float(value):+.0f} W to " + f"{len(targets)} inverters - that is the ARCH-01 fault; " + f"commanding 0 W", hint=messages.hint("all_blocked")) + _LOG.error("Refused to send %+.0f W to all %s at once, so " + "every inverter is set to 0 W. This is a software " + "fault.", float(value), + messages.count(len(targets), "inverter")) + _LOG.debug("ARCH-01: a site target handed to each unit is " + "supplied by each of them, so the gain at the meter " + "becomes N times the per-unit gain. Only 0 W may be " + "written site-wide, and shares come from the " + "allocator.") + value = 0.0 + else: + targets = [unit] + if not targets: + return + await asyncio.gather(*(self._write_unit(inv, value, force=force, + last=last) + for inv in targets)) + + async def _await_inflight(self, inv, budget_s: float) -> None: + """Wait, at most `budget_s`, for writes already on their way to `inv`; one + still running is left to its own WRITE_BUDGET_S. + DECISIONS/SAFETY-137-last-write-is-zero.md.""" + pending = [t for t in inv.inflight if not t.done()] + if pending: + await asyncio.wait(pending, timeout=budget_s) + + async def _release_last(self, inv) -> bool: + """`release()` once any write in flight to `inv` has finished (at most + SETTLE_BUDGET_S): the release is the LAST thing the unit hears. + DECISIONS/SMA-10-two-idle-states.md.""" + await self._await_inflight(inv, SETTLE_BUDGET_S) + return await self._driver(inv).release() + + async def _hand_back(self, inv, *, force: bool = False) -> bool: + """SMA-10. Give ONE unit back: exactly one `release()`, then nothing. + True when handed back. Never raises; a failure is retried on the next + idle write. ⚠️ `released` is set before the first await (one release per + unit, not two). ⚠️ It is not a write: no `note_write`, no `last_write`. + DECISIONS/SMA-10-two-idle-states.md.""" + if inv.released: + return True + if not inv.driver.configured(): + return False + # After a failure the next try waits one heartbeat; Stop and shutdown + # (`force`) always try. DECISIONS/SMA-10-two-idle-states.md. + now_m = time.monotonic() + if not force and now_m < inv.release_retry_at: + return False + inv.released = True + why = "" + try: + ok = bool(await _bounded(self._release_last(inv), + RELEASE_BUDGET_S)) + except (asyncio.TimeoutError, TimeoutError): + ok, why = False, f"took over {RELEASE_BUDGET_S:.0f} s" + except Exception as err: # noqa: BLE001 - one unit never stops the rest + ok, why = False, f"{type(err).__name__}: {err}" + if ok: + inv.last_write = None + if inv.release_fails: + _LOG.info("Handing back %s worked again after %d failed " + "tries.", inv.name, inv.release_fails) + inv.release_fails = 0 + inv.release_retry_at = 0.0 + inv.release_zero_sent = False + self.log_event(f"{inv.name}: handed back", + hint=messages.hint("handed_back", unit=inv.name)) + return True + # SMA-10: a failed hand-back is tried again, and sent 0 W once below. + inv.released = False + inv.release_fails += 1 + inv.release_retry_at = now_m + float(self.o.get("heartbeat_s", 10)) + _LOG.debug("Handing back %s failed (try %d): %s", inv.name, + inv.release_fails, why) + if inv.release_fails == 1: # one line per failure streak + _LOG.error("Handing back %s failed, so it is sent 0 W once and " + "handing back is tried again.", inv.name) + self.log_event(f"{inv.name}: hand-back failed", + hint=messages.hint("hand_back_failed", unit=inv.name)) + if not inv.release_zero_sent: + # ⚠️ ONCE: a 0 W re-sent on every try would reset the inverter's own + # fallback timer for ever. DECISIONS/SMA-10-two-idle-states.md. + inv.release_zero_sent = True + try: + if await _bounded(self._driver(inv).release_fallback(), + FALLBACK_BUDGET_S): + inv.last_write = 0.0 + except Exception as err: # noqa: BLE001 + _LOG.debug("The fallback write to %s failed: %r", inv.name, err) + return False + + async def _write_unit(self, inv, value: float, *, force: bool = False, + last: bool = False) -> None: + if not inv.driver.configured(): + return + # SMA-10: a unit that hands back is released once and not written while + # the add-on is idle (shutdown, stopped, shadow). ⚠️ A safety stop is + # NOT idle: it falls through to the 0 W write. Control starting again + # re-arms the unit; `stopping` never does. + # DECISIONS/SMA-10-two-idle-states.md. + if inv.driver.hands_back: + if self.stopping or self.shadow or not self.auto: + await self._hand_back(inv) + return + if inv.released or inv.release_fails or inv.release_zero_sent: + # Control has the unit again: forget the hand-back and any + # failed streak. + inv.released = False + inv.last_write = None + inv.release_fails = 0 + inv.release_retry_at = 0.0 + inv.release_zero_sent = False + entity = inv.driver.actuator_id() # for the log line below + + # SAFETY-03: the clamp is on the ONLY path to the wire (cycle, + # heartbeat, stop button, shutdown(); no optimizer, maintenance or + # manual path routes around it). A non-finite value is loss of input, + # not an out-of-range one (11.1): coerced to 0 W. + if not is_commandable(value): + self.log_event(f"non-finite setpoint {value!r} - commanding 0 W", + hint=messages.hint("bad_value")) + _LOG.error("refusing to write a non-finite setpoint %r - commanding " + "0 W and continuing to command. This is a bug upstream, " + "not a limit.", value) + value = 0.0 + + # SAFETY-28: the refusal is HERE, above the clamp and below the + # non-finite coercion (a nan is loss of input, not an unauthorised + # number), and asked about `inv`, not the site. + # DECISIONS/MAIN-orchestration.md. + refusal = self.write_refusal(value, inv) + if refusal is not None: + self.log_event( + f"{inv.name}: WRITE REFUSED {value:+.0f} W - commanding 0 W", + hint=messages.hint("write_blocked", unit=inv.name)) + _LOG.error("Refused to send %+.0f W to %s, so it is set to 0 W " + "instead, which is a software fault. The reason: %s.", + value, inv.name, refusal) + value = 0.0 + + # This unit's own three numbers: `inv.max_w` (supervised cap on THIS + # setpoint entity) and `inv.dev_min/dev_max` (what THIS device + # reported). Read off `self.o` they were one inverter's rating applied + # to every inverter. + result = clamp_to_rating(value, inv.max_w, inv.dev_min, inv.dev_max) + inv.clamp_last = result + if result.engaged: + # EVERY engagement is logged, never deduplicated: the action log + # (15) is a different surface from the deduplicated notification. + # The count says how hard the loop pushed. + self.log_event(f"{inv.name}: {result.describe()}", + hint=messages.hint("write_cut", unit=inv.name)) + value = result.applied_w + + # SAFETY-10: shadow mode runs the whole decision path and commands + # nothing, and the suppression is HERE, the last thing before the wire, + # in the one method every write reaches (so no call site routes round + # it). A substitution, not a return, like the two refusals above; below + # SAFETY-28's gate and SAFETY-03's clamp; not a second writer (no + # claim, no transport call). + if self.shadow and value != shadow.WIRE_W: + # UX-10: DEBUG, because it repeats every cycle in shadow mode; the + # INFO line when shadow comes on says it once. + _LOG.debug("Shadow mode: would send %+.0f W to %s, and holds " + "%+.0f W. Nothing was sent to the inverter.", + value, inv.name, shadow.WIRE_W) + value = shadow.WIRE_W + + # SAFETY-137: `last` (the Stop and shutdown 0 W) waits, bounded, for a + # write already on its way; once `stopping`, every other write is dropped + # here with no await before the write is made. + # DECISIONS/SAFETY-137-last-write-is-zero.md. + if last: + await self._await_inflight(inv, SETTLE_BUDGET_S) + elif self.stopping: + _LOG.debug("Shutting down, so %+.0f W to %s is not sent.", + value, inv.name) + return + changed = (inv.last_write is None or value != inv.last_write) + if not (changed or force): + return + # BOUNDED, and the budget is AC 6: one hung transport would hold the + # coroutine, the whole loop and every OTHER inverter's heartbeat. An + # abandoned write is re-issued next tick (`last_write` moves only on an + # ACCEPTED write). + try: + _w = self._driver(inv).write(value) + # SMA-10 / SAFETY-137: kept so a release or last 0 W can wait for + # it. DECISIONS/SAFETY-137-last-write-is-zero.md. + _w = asyncio.ensure_future(_w) + inv.inflight.add(_w) + _w.add_done_callback(inv.inflight.discard) + ok = await asyncio.wait_for(_w, timeout=WRITE_BUDGET_S) + except (asyncio.TimeoutError, TimeoutError): + ok = False + _LOG.error("Sending %+.0f W to %s (%s) took over %.0f s and was " + "dropped, so it is sent again next cycle.", + value, inv.name, entity, WRITE_BUDGET_S) + self.log_event(f"{inv.name}: write timed out after " + f"{WRITE_BUDGET_S:.0f} s - re-issuing next tick", + hint=messages.hint("write_slow", unit=inv.name)) + now = datetime.now(timezone.utc) + inv.note_write(bool(ok), now) + if ok: + inv.last_write = value + inv.last_write_at = now + + async def send_heartbeats(self, loop_now: float, heartbeat_s: float) -> None: + """Refresh every inverter whose own deadline has come. AC 6 lives here. + ⚠️ A METHOD RATHER THAN FIVE LINES INSIDE `run_control()` so a check + can inject a hang: "a hung write to A cannot consume B's layer-1 + budget"; inline, the mutation to a serial `for` loop passed the whole + suite. (DECISIONS/MAIN-orchestration-archive.md)""" + due = [inv for inv in self.inverters + if loop_now - inv.last_beat >= heartbeat_s] + if not due: + return + # ⚠️ THE DEADLINE MOVES BEFORE THE WRITE, NOT AFTER IT: after, a + # hanging write drifts into being re-sent every tick and a raising one + # never advances. (DECISIONS/MAIN-orchestration-archive.md) + for inv in due: + inv.last_beat = loop_now + # ⚠️ CONCURRENTLY: in series, every inverter behind a hung one waits + # out its whole budget, pushing a healthy sibling towards layer 1's ~30 + # s veto. (DECISIONS/MAIN-orchestration-archive.md) + await asyncio.gather(*( + self.write_setpoint(inv.target, force=True, unit=inv) + for inv in due)) + + async def command_site_release(self) -> None: + """SMA-10. The add-on is going away (Stop, shutdown, restart, task death, + config refusal): units that hand back are given back, the rest held at + 0 W as `command_site_zero()` does. ⚠️ Safety stops and refusals do NOT + come here: they hold 0 W for EVERY unit. A roster with no hand-back unit + is `command_site_zero()` line for line. + DECISIONS/SMA-10-two-idle-states.md.""" + if not any(inv.driver.hands_back for inv in self.inverters): + await self.command_site_zero(last=True) + return + self.target = 0.0 + for inv in self.inverters: + inv.target = 0.0 + await asyncio.gather(*( + self._hand_back(inv, force=True) if inv.driver.hands_back + else self._write_unit(inv, 0.0, force=True, last=True) + for inv in self.inverters)) + + async def command_site_zero(self, *, last: bool = False) -> None: + """Every inverter to 0 W, and every inverter's TARGET with it. ⚠️ NOT + BOOKKEEPING (DEV-02): the heartbeat re-emits `inv.target`, so zeroing + only `self.target` lets the next heartbeat put each unit's last share + back on the wire. ⚠️ 0 W IS THE ONE VALUE THAT MAY BE WRITTEN SITE-WIDE + (`write_setpoint()` refuses others: ARCH-01). + (DECISIONS/MAIN-orchestration-archive.md)""" + self.target = 0.0 + for inv in self.inverters: + inv.target = 0.0 + await self.write_setpoint(0.0, force=True, last=last) diff --git a/goodwe_controller/app/homeview.py b/goodwe_controller/app/homeview.py index ce644f1..dc19a7b 100644 --- a/goodwe_controller/app/homeview.py +++ b/goodwe_controller/app/homeview.py @@ -630,6 +630,11 @@ def maintenance_runs(c, day0, day1, now, shadow): run_cycle_why(shadow), run_cycle_amount(hours))) continue + until = m.backoff_until(now) + if until is not None: + # MAINT-25: a failed cycle waits (MAINT-13); no run is planned. + lines.append(line_cycle_backoff(inv.name, until)) + continue if not m.due(now) and (m.next_due(now) is None or m.next_due(now) >= day1): continue @@ -1529,6 +1534,13 @@ def line_cycle_waits(name) -> str: return _t("cycle_waits", name=name) +def line_cycle_backoff(name, until) -> str: + """MAINT-25: the failed cycle waits until `until` (MAINT-13).""" + local = brussels(until) + return _t("cycle_backoff", name=name, day=local.day, + month=month_name(local)) + + def line_no_prices(since, now) -> str: """PRICE-01: no price covers now. `since` is an instant or None.""" if since is None: @@ -1669,6 +1681,8 @@ def _samples() -> list: ("plan", run_house_why()), ("plan", run_house_why(True)), ("plan", run_house_amount()), ("plan", line_cycle_waits("Battery B")), + ("plan", line_cycle_backoff("Battery B", datetime( + 2026, 11, 19, 12, 0, tzinfo=timezone.utc))), ("plan", line_no_prices(None, datetime(2026, 10, 14, 9, 0, tzinfo=timezone.utc))), ("plan", line_no_prices(datetime(2026, 10, 14, 0, 0, diff --git a/goodwe_controller/app/main.py b/goodwe_controller/app/main.py index 25def79..9023c48 100644 --- a/goodwe_controller/app/main.py +++ b/goodwe_controller/app/main.py @@ -1,29 +1,28 @@ """GoodWe RS485 Controller add-on - entry point and orchestration. -WHAT THIS THING DOES, in one paragraph: it reads the house's net grid power from -Home Assistant, decides how hard the battery should charge or discharge to hold -that at zero, and writes that figure to an ESP32 which puts it on the inverter's -RS485 EMS port. Once a month it runs a full low->full battery cycle so the BMS -can balance cells and recalibrate its coulomb counter. +It reads the house's net grid power from Home Assistant, decides how hard the +battery should charge or discharge to hold that at zero, and writes the figure +to an ESP32 that puts it on the inverter's RS485 EMS port. Monthly it runs a +full low->full cycle so the BMS can balance cells and recalibrate. -⚠️ THE ONE THING TO UNDERSTAND BEFORE CHANGING ANY OF THIS: the inverter holds -the last command it understood FOREVER. It has no meter-timeout of its own. -Measured on real hardware: a controller died mid-command and the inverter held -5 kW of discharge for 113 s until a human noticed. Every failsafe in this system -exists because of that one fact: +THE ONE FACT BEHIND EVERY FAILSAFE: the inverter holds the last command it +understood FOREVER (measured: 5 kW of discharge held for 113 s after a +controller died). So when in doubt this process stops writing and the hardware +takes the battery to zero. Never "hold the last value to be safe". - layer 1 the ESP32's own watchdog - if we stop refreshing for ~30 s it - commands 0 W and KEEPS WRITING it. Stopping is the failure, not the - fix. This add-on's heartbeat is what feeds it. + layer 1 the ESP32 watchdog: no refresh for ~30 s -> 0 W, and it KEEPS + WRITING it. This add-on's heartbeat feeds it. layer 2 wind-down before a firmware update, in the ESP32. - layer 3 the optional RS485 e-stop, which writes 0 W after 30 s of total bus - silence. It is the ONLY thing that covers this add-on's host dying. + layer 3 the optional RS485 e-stop: 0 W after 30 s of bus silence; the only + cover for this add-on's host dying. -So: when in doubt, this process stops writing, and the hardware takes the -battery to zero on its own. Never "hold the last value to be safe". -""" +Per-section reasoning: DECISIONS/MAIN-orchestration.md. The Controller keeps +__init__, its roster views and shutdown here; its other methods are in +ctl_inputs, ctl_writes, ctl_trade, ctl_cycle, ctl_alarms, ctl_status and +ctl_tasks (MAINT-21), the status-row functions in rows.""" import asyncio +import collections import contextlib import dataclasses import functools @@ -65,6 +64,7 @@ from .clamp import ( ) from . import freshness from . import lateness +from .settle import Settle from . import dayview, homeview from .daycurve import SolarToday from . import handback @@ -74,9 +74,8 @@ from .freeze import ( ) from .drivers import GoodWeEsphomeDriver from .hass import CORE_API, OUTAGE, HomeAssistant -# ⚠️ `LINK_STALE_S` IS RE-EXPORTED DELIBERATELY. `live_units()` reasons about it -# and two checks read `app.main.LINK_STALE_S` to build a stale link, so the -# window an operator would look up here is the one the roster actually uses. +# `LINK_STALE_S` is re-exported deliberately: `live_units()` and two checks +# read `app.main.LINK_STALE_S`. from .inverter import (LINK_STALE_S, UNIT_A, build_roster, roster_entries, roster_names) from .maintenance import ( @@ -109,105 +108,49 @@ from .watchdog import ( ) from . import setuponly from . import web +# MAINT-21: the Controller's parts and the names they now define; every one +# stays importable from `app.main`. DECISIONS/MAIN-orchestration.md. +from .ctl_tasks import TasksMixin +from .ctl_status import StatusMixin +from .ctl_alarms import ( + AlarmsMixin, HANDBACK_CYCLES, REANNOUNCE_S, ROLLING_BOUND_CYCLES, + ROLLING_S, SHORT_CYCLES, SHORT_SPAN_S, +) +from .ctl_cycle import CycleMixin, _refused_interval +from .ctl_trade import ( + TradeMixin, CHARGE_LATCH_GRACE_S, CHARGE_LATCH_KEY, EDGE_HOLD_S, + HOUSE_PROFILE_KEY, MAINT_CHARGING_W, REF_CHEAP_KEEP, _night_limit, + pack_energy_of, +) +from .ctl_writes import ( + WritesMixin, FALLBACK_BUDGET_S, REFUSED_PROGRESS_W, REFUSED_SPAN_S, + RELEASE_BUDGET_S, SETTLE_BUDGET_S, WRITE_BUDGET_S, _bounded, +) +from .ctl_inputs import ( + InputsMixin, FC_HOLD_KEY, FORECAST_READ_S, METER_QUIET_REPEAT_S, + TARIFF_MAX_AGE_S, TARIFF_REFRESH_S, _mono, +) +from .rows import arbitrage_row, tariff_plan_row, why_key, why_raised OPTIONS_PATH = "/data/options.json" INGRESS_PORT = 8099 _LOG = logging.getLogger("goodwe") -# ⚠️ `UNIT_A` NOW LIVES IN app/inverter.py AND IS RE-EXPORTED HERE, because the -# roster does. It stays importable from this module: four checks read -# `app.main.UNIT_A` and it is still the name of the inverter this add-on drives. -# DEV-02 is what turned "the one inverter" into a list; `build_roster()` is the -# one function CFG-04 changes to put a second entry in it. +# `UNIT_A` lives in app/inverter.py and is re-exported here because the roster +# does and four checks read `app.main.UNIT_A`. `build_roster()` is the one +# function CFG-04 changes. __all__ = ["UNIT_A", "Controller", "amain", "main"] -# --- DEV-02: THE PER-WRITE BUDGET, AND WHY IT IS SMALLER THAN A HEARTBEAT ---- -# Every write to every inverter is dispatched CONCURRENTLY and each one is -# bounded by this. Both halves are the acceptance criterion, not an -# optimisation: one hung `hass.call()` used to sit on the single serialised -# write path and eat a SIBLING'S layer-1 budget - the ESP32 commands 0 W after -# ~30 s without a refresh, so a transport fault on inverter A could zero a -# perfectly healthy inverter B. -# -# ⚠️ THE NUMBER IS DERIVED, NOT CHOSEN. `heartbeat_s`'s schema maximum is 25 s -# (config.yaml) and layer 1's veto is `validate.FIRMWARE_INGEST_VETO_S` (30 s), -# so the budget has to fit in what is left: 25 + 4 < 30. That is the whole -# argument, and test_inverter.py grades the inequality rather than the literal, -# so raising the heartbeat's schema ceiling takes this red instead of taking an -# inverter to zero. It is also below `hass.py`'s own 10 s HTTP timeout on -# purpose - we would rather abandon a write and re-issue it on the next tick -# (one second later, and `last_write` is only updated on an ACCEPTED write, so -# the re-issue happens by itself) than hold the control loop for ten seconds. -WRITE_BUDGET_S = 4.0 -# SMA-10. The same bound for handing a unit back (`driver.release()`). It is the -# time the shutdown path already allows one 0 W write, and the units are -# released CONCURRENTLY, so one slow or hung unit costs the wind-down no more -# than a hung GoodWe write does today: the Supervisor's kill window is not lost -# to it. A release still running at the bound is abandoned, not awaited. -RELEASE_BUDGET_S = WRITE_BUDGET_S - -# SMA-10 round 2. The one fallback write after a failed release (default 0 W, -# `Driver.release_fallback()`). Worst case for a unit whose release hangs: -# RELEASE_BUDGET_S + FALLBACK_BUDGET_S = 6 s, against the Supervisor's 10 s. -FALLBACK_BUDGET_S = 2.0 HAND_BACK_WORST_S = RELEASE_BUDGET_S + FALLBACK_BUDGET_S -# SAFETY-137. How long a LAST write (the Stop 0 W, the shutdown 0 W, a release) -# waits for a write already on its way to the same unit. Half the release -# budget, as `_release_last` always waited. For a GoodWe unit that is -# SETTLE_BUDGET_S + WRITE_BUDGET_S = 6 s at worst, which is HAND_BACK_WORST_S: -# the wind-down is no slower than SMA-10's worst case. -SETTLE_BUDGET_S = RELEASE_BUDGET_S / 2 - -# SAFETY-34: a Core-only restart wipes persistent_notification and does NOT -# restart this add-on (measured on TEST-23), so a latched alarm is re-asserted -# this often. Why: goodwe docs/DECISIONS.md, SAFETY-34. -REANNOUNCE_S = 300.0 -# UX-11 review: a quiet meter logs at most one WARNING this often, because on -# `ha_signed` a healthy meter under a flat load can go 42-97 s between changes. -METER_QUIET_REPEAT_S = 600.0 -_mono = time.monotonic # patched by the checks; asyncio keeps the real one - -# --------------------------------------------------------------------------- # -# OPT-04: THE BACKGROUND TARIFF REFRESH, AND WHY IT IS NOT OPTIONAL -# -# `static_tariff.resolve_tariff()` may perform an HTTPS fetch. The control tick -# is what feeds the ESP32 heartbeat, and layer 1 commands 0 W if that heartbeat -# stops for ~30 s - so a supplier's TLS timeout on the tick is a SUPPLIER able -# to push this add-on into the failsafe. Every module in the price stack says -# so in its own words (static_tariff.static_plan, resolve_tariff, main's -# read_inputs) and this is the task those notes were waiting for. -# -# The tick therefore never awaits a fetch. It reads `self.tariff_plan`, an -# attribute this task assigns, and nothing else. -# -# ⚠️ THE CADENCE IS NOT A GUESS AT HOW OFTEN PRICES CHANGE. A day-ahead feed -# publishes ONCE, at 14-16 h CET, and §8.3's carried hours become firm at that -# moment; 30 minutes is short enough that the switch is picked up inside the -# hour it happens and long enough to be a polite 48 fetches a day. Nothing in -# the control law depends on it. -TARIFF_REFRESH_S = 1800.0 -# ⚠️ AND THE AGE BOUND IS NOT THE SAME QUESTION. A refresh that FAILS still -# stores a plan - resolve_tariff() degrades to the §11.4 static fallback, which -# is provisional and refuses arbitrage on its own. This bound covers the other -# case: the refresh task itself dying, leaving a plan that was true hours ago -# standing as if it were current. Three missed refreshes is the threshold, for -# `p1.max_age_s`'s reason - one missed poll is not a fault, a run of them is. -# A failed read is not an observation, and neither is a stale one. -TARIFF_MAX_AGE_S = 3 * TARIFF_REFRESH_S - def tariff_refresh_wanted(opts: dict) -> bool: - """Does this install need the background tariff refresh? (TARIFF-10, TARIFF-24) - - Yes with a price feed, with trading on price armed, or with battery modes - on: the modes read `self.tariff_plan` for their price runs. With - `price_provider` off the refresh is pure arithmetic on `static_profile`, so - no term here adds an HTTPS call. It decides whether prices are looked up, - never whether energy moves. See DECISIONS/TARIFF-10-fetching-is-not-trading.md - and DECISIONS/TARIFF-24-modes-need-the-tariff-task.md. - """ + """Does this install need the background tariff refresh? (TARIFF-10, + TARIFF-24) Yes with a price feed, trading armed, or battery modes on. It + decides whether prices are looked up, never whether energy moves. + DECISIONS/TARIFF-10-fetching-is-not-trading.md and + DECISIONS/TARIFF-24-modes-need-the-tariff-task.md.""" return (provider_configured(opts) or arbitrage.enabled(opts) or packmode.enabled(opts)) @@ -221,30 +164,6 @@ def load_options() -> dict: return {} - -# OPT-11 P3: how long the last cheap run stays the price stored energy is -# valued at (`priceruns.plan(ref_eur_kwh=)`): the rest of that day. -REF_CHEAP_KEEP = timedelta(hours=12) -# OPT-15: the longest a run edge holds the loop at E waiting for the meter to -# show the step: the plant's measured step time (control.PLANT_SETTLE_S). -EDGE_HOLD_S = _ctl.PLANT_SETTLE_S - -# OPT-11 P4: the store key of the house profile (dayplan.HouseProfile), and -# how often the forecast sensors are read (they change hourly at most). -HOUSE_PROFILE_KEY = "house_profile" -# OPT-27: the forecast sensors' last fresh readings (`solarfc.Hold`), so an -# evening restart keeps the figure the night plan uses. -FC_HOLD_KEY = "solar_fc_hold" -# OPT-34: the level of a night grid charge that has started, so it does not -# drop when the forecast goes (`Controller._latch_charge()`). -CHARGE_LATCH_KEY = "night_charge_latch" -# OPT-34: a latch outlives the cheap run it was last used in by one price -# slot, because the next run is planned at the slot edge, in the cycle after -# the old one ended. -CHARGE_LATCH_GRACE_S = 900.0 -FORECAST_READ_S = 60.0 - - def _load_latch(data, now=None): """`(until, {name: level %}, born)` from the store, or None if it is not a well-formed latch or has ended (OPT-34).""" @@ -262,206 +181,14 @@ def _load_latch(data, now=None): return until, levels, born -def _night_limit(born): - """OPT-34: a run that starts after this cannot carry the latch on: the - first bell start (`solarfc.BELL_FROM_H`, local) after `born`.""" - d0, d1 = solarfc._bounds(born) - bell = solarfc._bell_start(d0) - return bell if bell > born else solarfc._bell_start(d1) - - -def why_raised(resolution, claims) -> bool: - """F2 (OPT-11 P1 test): did the limit that bound the site target push it - ABOVE what the winner asked (the peak floor asking for more power)? Then - the Why line must not say "held back". False when nothing bound it.""" - if not resolution.bound_by or resolution.contradiction: - return False - asked = next((c.value for c in sorted( - (c for c in claims if c.kind == SET - and c.actuator == ACTUATOR_SITE and c.source == resolution.winner), - key=lambda c: c.priority, reverse=True)), None) - return asked is not None and resolution.target_w > float(asked) - - -def pack_energy_of(inv): - """OPT-09. ONE roster entry as the view `packshare` consumes. - - ⚠️ ONE BUILDER, TWO CALLERS, AND THAT IS THE POINT. `Controller.pack_energy` - needs the whole roster (for the weights and the trade sizing) and - `Controller.cycle()` needs one entry at a time (for that unit's `pack` - claim). Written out twice, the two would drift - and the direction they - would drift in is a unit whose envelope is computed from a different set of - numbers than its weight, which is precisely the class of defect DEV-02 spent - a card removing. It is a module function rather than a method on `Inverter` - so that `inverter.py` does not have to import `packshare`. - """ - return packshare.PackEnergy(inv.name, inv.soc, inv.bms_soc_floor, - inv.capacity_kwh, inv.max_w) - - -# SAFETY-73 review: the evidence must also span this long, not only -# SETTLE_CYCLES cycles. SETTLE_CYCLES was derived at the 2 s meter tick (22 s -# from its first to its twelfth cycle). A 1 s meter makes 12 cycles only 11 s, -# shorter than a healthy battery reading's lag (BATT_OBLIGED_S, 17 s, plus the -# plant's dead time), and both inverters of a site were then refused after -# ordinary load steps. At 2 s and slower this changes nothing. -REFUSED_SPAN_S = (_ctl.SETTLE_CYCLES - 1) * _ctl.LOOP_TICK_S - -# SAFETY-94: the evidence restarts when the reading has moved this far towards -# the ask since the evidence began. A refusing battery reads flat (-4 W live, -# 2026-09-06); live readings wander by under 25 W at rest (B's standby, -95 to -# -118 W, 2026-10-03). A battery crossing the 100 W band on a first-order lag -# gains 50 W in at most tau x ln(151/101) = 0.4 tau, so the evidence cannot -# span REFUSED_SPAN_S unless the lag is over 54 s. -REFUSED_PROGRESS_W = _ctl.PROBE_ANSWER_W / 2 - -# SAFETY-85 review: a battery another owner set is graded against the least it -# was told over the same span as above (the plant's measured settle time), so -# a healthy battery still settling on a new command is not short. -SHORT_CYCLES, SHORT_SPAN_S = _ctl.SETTLE_CYCLES, REFUSED_SPAN_S -# SAFETY-119/121: after a hand-back the loop's bound is hidden until -# HANDBACK_CYCLES cycles and SHORT_SPAN_S have passed; across all hand-backs -# on at most ROLLING_BOUND_CYCLES cycles in any ROLLING_S seconds. Measured in -# DECISIONS/SAFETY-121-bound-every-quarter.md. Without a monotonic clock the -# budget never refills. -HANDBACK_CYCLES = 4 -ROLLING_S = 900.0 -ROLLING_BOUND_CYCLES = 11 - - -def _refused_interval(sign: int) -> tuple: - """SAFETY-73: the (lo, hi) a refusing unit may be asked: 0 W that way.""" - return (-math.inf, 0.0) if sign > 0 else (0.0, math.inf) - - -def why_key(winner: str, claims) -> str: - """The key of `messages.WHY_WINNER` for a resolution's winner. - - "safety" and "failsafe" each stand for several causes, so for those the - winning claim's own reason is the key ("stopped", "inputs missing", "sign - disagreement"). A failsafe with no claim of its own is the arbiter's "no - claim was made", or main.py's refusal to split the power ("unsplit"). - """ - if winner == "loop": - # SAFETY-52: a loop holding a refused direction says so. - return next((c.reason for c in claims if c.source == "loop" - and c.reason in (_ctl.REFUSED, _ctl.PROBING)), winner) - if winner in ("safety", "failsafe"): - return next((c.reason for c in claims - if c.source == winner and c.kind == "set"), - "no claim was made" if not any( - c.kind == "set" for c in claims) else "unsplit") - return winner - - -def tariff_plan_row(plan, tick_words: str, *, age_s, horizon_h: float, - provider: bool, max_age_s: float) -> str: - """The *Tariff* status row: the 30 s tick's sentence AND the provider plan. - - THE DEFECT THIS PREVENTS (TARIFF-11). `origin`, `product`, the horizon, - the firm/carried split and the spacing appeared in NO status row. The row - was `static_status()`'s sentence alone, computed on the 30 s I/O-free tick - from its own static plan, and it NEVER SAW the provider plan - it read - `'no static profile'` at all 802 samples of a 40-hour soak on a site whose - feed was answering. The only external evidence a plan existed at all was - one `_LOG.info` line, and that line carried the point<->hour mislabel - `TariffPlan.words` is fixed for. - - ⚠️ TWO SOURCES, TWO CLOCKS, AND THE ROW SAYS SO IN WORDS. These sentences - are NOT computed at the same moment and presenting them as though they - were would be a new version of the defect being fixed: - - `tick_words` static_status() / the Home Assistant price entities, - regenerated on THIS tick, every 30 s, I/O-free; - `plan` the background refresh's resolution, up to - TARIFF_REFRESH_S old before it is retried and up to - TARIFF_MAX_AGE_S (5400 s since TARIFF-12) old before - `fresh_tariff_plan()` retires it. - - So the plan half is stamped with its OWN age in seconds, measured from - `tariff_at` - the moment of the fetch that produced it, which TARIFF-12 - deliberately does not move on a kept plan. - - ⚠️ AND `age_s` IS THE CALLER'S MEASUREMENT, NOT THIS FUNCTION'S. A clock - read in here would be a second clock disagreeing with the one that decided - the plan was fresh enough to pass at all. - - ⚠️ "NO PLAN" IS SAID OUT LOUD ON A SITE THAT CONFIGURED A PROVIDER. A - dynamic site whose refresh has never completed, or whose plan has aged - past `max_age_s`, is the exact state the soak measured; rendering it as - the bare static sentence is how it stayed invisible for 802 samples. - """ - # UX-08: plain words, every figure kept. The tick's sentence is "now"; - # the plan carries its own age. - if plan is None: - if not provider: - return tick_words - return (f"{tick_words}. No price plan: none yet, or the last one is " - f"over {max_age_s:.0f} s old") - return (f"{tick_words}. Price plan from {age_s:.0f} s ago, for " - f"{horizon_h:.0f} hours ahead: {plan.words}") - - -def arbitrage_row(*, on: bool, decision, decided_at, cycle_at, now, - why: str) -> str: - """The *Arbitrage* status row: THREE states, which used to render as two. - - THE DEFECT THIS PREVENTS (TARIFF-11). The row was - `"off (arbitrage_enabled)" if self.arb is None else self.arb.explain()`, - under a comment asserting that `self.arb is None` if and only if - `arbitrage.enabled(self.o)` was False. IT IS NOT: `cycle()` returns at the - input hold - inputs missing, `bad_for < stale_input_s`, default 15 s - - BEFORE it reaches `self.arb = None`. Driven: `arbitrage_enabled: true` - plus a sensor answering `None` gives `arbitrage.enabled(opts) = True`, - `self.arb = None` (its `__init__` value, untouched) and a row reading - `off (arbitrage_enabled)` - NAMING AN OPTION THAT IS ON. Past the first - completed cycle the same early return leaves the PREVIOUS decision - standing instead, which the row then rendered as a current one. - - THE THREE FACTS, and they are three because they have three remedies: - - trading is off the operator has not armed it. Nothing is - wrong and nothing will happen. - no decision this cycle it is armed, and the cycle did not get as far - as the arbitrage step. `why` is the control - loop's own reason - usually "inputs missing". - a decision the strategy's own sentence, with the age of - the cycle that produced it. - - ⚠️ `on` IS READ FROM THE OPTIONS, NOT INFERRED FROM `decision is None`. - Inferring it is the whole defect: the option is the only thing that - answers "is trading armed", and it is available on every render. - - ⚠️ THE AGE IS ALWAYS PRINTED, INCLUDING WHEN IT IS ZERO. A row that - reports staleness only once it is stale cannot be told, on any single - render, from one that never reports it - and the bound TARIFF-10's - comment claimed did not exist is ~15 s of it. - """ - # UX-08: plain words; the setting is named by its label. - if not on: - return (f"Off, “{messages.LABELS['arbitrage_enabled']}” is not " - f"switched on") - if decided_at is None: - return (f"On, but no decision yet, because control has not got that " - f"far. Control says: {why or 'no reason recorded'}") - age = (now - decided_at).total_seconds() - stale = cycle_at is not None and decided_at < cycle_at - head = (f"On, no decision this cycle ({why or 'no reason recorded'}), " - f"the last one {age:.0f} s ago: " if stale else - f"On, decided {age:.0f} s ago: ") - if decision is None: - return (f"On, no decision this cycle ({why or 'no reason recorded'}) " - f"and none before") - return head + decision.explain() - - -class Controller: +class Controller(InputsMixin, WritesMixin, TradeMixin, CycleMixin, AlarmsMixin, + StatusMixin, TasksMixin): def __init__(self, opts: dict, hass: HomeAssistant, store, mqtt_pub, *, stop, peak_db_path: str = "/data/tariff.db", price_history_path: str = "/data/price_history.json", site_tz=None): # UX-15: a read-only HomeAssistant belongs to setup-only mode, which - # builds no controller. Refused here so no controller can hold one. + # builds no controller. if getattr(hass, "read_only", False) is True: raise ValueError("a controller cannot run on a read-only " "HomeAssistant (setup-only mode)") @@ -469,135 +196,58 @@ class Controller: self.hass = hass self.store = store self.mqtt = mqtt_pub - # ⚠️ REQUIRED, AND KEYWORD-ONLY, AFTER A REVIEW CATCH. This started life - # as `stop=None`, which made a Controller that CANNOT STOP ITSELF the - # default one. On the late-refusal path in run_control() that default - # meant: log the banner, return, and leave the process alive forever - # with no control loop, no exit and no further output - the exact - # "inert but looks healthy" failure this whole module exists to refuse. - # amain() always passed a real Event, so it was latent, but test_p1.py - # was already constructing Controllers without one. No default now, so - # the broken shape does not typecheck. + # REQUIRED and keyword-only: a default `stop=None` made a Controller + # that cannot stop itself. DECISIONS/MAIN-orchestration.md. self.stop_event = stop self.refused: list[str] | None = None - # ⚠️ FIRST, BECAUSE THE STORE MIGRATION BELOW CAN LOG TO IT. §15's - # action log is how an operator finds out that a latch was re-armed on - # their behalf, and a guard that raises AttributeError on the way to - # saying so is a guard that stops the add-on booting. + # First: the store migration below can log to it. + # DECISIONS/MAIN-orchestration.md. self.events: list[str] = [] # UX-08: the last event in plain words, for the page. See log_event(). self.hint = "" - # --- DEV-02: THE ROSTER, BUILT BEFORE ANYTHING THAT READS A RATING --- - # ⚠️ EVERY PER-DEVICE VALUE IN THIS CONTROLLER LIVES ON ONE OF THESE - # OBJECTS AND NOWHERE ELSE. app/inverter.py carries the argument for - # each one, including the two it deliberately does NOT hold - a `Tuning` - # and an integrator, because §6.2's stability property is ONE integrator - # on P1 above the split and a second one regulating the same meter is - # the two-writers failure the arbiter exists to prevent. - # - # ⚠️ AND THE STORE MIGRATION RUNS HERE, BEFORE THE FIRST `Inverter` READS - # ITS LATCH. `Inverter.__init__` restores SAFETY-02 from - # `unit//sign_tripped`; on an install written before DEV-02 that - # key does not exist yet and the latch is under the flat one. Migrate - # first or every existing tripped install comes up ARMED, into the - # fault, with a green banner - which is the exact failure the latch was - # persisted to prevent, rebuilt by a key rename. - # SAFETY-02's pair, and since SAFETY-30 it is THE SITE COMPARISON's - # pair - which at the shipped roster of one is the same thing under a - # more careful name. It is what `Inverter.sign_wd` is armed with at N=1, - # byte for byte, and what the site detector is armed with at N>=2. + # DEV-02: the roster, built before anything reads a rating. The store + # migration runs here, BEFORE the first `Inverter` reads its SAFETY-02 + # latch. DECISIONS/MAIN-orchestration.md. self.sign_cfg = sign_cfg = SignWatchdogConfig( min_w=float(opts.get("sign_disagree_w", 300)), hold_s=float(opts.get("sign_disagree_s", 180)), ) - # SAFETY-30. THE PER-UNIT COMPARISON'S OWN PAIR, RE-DERIVED AT TWO - # INVERTERS AND NOT CARRIED ACROSS. `sign_disagree_w` / `sign_disagree_s` - # were measured on two SINGLE-INVERTER bus captures against a command - # opposed to THE METER; this comparison is a command against ONE UNIT'S - # OWN POWER, where the magnitudes, the transient and the worst - # legitimate episode are all different quantities. watchdog.py's - # SIGN_OPTION_DEFAULTS carries the campaign that produced these, and - # DECISIONS/SAFETY-30-per-unit-sign.md carries the tables. + # SAFETY-30: the per-unit pair, re-derived at two inverters, not + # carried. DECISIONS/SAFETY-30-per-unit-sign.md. self.unit_sign_cfg = SignWatchdogConfig( min_w=float(opts.get("unit_sign_disagree_w", SIGN_OPTION_DEFAULTS["unit_sign_disagree_w"])), hold_s=float(opts.get("unit_sign_disagree_s", SIGN_OPTION_DEFAULTS["unit_sign_disagree_s"])), ) - # SAFETY-30. THE SITE COMPARISON'S OWN PAIR, USED ONLY AT N>=2. The - # threshold is the shipped 300 W - carried, because the argument behind - # it is about the meter's noise floor and the deadband, neither of which - # the roster touches - and the WINDOW is not, because the transient it - # rejects is the loop crossing zero at `slew_w` per cycle across a rail - # that IS the roster sum. Measured at both rosters on the same stimuli: - # 110 s at one inverter, 215 s at two, against a 180 s hold. See - # watchdog.SIGN_OPTION_DEFAULTS. + # SAFETY-30: the site pair, used only at N>=2. + # DECISIONS/MAIN-orchestration.md. self.site_sign_cfg = SignWatchdogConfig( min_w=float(opts.get("site_sign_disagree_w", SIGN_OPTION_DEFAULTS["site_sign_disagree_w"])), hold_s=float(opts.get("site_sign_disagree_s", SIGN_OPTION_DEFAULTS["site_sign_disagree_s"])), ) - # SAFETY-42. THE WINDOW A UNIT MAY BE SHORT OF ITS SHARE BEFORE IT IS - # NAMED. There is no second key: the WATTS half of that check is - # `Tuning.saturation_w`, read at runtime rather than copied - see - # `delivery.MIN_W_IS_SATURATION_W`, and CFG-03 on why a fourth copy of a - # default is worth avoiding. + # SAFETY-42: the window a unit may be short of its share before it is + # named. No second key: the watts half is `Tuning.saturation_w`, read + # at runtime (`delivery.MIN_W_IS_SATURATION_W`, CFG-03). self.delivery_cfg = delivery_cfg = DeliveryConfig( hold_s=float(opts.get("delivery_hold_s", DELIVERY_OPTION_DEFAULTS["delivery_hold_s"])), ) - # SAFETY-44. THE NAMES THE MACHINES READ, HANDED TO THE MIGRATION THAT - # WRITES FOR THEM. This line used to read `migrate_unit_keys(store, - # UNIT_A)`, and the constant was wrong in exactly the way the - # `maint_migration` call below says the SAME constant would be wrong - - # ⚠️ this comment used to cite "line 315" and "two hundred lines - # below", and both were wrong. The correction I wrote for them was - # wrong too: it said "~54 lines down", which was review's distance to - # the WRONG line, carried to a new referent without re-measuring - - # inside the sentence apologising for a wrong number. There is no - # distance here now, because a distance is a coordinate and the - # sentence above already names the thing. On a declared roster the flat - # latch landed under - # `unit/inverter-a/`, which is on no roster, was read back under the - # name it was handed, and stamped the marker. `roster_names()` is the - # naming rule itself and returns `[UNIT_A]` on the flat shape, so the - # upgrade path every install runs today is byte-identical. - # - # ⚠️ AND `misdirected` IS UNREACHABLE FROM **THIS** CALL SITE, WHICH THE - # COMMIT MESSAGE ORIGINALLY CLAIMED AS A BENEFIT. `unit` is - # `roster_names(opts)[0]` and `build_roster()` names its entries from - # the same `roster_names()` list, so `unit` is a member of `roster` by - # construction and the refusal can never fire here. Review measured it: - # dropping the `roster` argument from the `_verify_moves()` call inside - # `migrate_unit_keys()` survives 28/28. - # - # THE ARGUMENT STAYS ANYWAY, and the reason is the one `_verify_moves()` - # already gives for keeping its own `roster=None` branch: it is what a - # NEW caller gets, and the grading it enables is measured at the - # function's own level in test_maintenance.py rather than through here. - # What is NOT true is that this call site buys the refusal, so that - # claim is gone rather than restated. + # SAFETY-44: the migration gets `roster_names(opts)[0]`, never + # `UNIT_A`. DECISIONS/MAIN-orchestration.md. _roster_names = roster_names(opts) self.store_migration = migrate_unit_keys( store, _roster_names[0], _roster_names) self.inverters = build_roster(opts, store, sign_cfg, delivery_cfg) - # SMA-10. Which units hand back decides what the page says about Stop, - # restart and shadow mode. A GoodWe-only roster adds nothing. + # SMA-10: which units hand back decides what the page says about Stop, + # restart and shadow mode (DECISIONS/SMA-10-two-idle-states.md). handback.set_roster(handback.units_of(self.inverters)) uitext.set_idle(handback.overlay(handback.current())) - # ⚠️ CFG-04. SAY WHICH SHAPE IS IN FORCE, BECAUSE THE OTHER ONE'S KEYS - # ARE STILL SITTING IN THE UI. A declared `inverters:` roster reads none - # of `soc_entity`, `batt_entity`, `batt_invert` or `max_w`, and an - # operator looking at the Configuration page sees all four with values - # in them. validate.py rule 9(e) refuses the one that is genuinely - # dangerous - a flat `setpoint_entity` naming an actuator nothing will - # write - and the rest cannot be refused (the schema gives them no blank - # value), so they are DISCLOSED instead: one line in §15's action log, - # at every start, naming the roster it built and the keys it ignored. - # Silence here is how "the site is running at half the rating I typed" - # takes a week to notice. + # CFG-04: a declared roster ignores flat keys the UI still shows; say + # so once at every start. DECISIONS/MAIN-orchestration.md. if roster_entries(opts): self.log_event( "roster: %d inverters from `inverters:` - %s. The flat " @@ -609,97 +259,52 @@ class Controller: self.tuning = Tuning( gain=float(opts.get("gain", 0.6)), - # ⚠️ THE SITE BOUND, SUMMED FROM THE ROSTER, NOT `opts["max_w"]`. - # This is the integrator bound and the output rail of the SITE loop, - # whose output is then SPLIT across the inverters - so the number it - # may reach is what the site can deliver, which is the sum of what - # each unit may be written. At the shipped roster of one that is - # `max_w` exactly, byte for byte; at N>=2 a per-unit `max_w` still - # binds each unit's own share through its own `supervised` claim, so - # nothing here can over-command a device. + # The SITE bound is summed from the roster, not `opts["max_w"]`. + # DECISIONS/MAIN-orchestration.md. max_w=self.site_max_w, - # ⚠️ SAFETY-39: THE FALLBACK IS 0 AND 0 MEANS "FOLLOW THE RAIL", - # which is what config.yaml ships and what `Tuning`'s own default - # is. It used to be 1000 - a third copy of a constant that had - # already gone stale against the rail in the other two - and rule - # 6's comment in validate.py documents what that costs when the - # copies disagree. `control.slew_limit_w()` is the one reader. + # SAFETY-39: 0 means "follow the rail"; `control.slew_limit_w()` + # is the one reader. DECISIONS/MAIN-orchestration.md. slew_w=float(opts.get("slew_w", 0) or 0), deadband_w=float(opts.get("deadband_w", 15)), target_grid_w=float(opts.get("target_grid_w", 0)), step_w=int(opts.get("step_w", 10)), saturation_w=float(opts.get("saturation_w", 500)), saturation_cycles=int(opts.get("saturation_cycles", 3)), - # 0 / unset means "follow max_w", which is the recommended - # value. Read the note in control.py before raising it above - # max_w: every watt above the rail is unwind latency. + # 0 / unset means "follow max_w", the recommended value. Read the + # note in control.py before raising it above max_w: every watt + # above the rail is unwind latency. integrator_max_w=(float(opts["integrator_max_w"]) if opts.get("integrator_max_w") else None), ) - # ⚠️ CFG-03. EIGHT `opts.get(key, )` CALLS USED TO LIVE HERE, - # and two of those literals disagreed with config.yaml - 2500 against a - # shipped 2000, which is a config validate.py refuses. The read now - # belongs to `MaintConfig.from_options()`, next to the one in-code - # mirror of config.yaml it falls back to, so this file states no opinion - # at all about what a missing maintenance key means. Read - # maintenance.MAINT_OPTION_DEFAULTS before adding a ninth key: it goes - # in config.yaml's `options:` and `schema:` blocks and in that dict, and - # nowhere else. - # --- MAINT-05: ONE `Maintenance` PER ROSTER ENTRY -------------------- - # ⚠️ AND THE MIGRATION RUNS FIRST, FOR THE REASON THE SAFETY-02 ONE - # DOES. These objects READ their history in their constructors' wake - - # `phase`, `last_completed` - so a history still sitting under the flat - # spelling when they are built is a pack that comes up believing it has - # never been recalibrated, on a site whose state file says otherwise. - # It targets `self.inverters[0].name` and NOT `UNIT_A`: the flat keys - # belonged to whichever pack the one FSM was driving, which is the first - # roster entry, and a declared `inverters:` roster names its own entries - # (`inverter.build_roster()` says so, and its fallback for a nameless - # entry is a POSITIONAL `inverter-1`, so `inverter-a` is not even the - # default there). Writing `UNIT_A` here would deposit an install's whole - # maintenance history under a name that is not on the roster at all. - # - # ⚠️ AND THAT SENTENCE USED TO BE A COMMENT NOTHING COULD GRADE, WHICH - # IS WHY THE ROSTER IS PASSED RATHER THAN A COUNT. Every two-pack - # fixture in the suite named its first entry `inverter-a`, so - # `self.inverters[0].name` and `UNIT_A` were the same string in every - # check that existed and swapping them left all 19 files green - while - # on a roster of `["garage", "shed"]` it silently loses the history and - # stamps the marker, so the next start skips the migration too. - # `migrate_maint_keys()` now grades the namespace it wrote against the - # names the machines read; test_maintenance.py sections 9 and 11 drive - # a `["garage", "shed"]` roster, which is what makes the mutation red - # instead of invisible. + # CFG-03: `MaintConfig.from_options()` reads the options. MAINT-05: + # one `Maintenance` per roster entry; the history migration runs first, + # onto `self.inverters[0].name`, NOT `UNIT_A`. + # DECISIONS/MAIN-orchestration.md. self.maint_migration = migrate_maint_keys( store, self.inverters[0].name, [inv.name for inv in self.inverters]) _LOG.info("maintenance history: %s", self.maint_migration.explain()) if not self.maint_migration.ok: - # Not a disarmed guard - history, not a latch - so it does not - # re-arm anything. It is still the difference between a pack that is - # recalibrated on schedule and one that silently is not, which is - # §12's opening sentence, so it is said where an operator looks. + # Not a disarmed guard (history, not a latch), but it is the + # difference between a pack recalibrated on schedule and one + # silently not (12), so it is said where an operator looks. self.log_event("maintenance history did not move over cleanly: " + self.maint_migration.explain(), hint=messages.hint("maint_history")) - # ⚠️ ONE CONFIG, N MACHINES. The `maintenance_*` options describe the - # PROCEDURE - how hard to drain, how full to charge, how long to hold - - # and the procedure is the same on every pack in the roster; what is per - # pack is the SCHEDULE and the HISTORY, which live in the store. A - # per-entry config block would be a second shape for CFG-04's roster to - # carry and a fifth place for a `maintenance_charge_w` to disagree with - # config.yaml. If a site ever needs two different procedures, that is a - # roster-schema card and it starts here. + # MAINT-05: one config, N machines: the `maintenance_*` options + # describe the PROCEDURE (same on every pack); the SCHEDULE and HISTORY + # are per pack, in the store. A per-entry config block would be a + # second shape for CFG-04 and a fifth place for `maintenance_charge_w` + # to disagree with config.yaml; two procedures would be a roster-schema + # card. _maint_cfg = MaintConfig.from_options(opts) _one_pack = len(self.inverters) <= 1 self.maints = [ Maintenance( _maint_cfg, store, - # ⚠️ `None` AT A ROSTER OF ONE IS THE FLAT LAYOUT, NOT A MISSING - # NAME. §6.2's identity: one pack, one history, and the keys it - # has been written under since the add-on shipped. See - # `maintenance.UnitHistory` and `store.migrate_maint_keys()` - - # this is the line that keeps a one-inverter state file - # byte-identical. + # `None` at a roster of one is the FLAT layout, not a missing + # name (6.2 identity): it keeps a one-inverter state file + # byte-identical (`maintenance.UnitHistory`, + # `store.migrate_maint_keys()`). unit=None if _one_pack else inv.name, name=inv.name, # The rollback view, and only ever the first pack's: the flat @@ -708,59 +313,37 @@ class Controller: tz=site_tz) # MAINT-10: the start hour's zone, from amain() for i, inv in enumerate(self.inverters)] - # SAFETY-02. ONE INSTANCE PER ACTUATOR - which is what watchdog.py's own - # docstring has always said and what this Controller did not do. Each - # `Inverter` builds its own, restored from ITS OWN namespaced store keys, - # so a trip caused by B latches B and leaves A commanding. - # - # ⚠️ RESTORED FROM THE STORE, and that is the difference between a latch - # and a pause. A trip held only in memory is cleared by the one action an - # operator staring at a FAILSAFE banner is most likely to take - restart - # the add-on - and the controller then comes back armed, into the fault, - # with nobody involved. - # - # ⚠️ AND THE LATCH IS GRADED HERE RATHER THAN TRUSTED, ON EVERY START. A - # latch that silently failed to move into its namespace - or that was - # taken by an OLDER add-on while this install was rolled back, which is - # the round trip store.py's rule 2 exists for - is a DISARMED SAFETY - # GUARD on an install whose state file still says `sign_tripped: true`. - # So the flat value is compared against what the roster actually came up - # with, and a disagreement is not a log line: it re-arms the latch by - # hand and shouts, because the fail-safe direction for a latch is ON. + # SAFETY-02: one watchdog per actuator, each restored from ITS OWN + # namespaced store keys (a trip on B latches B, A keeps commanding). + # Restored, because a latch held only in memory is cleared by the + # restart an operator tries first. Graded on every start: a + # disagreement with the flat value re-arms by hand and shouts (the + # fail-safe direction is ON). DECISIONS/MAIN-orchestration.md. self._grade_store_migration(store) for inv in self.inverters: if inv.sign_wd.tripped: - # UX-11: the plain sentence and the code. The saved reason, - # with its figures, is on the DEBUG line beside it. + # UX-11: the plain sentence and the code; the saved reason with + # figures is on the DEBUG line. _LOG.error("%s stays at 0 W after the restart because its " "power went the wrong way, so find out why before " "you start control: %s.", inv.name, messages.reason_code(inv.sign_wd.reason)) _LOG.debug("Evidence for %s: %s.", inv.name, inv.sign_wd.reason or "(reason not recorded)") - # UX-11 review: `events` starts empty and DEBUG is off by - # default, so the saved figures go on the action log too. + # UX-11: `events` starts empty and DEBUG is off by default, so + # the saved figures go on the action log too. saved = inv.sign_wd.reason or messages.NO_REASON_SAVED self.log_event(f"FAILSAFE {inv.name}, saved before the " f"restart: {saved}", hint=messages.hint("stop_restored", unit=inv.name)) - # --- SAFETY-42 + SAFETY-34 ------------------------------------------- - # ⚠️ A LATCH THAT DOES NOT ACT, WHICH IS THE ONE ASYMMETRY WITH EVERY - # OTHER RESTORED LATCH ON THIS OBJECT, AND IT IS DELIBERATE. SAFETY-02's - # and SAFETY-31's latches survive a restart because they command 0 W and - # an add-on that came back armed would drive straight into the fault - # again. This one commands nothing at all: it is restored so that the - # ALARM survives, which is the whole of SAFETY-34 and is exactly how the - # 2026-09-02 outage went unseen for 6 h 25 m with the detector correct - # the entire time. `delivery.py` carries the argument for reporting - # rather than acting, with the rig measurements on both sides of it. - # - # `_delivery_announced` is the per-PROCESS half - see `_circ_announced`, - # which is the same pattern for the same reason. The store says "this - # unit is tripped"; the flag says "this process has put that in front of - # a human". A restart clears the flag and keeps the latch. + # SAFETY-42 + SAFETY-34: a latch that does NOT act, unlike SAFETY-02's + # and SAFETY-31's (which command 0 W). It is restored so the ALARM + # survives (2026-09-02: an outage unseen for 6 h 25 m with the detector + # correct); `delivery.py` argues reporting rather than acting. + # `_delivery_announced` is per process (as `_circ_announced`): a + # restart clears the flag and keeps the latch. self._delivery_announced = set() for inv in self.inverters: if inv.delivery_wd.tripped: @@ -777,27 +360,12 @@ class Controller: hint=messages.hint("not_delivering", unit=inv.name)) - # --- SAFETY-30: THE SITE HALF OF THE SIGN CHECK ---------------------- - # ⚠️ ONE PER SITE, BESIDE THE ONE PER INVERTER, AND ARMED ONLY AT N>=2. - # The per-unit watchdogs above ask "is THIS actuator doing what I told - # it", graded on that unit's own measured power. This one asks "is the - # SITE driving the wrong way", graded on the SUM of the standing - # commands against P1 - the comparison SAFETY-02 shipped, re-scoped to - # the quantity it was always actually about. - # - # ⚠️ AT A ROSTER OF ONE IT IS CONSTRUCTED AND NEVER EVALUATED, and that - # is the whole compatibility promise of this card rather than an - # oversight. With one inverter the sum of the commands IS that - # inverter's command, so arming this would be arming a duplicate of - # `inverters[0].sign_wd`: two latches for one fault, two banners, and a - # false-positive record measured on ONE comparison being spent twice. - # `cycle()` is where that is enforced and says so at the line. - # - # Restored from the store like SAFETY-02's and SAFETY-31's latches, for - # the reason store.py gives: "restart the add-on" is the first thing an - # operator looking at a FAILSAFE banner tries, and a latch held only in - # memory brings the controller back armed, into the fault, unattended. - # FLAT keys, not namespaced - store.py carries that argument too. + # SAFETY-30: the SITE half of the sign check, one per site, armed only + # at N>=2: the SUM of the standing commands against P1. At a roster of + # one it is constructed and never evaluated (arming it would duplicate + # `inverters[0].sign_wd`: two latches, two banners, a false-positive + # record spent twice); `cycle()` enforces it. Restored from the store + # with FLAT keys (store.py). DECISIONS/SAFETY-30-per-unit-sign.md. self.site_sign_wd = SignWatchdog( self.site_sign_cfg, tripped=bool(store.data.get("site_sign_tripped", False)), @@ -813,36 +381,21 @@ class Controller: + (self.site_sign_wd.reason or messages.NO_REASON_SAVED), hint=messages.hint("site_direction")) - # And the per-unit detectors are told which question they are asking, - # here as well as in `cycle()`. `checks()` and the status page read - # `inv.sign_wd.cfg` and can be called before the first cycle has run, so - # a roster of two would otherwise advertise the site thresholds on a - # detector that is about to be graded against a unit's own power. + # The per-unit detectors are told which question they ask here as well + # as in `cycle()`: `checks()` and the status page read + # `inv.sign_wd.cfg` before the first cycle. self._arm_sign_watchdogs() - # SAFETY-18. The frozen-but-fresh meter detector - see freeze.py for why - # it is a conjunction and not an `unchanged_s` threshold, and for the - # measurements behind the default. - # - # ⚠️ NOT restored from the store, unlike SAFETY-02's latch, and the - # asymmetry is the point: this one does not latch because it does not - # act. A restart re-derives its state from the meter within one - # `meter_freeze_s` window, and until then the honest report is "not - # alarming yet" rather than an alarm nobody can clear. + # SAFETY-18: the frozen-but-fresh meter detector (freeze.py). NOT + # restored from the store: it does not act, so it does not latch; a + # restart re-derives it within one `meter_freeze_s`. self.freeze_wd = FreezeWatchdog( FreezeWatchdogConfig(hold_s=float(opts.get("meter_freeze_s", 300)))) - # SAFETY-31. ONE PER SITE, and restored from the store like SAFETY-02's - # latch rather than defaulted like SAFETY-18's - the asymmetry is the - # same one the freeze watchdog's own note draws, read the other way. - # This one ACTS: a trip files a P_SAFETY SET that stops every inverter, - # so a restart that cleared it would come back up straight into the loop - # it had just stopped, which is SAFETY-02's measured three-minutes-at-a- - # time failure with a different quantity in front of it. - # - # ⚠️ SITE-LEVEL KEYS, NOT NAMESPACED. store.py carries the argument: - # circulating power is defined over the roster and is identically zero - # for any one unit, so there is no inverter to hang the latch on. + # SAFETY-31: one per site, RESTORED (unlike SAFETY-18): a trip files a + # P_SAFETY SET that stops every inverter, and a cleared latch would + # restart straight into the loop it stopped. SITE-level keys, not + # namespaced: circulating power is defined over the roster (store.py). self.circ_wd = CirculationWatchdog( CirculationConfig( min_w=float(opts.get("circulation_w", @@ -851,14 +404,13 @@ class Controller: CIRC_OPTION_DEFAULTS["circulation_hold_s"]))), tripped=bool(store.data.get("circ_tripped", False)), reason=str(store.data.get("circ_reason", "") or "")) - # SAFETY-34. Has the durable alarm been put back in front of the - # operator since this process started? `persistent_notification` is in - # memory and does NOT survive the Home Assistant restart that the store - # does, so the latch alone is not the alarm - re-raising it is. - # `run_control()` does that, once, before the first cycle. + # SAFETY-34: has the durable alarm been put back in front of the + # operator since this process started? `persistent_notification` does + # not survive the HA restart the store does; `run_control()` re-raises + # it once before the first cycle. self._circ_announced = False # SAFETY-34: when each latched alarm was last put in front of HA, by - # notification_id - see REANNOUNCE_S. + # notification_id (REANNOUNCE_S). self._announced_mono = {} if self.circ_wd.tripped: _LOG.error( @@ -873,112 +425,51 @@ class Controller: or messages.NO_REASON_SAVED), hint=messages.hint("circulating")) - # SAFETY-03. The output clamp's alarm - see clamp.py for why the clamp - # itself is the cheap half. - # - # ⚠️ NO CONFIG OF ITS OWN, on purpose. The bound it clamps to is `max_w`, - # which is already an option, already validated against the device's - # rating at startup, and already used by Tuning and the arbiter. Giving - # this a second key would be a fourth place a limit has to be kept in - # step (CFG-03 already tracks three) and, worse, would recreate exactly - # the two-numbers-that-disagree failure the §14 warning box describes. - # The anti-flood cadence is a module constant for the same reason - # freeze.RAIL_FRAC is: it describes the event bus, not the plant. + # SAFETY-03: the output clamp's alarm (clamp.py). No config of its own: + # the bound is `max_w` (already validated against the device rating), + # and a second key would be another place a limit must be kept in step + # (CFG-03). The anti-flood cadence is a constant, like + # freeze.RAIL_FRAC. self.clamp_wd = ClampWatchdog() # P1 ingestion (TEL-01). `meter_source: off` keeps the original - # single-entity meter_entity path, so an existing install is unchanged - # until it opts in. + # single-entity `meter_entity` path, so an existing install is + # unchanged until it opts in. self.p1 = P1Ingest(phases=int(opts.get("meter_phases", 1)), max_age_s=float(opts.get("meter_max_age_s", 30))) self.p1_enabled = is_enabled(opts) - # TARIFF-01. The capacity-tariff peak: measured from the meter, banked - # in SQLite, restored across a restart. It is an INSTRUMENT - it files no - # claim and clamps nothing. SAFETY-07 is what will read it. - # - # ⚠️ NO NEW OPTION. The soft limit is `peak_cap_w`, already shipped, - # already validated, already read by control.peak_at_risk(). CFG-03 - # tracks three places option defaults live; a fourth, for a limit that - # already exists, is the mistake the clamp watchdog declined to make ~30 - # lines up. config.yaml and validate.py are untouched by this ticket. - # - # ⚠️ AND NO SECOND PEAK ENTITY. `peak_forecast_entity` is the existing - # HA-side delegation and it stays the input to maintenance_charge_floor(): - # repointing that consumer at this measurement CHANGES WHAT MOVES ENERGY - # during a maintenance charge, which belongs to SAFETY-07 with its own - # acceptance, not to a measurement ticket. What this adds is the MEASURED - # MONTH PEAK - a different quantity from a forecast entity, published - # nowhere as a duplicate of it. + # TARIFF-01: the capacity-tariff peak, measured from the meter, banked + # in SQLite, restored across a restart. An INSTRUMENT: it files no + # claim and clamps nothing (SAFETY-07 reads it). No new option + # (`peak_cap_w`) and no second peak entity: `peak_forecast_entity` + # stays the input to maintenance_charge_floor(), and repointing it + # would change what moves energy in a maintenance charge. + # DECISIONS/SAFETY-07-peak-guard.md. self.peak_store = PeakStore(peak_db_path) self.peak = PeakTracker(self.peak_store, cap_w=float(opts.get("peak_cap_w", 3500))) self.peak.restore(self.p1.averager) _LOG.info("Month peak store: %s", self.peak.restore_state) - # FCST-04. The §8.3 carry-forward store: the published prices of the - # last few Brussels days, so the hours a day-ahead feed has not printed - # yet can be filled from yesterday's profile and FLAGGED, instead of - # being absent from the series entirely. - # - # ⚠️ IT IS AN INSTRUMENT'S BACKING FILE, NOT A STRATEGY. It commands - # nothing and claims nothing; what it changes is how many hours the - # plan covers. Before this, a dynamic site between midnight and the - # 14-16 h CET publication had a series covering only the rest of today - # - typically 10-24 of the 48 hours `price_horizon_h` asked for - and - # `TariffPlan.arbitrage()` took its spread over that truncated window - # without anything reporting that it had. Every carried hour is - # provisional, so refusal 3 drops it from the trade set: CARRYING a - # price widens what the optimiser can SEE, never what it may act on. - # - # ⚠️ AND THE CAVEAT THAT BELONGS WITH THAT SENTENCE, because this is - # the one place a maintainer reads it on its own. THE OTHER HALF OF - # THIS CHANGE DOES MOVE ENERGY, and it is the windowing rather than the - # carrying: the filled series covers `[since, until)`, so hours that - # have ALREADY ELAPSED are no longer in the spread. A cheap night that - # has gone used to sit in the series as the day's cheapest hour, and no - # cycle can buy in an hour that is past - so the trade was quietly - # never taken. `resolve_tariff()`'s docstring, DOCS.md and the CHANGELOG - # all carry this beside the guarantee; it may not appear here without it. - # - # ⚠️ A BROKEN OR ABSENT STORE IS NOT AN ERROR HERE. It answers `no_data`, - # the fill carries nothing, and the plan is the pre-FCST-04 one minus - # the elapsed hours - short, but honest and still refusing on the same - # rules. It must not be an error in the other sense either: a day - # record this build cannot read is DROPPED by `PriceHistory._load()` - # and reported in `.words`, because both the constructor above and the - # `.words` read below are unguarded, and a cache that raises here is an - # add-on that does not start. + # FCST-04: the 8.3 carry-forward store (published prices of the last + # few Brussels days) so unprinted hours can be filled from yesterday + # and FLAGGED. An instrument, not a strategy: carrying widens what the + # optimiser SEES, never what it may act on. ⚠️ The windowing DOES move + # energy: hours ALREADY ELAPSED leave the spread, so a past cheap night + # no longer sets the day's cheapest hour; that caveat must always + # travel with the guarantee (`resolve_tariff()`, DOCS.md, CHANGELOG). + # DECISIONS/FCST-04-the-day-that-is-carried.md. self.price_history = PriceHistory(price_history_path) _LOG.info("Price history: %s", self.price_history.words) - # SAFETY-07. The guard TARIFF-01 was built for. It is stateless by - # design (peakguard.py holds no history between calls), so the only - # state here is what an EDGE needs: what the last cycle concluded, so - # the action log and the notification fire on transitions rather than - # once per cycle for a quarter of an hour. - # - # ⚠️ THE CEILING HAS NO CONFIG OF ITS OWN, for the reason the clamp - # watchdog gives ~90 lines up and TARIFF-01 repeats: it is `peak_cap_w`, - # already shipped and already validated, and every other term of the - # projection is read off something the arbiter or the averager already - # owns. - # - # ⚠️ SAFETY-24'S FLOOR DOES HAVE ONE, AND IT COULD NOT NOT HAVE. How far - # down the guard may spend the pack for money is a number only the site - # knows, and refusing one set below the pack's own cut-out means knowing - # that cut-out too. So this card adds exactly two keys and reads their - # defaults from `peakguard.PEAK_OPTION_DEFAULTS` - TARIFF-02's mirror - # pattern - rather than typing literals here. THAT is what kept this - # card from widening: the divergence validate.py's rule 6 used to - # document (`maintenance_charge_w` 2000 in config.yaml, 2500 in this - # file) is exactly what a literal here would have repeated. CFG-03 has - # since closed that one too - `maintenance.MAINT_OPTION_DEFAULTS`, - # read through `MaintConfig.from_options()` - so the rule now holds for - # every option family this file builds: no numeric fallback in main.py - # that config.yaml has not shipped. + # SAFETY-07: the guard is stateless (peakguard.py); the only state here + # is what an EDGE needs. The ceiling has no config of its own + # (`peak_cap_w`); SAFETY-24's floor has exactly two keys, defaults from + # `peakguard.PEAK_OPTION_DEFAULTS`: no numeric fallback in main.py that + # config.yaml has not shipped. DECISIONS/SAFETY-07-peak-guard.md. self.peak_guard = None - # SAFETY-79. The guard aims this far under `peak_cap_w`; the bill and + # SAFETY-79: the guard aims this far under `peak_cap_w`; the bill and # every report keep the real cap (`self.peak.cap_w`). self.peak_margin_w = float(opts.get( "peak_margin_w", peakguard.PEAK_OPTION_DEFAULTS["peak_margin_w"])) @@ -1014,17 +505,16 @@ class Controller: self._land_batt_prev = None self._peak_needed = False self._maint_shape_suspended = False - # OPT-11. Battery modes, off by default so an install that has not - # turned them on behaves exactly as before (SAFETY-10 section 1). Each + # OPT-11: battery modes, off by default (SAFETY-10 section 1). Each # battery's mode and on/off switch live in the store, not in options, - # so a change applies at once (`pack_use`, `pack_mode` actions). + # so a change applies at once (`pack_use`, `pack_mode`). self.modes_on = packmode.enabled(opts) # The units whose mode fault is logged already (edge-logged). self._mode_faults = set() - # OPT-11 P3: the price runs (`priceruns.RunPlan`, or None), the key - # they were built for, this tick's roles (`modetrade.Tick`), the - # batteries that left a run (full, or at the floor) keyed by the run, - # and whether last tick filed a mode trade (a run edge reseeds). + # OPT-11 P3: the price runs (`priceruns.RunPlan` or None), the key they + # were built for, this tick's roles (`modetrade.Tick`), batteries that + # left a run keyed by the run, and whether last tick filed a mode trade + # (a run edge reseeds). self.mode_runs = None self._runs_key = None # TARIFF-24: the end of the run that was under way while a forecast @@ -1039,15 +529,16 @@ class Controller: self._mode_trade_was = False self._charge_blocked_q = None self._charge_gap_q = None # OPT-15: an unmeasured stop's quarter + self._charge_stop = None # SAFETY-135: (quarter, t) first stop + self._gave = collections.deque() # SAFETY-135: (t, W given), GAVE_S self._ref_cheap = None # OPT-15: a run edge the loop holds at E: (E, step sign, until, the # last battery reading). self._edge = None - # OPT-11 P4: the solar forecast and the day plan. Only with battery - # modes on AND a forecast for today set; otherwise none of this runs - # and every mode acts as in P3 option A. OPT-17: each day may name - # several entities, summed (`solarfc.entities()`); `fc_entity` is - # the first, and None means no forecast. + # OPT-11 P4/OPT-17: the solar forecast and day plan, only with battery + # modes on AND a forecast for today set; each day may name several + # entities, summed (`solarfc.entities()`); `fc_entity` is the first, + # None means no forecast. self.fc_entities = (solarfc.entities(opts) if self.modes_on else ()) self.fc_tomorrow_entities = solarfc.entities(opts, tomorrow=True) @@ -1076,11 +567,11 @@ class Controller: # OPT-11 P2: (topic, reason) of MQTT commands refused and logged once. self._mqtt_refused = set() self._mqtt_refused_more = 0 - # [(pack name, why)] for packs that are due and waiting their turn. - # Empty at a roster of one, where nothing can defer anything. + # [(pack name, why)] for packs due and waiting their turn. Empty at a + # roster of one. self._maint_deferred = [] - # SAFETY-78: names of draining packs that cannot give power now, so - # the "waits" line is logged once, not every cycle. + # SAFETY-78: names of draining packs that cannot give power now, so the + # "waits" line logs once. self._drain_waits = set() # SAFETY-91: last cycle's held-back batteries (`_held_back()`). self._held_was = frozenset() @@ -1105,101 +596,70 @@ class Controller: self._live_was = None self._loop_start = {} self._settle = {} - # Set by amain() once the transport is built, so the status page can show - # what only the transport knows (homewizard_local's unchanged_s). Stays - # None when P1 is off, or under a transport that has no such counter. + # Set by amain() once the transport is built, so the status page can + # show what only the transport knows (homewizard_local's unchanged_s). + # None when P1 is off or the transport has no such counter. + # (DECISIONS/MAIN-orchestration-archive.md) self.p1_source = None - # --- ARB-03: which actuators this site has --------------------------- - # ⚠️ THE ROSTER IS `self.inverters` AND `units` IS ITS NAMES, DERIVED. - # Every claim below is filed on an actuator, and `arbiter.actuator_for()` - # needs to know how many there are: at N=1 §6.2's identity holds - the - # fabricated grid reading and the battery setpoint are the same number - - # so the grid connection and the only inverter ARE one actuator and every - # claim routes to the site. With a second entry the per-inverter claims - # stop being site claims on their own, which is the seam ALLOC-01 - # occupies and this card fills. - # - # ⚠️ IT IS A PROPERTY, NOT A FIELD, AND THAT IS THE POINT OF THE CARD. - # `self.units = (...)` was a tuple somebody could set beside a roster of - # one Inverter object, i.e. a site that claims two actuators and has one - # writer. Deriving it means the roster and the actuator list cannot - # disagree - to add an inverter you add an Inverter. + # ARB-03: which actuators this site has. The roster is `self.inverters` + # and `units` is its names, DERIVED (a property, not a field): a + # settable tuple beside a roster of one Inverter would be two actuators + # and one writer. At N=1 (6.2) the grid connection and the only + # inverter are ONE actuator and every claim routes to the site; a + # second entry makes per-inverter claims stop being site claims (the + # ALLOC-01 seam). DECISIONS/MAIN-orchestration.md. # live state self.auto = bool(store.data.get("auto", opts.get("auto_start", False))) - # --- SAFETY-10 ------------------------------------------------------- - # What the decision path reached on the last shadow cycle, in W, or - # None before the first one. ⚠️ IT IS KEPT SEPARATELY FROM - # `self.target` BECAUSE THEY ARE DIFFERENT FACTS: `self.target` is what - # is STANDING ON THE WIRE - held at `shadow.WIRE_W` for the whole of a - # shadow run, and re-seeded to it at the end of every shadow cycle so - # the loop and the sign watchdogs track reality - and this is what a - # live controller WOULD have put there. Folding them into one field is - # how a shadow run starts telling an operator a number nothing is + # SAFETY-10: what the decision path reached on the last shadow cycle, + # in W, or None. Kept apart from `self.target` (STANDING ON THE WIRE: + # held at `shadow.WIRE_W`, re-seeded each shadow cycle): different + # facts, and folding them would show an operator a number nothing is # doing. self.shadow_would_w = None - # SAFETY-47. Was the number above SIZED FROM THE BILLED-QUARTER METER - # on the cycle it was recorded? ⚠️ IT IS RECORDED WHERE THE DECISION - # WAS TAKEN, NOT RE-DERIVED WHERE THE PAGE IS RENDERED. The status page - # runs on its own task and `self.peak_guard` has moved on by then, so a - # page that asked the question again would be answering it about a - # different cycle from the one whose watts it is displaying - which is - # the same two-facts-one-field defect the comment above this one is - # about. ⚠️ False AND NOT None BEFORE THE FIRST SHADOW CYCLE, unlike - # the field above: this one is a claim ABOUT a number, and there is no - # number yet, so the honest value is "nothing to disclose". The row's - # `would_w is None` branch renders no watts at all there. + # SAFETY-47: was the number above SIZED FROM THE BILLED-QUARTER METER + # on the cycle it was recorded? Recorded where the decision was taken, + # not re-derived at render (the page runs on its own task). False, not + # None, before the first shadow cycle: it is a claim about a number. self.shadow_sized_from_meter = False - # Edge state for the action log, both of them. `_shadow_was` is None - # until the first cycle, so an install that comes up IN shadow mode - # says so in the log it will be read from rather than leaving the - # operator to infer it from a page nobody is looking at yet. Coming up - # LIVE is silent - see `_shadow_settle()`, which says why. + # Edge state for the action log. `_shadow_was` is None until the first + # cycle so an install that comes up IN shadow mode says so; coming up + # LIVE is silent (`_shadow_settle()`). self._shadow_was = None self._shadow_winner = None self.target = 0.0 self.sat_count = 0 self.i_w = 0.0 # the loop's integrator, carried between cycles - # SAFETY-52. The direction the battery refuses (+1 / -1 / 0), carried + # SAFETY-52: the direction the battery refuses (+1 / -1 / 0), carried # like `i_w`, and when the refusal (or its last probe) started. self.batt_refused = 0 self.batt_refused_at = None self._now_mono = None self._refusal_auto = False - # TEL-10. What the last cycle's loop did, kept for publication. Seeded - # to the SAME values the "stopped or blind" branch of `cycle()` writes, - # because before the first cycle the loop has not run - which is the - # thing that branch is for. + # TEL-10: what the last cycle's loop did, for publication; seeded to + # the values the "stopped or blind" branch of `cycle()` writes. self.loop_i_w = 0.0 self.loop_i_lead = 0.0 self.loop_reason = "not-running" self.loop_w = None # what the loop asked for last cycle, or None - # --- TEL-11: the site's PV production, and NOTHING READS IT ---------- - # ⚠️ INSTRUMENTATION. It is published, it is shown on the status page, - # and it reaches no decision: not `inputs_ok`, not the allocator, not - # the arbiter, not a claim, not a watchdog. Wiring it into the control - # law would be an unrequested behaviour change on a system driving a - # real battery AND would destroy the measurement, because the loop would - # then react to the quantity being measured. `tools/tel11_pv_trace.py` - # is the instrument that says so, on both trees and both settings. - # - # ⚠️ `None` IS A READING THAT DOES NOT EXIST, AND IT IS SEEDED AS ONE. - # Nothing here ever becomes 0.0 by default; see `app/pv.py`. + # TEL-11: the site's PV production is INSTRUMENTATION and nothing reads + # it: not `inputs_ok`, the allocator, the arbiter, a claim or a + # watchdog. Wiring it in would change behaviour and destroy the + # measurement (`tools/tel11_pv_trace.py`). `None` is a reading that + # does not exist and is seeded as one (`app/pv.py`). self.pv_w = None - # Why there is no reading, in words the page prints - or, on a good - # read, the UNIT the value came in. Never empty. + # Why there is no reading, in words the page prints, or on a good read + # the UNIT the value came in. Never empty. self.pv_why = ("not configured" if not self.pv_roster else "not read yet") - # TEL-12. EVERY configured entity's own answer, `(entity, watts, why)`, - # in roster order - kept because `checks()` has to be able to name the - # sensor that is missing, and `self.pv_w` alone cannot. Empty before the - # first read, which is what "no entity has answered yet" is. + # TEL-12: every configured entity's own answer `(entity, watts, why)` + # in roster order, so `checks()` can name the missing sensor. Empty + # before the first read. self.pv_parts = [] - # Did the grid-following loop actually win the LAST arbitration? That is - # the question SAFETY-02 has to ask about the command standing on the - # wire right now, so it is recorded when the arbitration happens rather - # than re-derived a cycle later. Starts False: nothing is on the wire. + # Did the grid-following loop win the LAST arbitration? SAFETY-02 asks + # it about the command on the wire, so it is recorded at arbitration. + # Starts False. self.following = False self.reason = "starting" self.why_words = "Starting" @@ -1208,46 +668,28 @@ class Controller: # ...when the last WARNING was, and whether this episode logged one. self._meter_quiet_warned = None self._meter_quiet_loud = False - # ALLOC-01. The allocation record from the last resolution, or None - # before the first cycle. ⚠️ IT IS KEPT SO THAT SOMETHING CAN GATE ON - # IT: SAFETY-28 puts the write path behind this record, and DEV-02 reads - # `shares` off it to drive a second inverter. It is REPLACED every cycle - # and never merged - a record from a tick whose envelopes have moved is - # the cached envelope this card exists to forbid, wearing a different - # hat. + # ALLOC-01: the allocation record from the last resolution, or None. + # REPLACED every cycle, never merged (a record from a tick whose + # envelopes moved is a cached envelope). SAFETY-28 gates the write path + # on it and DEV-02 reads `shares` off it. self.allocation = None - # SAFETY-28. THE TICK THE RECORD ABOVE BELONGS TO, and the counter that - # mints it. It is incremented ONCE PER RESOLUTION - not once per loop - # iteration - and that distinction is load-bearing in both directions: - # - # * a NEW resolution makes the previous record stale IMMEDIATELY, so a - # record cannot be replayed into a later tick after the envelopes it - # describes have moved. That is the replay half of the gate. - # * a cycle that produced NO resolution does not bump it. The "inputs - # missing, not yet stale" hold above returns before the allocator - # runs precisely so that a single missed poll does not zero the - # inverter, and the heartbeat re-affirms `self.target` through the - # write path while it does. Bumping here would make that heartbeat - # unauthorised and drop the site to 0 W on the first dropped poll - - # turning a hold into the outage it exists to prevent. - # - # So the record is SUPERSEDED, never expired: it stands until the - # allocator produces its successor, and nothing else has moved in - # between that it does not still describe. + # SAFETY-28: the tick the record above belongs to, incremented ONCE PER + # RESOLUTION, not per loop iteration. A cycle with NO resolution (the + # "inputs missing, not yet stale" hold) does not bump it: the heartbeat + # re-affirms `self.target` meanwhile, and bumping would make that + # heartbeat unauthorised and drop the site to 0 W. The record is + # SUPERSEDED, never expired. DECISIONS/MAIN-orchestration.md. self.alloc_tick = 0 - # What the last cycle's allocator dropped, so the log line above is - # edge-triggered. Starts as the empty tuple - nothing has been dropped - # yet and nothing has been said about it. + # What the last cycle's allocator dropped, so the log line is + # edge-triggered. Starts empty. self._dropped_last = () - # OPT-09. The last cycle's `unmet_w`, so the line that reports it is - # edge-triggered for `_dropped_last`'s reason: a site that cannot place - # every watt stays that way for as long as the pack is empty, and a line - # a second would flush the 40-row action log of the context explaining - # it. 0 is "every watt was placed", which is the state at boot. + # OPT-09: the last cycle's `unmet_w`, so its line is edge-triggered (a + # second-by-second line would flush the 40-row action log). 0 is "every + # watt placed", the boot state. self._unmet_last = 0 - # ⚠️ THE SITE MEASUREMENT, AND THE ONLY ONE LEFT ON THIS OBJECT. `soc` - # and `batt` were per-device scalars and now live on each `Inverter`; - # `grid` is P1, one meter, one connection, and belongs here. + # The site measurement, the only one left on this object: `soc` and + # `batt` live on each `Inverter`; `grid` is P1, one meter, one + # connection. self.grid = None self.peak_fc = None # SAFETY-118: the unit fault last logged for the peak forecast (None = @@ -1255,11 +697,11 @@ class Controller: self._peak_fc_fault = None self.cheap = False self._price_gated = False # MAINT-13: is a price gate set up - # PRICE-01. Which step of the price chain the prices come from (logged - # once per change), the last series that was published (so a gap can say - # since when), and the gap itself: True while a refresh has finished and - # no published price covers now. The notification is raised once per - # gap and taken down when it ends. + # PRICE-01: which step of the price chain the prices come from (logged + # once per change), the last published series (so a gap can say since + # when), and the gap itself: True while a refresh has finished and no + # published price covers now. Notified once per gap, taken down when it + # ends. self.price_watch = PriceWatch() self._last_published = None self.price_gap = False @@ -1267,32 +709,26 @@ class Controller: self._price_gap_announced = False self._fixed_note_said = False self._gated_key = None # MAINT-13: (options, hour) of the cache - # TARIFF-03. One line of prose for the status page saying WHICH tariff - # window we are in and why it is or is not cheap - so "Cheap window: - # no" is an evidenced answer rather than a bare no. + # TARIFF-03: one line of prose for the status page saying which tariff + # window we are in and why it is or is not cheap. self.tariff_words = "No fixed tariff set" - # OPT-04. The tariff plan the BACKGROUND task last resolved, and when. - # cycle() reads these two attributes and never awaits a fetch - see - # TARIFF_REFRESH_S. `None` means no refresh has completed yet, which is - # not "no prices" and certainly not "free": arbitrage.decide() reports - # it as its own reason and does nothing. + # OPT-04: the tariff plan the BACKGROUND task last resolved, and when. + # cycle() reads these and never awaits a fetch (TARIFF_REFRESH_S). + # `None` means no refresh has completed: not "no prices" and certainly + # not "free". self.tariff_plan = None self.tariff_at = None self.arb = None - # TARIFF-11. WHEN the standing arbitrage decision was taken, or None if - # this controller has never reached the arbitrage step. ⚠️ `self.arb is - # None` DOES NOT MEAN "TRADING IS OFF" AND NEVER DID - see - # `arbitrage_row()`. It also means "cycle() returned before the step - # ran", and at that point `self.arb` is either this attribute's initial - # None (startup) or the PREVIOUS cycle's decision (an input hold), and - # the status row rendered all three identically. + # TARIFF-11: WHEN the standing arbitrage decision was taken, or None. + # `self.arb is None` does NOT mean "trading is off": it also means + # cycle() returned before the step, so `self.arb` is None (startup) or + # the PREVIOUS cycle's decision (input hold). See `arbitrage_row()`. self.arb_at = None - # SAFETY-45/47. The billed-quarter charging headroom the arbitrage step - # was handed on the cycle above, or None when nothing measured it. It - # is CARRIED rather than recomputed for `arbitrage.sized_from_meter()`, - # because `self.peak_guard` is a different cycle's decision by the time - # the status page renders. + # SAFETY-45/47: the billed-quarter charging headroom the arbitrage step + # was handed, or None. CARRIED, not recomputed for + # `arbitrage.sized_from_meter()`: `self.peak_guard` is a different + # cycle's by the time the page renders. self.arb_headroom_w = None # SAFETY-125: a grid charge sized to the quarter's room this cycle. self.room_charge = False @@ -1302,35 +738,32 @@ class Controller: # UX-54: the site's measured solar per hour, for the Forecast tab. # In memory, display only; nothing reads it back into a decision. self.solar_today = SolarToday() - # TARIFF-11. When the most recent cycle() STARTED. `arb_at < cycle_at` - # is the exact, derived statement of "the latest cycle did not get as - # far as the arbitrage step", which is the fact the *Arbitrage* row - # used to render identically to "trading is switched off". + # TARIFF-11: when the most recent cycle() STARTED. `arb_at < cycle_at` + # is the derived statement "the latest cycle did not reach the + # arbitrage step". self.cycle_at = None self._arb_action = None self.inputs_bad_since = None self.answer = lateness.Answer() # SAFETY-128 + self.settle = Settle() # SAFETY-136 self._late_logged = self._late_zero = False - # SAFETY-03. What the loop's OWN bounds did last cycle - a - # (engaged, note) pair so the alarm can say WHICH bound bit without - # re-deriving it from a string. ⚠️ THIS ONE STAYS SITE-LEVEL, and it is - # the counterpart to `clamp_last` moving onto the Inverter: the integrator - # that wound is the SITE integrator, of which there is exactly one, while - # the value a clamp bit is a value written to ONE device. - # (engaged, note, over_rating) - SAFETY-40 splits the last one out. + # SAFETY-03: what the loop's OWN bounds did last cycle, `(engaged, + # note, over_rating)` (SAFETY-40 splits the last out). Site-level: the + # integrator that wound is the one SITE integrator; a clamp bit a value + # written to ONE device (`clamp_last` is on the Inverter). self.loop_clamped: tuple[bool, str, bool] = (False, "", False) # UX-08: the numbers of a loop-side over-rating, for the notification. self.loop_clamp_facts: tuple = () - # SAFETY-85: this cycle's loop Decision, each battery's recent - # standing commands, and how many cycles in a row a battery set by - # another owner gave less than asked. + # SAFETY-85: this cycle's loop Decision, each battery's recent standing + # commands, and how many cycles in a row a battery set by another owner + # gave less than asked. self._loop_decision = None self._asked_hist: dict = {} self._short_run = 0 # SAFETY-119: did another owner set the wire last cycle; the window - # after a hand-back (monotonic s, the loop's cycles in a row); the - # monotonic s of the bound cycles hidden in the last ROLLING_S (a - # stop does not clear them). + # after a hand-back (monotonic s, loop cycles in a row); monotonic s of + # the bound cycles hidden in the last ROLLING_S (a stop does not clear + # them). self._wire_lost = False self._handback = None self._hidden = () @@ -1338,243 +771,6 @@ class Controller: # SAFETY-61. time.monotonic() at the end of the last run_control() pass. self.loop_pass_mono = None - # -- helpers ------------------------------------------------------------- - # --- SAFETY-52: a battery that refuses is asked for 0 W ------------------ - def _refusal_probe(self) -> bool: - """True while a refused direction may try `PROBE_W` (every 15 min).""" - if (not self.batt_refused or self.batt_refused_at is None - or self._now_mono is None): - return False - held = self._now_mono - self.batt_refused_at - if held >= _ctl.PROBE_EVERY_S + _ctl.PROBE_S: - self.batt_refused_at = self._now_mono - return False - return held >= _ctl.PROBE_EVERY_S - - def _refusal_start(self, sign: int, evidence: str) -> None: - self.batt_refused = sign - self.batt_refused_at = self._now_mono - self.log_event(f"BATTERY REFUSES {evidence}", - hint=messages.hint("battery_refuses")) - _LOG.info("The battery refuses to give power, so the add-on asks 0 W " - "and tries %.0f W every %.0f minutes: BATTERY_REFUSES.", - _ctl.PROBE_W, _ctl.PROBE_EVERY_S / 60) - _LOG.debug("Evidence: BATTERY_REFUSES: %s.", evidence) - - def _refusal_end(self, why: str) -> None: - if not self.batt_refused: - return - self.batt_refused, self.batt_refused_at = 0, None - self.log_event(f"BATTERY REFUSES ENDED: {why}", - hint=messages.hint("battery_gives")) - _LOG.info("The battery refusal ends, control asks for power again: %s.", - why) - - def _refusal_update(self, decision, asked_w, batt_w, probe, - rejudged: int = 0) -> None: - """Follow `compute()`'s carried refused direction, and say so. - - `rejudged`: the refusal held while another writer had the wire, so - `compute()` judged it afresh against that writer's ask (SAFETY-107). - """ - now = decision.refused or 0 - if rejudged: - if now == rejudged: - # Still refused against the ask on the wire: the same episode. - # The probe clock restarts, as it did when this was an end and - # a new start: a probe is the loop's ask, and it is not on the - # wire while another writer is. - self.batt_refused_at = self._now_mono - return - gave = (rejudged * (batt_w - self._site_idle_w()) - >= _ctl.PROBE_ANSWER_W) - self._refusal_end("the battery gives power" if gave - else "another writer") - if now and not self.batt_refused: - self._refusal_start(now, f"asked {asked_w:+.0f} W, the battery " - f"gave {batt_w:+.0f} W for " - f"{decision.sat_count} cycles") - elif self.batt_refused and not now: - gave = (self.batt_refused * (batt_w - self._site_idle_w()) - >= _ctl.PROBE_ANSWER_W) - self._refusal_end("the probe was answered" if gave and probe - else "the battery gives power" if gave - else "the grid now asks the other direction") - - def _refusal_from_stale(self, inv, now_mono) -> None: - """A stale-reading stop while the loop is frozen on ~0 W is a refusal. - - Only at one inverter: with several, one empty battery must not stop the - site (OPT-09's pack limit moves its share to the others). - """ - t = self.tuning - standing = inv.standing_w() - if len(self.inverters) > 1: - # SAFETY-73: at N>1 the same trip refuses THIS unit only. - if ((self.auto or self.shadow) and not inv.refused - and inv.ref_count >= t.saturation_cycles - and inv.batt_fresh.held is not None - and abs(inv.batt_fresh.held - inv.idle_w) - < _ctl.REFUSED_BELOW_W - and abs(standing) > _ctl.PROBE_W): - self._now_mono = now_mono - self._unit_refusal_start( - inv, 1 if standing > 0 else -1, - f"stale reading {inv.batt_fresh.held:+.0f} W while asked " - f"{standing:+.0f} W") - return - if (len(self.inverters) == 1 and (self.auto or self.shadow) - and not self.batt_refused - and self.sat_count >= t.saturation_cycles - and inv.batt_fresh.held is not None - and abs(inv.batt_fresh.held - inv.idle_w) - < _ctl.REFUSED_BELOW_W - and abs(standing) > t.saturation_w): - self._now_mono = now_mono - self._refusal_start(1 if standing > 0 else -1, - f"stale reading {inv.batt_fresh.held:+.0f} W " - f"while asked {standing:+.0f} W") - - # --- SAFETY-73: the same refusal, per inverter, at N>1 ------------------- - # SAFETY-52's decisions applied to one unit of several: a unit that gives - # < REFUSED_BELOW_W for SETTLE_CYCLES while asked > PROBE_W is closed in - # that direction by a P_SAFETY unit limit, so the allocator hands its share - # to the others; it is probed at PROBE_W every PROBE_EVERY_S, one unit at a - # time. The ask is PROBE_W, not `saturation_w`: a unit's share is often - # small (a 400 W night load split two ways) and SAFETY-43 would otherwise - # name the empty battery as not delivering. DECISIONS/SAFETY-73. - def _unit_refusal_start(self, inv, sign: int, evidence: str) -> None: - inv.refused, inv.refused_at = sign, self._now_mono - inv.probe_from, inv.ref_count = None, 0 - self.log_event(f"BATTERY REFUSES {inv.name}: {evidence}", - hint=messages.hint("unit_refuses", unit=inv.name)) - _LOG.info("%s: the battery refuses power, so it is asked 0 W and the " - "other inverters take over: BATTERY_REFUSES.", inv.name) - _LOG.debug("Evidence for %s: BATTERY_REFUSES: %s.", inv.name, evidence) - # Only a refusal to GIVE: a full battery that stops taking charge is - # above its cut-out level by definition and says nothing about it. - if (sign > 0 and inv.soc is not None and inv.bms_soc_floor is not None - and float(inv.soc) > float(inv.bms_soc_floor)): - # Owner decision 3: a refusal above the configured cut-out level - # may mean that level is set wrong. One line, no safety stop. - _LOG.warning("%s refuses power above its battery cut-out level, " - "check its cut-out level: REFUSES_ABOVE_CUT_OUT.", - inv.name) - _LOG.debug("Evidence for %s: REFUSES_ABOVE_CUT_OUT: battery level " - "%.0f %%, cut-out level %.0f %%.", inv.name, - float(inv.soc), float(inv.bms_soc_floor)) - - def _unit_refusal_end(self, inv, why: str) -> None: - if not inv.refused: - return - inv.refused, inv.refused_at, inv.probe_from = 0, None, None - inv.ref_count = 0 - self.log_event(f"BATTERY REFUSES ENDED {inv.name}: {why}", - hint=messages.hint("unit_gives", unit=inv.name)) - _LOG.info("%s: the battery refusal ends, it is asked for power again: " - "%s.", inv.name, why) - # The site target may stand above what was placed (the refused share - # was unmet). Restart it from the watts on the wire, or the reopened - # unit is handed the parked remainder at once (phase A: -1059 W). - placed = float(sum(i.standing_w() for i in self.inverters)) - self.target = self.i_w = placed - self.sat_count = 0 - - def _unit_probe(self, inv) -> bool: - """True while `inv` may try PROBE_W. One unit probes at a time.""" - now = self._now_mono - if not inv.refused or inv.refused_at is None or now is None: - return False - if inv.probe_from is not None: - if now - inv.probe_from < _ctl.PROBE_S: - return True - inv.probe_from, inv.refused_at = None, now - return False - if now - inv.refused_at < _ctl.PROBE_EVERY_S or any( - i.probe_from is not None for i in self.inverters): - return False - inv.probe_from = now - return True - - def _unit_refusals(self) -> None: - """Engage and end each unit's refusal from its own reading.""" - for inv in self.inverters: - b = inv.batt - if inv.refused: - # SAFETY-97: given and taken are counted from the idle reading. - if (b is not None and inv.refused * (b - inv.idle_w) - >= _ctl.PROBE_ANSWER_W): - self._unit_refusal_end( - inv, "the probe was answered" - if inv.probe_from is not None - else "the battery gives power") - continue - # The other direction: the battery takes PROBE_ANSWER_W or more - # the other way (charge at the floor) for SETTLE_CYCLES. Counted - # on its own reading, so one cycle of the loop overshooting - # through zero does not hand it its share back. - inv.ref_count = (inv.ref_count + 1 if b is not None and - -inv.refused * (b - inv.idle_w) - >= _ctl.PROBE_ANSWER_W else 0) - if inv.ref_count >= _ctl.SETTLE_CYCLES: - self._unit_refusal_end( - inv, "the battery takes power the other way") - continue - if inv.rejected_since is not None: - # SAFETY-96: its writes are refused, so its board may have - # gone to 0 W on its own; that is no refusal by the battery. - # The count is kept, as across a gap, so a link that refuses - # now and then does not hide a battery that does refuse. - continue - sign = self._gave_nothing(inv) - if sign: - self._unit_refusal_start( - inv, sign, - f"asked {inv.standing_w():+.0f} W, the battery gave " - f"{b:+.0f} W for {_ctl.SETTLE_CYCLES} cycles") - - def _gave_nothing(self, inv) -> int: - """The refusal evidence, one cycle of it: the sign `inv` has given - under REFUSED_BELOW_W while asked over PROBE_W, one way, for - SETTLE_CYCLES spanning REFUSED_SPAN_S, else 0. SAFETY-73 at N>1; - SAFETY-94 adds it to the N=1 engage in compute(). SAFETY-97: the band - is centred on the unit's idle reading.""" - b = inv.batt - if b is None: - return 0 # a gap keeps the count: the gate's trip seeds - standing = inv.standing_w() - sign = 1 if standing > 0 else -1 - # One direction throughout: a command that swaps sign every cycle - # (a flapping load) reads ~0 through the plant's own lag, and that - # is a battery following, not refusing (TEST-19 flapping family). - if (abs(standing) > _ctl.PROBE_W - and abs(b - inv.idle_w) < _ctl.REFUSED_BELOW_W): - # SAFETY-94: a reading still moving towards the ask is a battery - # catching up through its lag, not one refusing: start again. - if (sign != inv.ref_sign or not inv.ref_count - or sign * (b - inv.ref_from) >= REFUSED_PROGRESS_W): - inv.ref_count, inv.ref_since, inv.ref_from = ( - 0, self._now_mono, b) - inv.ref_count = min(inv.ref_count + 1, _ctl.SETTLE_CYCLES) - else: - inv.ref_count = 0 - inv.ref_sign = sign - if inv.ref_count >= _ctl.SETTLE_CYCLES and ( - inv.ref_since is None or self._now_mono is None - or self._now_mono - inv.ref_since >= REFUSED_SPAN_S): - return sign - return 0 - - def _site_idle_w(self) -> float: - """SAFETY-97: the site reading at idle, the sum of the units'.""" - return float(sum(inv.idle_w for inv in self.inverters)) - - def _site_refused(self): - """Owner decision 4: every unit refuses the same way, so the site law - holds 0 W (SAFETY-52's, in compute()). Otherwise None, the old law.""" - signs = {inv.refused for inv in self.inverters} - return signs.pop() if len(signs) == 1 and 0 not in signs else None - def log_event(self, msg: str, hint: str | None = None) -> None: """`msg` goes on the action log, the add-on's own technical record. `hint` is `messages.hint()`'s plain words for the same event, and is @@ -1585,236 +781,17 @@ class Controller: if hint is not None: self.hint = f"{datetime.now().astimezone():%H:%M} {hint}" - def _grade_store_migration(self, store) -> None: - """DEV-02. Did SAFETY-02's latch actually survive the key rename? - - ⚠️ THIS IS THE HALF THE CARD CALLS RISKY, AND IT IS GRADED RATHER THAN - PERFORMED. Namespacing `sign_tripped` is right - flat, a trip on B - latches A - but a latch that silently fails to move is a DISARMED SAFETY - GUARD ON AN INSTALL THAT BELIEVES IT IS PROTECTED: the state file still - reads `sign_tripped: true`, the banner is green, and the controller - resumes commanding into the fault that tripped it. That is strictly - worse than never having persisted the latch, because now there is - evidence that says it is fine. - - So the pre-DEV-02 flat value is compared against what the roster - ACTUALLY came up with, and a disagreement is not reported and survived - - the latch is re-armed by hand, from the flat value, and the store is - written so the next start does not need this branch. The fail-safe - direction for a latch is ON: a spurious trip costs a 0 W hold an - operator clears with one button, and a missing one costs whatever - SAFETY-02 was watching for. - - ⚠️ AND IT RUNS ON EVERY START, NOT ONLY ON THE ONE THAT MIGRATES. It - used to return early on `not rep.ran`, for a real reason: while nothing - cleared the flat key, an install that had ever tripped carried - `sign_tripped: true` in its file forever, and a guard reading it would - have re-armed the failsafe on every restart for the rest of the - install's life. - - THAT GATE SWALLOWED THE EXACT ROUND TRIP store.py's RULE 2 EXISTS FOR, - and it is not hypothetical - a firmware version change with a rollback - path was performed on this site on 2026-09-02: - - 1. the install migrates -> `schema_version = 1`, - `unit/inverter-a/sign_tripped = False` - 2. the operator DOWNGRADES, and SAFETY-02 trips inside the downgrade - window. The old code knows only the flat key, so the file gains - `sign_tripped: true` and nothing namespaced - 3. the operator upgrades again. `rep.ran` is False - the store is - already at schema 1 - so BOTH the migration and this guard are - skipped, `Inverter.__init__` reads the namespaced key, and the - controller comes up with `sign_wd.tripped = False` while - /data/state.json says `sign_tripped: true` - - Which is this module's own sentence, rebuilt by the version marker: the - file still says tripped, the banner is green, and the controller resumes - driving the wrong way. - - The gate is gone because the reason for it is gone. `handle_action()` - now clears the flat keys alongside the namespaced ones when the operator - clears the latch, and the trip mirrors them, so the two spellings can - disagree in exactly one direction: FLAT SAYS TRIPPED AND NO UNIT CAME UP - TRIPPED means the flat key was written by a version that did not know - about namespaces - a downgrade-window trip - or a migration that lost - the latch. Both want the same answer, which is the one below. - """ - rep = self.store_migration - if rep.ran and not rep.ok: - _LOG.error("The saved safety stops did not copy over cleanly, so " - "they are read again from the older saved state: %s.", - rep.explain()) - data = getattr(store, "data", {}) - legacy_tripped = bool(data.get("sign_tripped", False)) - if not legacy_tripped or not self.inverters: - return - # ⚠️ THE QUESTION IS "IS ANY NAMESPACED LATCH SET **THAT A MACHINE - # READS**", AND THE LAST CLAUSE IS SAFETY-44's SECOND HALF. At a roster - # of two a trip on B leaves A untripped, so re-arming A off a flat key - # that B's own trip mirrored would latch a healthy inverter on every - # restart - the flat-key defect DEV-02 removed, coming back through its - # own guard. That much stands, and it is why the question is asked of - # the STORE's keys rather than of the roster's objects. - # - # ⚠️ BUT IT USED TO ACCEPT **ANY** `unit/*/sign_tripped`, and the - # paragraph here defended that: the store "holds every one this install - # has ever written, including one belonging to a unit that is not in - # TODAY's roster ... whereas the roster only knows what is configured - # right now". THE PREMISE IS TRUE AND IT ARGUES THE WRONG WAY. A latch - # under a name no unit answers to is not protection an operator has - it - # is a key nothing reads, which is the definition of the state this - # method exists to repair. Counting it as protection made the guard - # return early on precisely the install that needed it, and that is not - # hypothetical: it is where the migration above USED to put the latch - # on every declared roster, so the guard was blinded by its own upgrade. - # - # THE MIGRATION FIX DOES NOT REACH THOSE INSTALLS. A store stamped by - # the shipped version already has the marker, so `migrate_unit_keys()` - # returns at the version check and never runs again. This guard is the - # ONLY repair path for a site that upgraded before this card, and it - # re-arms onto `inverters[0]` - which lands the latch back under a name - # the roster reads. - # ⚠️ AND "OFF THE ROSTER" IS NOT ENOUGH ON ITS OWN - IT HAS TO BE THE - # MIGRATION'S OWN FINGERPRINT, WHICH IS `UNIT_A`. The first draft of - # this treated EVERY off-roster latch as litter, and test_inverter.py's - # DEV-02 restart case caught it: there the store carries - # `unit/inverter-b/sign_tripped = True` from B's own trip while the - # roster being graded holds only A, and the blunt rule re-armed a - # HEALTHY A off the flat key that B's trip had mirrored - DEV-02's - # defect rebuilt inside its own guard, which is exactly what the - # paragraph above was right to be afraid of. - # - # `UNIT_A` is the discriminator because it is the ONLY name the broken - # migration ever wrote. `roster_names()` falls back to a POSITIONAL - # `inverter-N`, so `inverter-a` is not a name this code hands to anyone - # else. A latch stranded under any OTHER name is a real unit that is - # out of today's config - a roster is configuration and it changes - - # and it still counts as protection. - # - # ⚠️ THE RESIDUAL, STATED RATHER THAN LEFT TO BE FOUND: a site whose - # own first unit is NAMED `inverter-a`, latched, and then taken out of - # the roster gets re-armed on `inverters[0]`. That is a healthy unit - # held at 0 W until an operator clears it, which is the conservative - # direction; SAFETY-44's is a site DRIVING on a state file that says it - # is latched. - # - # ⚠️ AND THE SECOND HALF OF THAT RESIDUAL IS THE **SENTENCE**, NOT THE - # BOOLEAN. The reason re-armed from is the FLAT mirror, which carries - # whatever tripped LAST - so on a multi-unit site this path can print - # one inverter's evidence under another inverter's name. The latch is - # right and the explanation may not be. It is disclosed here because the - # banner is what an operator acts on, and `test_maintenance.py`'s check - # that the reason is not the removed unit's is guaranteed by that - # fixture's choice of flat string, NOT by this code. - # ⚠️ AND THE THREE CASES ARE THREE VARIABLES, NOT ONE SHARED FLAG. - # THIS IS WHERE THE FIRST VERSION OF THIS FIX WAS DEFEATED, BY ONE KEY. - # It wrote `namespaced_latched = True` for BOTH "on the roster" and "off - # the roster but not UNIT_A", so a single latched key belonging to a - # unit the operator had removed from `inverters:` vetoed the repair of - # the misdirected `inverter-a` latch sitting beside it. Measured on the - # shipped build, roster ['garage', 'shed'], store stamped so the - # migration cannot reach it: - # - # sign_tripped + unit/inverter-a/sign_tripped - # -> [('garage', True), ('shed', False)] repaired - # ...AND unit/old-shed/sign_tripped - # -> [('garage', False), ('shed', False)] ⚠️ DRIVING - # - # A site DRIVING on a state file that reads `sign_tripped: true`, which - # is the sentence this whole card exists to make false - and - # `tools/rehearse_roster.py` said so, on the unmodified tree, exit 1. - # - # ⚠️ IT IS ALSO INSTANCE #17 OF HABIT 4, IN THE EXTENSION MUTATION.md - # ADDED TWO DAYS AGO. The two fixtures written for this card each hold - # ONE arrangement - `_staged_store` has only `inverter-a`, `_other_store` - # has only `inverter-b` - and the flag is written twice with opposite - # intents only when BOTH are present. A per-key check whose keys have - # never disagreed WITHIN ONE STORE is a check over whichever key came - # last. The fixture below now holds both. - # - # THE THREE CASES, AND WHY THE ANSWER DIFFERS FOR EACH: - # on the roster a machine reads it: real protection, stop. - # off-roster, `UNIT_A` the broken migration's fingerprint - this - # IS the flat latch, misdirected. Repair. - # off-roster, other name a real unit out of today's config. Its - # latch is unread too, but it is NOT the flat - # key's misdirection, and re-arming a healthy - # sibling off it is DEV-02's defect. Stop - - # UNLESS a stranded `UNIT_A` latch is also - # present, because then the flat key IS - # accounted for and the repair is the point. - on_roster = {inv.name for inv in self.inverters} - stranded, on_roster_latched, other_off_roster = [], False, False - for k, v in data.items(): - if not (k.startswith("unit/") and k.endswith("/sign_tripped")): - continue - if not bool(v): - continue - # `unit_key()` builds `unit//`, so the unit is field 1 - - # split through the writer's own spelling rather than re-deriving. - unit = k.split("/")[1] - if unit in on_roster: - on_roster_latched = True - elif unit == UNIT_A: - stranded.append(k) - else: - other_off_roster = True - if on_roster_latched or any(inv.sign_wd.tripped - for inv in self.inverters): - return - if other_off_roster and not stranded: - # A removed unit's own latch, and no misdirected one. The flat key - # is that unit's mirror, so it carries no new information and - # re-arming `inverters[0]` from it would latch a healthy pack. - return - if stranded: - _LOG.error( - "A saved safety stop belongs to %s, which is not in the " - "inverter list %s, so it is set again on the first inverter.", - ", ".join(sorted(stranded)), sorted(on_roster)) - first = self.inverters[0] - # The one state this method exists for. - reason = str(data.get("sign_reason", "") or "") - first.sign_wd.tripped = True - first.sign_wd.reason = reason or ( - "SIGN_DISAGREEMENT: latched before this version; the reason was " - "not carried across the per-inverter store migration") - first.store_set("sign_reason", first.sign_wd.reason) - first.store_set("sign_tripped", True) - _LOG.error( - "%s is set to 0 W again because an older saved safety stop was " - "found, so find out why before you start control: %s.", - first.name, messages.reason_code(first.sign_wd.reason)) - _LOG.debug("Evidence for %s: %s.", first.name, first.sign_wd.reason) - _LOG.debug( - "SAFETY-02 latch guard: the pre-DEV-02 flat key says the " - "sign-disagreement failsafe is latched and no inverter came up " - "latched. Either the per-inverter migration lost it, or an older " - "add-on wrote it during a rollback. Both would be a disarmed " - "guard, so the latch is re-armed on %s.", first.name) - self.log_event("FAILSAFE re-armed from the pre-DEV-02 store keys - " - + first.sign_wd.reason, - hint=messages.hint("stop_restored", unit=first.name)) - - # -- the roster, and the N=1 views of it --------------------------------- + # the roster, and the N=1 views of it @property def units(self) -> tuple: - """The actuator names, DERIVED from the roster. Never assignable. - - See the note in `__init__`: a settable `units` is a site that can claim - two actuators while holding one writer, which is a half-driven site with - nothing to say so. - """ + """The actuator names, DERIVED from the roster. Never assignable (see + ARB-03 in `__init__`).""" return tuple(inv.name for inv in self.inverters) @property def maint_index(self) -> int: - """Which roster slot holds the site's ONE maintenance slot right now. - - The pack that is mid-cycle if there is one, otherwise the first - which - at a roster of one is always 0, always was, and is the whole of this - property's N=1 behaviour. - """ + """Which roster slot holds the site's ONE maintenance slot: the pack + mid-cycle if any, otherwise the first (always 0 at a roster of one).""" for i, m in enumerate(self.maints): if m.phase in POWER_MOVING: return i @@ -1822,61 +799,29 @@ class Controller: @property def maint(self): - """The `Maintenance` the site's one maintenance slot belongs to. - - ⚠️ MAINT-05 TURNED THIS FROM AN ATTRIBUTE INTO A VIEW, AND THE THING IT - IS A VIEW OF CHANGED WITH IT. There are now `self.maints` - one FSM per - roster entry, each with its own schedule, phase and history - and every - SITE-level surface that used to read `self.maint` (the `phase` MQTT - value, the status banner, the operator's start/abort buttons) wants THE - ONE THAT IS RECALIBRATING, not "the first one". `maintenance.arbitrate()` - guarantees at most one pack is ever out of IDLE, so "the one that is - recalibrating" is well defined; when none is, this is `maints[0]` and - the surfaces read exactly what they read before. - - ⚠️ AT A ROSTER OF ONE IT IS `maints[0]` ON EVERY TICK, in both branches, - which is the object that used to be assigned here. Nothing downstream - can tell the difference - that is AC 6, and test_maintenance.py part 9 - asserts it rather than trusting this paragraph. - """ + """The `Maintenance` the site's one maintenance slot belongs to + (MAINT-05): a VIEW over `self.maints` (one FSM per roster entry). + Site-level surfaces (`phase` MQTT value, banner, start/abort + buttons) want the one that is recalibrating; + `maintenance.arbitrate()` guarantees at most one is out of IDLE. + None active gives `maints[0]`, as at a roster of one on every tick + (AC 6, test_maintenance.py part 9).""" return self.maints[self.maint_index] @property def maint_unit(self): - """The pack the site's one maintenance slot is currently on. - - ⚠️ THIS USED TO BE `self.inverters[0]`, FLATLY, AND THE COMMENT THAT - STOOD HERE EXPLAINED WHY: there was exactly one `Maintenance`, its - history lived under the store's un-namespaced `phase` / `last_completed` - keys, so the pack it drove could only be the first in the roster. That - sentence is what MAINT-05 removed. There is now one FSM and one - namespaced history PER ROSTER ENTRY, so the pack being recalibrated is - whichever one holds the site's maintenance slot, and `maint_index` - - not the roster's order - is what answers it. - - ⚠️ AND `validate.py` RULE 6 MOVED WITH IT, exactly as its own comment - said it must ("when `maint_unit` stops being `inverters[0]`, this line - moves with it"). It graded `maintenance_charge_w` against the FIRST - entry's cap on the argument that the cycle never touches the others; - that argument is now false, so it grades against the weakest cap on the - roster, like rule 5. See the ⚠️ block there. - """ + """The pack the site's one maintenance slot is currently on: whichever + holds the slot, by `maint_index`, not roster order (MAINT-05 removed + the flat `inverters[0]`). validate.py rule 6 moved with it: it + grades `maintenance_charge_w` against the weakest cap on the roster, + like rule 5.""" return self.inverters[self.maint_index] def _maint_button(self, now): - """The pack an operator's one maintenance button acts on. - - The pack holding the site's maintenance slot when one holds it, so - "abort" stops the cycle that is running and "start" restarts it - - exactly what both buttons meant while there was one pack, and the reason - this is not simply "the longest-waiting one". When every pack is idle it - IS the longest-waiting one, which is `arbitrate()`'s own clause 2, so a - forced start and a scheduled start choose the same pack rather than two - different ones. - - ⚠️ AT A ROSTER OF ONE BOTH BRANCHES ARE `maints[0]`. There is no third - case: `max()` over a one-element list is that element. - """ + """The pack an operator's one maintenance button acts on: the pack + holding the slot, so "abort" stops the running cycle and "start" + restarts it; when all are idle, the longest-waiting (`arbitrate()` + clause 2), so forced and scheduled starts choose the same pack.""" if self.maints[self.maint_index].phase in POWER_MOVING: return self.maints[self.maint_index] return max(enumerate(self.maints), @@ -1895,14 +840,10 @@ class Controller: return inv is not None and inv.has_writer() def _only(self): - """The sole inverter, or an error naming why the caller cannot have one. - - ⚠️ THIS IS WHAT MAKES THE N=1 VIEWS BELOW SAFE. §6.2's identity - one - inverter means the site and the unit are the same thing - is true at N=1 - and false at N>=2, so a view built on it must not quietly answer for - "the first one" once the roster grows. Every one of them refuses instead, - loudly, naming the per-instance attribute to use. - """ + """The sole inverter, or an error naming why the caller cannot have + one. 6.2's identity (one inverter means site and unit are the same + thing) is false at N>=2, so every N=1 view refuses loudly instead of + answering for "the first one".""" if len(self.inverters) != 1: raise AttributeError( f"this site has {len(self.inverters)} inverters, so there is no " @@ -1911,23 +852,13 @@ class Controller: f"`for inv in controller.inverters: inv.`") return self.inverters[0] - # ⚠️ PROPERTIES, NOT FIELDS, AND EVERY ONE OF THEM IS A COMPATIBILITY VIEW. - # These are the scalars this card removed. They survive as read/write views - # of the SOLE inverter so that an N=1 install, and every replay in this - # repository that constructs one, is byte-identical - which is AC 8. They - # are properties rather than attributes for two reasons that are the card: - # - # * an assignment cannot re-create the scalar. `self.soc = 4` now writes - # inverter A's own SoC; there is no second copy to drift. - # * they REFUSE at N>=2 rather than answering for the first unit, so a - # consumer that has not been made per-instance fails on the line that - # reads it instead of grading inverter B against inverter A's number. - # That is the whole defect, and this is the tripwire on it. - # - # ⚠️ NOTHING INSIDE THIS FILE MAY READ THEM. main.py's own paths iterate the - # roster; test_inverter.py's grader scans this module's AST and goes red on - # a `self.` inside any method of `Controller`. A view that main.py used - # would be the scalar back with a longer name. + # Compatibility views, as properties not fields: the scalars removed by + # ARB-03/DEV-02 survive as read/write views of the SOLE inverter so an N=1 + # install and every replay stay byte-identical (AC 8), and they REFUSE at + # N>=2 so a consumer not yet made per-instance fails on the line that reads + # it. NOTHING INSIDE THIS FILE MAY READ THEM: test_inverter.py scans this + # module's AST and goes red on a `self.` inside any `Controller` + # method. @property def unit(self) -> str: return self._only().name @@ -1988,139 +919,49 @@ class Controller: def sign_wd(self): return self._only().sign_wd - # -- SAFETY-30: which comparison each sign detector is making ------------- + # SAFETY-30: which comparison each sign detector is making def _arm_sign_watchdogs(self) -> None: - """Tell every sign detector which of SAFETY-30's two questions it asks. - - ⚠️ A PURE FUNCTION OF `len(self.inverters)`, AND THE ONLY PLACE THE - ROSTER DECIDES ANYTHING ABOUT THIS CHECK. Written as one method rather - than as a conditional at the two call sites for `loop_is_following()`'s - reason: the arrangement that does not keep two things in step is the one - where they are written down twice. - - AT ONE INVERTER - §6.2's identity, and the whole of AC 8. The single - unit's detector is armed against THE METER with the shipped - `sign_disagree_w` / `sign_disagree_s`, which is what it has always been - armed against, and the site detector is not armed at all. A one-inverter - install therefore makes the same comparison, at the same thresholds, - writes the same reason string, latches under the same keys and files the - same `failsafe` claim as it did before this card. - - AT TWO OR MORE - the identity is gone and the meter stops being a view - of any one actuator. Each unit's detector is armed against ITS OWN - MEASURED POWER (`Inverter.batt`, register 0x0518) under the re-derived - per-unit pair, and the site detector is armed against the meter under - the site pair. Two questions, two remedies, two latches. - - ⚠️ CALLED AGAIN AT THE TOP OF EVERY `cycle()`, not only from - `__init__`. The roster is re-read every cycle for liveness and for the - allocation, and this repository's two-inverter fixtures append an - `Inverter` AFTER the Controller is constructed - a detector frozen at - construction would then be graded against the meter at a roster of two, - which is the defect this card exists to remove, wearing a fixture's - name. `arm()` touches no timer and no latch, so calling it every cycle - cannot disturb an episode in progress. - """ + """Tell every sign detector which of SAFETY-30's two questions it asks; + a pure function of `len(self.inverters)`. At ONE inverter (6.2, AC 8) + the unit's detector is armed against THE METER with the shipped pair + and the site detector is not armed. At TWO OR MORE each unit is armed + against ITS OWN measured power (`Inverter.batt`) under the per-unit + pair, and the site detector against the meter under the site pair. + Called at the top of EVERY `cycle()` (fixtures append an `Inverter` + after construction); `arm()` touches no timer or latch. + DECISIONS/MAIN-orchestration.md.""" one = len(self.inverters) <= 1 for inv in self.inverters: inv.sign_wd.arm(self.sign_cfg if one else self.unit_sign_cfg, AGAINST_METER if one else AGAINST_OWN_POWER) self.site_sign_wd.arm(self.site_sign_cfg, AGAINST_METER) - # -- the site aggregates, each one named for the question it answers ------ - # ⚠️ THESE ARE NOT "THE SCALARS WITH A SUM IN FRONT". Each one picks a - # DIFFERENT reduction, because the questions are different, and getting the - # reduction wrong is how a pack gets driven below its own floor. The - # reduction is written at the definition, with its reason, rather than - # inline at four call sites. + # The site aggregates, each named for the question it answers. Each picks a + # DIFFERENT reduction (the wrong one drives a pack below its own floor); + # the reason is written at each definition. @property def site_max_w(self) -> float: - """The supervised bound on the SITE target: what the roster can deliver. - - SUM. Each unit's own `supervised` claim still binds its own share, so - this cannot over-command a device; what it must not do is bound the site - loop at ONE unit's rating, which would waste the second inverter - entirely. At N=1 it is `max_w`, exactly. - """ + """The supervised bound on the SITE target: what the roster can + deliver. SUM: each unit's own `supervised` claim still binds its + share, and bounding the site loop at ONE unit's rating would waste + the second inverter. `max_w` exactly at N=1.""" return float(sum(inv.max_w for inv in self.inverters)) - def trade_power_w(self, floor_pct, ceiling_pct) -> tuple: - """OPT-09. `(charge_w, discharge_w)` - how hard a trade may be SIZED. - - The site rating is what the site can push; this is what the site can - push AND STILL HAVE SOMEWHERE TO PUT IT. `arbitrage.decide()` used to be - handed `site_max_w` on both sides, so on a roster of two the trade was - sized at the sum of the ratings whatever either pack's state of charge - was - the site would buy at 9600 W with only one pack able to absorb it, - and the watts that could not be placed would come back as `unmet_w` for - the site integrator to chase for the rest of the hour. - - ⚠️ THE BOUNDS ARE ARBITRAGE'S OWN (`arbitrage_soc_floor` / - `arbitrage_soc_ceiling`) AND NOT THE PACK'S BMS CUT-OUT, because SIZING - A TRADE IS THE TRADE'S BUSINESS. This method answers "how much may this - strategy ask for"; the ENVELOPE - `packshare.envelope()`, filed as a - `pack` claim - answers "what may this pack be commanded at all", and - that one is the pack's own physical cut-out for the reason SAFETY-25 - gives. Sizing with the physical floor would let the strategy ask for - watts its own reserve forbids; bounding the envelope with the trade's - reserve would let a trade preference stop the grid-following loop. - THEY ARE DIFFERENT QUESTIONS AND THEY GET DIFFERENT NUMBERS. - - ⚠️ AND IT SIZES THE ASK, IT DOES NOT ROUTE IT. Which pack ends up - carrying the trade is the allocator's answer, and the only per-pack - instrument it has for a TRADE reserve is the weights - which are a - preference, not a permission (`allocator._fill()` will hand watts to a - zero-weighted unit rather than leave them unmet). So a pack between its - arbitrage floor and its BMS cut-out can still take part of a sell. That - is stated rather than fixed: fixing it needs a per-pack envelope that - depends on WHICH claim won the tick, which the arbiter's partition does - not express, and is a card of its own. - - A pack whose SoC did not read is counted on NEITHER side. It is not - reachable with control running - `inputs_ok` stops the site when any - pack's SoC is missing - and withholding is the direction that cannot - over-size. - - ⚠️ NEITHER SIDE CAN BE ZERO ON A TICK THAT ACTUALLY TRADES, and it is - not left to that coincidence: `arbitrage.decide()` refuses a 0 W sizing - by name (`IDLE_NO_SIZE`), because a 0 W arbitrage claim is a park order - that outranks the loop. - """ - # ⚠️ THE REDUCTION ITSELF LIVES IN `packshare`, NOT HERE, and this - # method is the roster view it is applied to. A transcription of the - # arithmetic into a check is one copy plus a future disagreement about - # what it means, and the copy that drifts is always the grading one - - # so `test_packshare.py` part 9 calls the SAME function this does. - return packshare.trade_power_w(self.pack_energy, floor_pct, ceiling_pct) - @property def site_rating_w(self) -> float: - """The largest magnitude the SITE can actually be commanded, in W. - - SUM of each unit's own `min(max_w, |dev_min|, |dev_max|)`. This is the - peak guard's `achievable_w` and the freeze detector's rail, and summing - the PER-UNIT conjunction rather than conjoining the sums is what makes - inverter B's rating bind inverter B (AC 4). A unit whose device range has - not been read yet contributes its `max_w`, which is what the shipped - single-inverter path already did with (None, None). - """ + """The largest magnitude the SITE can be commanded, in W: SUM of each + unit's own `min(max_w, |dev_min|, |dev_max|)` (the peak guard's + `achievable_w` and the freeze detector's rail). Summing the per-unit + conjunction makes B's rating bind B (AC 4). An unread device range + contributes `max_w`.""" return float(sum(inv.rating_w() for inv in self.inverters)) - def peak_aim_w(self) -> float: - """SAFETY-79. `peak_cap_w` less `peak_margin_w`: what the forecast - checks aim at. Reports and the bill use the real cap.""" - return float(self.o.get("peak_cap_w", 3500)) - self.peak_margin_w - def site_dev_bound(self, which: str): """The roster's summed device floor / ceiling, or None if unknown. - - `freeze.looks_frozen()` and `rail_unreachable()` take a device range and - SKIP a bound they were handed None for - "ESPHome is not up yet", not - "the device can do nothing". So a bound is summed only when EVERY unit - has answered; one silent unit makes the site bound unknown rather than - making it smaller, which is the same direction the shipped code took. - """ + `freeze.looks_frozen()` and `rail_unreachable()` SKIP a bound handed + None, so a bound is summed only when EVERY unit has answered: one + silent unit makes it unknown, not smaller.""" vals = [getattr(inv, which) for inv in self.inverters] if not vals or any(v is None for v in vals): return None @@ -2128,19 +969,12 @@ class Controller: @property def site_batt_w(self): - """SUM. The battery power the SITE loop is regulating against. - - ⚠️ THIS IS THE FINDING ALLOC-01'S REVIEW HANDED THIS CARD, AND IT GOES - THE OPPOSITE WAY TO EVERYTHING ELSE HERE. `compute()`'s anti-windup test - is `abs(prev_w - actual_w) > saturation_w`, where `prev_w` is the SITE - target. Fed ONE inverter's power at a roster of two it compares a site - number against a unit number, trips the saturation freeze permanently and - leaves a standing grid error - measured on admin/goodwe's two-master rig - as up to 510 W of split-dependence at gain 0.2 and 250 W at gain 0.4, - with the allocator's shares summing to S in every one of those runs. The - counterfactual is the proof: with this sum every split is bit-identical - at every gain. See test_alloc.py part 8. - """ + """SUM. The battery power the SITE loop regulates against. Opposite to + the rest here (ALLOC-01 review): `compute()`'s anti-windup test + `abs(prev_w - actual_w) > saturation_w` compares the SITE target, so + one unit's power at N=2 trips the saturation freeze permanently (up + to 510 W of split-dependence at gain 0.2 on the two-master rig; with + the sum every split is bit-identical, test_alloc.py part 8).""" vals = [inv.batt for inv in self.inverters] if not vals or any(v is None for v in vals): return None @@ -2148,49 +982,25 @@ class Controller: @property def site_circulating_w(self): - """SAFETY-31. `sum(|B_i|) - |sum(B_i)|` over MEASURED per-unit power. - - ⚠️ `inv.batt`, NOT `self.allocation`. THIS IS THE WHOLE CARD, and the - wrong version is the tempting one: the same formula over the allocation - record would be simpler, would never be None, and would be worth - nothing. ALLOC-01's sign-coherence gate (`allocator.REFUSE_SIGN`) already - refuses an allocation whose shares carry two signs, so a record-derived - sensor reads zero BY CONSTRUCTION, forever, and can only ever confirm - that the allocator agrees with itself. Every fault this card is for is a - divergence between what was commanded and what the hardware is doing - a - unit ignoring or lagging its share, a stale share still being executed, - or HW-01's power stage running its last instruction for 6 h 25 m with - the comms dead and the allocation record impeccable throughout. - Measured on the TEST-19 rig: with one unit wedged, the record stays - `ok` with both shares at -1250 W - a record-derived sensor reads 0 W - - while this one reads 2000 W. - - `batt` became per-instance in DEV-02; before that there was one scalar - on the Controller and this property could not have been written. - - None when any unit has not answered, and NOT zero - circulation.py says - why at length. The short version: zero would be this sensor reporting - health from an absence, which is the 2026-09-02 failure itself. - Identically 0.0 at the shipped roster of one (AC 5). - """ + """SAFETY-31. `sum(|B_i|) - |sum(B_i)|` over MEASURED per-unit power: + `inv.batt`, NOT `self.allocation`. The allocation record already has + sign-coherence (`REFUSE_SIGN`), so a record-derived sensor reads + zero by construction and can only confirm the allocator agrees with + itself; every fault this card covers is a divergence between command + and hardware (TEST-19 rig: one unit wedged, record `ok` at -1250 W + each, record-derived 0 W, this 2000 W; HW-01's 6 h 25 m). None when + any unit has not answered, never zero (circulation.py): zero would + report health from an absence. 0.0 at a roster of one (AC 5).""" return circulating_w([inv.batt for inv in self.inverters]) @property def pack_floor_soc(self): - """MINIMUM. The SoC that a discharge PERMISSION must be graded against. - - SAFETY-24's floor asks "may this site spend the pack for money", and the - honest answer at N>=2 is the EMPTIEST pack: an average lets it be driven - below its own floor, which is the failure the option exists to prevent. - None if any unit did not answer - `peakguard.decide()` treats None as - floor-limited, which costs a shave rather than a pack. - - ⚠️ AND IT IS NOT THE RIGHT REDUCTION FOR A CHARGE CEILING, which is the - FULLEST pack. Nothing in the add-on files a per-pack charge ceiling yet - (arbitrage's `soc_ceiling` is the only consumer and it takes one number); - that is CFG-04/SPIKE-04's per-pack bound, and it is named here so the - next reader knows this reduction was chosen rather than assumed. - """ + """MINIMUM. The SoC a discharge PERMISSION is graded against: the + EMPTIEST pack (an average lets one be driven below its floor). None + if any unit did not answer (`peakguard.decide()` reads None as + floor-limited). Not the right reduction for a charge ceiling (the + FULLEST pack); nothing files a per-pack ceiling yet + (CFG-04/SPIKE-04).""" vals = [inv.soc for inv in self.inverters] if not vals or any(v is None for v in vals): return None @@ -2198,5018 +1008,12 @@ class Controller: @property def packs(self) -> list: - """SAFETY-32. Each pack as its own THREE numbers, in roster order. - - `pack_floor_soc` above is the site's ONE verdict and stays exactly what - DEV-02 made it - the emptiest measured pack. This is the thing that - reduction cannot produce: by the time `min()` has answered, WHICH pack - the number came from and how far that pack was from ITS OWN cut-out have - both been thrown away, and two packs at 15 % against cut-outs of 10 % and - 20 % have opposite answers that are indistinguishable afterwards. - - ⚠️ EVERY unit, live or not. Same reason as `inputs_ok`: a pack whose SoC - did not answer is a pack nothing can grade, and dropping it from this - list would let the site spend the packs that DID answer while one sat - unmeasured. `peakguard.discharge_permitted()` treats a None SoC as no - permission, which is where that must be decided. - """ + """SAFETY-32. Each pack as its own THREE numbers in roster order, + beside `pack_floor_soc` (the site's one verdict, the emptiest pack). + EVERY unit, live or not, as `inputs_ok` does.""" return [peakguard.Pack(inv.name, inv.soc, inv.bms_soc_floor) for inv in self.inverters] - @property - def pack_energy(self) -> list: - """OPT-09. Each pack as the FOUR numbers a split needs, in roster order. - - The fourth is `capacity_kwh`, and it is why this is not `packs` above. - That list answers the FLOOR question - may this pack be spent - and its - consumers (`pack_permissions`, `binding_soc_floor`) have no use for a - capacity and would have to default one. This list answers the SPLIT - question - which pack should carry more of the site target - and cannot - be asked without one. - - ⚠️ EVERY unit, live or not, for `packs`'s reason. The allocator drops - what `live_units()` does not list and `plan()` ignores a weight for a - unit it dropped, so filtering here would only move the same decision to - a worse place - and `packshare.weights()` needs to see a pack that did - not answer in order to withhold its opinion about the whole roster. - """ - return [pack_energy_of(inv) for inv in self.inverters] - - def pack_weights(self, target_w): - """OPT-09. The comfort weights for a site target of `target_w`. - - ⚠️ IT IS A METHOD HANDED TO `resolve()`, NOT A DICT COMPUTED BEFORE IT, - and that is not indirection for its own sake. An energy-headroom - weighting is direction-dependent - room above the floor when the site is - discharging, room below full when it is charging - and the two give - opposite answers on the same roster. The direction is the SIGN OF THE - SITE TARGET, which is stage 2's output, so nothing here can know it - until `resolve()` has run stage 2. `arbiter.resolve()` calls this once, - between stage 2 and stage 3, with the number it just chose. - - ⚠️ AND IT IS READ FRESH ON EVERY CALL, NEVER CACHED, for the reason the - allocator refuses to cache an envelope: a pack's SoC moves for reasons - that have nothing to do with the allocator, and a weighting held from - construction prefers a pack that has since emptied. - """ - base = packshare.weights(self.pack_energy, target_w) - if not self.modes_on: - return base - # OPT-11: the solar order. While the site charges, Leftover solar - # batteries weigh 0, so Solar first batteries fill first. A comfort - # choice like the rest of this method: permission is the mode claim. - w = packmode.charge_weights(base, self.pack_modes(), target_w) - # P3: in a price run, the batteries whose run it is carry it first. - tick = self.mode_tick - return w if tick is None else modetrade.weights(tick.roles, w, - target_w) - - def pack_mode(self, inv) -> "packmode.PackMode": - """OPT-11. This battery's on/off switch and mode, read from the store.""" - return packmode.read(getattr(self.store, "data", None) or {}, inv.name) - - def pack_modes(self) -> dict: - return {inv.name: self.pack_mode(inv) for inv in self.inverters} - - def loop_bound(self, claims): - """OPT-11. `(lo, hi)`: what the batteries may place if the loop decides. - - The sum over live units of each unit's hard limits with its mode - applied (`allocator.loop_bound()`), from THIS cycle's unit claims. At - one inverter every claim is on the site, so it is the mode range - itself, or None when no mode is filed (maintenance) or the range - leaves out 0 W (a fault `resolve()` reports). - """ - if len(self.inverters) <= 1: - modes = [c for c in claims if c.source == "mode"] - if not modes: - return None - lo = max(c.lo for c in modes) - hi = min(c.hi for c in modes) - return (lo, hi) if lo <= 0.0 <= hi else None - bounds = {u: pre_resolve([c for c in claims if c.actuator == u]) - for u in self.units} - return allocator.loop_bound(bounds, live=self.live_units()) - - # --- OPT-11 P3: price runs, per battery ------------------------------- - def _mode_packs(self, maint_results=None) -> list: - """Each battery as `modetrade.Pack`, in roster order.""" - live = set(self.live_units()) - out = [] - for i, inv in enumerate(self.inverters): - pm = self.pack_mode(inv) - idle = (maint_results is None - or maint_results[i].phase == IDLE) - refused = (inv.refused if len(self.inverters) > 1 - else self.batt_refused) or 0 - # OPT-15: a charge refusal's probe (SAFETY-73, N>1) as it stood - # when last decided; its pin is filed after this, in cycle(). - probing = (len(self.inverters) > 1 and refused < 0 - and inv.probe_from is not None) - out.append(modetrade.Pack( - inv.name, pm.use, pm.mode, pm.sell and pm.can_sell, - float(inv.max_w), inv.soc, inv.capacity_kwh, - live=inv.name in live, idle=idle, refused=int(refused), - probing=probing)) - return out - - def _wx_track(self, now) -> None: - """TARIFF-24, once per cycle, before the plan: with a forecast read, - remember when the run now under way (cheap, give or sell) ends.""" - if self.solar_fc is None: - return - rp = self.mode_runs - ends = [] - if rp is not None and rp.on: - ends = [r.end for r in (rp.cheap, rp.sell) - if r is not None and r.holds(now)] - g = rp.give_at(now) - if g is not None: - ends.append(g.end) - self._wx_free_to = max(ends) if ends else None - - def weather_held(self, now) -> bool: - """TARIFF-24: no forecast now, but a run planned with one is under - way: it keeps its gap to its end. The wider gap applies from the next - run. OPT-34: a night charge that keeps its level (`_latch_charge()`) - keeps the gap too, run after run, or the next slice of it would be - refused. Pure; Home asks the same (`homeview.trade_verdict()`).""" - return self.solar_fc is None and ( - (self._wx_free_to is not None and now < self._wx_free_to) - or (self._charge_latch is not None - and now < self._charge_latch[0])) - - def _price_runs(self, now, packs, floor_pct, ceiling_pct): - """The kept run plan, rebuilt at most once per price slot (15 min) or - when the prices or a battery's choice change; a run under way is - kept to its end (`priceruns.keep_started()`). None with no fresh - firm prices: then no battery holds or trades (design section 5).""" - plan = self.fresh_tariff_plan(now) - if plan is None or not plan.has_prices: - self.mode_runs, self._runs_key = None, None - self.day_plan = None - return None - slot = int(now.timestamp() // 900) - key = (id(plan), slot, tuple((p.name, p.use, p.mode, p.sell) - for p in packs)) - held = self.weather_held(now) - if self.fc_entity is not None: - # P4: a forecast arriving or going rebuilds the plan at once (and - # so does the end of a run that held the gap, TARIFF-24). - key += (self.solar_fc is None, held) - if key != self._runs_key: - done_c = self._run_done.get("charge", (None, set()))[1] - done_s = self._run_done.get("sell", (None, set()))[1] - e = modetrade.energy(packs, floor_pct, ceiling_pct, done_c, - done_s) - required = price_required_spread( - arbitrage.threshold_eur_kwh(self.o), - price_uncertainty_of(plan.read.product) - | arbitrage.weather_uncertainty(True, self.solar_fc, held)) - ref = self._ref_cheap - if ref is not None and now - ref.end > REF_CHEAP_KEEP: - ref = self._ref_cheap = None - new = priceruns.plan( - plan.read.points, now, required_eur_kwh=required, - charge_kwh=e[0], charge_kw=e[1], sell_kwh=e[2], - sell_kw=e[3], - ref_eur_kwh=None if ref is None else ref.mean_eur_kwh) - if self.fc_entity is not None: - new = self._day_plan(now, packs, floor_pct, ceiling_pct, - new, plan, required, ref, done_c, e) - self.mode_runs = priceruns.keep_started(self.mode_runs, new, now) - self._runs_key = key - runs = self.mode_runs - # The cheapest cheap run under way lately is the price the stored - # energy was bought at; it stays the reference for REF_CHEAP_KEEP - # after it ends, unless a cheaper one comes. - ref = self._ref_cheap - if runs is not None and runs.cheap is not None \ - and runs.cheap.holds(now) and ( - ref is None or now - ref.end > REF_CHEAP_KEEP - or runs.cheap.mean_eur_kwh <= ref.mean_eur_kwh): - self._ref_cheap = runs.cheap - return runs - - def _day_plan(self, now, packs, floor_pct, ceiling_pct, runs, plan, - required, ref, done_c, e): - """OPT-11 P4: the day plan (`dayplan.plan()`) on the runs just made, - its levels held by the hysteresis (`dayplan.hold()`), then the runs - made again with each battery's shortfall as the charge, so the cheap - run is only as long as the shortfall needs. With no plan (no or stale - forecast, no house profile yet) the levels are dropped: P3 option A. - Returns the runs to keep.""" - dp = dayplan.plan( - self.solar_fc, - None if self.house_profile is None - else self.house_profile.estimator(), - priceruns.keep_started(self.mode_runs, runs, now), now, packs, - trust_pct=self.solar_trust_pct, floor_pct=floor_pct, - ceiling_pct=ceiling_pct, aim_w=self.peak_aim_w(), - slots=priceruns.firm_slots(plan.read.points, now), - spread=required) - self.day_plan = dp - if dp is None: - self._plan_targets = None - return runs - self._plan_targets = dayplan.hold( - self._plan_targets, dp.targets, - {p.name: p.capacity_kwh for p in packs}) - e2 = modetrade.energy(packs, floor_pct, ceiling_pct, done_c, (), - targets=self._plan_targets) - return priceruns.plan( - plan.read.points, now, required_eur_kwh=required, - charge_kwh=e2[0], charge_kw=e2[1], sell_kwh=e[2], sell_kw=e[3], - ref_eur_kwh=None if ref is None else ref.mean_eur_kwh) - - def plan_targets(self): - """P4: each battery's planned level, or None (no day plan). Dropped - at once when the forecast goes (stale or missing), except the level - of a night charge that has started (OPT-34): it keeps that level.""" - if self.solar_fc is None: - lt = self._charge_latch - if lt is None or datetime.now(timezone.utc) >= lt[0]: - return None - return dict(lt[1]) - return self._plan_targets - - def _latch_charge(self, now, runs, targets, packs=None) -> None: - """OPT-34, once per cycle after `modetrade.decide()`. A night grid - charge that has started keeps its planned level when the forecast goes - mid-charge (the kept figure ends and the sensors are still silent). - - While there is a forecast, fresh or kept, the latch is rebuilt each - cycle from the plan: a battery that charges from the grid in the cheap - run comes in with its planned level, and stays in it at whatever level - the plan gives it, up or down as a fresh figure moves it (also when it - has stopped, at a lowered level), until it leaves the plan. While there - is none, `plan_targets()` gives the latched levels, so the charge goes - on to them, and `weather_held()` keeps the narrow price gap. The latch - lasts through every cheap run on and one price slot after the last - (`CHARGE_LATCH_GRACE_S`), but a run is carried on only if it starts - by the bell start of the night the latch began in (`_night_limit()`; - the run under way then finishes). It is dropped when `now` passes its - end whatever the run state, and a battery that is off or no longer in - a mode with a planned level (`packs`) leaves it. A charge that never - started has none.""" - old = lt = self._charge_latch - tick = self.mode_tick - run = None if runs is None else runs.cheap - in_run = run is not None and run.holds(now) - grace = timedelta(seconds=CHARGE_LATCH_GRACE_S) - if lt is not None and now >= lt[0]: - lt = None - if lt is not None and packs is not None: - ok = {p.name for p in packs - if p.use and p.mode in packmode.PLAN_CHARGE_MODES} - lv = {n: v for n, v in lt[1].items() if n in ok} - lt = (lt[0], lv, lt[2]) if lv else None - # A run may carry the latch on only if it starts by the night's bell. - carry = in_run and (lt is None or run.start <= _night_limit(lt[2])) - if in_run and self.solar_fc is not None: - # Rebuilt from the plan: a battery already latched follows its - # level up or down whatever its role this tick (a fresh figure may - # lower it below the SoC), one that left the plan is dropped, and - # a new one comes in only while it charges from the grid. - tg = targets or {} - lv = {n: float(tg[n]) for n in (lt[1] if lt else {}) if n in tg} - if tick is not None and tick.action == modetrade.CHARGE: - lv.update({n: float(tg[n]) for n, r in tick.roles.items() - if r == modetrade.CHARGE and n in tg}) - if not lv: - lt = None - elif lt is None: - lt = (run.end + grace, lv, now) - else: - lt = (max(run.end + grace, lt[0]) if carry else lt[0], lv, - lt[2]) - elif lt is not None and carry: - lt = (max(lt[0], run.end + grace), lt[1], lt[2]) - if lt != old: - self._charge_latch = lt - self.store.set(CHARGE_LATCH_KEY, None if lt is None else { - "until": lt[0].isoformat(), "levels": lt[1], - "born": lt[2].isoformat()}) - - def _mode_roles(self, now, maint_results): - """OPT-11 P3: each battery's role and range this tick. Grid charging - and selling need a fresh plan that `TariffPlan.arbitrage()` allows - with the MEASURED peak guard (None refuses: nothing measures the - quarter), exactly the gate `arbitrage.decide()` has.""" - floor_pct, ceiling_pct = arbitrage.soc_bounds(self.o) - packs = self._mode_packs(maint_results) - self._wx_track(now) - runs = self._price_runs(now, packs, floor_pct, ceiling_pct) - guard = arbitrage.guard_state(self.peak_guard) - plan = self.fresh_tariff_plan(now) - charge_ok = sell_ok = False - trade_why = "not_covered" - - def allowed(active): - return plan.arbitrage( - peak_guard_active=active, - min_spread_eur_kwh=arbitrage.threshold_eur_kwh(self.o), - uncertainty=arbitrage.weather_uncertainty( - True, self.solar_fc, self.weather_held(now)), - now=now).match( - allowed=lambda _v: True, refused=lambda _v: False) - if guard is not None and plan is not None and runs is not None: - # A charge asks the guard (section 9.1 interlock); a sell only - # needs it to have measured the quarter, since discharge is never - # capped by it (a big discharge alone engages it on export). - sell_ok = allowed(False) - charge_ok = sell_ok and allowed(guard) - trade_why = (None if charge_ok else "peak" if sell_ok - else "not_worth") - self.mode_gate = None if charge_ok else trade_why - price_now = None - if plan is not None: - try: - pt = plan.read.match(series=lambda r: r.at(now), - no_data=lambda _r: None) - price_now = (None if pt is None or pt.provisional - else float(pt.eur_per_kwh)) - except Absence: - price_now = None - house = (None if self.grid is None or self.site_batt_w is None - else float(self.grid) + float(self.site_batt_w)) - if self.house_profile is not None and \ - self.house_profile.add(now, house): - self.store.set(HOUSE_PROFILE_KEY, self.house_profile.dump()) - targets = self.plan_targets() - if targets is None: - done_c = self._run_mark("charge", runs and runs.cheap, packs, - lambda p: p.soc is not None - and p.soc >= ceiling_pct) - else: - # P4: out of the run at its planned level. A level the - # hysteresis moved opens the run to it again (a new mark key). - def full(p): - to = modetrade.charge_to(p, ceiling_pct, targets) - return p.soc is not None and (to is None or p.soc >= to) - done_c = self._run_mark("charge", runs and runs.cheap, packs, - full, tuple(sorted(targets.items()))) - done_s = self._run_mark("sell", runs and runs.sell, packs, - lambda p: p.soc is not None - and p.soc <= floor_pct) - quarter = int(now.timestamp() // 900) - was = self.mode_tick is not None and \ - self.mode_tick.action == modetrade.CHARGE - self.mode_tick = modetrade.decide( - runs, now, packs, charge_ok=charge_ok, sell_ok=sell_ok, - trade_why=trade_why, price_now=price_now, - headroom_w=self.arb_headroom_w, floor_pct=floor_pct, - ceiling_pct=ceiling_pct, house_w=house, charging_now=was, - blocked=self._charge_blocked_q == quarter, - done_charge=done_c, done_sell=done_s, targets=targets, - draining=any(r.phase == DRAIN for r in maint_results or ())) - self._latch_charge(now, runs, targets, packs) - # A charge the guard or the headroom stopped stays off this period. - # OPT-15: only a MEASURED stop latches; the first unmeasured headroom - # (None) in a quarter stops this tick only, so a gap cannot cost the - # whole quarter. A second one latches, so gaps cannot flip the charge. - if was and self.mode_tick.action != modetrade.CHARGE: - why = self.mode_tick.why - gap = why == "headroom" and self.arb_headroom_w is None - if why == "peak" or (why == "headroom" and not gap) or ( - gap and self._charge_gap_q == quarter): - self._charge_blocked_q = quarter - elif gap: - self._charge_gap_q = quarter - return self.mode_tick - - def _run_mark(self, kind, run, packs, out, extra=None) -> set: - """The batteries that left run `run` (full, or at the floor); they - stay out until it ends, so a level edge does not re-arm them. - `extra` (P4: the planned levels) is part of the run's key.""" - key = None if not run else (run.start, run.end) - if key is not None and extra is not None: - key += (extra,) - was_key, done = self._run_done.get(kind, (None, set())) - if key != was_key: - done = set() - if key is not None: - done |= {p.name for p in packs if out(p)} - self._run_done[kind] = (key, done) - return done - - def _mode_trade(self, claims, now) -> bool: - """OPT-11 P3: file the site trade the roles ask for, sized inside the - modes and the hard limits (the loop bound) and, for a charge, the - billed quarter's headroom (SAFETY-45, aim cap - margin, SAFETY-79). - So no battery that its mode or a refusal holds is asked for watts it - may not give (P1's unmet share). Returns True when a trade is filed. - """ - tick = self.mode_tick - if tick is None: - return False - if tick.action == modetrade.CHARGE: - # OPT-20: the ask carries PROBE_W for exactly the probes whose pin - # is filed this tick. `decide()` ran before the pin was (or the - # window closed since), so the two can differ by one cycle; left - # alone, the allocator takes the pin's watts out of another - # battery's share, or hands them to one it can reach. - pins = _ctl.PROBE_W * sum( - 1 for c in claims if c.source == "refused" - and c.kind == "set" and c.value < 0) - if pins != tick.probe_w: - tick = self.mode_tick = dataclasses.replace( - tick, ask_w=tick.ask_w + tick.probe_w - pins, - probe_w=pins) - size = modetrade.size(tick, self.loop_bound(claims) - if tick.action else None, self.arb_headroom_w) - runs = self.mode_runs - if tick.action and (size == 0.0 or runs is None): - # Nothing the batteries may place (a refusal, a hard limit): no - # trade, and the roles say so rather than "charging". - back = {modetrade.CHARGE: modetrade.HOLD, - modetrade.REST: modetrade.HOUSE, - modetrade.SELL: modetrade.GIVE} - tick = self.mode_tick = modetrade.Tick( - tick.ranges, {n: back.get(r, r) for n, r in tick.roles.items()}, - None, 0.0, "size") - if size == 0.0 or runs is None: - reason = ("battery modes: no price run now" if tick.why is None - else f"battery modes: no trade ({tick.why})") - self.arb = arbitrage.ArbitrageDecision( - action=None, power_w=None, reason=reason, - spread_eur_kwh=None, required_eur_kwh=None, - price_now_eur_kwh=None) - else: - charge = tick.action == modetrade.CHARGE - run = runs.cheap if charge else runs.sell - who = ", ".join(n for n, r in sorted(tick.roles.items()) - if r == tick.action) - act = arbitrage.CHARGE if charge else arbitrage.DISCHARGE - self.arb = arbitrage.ArbitrageDecision( - action=act, power_w=size, - reason=(f"{act}: battery modes, " - f"{'cheap' if charge else 'sell'} run " - f"{run.start.isoformat()} to {run.end.isoformat()} " - f"at {run.mean_eur_kwh:.4f} EUR/kWh; " - f"{abs(size):.0f} W on {who}"), - spread_eur_kwh=None, required_eur_kwh=runs.level_eur_kwh, - price_now_eur_kwh=None) - claims.append(arbitrage.claim(self.arb)) - if self.arb.action != self._arb_action: - self._arb_action = self.arb.action - self.log_event(self.arb.explain(), hint=messages.hint( - "trade_charge" if self.arb.action == arbitrage.CHARGE else - "trade_give" if self.arb.action == arbitrage.DISCHARGE - else "trade_off")) - return self.arb.action is not None - - def _reseed_run_edge(self, claims, now) -> None: - """OPT-11 P3: a mode trade just ended, so the loop takes over from a - command no loop chose. Start it at the house's own point E, the - command that brings the grid to its target now (`site battery + grid - - target`, inside the loop bound), instead of at the trade's watts. - OPT-15: then HOLD it at E (`_edge_grid()`) until the meter shows the - step or `EDGE_HOLD_S` passes. The readings still describe the trade for - a second or two (meter and battery lag), and stepping on them sent - E 810 -> 1370 -> 1920 W on TEST-23: -1120 W export at a charge end. - Measured: DECISIONS/OPT-11-battery-modes.md. - """ - self._edge = None - batt = self.site_batt_w - if batt is None or self.grid is None: - return - want = float(batt) + float(self.grid) - self.tuning.target_grid_w - bound = self.loop_bound(claims) - if bound is not None: - want = max(bound[0], min(bound[1], want)) - want = float(round(max(-self.site_max_w, min(self.site_max_w, want)))) - self.target = self.i_w = want - if want != float(batt): - self._edge = (want, 1.0 if want > float(batt) else -1.0, - now + timedelta(seconds=EDGE_HOLD_S), float(batt)) - - def _edge_grid(self, end, now): - """OPT-15: the grid reading the loop acts on this tick. While a run - edge is held, the target itself (no error, the command stays at E). - The hold ends when the meter reaches the target in the step's - direction (or passes it), on `end` (a trade started, or another claim - moved the command), or after `EDGE_HOLD_S` - later, up to twice that, - while the battery reading is still moving towards E.""" - e = self._edge - if e is None: - return self.grid - held_w, sign, until, last_b = e - tg, db = self.tuning.target_grid_w, self.tuning.deadband_w - b = self.site_batt_w - moving = (b is not None and sign * (float(b) - last_b) >= db - and sign * (held_w - float(b)) >= db - and now < until + timedelta(seconds=EDGE_HOLD_S)) - if (end or (now >= until and not moving) - or sign * (float(self.grid) - tg) < db): - self._edge = None - return self.grid - self._edge = (held_w, sign, until, last_b if b is None else float(b)) - self.i_w = held_w - return tg - - def _charge_track(self, claims, maint_results) -> None: - """SAFETY-93, N>=2: a charge ends when its battery leaves CHARGE or can - no longer be placed (stale link, refusal). Kept until the loop runs. - SAFETY-95: a drain likewise; its refusal (SAFETY-73) outranks the pin - without a contradiction, so it is read from the battery (+1, will not - give; a battery that will not take still drains).""" - if len(self.inverters) < 2: - return - live = set(self.live_units()) - now = {CHARGE: set(), DRAIN: set()} - for inv, res in zip(self.inverters, maint_results): - u = self.actuator_of("maintenance", inv) - if res.phase in now and u in live and not pre_resolve( - [c for c in claims if c.actuator == u]).contradiction \ - and not (res.phase == DRAIN and (inv.refused or 0) > 0): - now[res.phase].add(inv.name) - self._charge_ended |= self._charging_was - now[CHARGE] - self._charging_was = frozenset(now[CHARGE]) - self._drain_ended |= self._draining_was - now[DRAIN] - self._draining_was = frozenset(now[DRAIN]) - - def _reseed_charge_end(self, maint_results) -> None: - """SAFETY-93, N>=2: when a battery's maintenance charge ends, the loop - starts from what the others stood at plus that battery's new command - (its HOLD pin, or its last discharge if it is free; a charge stops). - Else the charge's watts stay in the site target and land on the - others: B 0 -> -1600 W in one cycle. DECISIONS/SAFETY-93-charge-end.md. - """ - ended, self._charge_ended = self._charge_ended, frozenset() - if len(self.inverters) < 2 or not ended: - return - for inv, res in zip(self.inverters, maint_results): - if inv.name not in ended: - continue - now_w = (float(res.setpoint_w or 0.0) if res.owns_setpoint - else max(float(inv.target), 0.0)) - if not inv.is_live(datetime.now(timezone.utc))[0]: - now_w = 0.0 # SAFETY-96: out of the split, it is sent 0 W - self.target += now_w - float(inv.target) - # SAFETY-96: it settles from its charge to that command. - self._loop_start[inv.name] = now_w - self._settle[inv.name] = self._now_mono - self.i_w = self.target - - def _reseed_drain_end(self, maint_results, live) -> None: - """SAFETY-95, N>=2: when a battery's maintenance drain ends, its - drain leaves the loop's start point, as a charge does (SAFETY-93): the - start is what the others stood at plus its new command (its pin, else - 0 W). Where the house needs more, the start is the house's own point - (the live batteries' readings + grid - target), never above last - cycle's start. The loop then moves one slew step a cycle. Else the - drain's floor stays in the target and lands on the others: B 0 -> - +1600 W in one cycle, exporting. DECISIONS/SAFETY-95-drain-end.md. - """ - ended, self._drain_ended = self._drain_ended, frozenset() - if len(self.inverters) < 2 or not ended: - return - hi = self.target - for inv, res in zip(self.inverters, maint_results): - if inv.name not in ended: - continue - now_w = (float(res.setpoint_w or 0.0) - if res.owns_setpoint and res.phase != DRAIN - else min(float(inv.target), 0.0)) - if inv.name not in live: - now_w = 0.0 # SAFETY-96: out of the split, it is sent 0 W - else: - self._drain_tail.add(inv.name) - self.target += now_w - float(inv.target) - self._loop_start[inv.name] = now_w - self._settle[inv.name] = self._now_mono - lo, hi = sorted((self.target, hi)) - # A dropped battery's power is the meter's, like the house's. - here = float(self.grid) - self.tuning.target_grid_w + sum( - float(inv.batt) for inv in self.inverters if inv.name in live) - self.target = self.i_w = min(hi, max(lo, here)) - - def _drain_grid_w(self, live) -> float: - """SAFETY-95: the grid the loop regulates. While a battery settles - from its ended drain (`_held_out_w`: until within the deadband, at - most PLANT_SETTLE_DOWN_S), the meter still shows the drain's tail and - the others' climb, so the loop would chase them (B down, then up - again). Meanwhile the batteries count at the site command: the error - is the house's own point minus the loop's start. - - SAFETY-103: a reading can be up to a register period (10 s) older - than the meter, so the house point is held, and moved only as far as - the meter proves: to the nearest value the batteries can be at (each - between its last changed reading and its commands since; a reading - that changed this cycle, or the side a battery refuses, is taken as - it reads). DECISIONS/SAFETY-103-old-readings-after-a-drain.md. - """ - grid = float(self.grid) - self._drain_tail &= set(self._settle) & set(live) - if not self._drain_tail: - self._drain_house = None - return grid - aim = self.tuning.target_grid_w - lo = hi = grid - aim - for inv in self.inverters: - if inv.name not in live: - continue - r = float(inv.batt) - span = self._read_span.get(inv.name) - if (span is None or span[2] != inv.batt_fresh.changed_mono - or span[2] == self._now_mono): - span = (r, r) - # A battery that refuses one way (SAFETY-73) is not heading - # that way, whatever it was asked: that side is its reading. - if (inv.refused or 0) > 0: - span = (min(span[0], r), r) - elif (inv.refused or 0) < 0: - span = (r, max(span[1], r)) - lo, hi = lo + span[0], hi + span[1] - held = (float(self.target) if self._drain_house is None - else self._drain_house) - self._drain_house = min(hi, max(lo, held)) - return self._drain_house - float(self.target) + aim - - def _track_reads(self) -> None: - """SAFETY-103, N>=2: per battery, the range its power can be in now: - its last changed reading and every command on its wire since (a - lagging battery moves from one toward the others, never beyond).""" - if len(self.inverters) < 2: - return - for inv in self.inverters: - if inv.batt is None: - continue - cmd, since = inv.standing_w(), inv.batt_fresh.changed_mono - lo, hi, was = self._read_span.get(inv.name, (0.0, 0.0, None)) - if was is None or since != was: - lo = hi = float(inv.batt) - self._read_span[inv.name] = (min(lo, cmd), max(hi, cmd), since) - - def _reseed_drop(self, live) -> None: - """SAFETY-96, N>=2: a battery that drops out of the split (stale - link) leaves the loop's start point, so the others take over at one - slew step a cycle instead of taking its share at once. One that comes - back enters it at its reading, and every battery settles while the - split is made again (`_held_out_w`). - DECISIONS/SAFETY-96-dropped-battery.md. - """ - was, self._live_was = self._live_was, frozenset(live) - if len(self.inverters) < 2 or was is None or was == live: - return - for inv in self.inverters: - if inv.name in self._charge_ended | self._drain_ended: - continue # SAFETY-93/95's edge: `_reseed_*_end()` - if inv.name in was and inv.name not in live: - now_w = 0.0 - elif inv.name in live and inv.name not in was: - now_w = float(inv.batt) - # The split is made again, so every battery's command steps. - self._settle.update( - {u: self._now_mono for u in live}) - else: - continue - self.target += now_w - float(inv.target) - self._loop_start[inv.name] = now_w - self.i_w = self.target - - def _held_out_w(self, live) -> float: - """SAFETY-96, N>=2: what to add to the site sum so that a battery - the loop cannot move right now counts at its command, not at its - reading. That is a battery out of the split, one whose writes are - refused, or one settling after a step the loop did not make (a charge - end, a rejoin) until its reading is within the deadband of its - command or PLANT_SETTLE_DOWN_S has passed. Its real power still - reaches the loop through the meter, so it is neither lost nor counted - twice; only the saturation freeze stops seeing it as the loop's. - """ - if len(self.inverters) < 2: - return 0.0 - out = 0.0 - for inv in self.inverters: - cmd = self._loop_start.get(inv.name, float(inv.target)) - since = self._settle.get(inv.name) - age = (None if since is None or self._now_mono is None - else self._now_mono - since) - if since is not None and ( - age is None or age >= _ctl.PLANT_SETTLE_DOWN_S - or (age > 0 and abs(float(inv.batt) - cmd) - < self.tuning.deadband_w)): - del self._settle[inv.name] - if (inv.name not in live or inv.rejected_since is not None - or inv.name in self._settle): - out += cmd - float(inv.batt) - return out - - def _mode_fault_log(self, resolution) -> None: - """OPT-11: say once, per battery, that its mode was dropped as a fault. - - A mode range without 0 W would force a direction, which no mode may do, - so it is never applied (allocator.unit_interval()). main.py never - builds one; this is the line that says so if it ever does. - """ - alloc = resolution.allocation - now = {u for u, _ in getattr(alloc, "mode_faults", ())} - if resolution.mode_fault is not None and self.inverters: - now.add(self.inverters[0].name) - for inv in self.inverters: - if inv.name in now and inv.name not in self._mode_faults: - _LOG.error("Battery mode ignored for %s. Software fault " - "MODE_RANGE.", inv.name) - self.log_event(f"battery mode ignored on {inv.name}, a " - f"software fault", hint=messages.hint( - "mode_fault", unit=inv.name)) - self._mode_faults = now - - def _pack_action(self, what, unit, value, now) -> dict: - """OPT-11: switch one battery on or off, set its mode, or (P3) turn - its selling on or off. - - Store state, not an option, so it applies on the next cycle with no - restart. Written to the action log. Switching a battery off also stops - its maintenance cycle (the owner's 2026-09-27 answer). Refused, with a - plain reason, while battery modes are off or for an unknown battery or - value. - """ - if not self.modes_on: - return {"error": messages.pack_refused("off")} - inv = next((i for i in self.inverters if i.name == unit), None) - if inv is None: - return {"error": messages.pack_refused("unit")} - if what == "pack_use": - if not isinstance(value, bool): - return {"error": messages.pack_refused("value")} - inv.store_set(packmode.USE_KEY, value) - self.log_event(f"{inv.name} switched {'on' if value else 'off'} " - f"by operator", - hint=messages.hint("pack_on" if value - else "pack_off", unit=inv.name)) - if not value: - self._maint_stop_off(self.maints[self.inverters.index(inv)], - now) - elif what == "pack_sell": - if not packmode.SELLING_ENABLED: - return {"error": messages.pack_refused("sell_off")} - if not isinstance(value, bool): - return {"error": messages.pack_refused("value")} - inv.store_set(packmode.SELL_KEY, value) - self.log_event(f"{inv.name} selling switched " - f"{'on' if value else 'off'} by operator", - hint=messages.hint("pack_sell", unit=inv.name)) - else: - if value not in packmode.MODES: - return {"error": messages.pack_refused("value")} - inv.store_set(packmode.MODE_KEY, value) - self.log_event(f"{inv.name} mode set to {value.replace('_', ' ')} " - f"by operator", - hint=messages.hint("pack_mode", unit=inv.name)) - pm = self.pack_mode(inv) - out = {"unit": inv.name, "use": pm.use, "mode": pm.mode} - if what == "pack_sell": - out["sell"] = pm.sell - return out - - async def _maint_unit_action(self, what, unit, now) -> dict: - """MAINT-11: start or abort the maintenance cycle of ONE named battery. - - Returns `{"error", "code", "unit"}` for a refusal and changes nothing. - The site keeps its one maintenance slot: a start while any battery - holds it is refused (no queue), see DECISIONS/MAINT-11. The phase - machine is not touched beyond `force_start()` and `abort()`, the same - two calls the bare button makes. - """ - inv = next((i for i in self.inverters if i.name == unit), None) - if inv is None: - return self._maint_refusal("unit") - machine = self.maints[self.inverters.index(inv)] - if what == "maint_start": - holder = next((i for i, m in zip(self.inverters, self.maints) - if m.phase in POWER_MOVING), None) - if holder is not None: - return self._maint_refusal("busy", holder.name) - if self.modes_on and not self.pack_mode(inv).use: - return self._maint_refusal("off", inv.name) - for msg in machine.force_start(now): - self.log_event(msg, hint=messages.hint( - "maintenance", phase=machine.phase)) - return {"unit": inv.name, "phase": machine.phase} - if machine.phase not in POWER_MOVING: - return self._maint_refusal("idle", inv.name) - for msg in machine.abort(now, "operator"): - self.log_event(msg, hint=messages.hint("maintenance", - phase=machine.phase)) - await self.command_site_zero() - return {"unit": inv.name, "phase": machine.phase} - - @staticmethod - def _maint_refusal(code, unit="") -> dict: - return {"error": messages.maint_refused(code, unit), "code": code, - "unit": unit} - - def mode_values(self) -> dict: - """OPT-11 P2: each battery's mode and switch, for their HA state - topics. Read from the store, so they are right after a restart. Empty - while battery modes are off.""" - if not self.modes_on: - return {} - out = {} - names = [inv.name for inv in self.inverters] - for inv, slug in zip(self.inverters, unit_slugs(names)): - pm = self.pack_mode(inv) - out[unit_state_key(slug, "mode")] = MODE_LABELS.get(pm.mode, - pm.mode) - out[unit_state_key(slug, "use")] = USE_ON if pm.use else USE_OFF - return out - - async def mqtt_command(self, topic, payload, retained) -> None: - """OPT-11 P2: one command from a battery's HA switch or mode list. - - It goes through handle_action(), the page's /action path, so the - checks and the store write are the same. A retained command (one the - broker replays on subscribe, e.g. after a restart) is never applied: - the store already holds the last choice. A refusal is logged once per - topic and reason, at most 32, and further refusals are counted in the - log at 1, 10, 100 and so on. Never raises: MQTT must not reach control. - """ - try: - slug, action, value, why = parse_command( - topic, payload, retained, packmode.MODES) - if why is None: - names = [inv.name for inv in self.inverters] - unit = dict(zip(unit_slugs(names), names)).get(slug) - result = await self.handle_action(action, unit=unit, - value=value) - if not (isinstance(result, dict) and "error" in result): - self.mqtt.publish(self.mode_values()) - return - why = result["error"] - else: - why = messages.pack_refused(why) - # Printable only: a topic is sender-chosen, so no log injection. - topic_s = "".join(c if c.isprintable() else "?" - for c in str(topic)[:128]) - _LOG.debug("Home Assistant command %s %s refused: %s", topic_s, - repr(payload)[:48], why) - if (topic_s, why) in self._mqtt_refused \ - or len(self._mqtt_refused) >= 32: - # Not logged again, but counted: 1, 10, 100... stay visible. - self._mqtt_refused_more += 1 - more = self._mqtt_refused_more - if str(more).rstrip("0") == "1": - _LOG.warning("Home Assistant commands still ignored: %d " - "more so far.", more) - return - self._mqtt_refused.add((topic_s, why)) - _LOG.warning("Home Assistant command on %s ignored: %s", topic_s, - why) - except Exception: # noqa: BLE001 - _LOG.exception("Home Assistant command could not be handled") - - def _drain_floor(self, claims, maint_results): - """SAFETY-78: the site `lo` for a pinned maintenance drain, or None. - - At N>=2 the drain pins its pack and the site target is split around - the pin. Below the pin a sibling would have to charge (opposite - directions, refused, 0 W, and the drain never moves). So the site - target may not go below what the pin places: the drained pack covers - the house up to its drain rate and exports the rest, as at N=1, and - a sibling only ever adds power in the same direction. At N=1 the - drain is the site SET itself, so nothing is filed. - A draining pack whose own limits leave it nothing to give (a refusal, - a stale link) adds no floor, and that is logged once. - """ - if len(self.inverters) < 2: - return None - live = set(self.live_units()) - floor, waits = 0.0, set() - for inv, res in zip(self.inverters, maint_results): - if res.phase != DRAIN or not res.owns_setpoint \ - or not (res.setpoint_w or 0.0) > 0.0: - continue - u = self.actuator_of("maintenance", inv) - b = pre_resolve([c for c in claims if c.actuator == u]) - p = (None if u not in live or b.contradiction - or b.pinned_by != "maintenance" else allocator.pin_w(b)) - if p is not None and p > 0.0: - floor += p - else: - waits.add(inv.name) - for name in sorted(waits - self._drain_waits): - self.log_event(f"maintenance: {name} cannot give power now, so " - f"its monthly cycle waits", - hint=messages.hint("maint_waits", unit=name)) - self._drain_waits = waits - return floor if floor > 0.0 else None - - def _peak_on_able(self, decision, maint_results): - """SAFETY-87: at N>=2, `decision` placed on the batteries that can - still give: live, not refusing, above their own reserve. `able_w` is - their rating plus the drain a held battery gives anyway (its - maintenance pin). Unchanged when no battery is held back. - DECISIONS/SAFETY-87-guard-uses-able-batteries.md.""" - if len(self.inverters) < 2: - return decision - floor = float(self.o.get( - "peak_soc_floor", peakguard.PEAK_OPTION_DEFAULTS["peak_soc_floor"])) - ok, held = peakguard.reserve_split(self.packs, floor) - if not held: - return decision - live = set(self.live_units()) - able = [p for p, inv in zip(self.packs, self.inverters) - if p in ok and inv.name in live and not (inv.refused or 0) > 0] - if not able: - return dataclasses.replace(decision, held=held) - drain = sum(min(float(r.setpoint_w), i.rating_w()) - for i, r in zip(self.inverters, maint_results) - if i.name in held and r.phase == DRAIN - and r.owns_setpoint and (r.setpoint_w or 0.0) > 0.0) - names = {p.name for p in able} - return peakguard.place_on_able( - decision, held, - able_w=drain + sum(i.rating_w() for i in self.inverters - if i.name in names), - soc=min(float(p.soc) for p in able), - soc_floor=peakguard.binding_soc_floor(able, floor)) - - def _peak_landing(self, decision): - """SAFETY-126: `decision` marked `within_aim` while the guard wants - power but the batteries at 0 W would end the quarter within - `ALARM_MISS_W` of the aim (`peakguard.misses_aim()`). Once a real miss - is seen, the need stands until the guard lets go. The claim and the - commands are unchanged; only the alarms and the "Why" read it. - DECISIONS/SAFETY-126-landing-error-is-not-an-overrun.md.""" - batt, prev = self.site_batt_w, self._land_batt_prev - self._land_batt_prev = batt - if not (decision.engaged and decision.blind is None - and (decision.wanted_w or 0.0) > 0.0): - self._peak_needed = False - return decision - if batt is not None and prev is not None: - batt = min(float(batt), float(prev)) - self._peak_needed = self._peak_needed or ( - self._peak_proj is not None and peakguard.misses_aim( - self._peak_proj, batt_w=batt, target_w=decision.target_w)) - return (decision if self._peak_needed - else dataclasses.replace(decision, within_aim=True)) - - def _readings_late(self, standing_w): - """SAFETY-128: update the answer gate; seconds the late verdict has - stood, or None. Readings found late are logged once per episode. - DECISIONS/SAFETY-128-late-readings.md.""" - a = self.answer - if self._now_mono is None: - return None - a.observe(self._now_mono, standing_w, self.site_batt_w, - grid_w=self.grid, exempt=bool(self.batt_refused) or any( - i.refused or ( - i.batt is not None - and abs(i.standing_w()) >= lateness.ANSWER_W - and abs(i.batt - i.idle_w) < lateness.ANSWER_W) - for i in self.inverters), - idle_w=self._site_idle_w()) - if a.late_seen != self._late_logged: - self._late_logged = a.late_seen - if a.late_seen: - self.log_event("readings late - holding", - hint=messages.hint("readings_late")) - _LOG.warning("Home Assistant readings arrive late, so control " - "holds the batteries: READINGS_LATE.") - _LOG.debug("READINGS_LATE: the readings show a power request " - "%.0f s after it is sent.", a.delay_s) - else: - self.log_event("readings on time", hint=messages.hint( - "readings_back")) - _LOG.info("Home Assistant readings are on time again.") - return a.late_s(self._now_mono) - - def _peak_reserve(self) -> frozenset: - """SAFETY-87: the batteries that give nothing for the peak this - cycle: under their reserve while the others carry a peak floor.""" - g = self.peak_guard - if g is None or g.able_w is None or not (g.floor_w or 0.0) > 0.0: - return frozenset() - return frozenset(g.held) - - def _held_back(self) -> frozenset: - """SAFETY-91, N>=2: the batteries at or under their own peak reserve - while another can still give (live, not refusing). They weigh 0 in - every split where the site gives, so they give last (SAFETY-25 - option A: still drawn once the others are full). One held back - stays so until its SoC reads more than 1 point above its reserve, so - a reading flipping across it does not swap the split each cycle.""" - if len(self.inverters) < 2: - return frozenset() - floor = float(self.o.get( - "peak_soc_floor", peakguard.PEAK_OPTION_DEFAULTS["peak_soc_floor"])) - ok, held = peakguard.reserve_split(self.packs, floor) - held = set(held) | { - p.name for p in ok if p.name in self._held_was - and float(p.soc) <= peakguard.pack_floor_pct(p, floor) + 1.0} - live = set(self.live_units()) - if not held or not any( - p.name not in held and inv.name in live - and not (inv.refused or 0) > 0 - for p, inv in zip(self.packs, self.inverters)): - self._held_was = frozenset() - else: - self._held_was = frozenset(held) - return self._held_was - - def _drain_rise(self, claims, maint_results) -> None: - """SAFETY-91, N>=2: while a battery is held back (`_held_back()`), a - draining battery's pin becomes a floor at its drain rate, so it rises - towards its rating before the held one gives. A site stop still - decides alone. DECISIONS/SAFETY-91-held-battery-last.md.""" - held = self._held_back() - if not held or any(c.kind == SET and c.actuator == ACTUATOR_SITE - and c.priority > P_PEAK for c in claims): - return - live = set(self.live_units()) - for inv, res in zip(self.inverters, maint_results): - u = self.actuator_of("maintenance", inv) - if res.phase != DRAIN or not res.owns_setpoint \ - or inv.name in held or u not in live: - continue - b = pre_resolve([c for c in claims if c.actuator == u]) - p = (None if b.contradiction or b.pinned_by != "maintenance" - else allocator.pin_w(b)) - if p is None or not p > 0.0: - continue - for i, c in enumerate(claims): - if c.source == "maintenance" and c.kind == SET \ - and c.actuator == u: - claims[i] = Claim.limit("maintenance", P_MAINTENANCE, - lo=p, reason=c.reason, - actuator=u) - - def _fill_peak_gaps(self, proj, now, reading): - """SAFETY-90: `proj` with a meter gap's uncounted seconds counted at - `peakguard.gap_w()` of the imports seen just before and just after it, - and those before this run's first reading likewise at the import seen - first (shown as not measured). - DECISIONS/SAFETY-90-peak-guard-after-a-gap.md.""" - self.peak_gap_s = self.peak_unmeasured_s = 0.0 - avg = self.p1.averager - since = avg.held_since - if proj is None or proj.block_start is None or since is None: - return proj - if self._unseen is None and self.p1.last is not None: - self._unseen = [proj.block_start, max(0.0, ( - since - proj.block_start).total_seconds() - avg.elapsed_s), - since, None] - seen = (None if self.grid is None or self.site_batt_w is None - else float(self.grid) + max(0.0, float(self.site_batt_w))) - if proj.block_start != self._gap_block: - self._gap_block, self._gap_w = proj.block_start, None - self._gap_filled_s = self._gap_held_ws = 0.0 - cap = float(self.o.get("peak_cap_w", 3500)) - ceiling = peakguard.quarter_ceiling_w(cap, reading)[0] - unseen_on = (self._unseen is not None - and self._unseen[0] == proj.block_start) - if unseen_on and self._unseen[3] is None and seen is not None: - # While the add-on was down the batteries were at 0 W, so the - # seconds before its first reading count like a gap, at the - # import seen first; a restored reading's held part is topped up. - self._unseen[3] = peakguard.gap_w(ceiling, seen) - if self._run_pre is not None: - s0, g0 = self._run_pre - h = (min(s0 + timedelta(seconds=avg.max_hold_s), - self._unseen[2]) - - max(s0, proj.block_start)).total_seconds() - self._unseen_held_ws = max(0.0, h) * max( - 0.0, self._unseen[3] - max(0.0, g0)) - kw = dict(tail_s=(now - since).total_seconds(), - max_hold_s=avg.max_hold_s, - unseen_s=self._unseen[1] if unseen_on else 0.0, - unseen_w=(self._unseen[3] if unseen_on - and self._unseen[3] is not None else ceiling)) - _p, gap_s, _u = peakguard.fill_gaps(proj, gap_w=0.0, **kw) - if gap_s > self._gap_filled_s + peakguard.GAP_TOL_S: - self._gap_w = peakguard.gap_w(ceiling, self._gap_w, - self._gap_seen_w, seen) - if self._gap_pre is not None: - # The averager credited the gap's first max_hold_s at the - # reading before it; top that part up to gap_w as well. - s0, g0 = self._gap_pre - h = (min(s0 + timedelta(seconds=avg.max_hold_s), since) - - max(s0, proj.block_start)).total_seconds() - self._gap_held_ws += max(0.0, h) * max( - 0.0, self._gap_w - max(0.0, g0)) - self.log_event(f"PEAK_GUARD_GAP: the meter missed {gap_s:.0f} s " - f"of this 15-minute period, counted at " - f"{self._gap_w:.0f} W", - hint=messages.hint("peak_gap")) - self._gap_filled_s = max(self._gap_filled_s, gap_s) - if seen is not None: - self._gap_seen_w = seen - if self.grid is not None: - self._gap_pre = (since, float(self.grid)) - out, self.peak_gap_s, self.peak_unmeasured_s = peakguard.fill_gaps( - proj, gap_w=self._gap_w if self._gap_w is not None else ceiling, - held_ws=self._gap_held_ws + (self._unseen_held_ws if unseen_on - else 0.0), **kw) - return out - - def _peak_over_drain(self, claims, maint_results) -> None: - """SAFETY-83: at N=1 a peak floor above the drain rate outranks it. - - The drain is the site SET at P_MAINTENANCE, above the peak floor - (P_PEAK), so the floor did not bind and the house imported what the - drain left. Where the floor asks for more than the drain rate, it is - refiled at P_MAINTENANCE and wins; nothing else changes. Safety claims - (P_SAFETY) still outrank it. At N>=2 the `drain` floor does this, and - `_drain_over_reserve()` when a battery is held at its reserve. - """ - if len(self.inverters) != 1: - self._drain_over_reserve(claims, maint_results) - return - res = maint_results[0] - if res.phase != DRAIN or not res.owns_setpoint: - return - rate = float(res.setpoint_w or 0.0) - for i, c in enumerate(claims): - if c.source == peakguard.SOURCE and c.lo > rate: - claims[i] = dataclasses.replace(c, priority=P_MAINTENANCE) - - def _held_pin(self, claims, u): - """SAFETY-87: what held unit `u` places anyway (its own pin), or None - when that pin charges, so the site is never split both ways.""" - b = pre_resolve([c for c in claims if c.actuator == u]) - p = None if b.contradiction else allocator.pin_w(b) - return None if p is not None and p < 0.0 else max(p or 0.0, 0.0) - - def _drain_over_reserve(self, claims, maint_results) -> None: - """SAFETY-87, N>=2: while a battery is held at its peak reserve, a - draining battery that may still give is raised from its drain rate - towards its rating for the peak floor, after the others. Otherwise - the floor's rest lands on the held battery (its weight 0 only orders - the split; the drain pin binds). A site stop still decides alone.""" - reserve = self._peak_reserve() - floor = max((c.lo for c in claims if c.source == peakguard.SOURCE), - default=0.0) - if not reserve or not floor > 0.0 or any( - c.kind == SET and c.actuator == ACTUATOR_SITE - and c.priority > P_PEAK for c in claims): - return - live = set(self.live_units()) - drains, others = [], 0.0 - for inv, res in zip(self.inverters, maint_results): - u = self.actuator_of("maintenance", inv) - if u not in live: - continue - if inv.name in reserve: - p = self._held_pin(claims, u) - if p is None: - return - others += p - continue - b = pre_resolve([c for c in claims if c.actuator == u]) - if b.contradiction: - continue - p = allocator.pin_w(b) - if p is not None and p < 0.0: - return # a pack pinned to charge: never split both ways - if res.phase == DRAIN and b.pinned_by == "maintenance" \ - and p is not None and p > 0.0: - drains.append((u, p, allocator.hi_w(b))) - others += allocator.hi_w(b) if p is None else p - give = floor - others - for u, p, hi in drains: - if give <= 0.0: - break - up = max(p, min(hi, p + give)) - give -= up - p - for i, c in enumerate(claims): - if c.source == "maintenance" and c.kind == SET \ - and c.actuator == u: - claims[i] = dataclasses.replace(c, value=up) - - def _peak_over_hold(self, claims, maint_results): - """SAFETY-86: a peak floor outranks a maintenance HOLD (0 W). - - At N=1 the floor is refiled at P_MAINTENANCE, as for a drain. At N>=2 - the holding pack gives only what the others cannot: its pin is raised - to the floor minus what they may place, and the floor is returned as - the site `hold` ceiling (else None). A site stop still decides alone. - DECISIONS/SAFETY-86-peak-over-hold.md. - """ - hold = {self.actuator_of("maintenance", inv) - for inv, res in zip(self.inverters, maint_results) - if res.phase == HOLD and res.owns_setpoint} - peak = [i for i, c in enumerate(claims) - if c.source == peakguard.SOURCE and c.lo > 0.0] - if not hold or not peak: - return - if len(self.inverters) == 1: - for i in peak: - claims[i] = dataclasses.replace(claims[i], - priority=P_MAINTENANCE) - return - if any(c.kind == SET and c.actuator == ACTUATOR_SITE - and c.priority > P_PEAK for c in claims): - return - live = set(self.live_units()) - reserve = self._peak_reserve() # SAFETY-87: they give nothing - others = 0.0 - for inv in self.inverters: - u = self.actuator_of("maintenance", inv) - if u in hold or u not in live: - continue - if inv.name in reserve: # only its own pin, never both ways - p = self._held_pin(claims, u) - if p is None: - return - others += p - continue - b = pre_resolve([c for c in claims if c.actuator == u]) - if b.contradiction: - continue - p = allocator.pin_w(b) - if p is not None and p < 0.0: - return # a pack pinned to charge: never split both ways - others += allocator.hi_w(b) if p is None else p - floor = max(claims[i].lo for i in peak) - give = floor - others - if give <= 0.0: - return - for i, c in enumerate(claims): - if c.source == "maintenance" and c.kind == SET \ - and c.actuator in hold: - claims[i] = dataclasses.replace(c, value=give) - return floor - - def _charge_headroom(self, floor: float, claims) -> float: - """SAFETY-84: a cheap-window charge pulls no more than the quarter's - room under the peak aim (`charge_room_w()`), so it yields just enough - to the peak guard; at N>=2 nothing under a site stop (its 0 W would - need the other pack to give). SAFETY-125: at N=1 too, owner - 2026-10-29; the stop rule stays N>=2 only.""" - if len(self.inverters) > 1 and any( - c.kind == SET and c.actuator == ACTUATOR_SITE - and c.priority > P_MAINT_SHAPE for c in claims): - return 0.0 - room = peakguard.charge_room_w(self.peak_guard, self._peak_proj) - floor = floor if room is None else min(floor, room) - self.room_charge = self.room_charge or floor > 0.0 - return floor - - def _charge_ceiling(self, claims): - """SAFETY-84: the site `hi` for a cheap-window charge at N>=2, or None. - - The charging pack's own `hi` (P_MAINT_SHAPE) makes it charge; above - that the other pack would have to give (opposite directions, refused, - 0 W). So the site target stays at or below it. Not filed at N=1, nor - when the pack's own limits cancel the charge (a refusal, a stale link). - DECISIONS/SAFETY-84-charge-at-two.md. - """ - if len(self.inverters) < 2: - return None - live = set(self.live_units()) - ceiling = 0.0 - for inv in self.inverters: - u = self.actuator_of("maintenance", inv) - b = pre_resolve([c for c in claims if c.actuator == u]) - if u in live and not b.contradiction and b.hi < 0.0: - ceiling += allocator.hi_w(b) - return ceiling if ceiling < 0.0 else None - - def _maint_stop_off(self, machine, now) -> None: - """OPT-11: stop this battery's maintenance cycle because it is off.""" - if machine.phase == IDLE: - return - for msg in machine.abort(now, "battery switched off"): - self.log_event(msg, hint=messages.hint("maint_off", - unit=machine.name)) - - @property - def why_words(self) -> str: - """The page's "Why" line. While control waits for a missing reading - the age is counted when the page asks (UX-10), not frozen at the age - the last cycle saw.""" - if self._why_waiting_since is not None: - return messages.why_waiting(max(0.0, ( - datetime.now(timezone.utc) - - self._why_waiting_since).total_seconds())) - return self._why_words - - @why_words.setter - def why_words(self, text: str) -> None: - self._why_words = text - self._why_waiting_since = None - - @property - def inputs_ok(self) -> bool: - """The site meter, and EVERY pack's own two readings. - - ⚠️ EVERY pack, not the live ones: a unit whose SoC did not answer is a - unit nothing can grade the maintenance FSM or the pack floor against, and - §11.1 rule 1 for a missing input is command zero and keep commanding. - Dropping it from the SPLIT instead would hand its share to a sibling - while the site went on regulating - see `Inverter.is_live()` on why - liveness is about the WRITE path and this is not. - """ - if self.grid is None or not self.inverters: - return False - return all(inv.soc is not None and inv.batt is not None - for inv in self.inverters) - - def missing_reading(self) -> str: - """UX-11: the first reading `inputs_ok` finds missing, in words.""" - if self.grid is None or not self.inverters: - return "meter" - for inv in self.inverters: - of = "" if len(self.inverters) == 1 else f" from {inv.name}" - if inv.batt is None: - return f"battery power{of}" - if inv.soc is None: - return f"battery level{of}" - return "input" - - # -- io ------------------------------------------------------------------ - @property - def pv_roster(self) -> tuple: - """Every configured PV production entity, or `()`. TEL-11/TEL-12. - - ⚠️ ONE READING OF THE OPTIONS, and it is `pv.entities()` - the SAME call - `mqtt.optional_keys()` makes. The thing that decides whether the row is - ANNOUNCED, the thing that decides whether it is READ and the thing that - decides WHAT IS SUMMED have to be one predicate, or the add-on ends up - with an entity nothing feeds, a topic nothing declared, or a total taken - over a different list from the announced one. `announced_units()` in - mqtt.py is the same argument for the inverter roster, in its own words. - - ⚠️ IT REPLACED A `pv_entity` PROPERTY RATHER THAN JOINING ONE. Two - properties where one is a subset of the other is the second spelling - arriving by the back door; every gate in this file reads this one. - """ - return pv_read.entities(self.o) - - async def _read_pv(self) -> None: - """This cycle's SITE PV production, or an ABSENCE with a reason. - - TEL-11 for one entity, TEL-12 for a roster of them. `pv.total()` is where - "one of three is absent" becomes an absence of the SITE figure rather - than the sum of the two that answered, and its docstring is the argument. - - ⚠️ IT ASSIGNS ON EVERY CALL, INCLUDING THE FAILING ONES. Leaving the - last good number standing through an outage is what `circulation` does - on purpose - there, a stale figure beats a zero that reads as health - - and it is exactly wrong here: this row is read back as HISTORY, and a - value that persists through an outage is indistinguishable from a real - one at the moment somebody is trying to work out whether the sun was - shining. - - ⚠️ `hass.state()` RATHER THAN `hass.number()`, because the UNIT is half - the reading. See `pv.watts()`: a PV integration may publish kW, and - there is no magnitude heuristic that can separate 30 W of dusk from - 30 kW of noon. - """ - # ⚠️ TEL-12: EVERY ENTITY IN ONE GATHER, for the reason the outer - # gather exists (see `read_inputs()`). Read serially, a three-inverter - # roster with one slow sensor would add up to three of `hass.state()`'s - # 10 s timeouts to a cycle that feeds the ESP32 heartbeat - i.e. the - # telemetry channel would be able to push a healthy battery towards - # layer 1's veto, which is exactly the foot in the control path this - # card is not allowed to have. Gathered, N entities cost what one does. - roster = self.pv_roster - states = await asyncio.gather( - *(self.hass.state(entity) for entity in roster)) - self.pv_w, self.pv_why, self.pv_parts = pv_read.total( - list(zip(roster, states)), pv_read.inverted(self.o)) - # UX-54: kept for the Forecast tab only. It must never cost a cycle. - try: - self.solar_today.add(datetime.now(timezone.utc), self.pv_w) - except Exception: # noqa: BLE001 - _LOG.debug("measured solar not kept", exc_info=True) - - def _peak_fc_unit_log(self, fault) -> None: - """SAFETY-118. One WARNING when the peak forecast's unit cannot be read - in watts, and again only if the unit changes; the unit is on DEBUG.""" - if fault == self._peak_fc_fault: - return - self._peak_fc_fault = fault - if fault is None: - _LOG.info("The 15-minute demand forecast is used again.") - elif fault == "": - _LOG.warning("The 15-minute demand forecast has no unit, so it " - "is not used.") - else: - _LOG.warning("The 15-minute demand forecast is not in a power " - "unit, so it is not used.") - _LOG.debug("The 15-minute demand forecast reads in %r.", fault) - - async def _read_forecast(self) -> None: - """OPT-11 P4: the solar forecast sensors (`solarfc.read()`). A - failed or stale read is no forecast, never a zero.""" - # OPT-17: every member of both days in one gather. - ents = self.fc_entities + self.fc_tomorrow_entities - states = await asyncio.gather(*(self.hass.state(e) for e in ents)) - n = len(self.fc_entities) - now = datetime.now(timezone.utc) - fc, why, gaps = solarfc.read_sum( - list(zip(self.fc_entities, states[:n])), - list(zip(self.fc_tomorrow_entities, states[n:])), now, - hold=self.fc_hold) - if self.fc_hold.changed: - self.fc_hold.changed = False - self.store.set(FC_HOLD_KEY, self.fc_hold.dump()) - # A member is named only in a sum of several; one entity reads as - # before. Logged once per episode: on a change, never every read. - gaps = tuple(g for g in gaps if len( - self.fc_entities if g[0] == "today" - else self.fc_tomorrow_entities) > 1) - was_kept = bool(self.solar_fc is not None and self.solar_fc.kept) - if (fc is None) != (self.solar_fc is None) \ - or why != self.solar_fc_why or gaps != self.solar_fc_gaps \ - or bool(fc is not None and fc.kept) != was_kept: - self.log_event( - "solar forecast: " + ( - "none (" + str(why) + ")" if fc is None else - f"read, kept from {brussels(fc.at):%H:%M}" if fc.kept - else "read") - + "".join(f", {d} {e} not usable ({w})" - for d, _i, e, w in gaps), - hint=messages.hint( - "forecast_none" if fc is None else - "forecast_no_tomorrow" if gaps else "forecast_read")) - self.solar_fc, self.solar_fc_why = fc, why - self.solar_fc_gaps = gaps - - async def read_inputs(self, now_mono: float | None = None) -> None: - """Every input this cycle needs, and SAFETY-37's freshness verdict. - - `now_mono` the monotonic clock the per-unit freshness records are - stamped on. Defaulted rather than read inside `_read_unit()` - so that ONE instant covers every unit in a gather - two - units stamped from two clock reads would carry a freshness - skew nobody could reproduce - and so that a check can drive - real seconds through the gate without sleeping through them. - """ - o = self.o - now_mono = freshness.monotonic() if now_mono is None else float(now_mono) - self._now_mono = now_mono - if self.p1_enabled: - # ⚠️ P1 is the only authoritative measurement of what the utility - # sees (§5.1). When it is stale this is None, which falls into the - # existing "inputs missing -> command 0 W" path below. There is - # deliberately NO fallback to an inverter-side figure: the - # inverter's own AC power correlates 0.998 with battery power and - # 0.09 with the real meter, so a controller that failed over to it - # would be regulating against its own output. - self.grid = self.p1.net_w - else: - self.grid = await self.hass.number(o.get("meter_entity", ""), - bool(o.get("meter_invert"))) - # --- DEV-02: EACH INVERTER'S OWN TWO READINGS, FROM ITS OWN ENTITIES -- - # ⚠️ CONCURRENTLY ACROSS UNITS, SEQUENTIALLY WITHIN ONE. Read serially, - # a unit whose Home Assistant entity is slow delays every unit after it - # on the path that feeds the ESP32 heartbeat - the same defect AC 6 - # names for the WRITE path, one function up. Within a unit the order is - # unchanged (SoC, then battery power), so at the shipped roster of one - # this is the same two calls in the same order. - # - # --- TEL-11: AND THE PV READ RIDES IN THIS SAME GATHER --------------- - # ⚠️ IN THE GATHER RATHER THAN ON A LINE OF ITS OWN, AND THAT IS THE - # WHOLE "OBSERVABILITY MUST NOT BE ABLE TO DELAY CONTROL" DECISION. - # This coroutine feeds the ESP32 heartbeat; a sequential read would add - # its own worst case - `hass.state()`'s 10 s timeout - to every cycle, - # so a hung PV sensor at a client site would push a healthy battery - # towards layer 1's ~30 s veto for the sake of a telemetry row. - # Gathered, its latency OVERLAPS reads that already happen and the - # added worst case is zero. `peak_forecast_entity` below is read - # serially and stays that way because it is a CONTROL input (the - # capacity guard sizes off it), so the site is entitled to wait for it. - # - # ⚠️ AND AN EMPTY PV ROSTER APPENDS NOTHING. Not a coroutine, not an - # HTTP call, not a log line: at the shipped default this gather is the - # same list of the same coroutines it has always been. - _reads = [self._read_unit(inv, now_mono) for inv in self.inverters] - if self.pv_roster: - _reads.append(self._read_pv()) - # OPT-11 P4: the solar forecast, in the same gather (a slow sensor - # must not delay control), at most once per FORECAST_READ_S. - if self.fc_entity is not None and ( - self._fc_read_mono is None - or now_mono - self._fc_read_mono >= FORECAST_READ_S - or now_mono < self._fc_read_mono): - self._fc_read_mono = now_mono - _reads.append(self._read_forecast()) - await asyncio.gather(*_reads) - if o.get("peak_forecast_entity"): - # SAFETY-118: read in its own unit, like the PV path. One state - # read, as `hass.number()` made. No unit or a unit that is not - # power: not used, as if the option were empty. - st = await self.hass.state(o["peak_forecast_entity"]) - self.peak_fc, _why = pv_read.watts(st) - # A missing reading leaves the unit-fault state as it was. - if pv_read.has_reading(st): - self._peak_fc_unit_log(pv_read.unit_fault(st)) - else: - self.peak_fc = None - self._peak_fc_fault = None - - now_e, avg_e = o.get("price_now_entity"), o.get("price_avg_entity") - if now_e and avg_e: - now_p = await self.hass.number(now_e) - avg_p = await self.hass.number(avg_e) - self.cheap = (now_p is not None and avg_p is not None and now_p <= avg_p) - self._price_gated = True - self.tariff_words = "Prices from Home Assistant entities" - elif uses_chain(o): - # PRICE-01. A provider with fallbacks gives the maintenance gate - # its own prices: the current 15-minute price against today's - # average, as the Home Assistant pair did. Still no I/O here - the - # series is the one the background refresh stored. - self._provider_gate(datetime.now(timezone.utc)) - else: - # TARIFF-03. §9.2 makes a static day/night tariff a first-class - # product, and its required EMS handling is TIME-WINDOW SHIFTING. - # The add-on has exactly one shiftable load in 0.5.x - the - # maintenance cycle's cheap-window grid top-up, ~15 lines below in - # cycle() - so this is where the window reaches something that moves - # energy. With `static_profile` empty this returns False and the - # behaviour is bit-for-bit what it has always been: "fixed-tariff - # site, never force a paid grid top-up, wait for sun". - # - # ⚠️ SYNCHRONOUS AND I/O-FREE, ON PURPOSE. The provider-backed - # resolver (static_tariff.resolve_tariff) can perform an HTTP fetch, - # and this coroutine is on the path that feeds the ESP32 heartbeat - - # a supplier's TLS timeout here would be a supplier able to push the - # add-on towards layer 1's 30 s veto. Generation from a static - # profile is pure arithmetic, so §2.3's "regenerate on the tick" - # applies and there is nothing to block on. Putting a fetched series - # on this path needs a BACKGROUND refresh and belongs with OPT-04. - # - # ⚠️ AND IT CANNOT BE BOTH. validate.py refuses static_profile - # alongside the two Home Assistant entities, because this `if` picks - # one and the loser is silent. - _now = datetime.now(timezone.utc) - self.cheap, self.tariff_words = static_status(o, _now) - self._price_gated = self._static_gated(o, _now) - - # ⚠️ TARIFF-11. THE PROVIDER PLAN REACHES THE *Tariff* ROW HERE, AND - # THIS IS THE ONLY PLACE THE TWO SOURCES MEET. Everything above is the - # 30 s I/O-free tick; `fresh_tariff_plan()` is an attribute read and an - # age comparison against TARIFF_MAX_AGE_S - still no fetch on this path, - # which is the rule the whole branch above exists to keep. What the row - # gains is the plan's SHAPE (origin, product, horizon, the firm/carried - # split, the spacing) and what it must never gain is the suggestion - # that the two halves were computed at the same instant, so the plan - # half carries its own age in seconds. See `tariff_plan_row()`. - _tick = datetime.now(timezone.utc) - _standing = self.fresh_tariff_plan(_tick) - self.tariff_words = tariff_plan_row( - _standing, self.tariff_words, - age_s=(None if _standing is None - else (_tick - self.tariff_at).total_seconds()), - horizon_h=float(price_option(o, "price_horizon_h")), - provider=provider_configured(o), max_age_s=TARIFF_MAX_AGE_S) - - # UX-11: the red meter row says "the add-on log shows why", so a meter - # that goes quiet gets one WARNING per episode, not one per cycle. It - # is a log line only: no notification, and nothing it decides. - # A flapping meter logs at most one WARNING per METER_QUIET_REPEAT_S, - # and the episodes in between go to DEBUG. - if self.p1_enabled: - if (self.p1.stale and not self._meter_quiet_logged - and self.p1.published_age_s > self.p1.max_age_s): - self._meter_quiet_logged = True - now = _mono() - self._meter_quiet_loud = ( - self._meter_quiet_warned is None - or now - self._meter_quiet_warned >= METER_QUIET_REPEAT_S) - if self._meter_quiet_loud: - self._meter_quiet_warned = now - _LOG.warning("No meter reading for over %s, so control " - "waits and then sets the battery to 0 W.", - messages.seconds(self.p1.max_age_s)) - else: - _LOG.debug("No meter reading for over %s again.", - messages.seconds(self.p1.max_age_s)) - elif not self.p1.stale and self._meter_quiet_logged: - self._meter_quiet_logged = False - if self._meter_quiet_loud: - _LOG.info("Meter readings are back.") - else: - _LOG.debug("Meter readings are back.") - - self.answer.watch(now_mono, [(inv.name, inv.standing_w(), inv.batt) - for inv in self.inverters], # SAFETY-128 - sum(inv.standing_w() for inv in self.inverters), - self.grid) - if self.inputs_ok: - if self.inputs_bad_since is not None: - self.log_event("inputs recovered", - hint=messages.hint("inputs_back")) - self.inputs_bad_since = None - elif self.inputs_bad_since is None: - self.inputs_bad_since = datetime.now(timezone.utc) - - def _driver(self, inv): - """`inv`'s driver, wired to this Controller's Home Assistant on first use. - - SMA-2. Bound HERE rather than when the roster is built, so a unit added - to `self.inverters` afterwards is wired too, and the driver follows - whatever `self.hass` is at the time (a check may swap it). - """ - drv = inv.driver - if not drv.bound(): - drv.bind_getter(lambda: self.hass) - return drv - - async def _read_unit(self, inv, now_mono: float) -> None: - """One inverter's own SoC and battery power, from ITS OWN entities. - - ⚠️ SAFETY-37: THE POWER READING GOES THROUGH THE FRESHNESS GATE AND THE - SoC READING DOES NOT, AND THE ASYMMETRY IS DELIBERATE. `batt` feeds the - two consumers this card is about - SAFETY-30's per-unit sign check and - SAFETY-31's circulating-power sensor - and its obligation term is - command travel, which this method already has. SoC's obligation term is - ENERGY through the pack and the constant it needs has never been - measured on this site; wiring it here with a guessed constant would be a - gate that fires on a rested pack, which is TEL-08's whole hazard. - `freshness.BOUNDS["soc"]` states the bound and what TEL-08 owes. - - ⚠️ THE STANDING COMMAND IS ASKED OF THE UNIT, NOT RECOMPUTED. `cycle()` - grades the sign watchdog against `inv.standing_w()` and this gate arms - off the same method, because the gate exists to protect that check and a - second spelling of "what is standing" would let the two disagree about - the number they are both reasoning about. - """ - # SMA-2. The driver reads, in the order this method always did: SoC, - # then power. `extra` is whatever else the driver learned; nothing - # consumes it yet. - inv.soc, raw, _extra = await self._driver(inv).read() - was_stale = inv.batt_fresh.stale - was_releases = inv.batt_fresh.releases - inv.batt_fresh.submit(raw, inv.standing_w(), now_mono) - # ⚠️ `inv.batt` IS THE GATED VALUE. A stale register is a MISSING input, - # not a measurement - `inputs_ok` sees the None, the site holds for - # `stale_input_s` and then commands 0 W and keeps commanding, which is - # §11.1 rule 1 and is already what a missing reading does here. - inv.batt = inv.batt_fresh.reading() - # SAFETY-97: learn this unit's idle reading, only while control runs - # and nothing says the unit is refusing, stale or faulty. - if inv.idle.observe( - inv.batt, inv.standing_w(), now_mono, - bool(self.auto) and inv.batt is not None - and not inv.batt_fresh.stale and not inv.refused - and not self.batt_refused and not inv.sign_wd.tripped): - inv.store_set("idle_w", round(inv.idle.value, 1)) - if inv.batt_fresh.stale and not was_stale: - self.log_event(f"STALE {inv.name}: " + inv.batt_fresh.reason, - hint=messages.hint("battery_stuck", unit=inv.name)) - self._refusal_from_stale(inv, now_mono) - # ⚠️ SAFETY-57 REWROTE THE LAST SENTENCE OF THIS LINE AND NOTHING - # ELSE IN IT. The escape clause used to read "It clears itself the - # moment the register reports a different value", full stop - and - # that was FALSE for the state this same line announces, because the - # 0 W it announces in the sentence before is exactly what stops the - # register ever being asked to report anything different. The live - # site sat in it for 790 s on 2026-09-21 and was freed by a human. - # ⚠️ SAFETY-56 REWROTE THE DIAGNOSIS HALF, WHICH SAFETY-57 LEFT - # STANDING ON PURPOSE. It used to open "battery-power register is - # not following its own command" - an accusation against a named - # piece of hardware, and FALSE on the very episode above. The - # pack read 11 % for the whole hold, every command in it was a - # DISCHARGE, and the register answered the first CHARGE command - # three seconds later - so the BMS was refusing, the register was - # publishing that refusal correctly, and the operator was sent to - # look at a working sensor. All three numbers are measured off the - # committed capture by test_freshness.py part 11a. The gate's - # conjunction is right and is NOT touched; only its conclusion was. - # - # ⚠️ AND THE TWO EXPLANATIONS ARE NAMED ONCE, IN `%s`, NOT TWICE. - # This line's own words are the OBSERVATION plus the one thing a - # log reader has to be told before acting - that the observation is - # not yet a verdict - and `freshness._grade()`'s sentence, which - # this line already interpolates, is where the pair is spelled out. - # Saying it in both halves of one sentence is how an operator - # learns to skim it. - # UX-08 2d: plain, with SAFETY-57's escape clause kept as an - # ordered pair (time, then power), and the reason still in `%s`. - # UX-11: one sentence and the code. The reason, with SAFETY-56's - # two explanations and its figures, and the limits are on the - # DEBUG lines below and in the action log. - _LOG.error("%s: battery power reading stopped changing, set to " - "0 W until it changes, or %.0f s after the command " - "drops below %.0f W: %s.", - inv.name, inv.batt_fresh.bound.release_s, - inv.batt_fresh.bound.move_w, - messages.reason_code(inv.batt_fresh.reason)) - _LOG.debug("Evidence for %s: %s.", inv.name, inv.batt_fresh.reason) - _LOG.debug("%s: the limits are unchanged for %.0f s while asked " - "to move: a command over %.0f W that moved over %.0f W.", - inv.name, - inv.batt_fresh.bound.unchanged_s, - inv.batt_fresh.bound.move_w, - inv.batt_fresh.bound.move_w) - elif inv.batt_fresh.releases > was_releases: - # ⚠️ SAFETY-57. REPORTED, NEVER SILENT. A latch that lets go on a - # timer and says nothing is a latch no operator can audit - and this - # one is withdrawing a SITE STOP. `release_note()` is written to say - # that nothing has been learned about the register, because nothing - # has. - self.log_event(f"STALE WITHDRAWN {inv.name}", - hint=messages.hint("battery_back", unit=inv.name)) - # Not "recovered": nothing is known about the reading yet, so the - # line gives the value it still holds and the window it is - # rechecked over (SAFETY-57). - _LOG.warning("%s: the command stayed below %.0f W for %.0f s, so " - "battery power reading %+.0f W is used again and " - "rechecked over %.0f s.", inv.name, - inv.batt_fresh.bound.move_w, - inv.batt_fresh.bound.release_s, inv.batt_fresh.held, - inv.batt_fresh.bound.unchanged_s) - _LOG.debug("SAFETY-57: %s", inv.batt_fresh.release_note(inv.name)) - - @property - def shadow(self) -> bool: - """SAFETY-10. Is the battery being left alone right now? - - ⚠️ A PROPERTY, NOT A FIELD, AND FOR THE REASON `self.units` IS ONE. - Three surfaces ask this question at three different moments - the - cycle, the write, and the status page rendered between two cycles - and - a cached flag is a fourth answer that can disagree with the option and - the button it is derived from. Derived, they cannot. - - ⚠️ AND THE WRITE GATE ASKS THIS, NOT A PARAMETER PASSED DOWN TO IT. A - suppression that had to be threaded through `write_setpoint()` would be - absent from every call site that forgot it - the heartbeat, the stop - button, `shutdown()` - which is exactly the shape of hole this add-on's - single choke point exists to close. - """ - return shadow.engaged(self.o, control_started=self.auto) - - def shadow_latches(self) -> tuple: - """The failsafe latches that are UP, named, for the shadow banner. - - A latch that is standing while the controller is inert is standing when - it stops being inert. `shadow.banner()` carries them so an operator who - turns shadow mode off is not handed a battery that will not move and a - page that never mentioned why. - """ - out = [] - if self.circ_wd.tripped: - out.append("circulating power") - if self.site_sign_wd.tripped and len(self.inverters) > 1: - out.append("site sign watchdog") - for inv in self.inverters: - if inv.sign_wd.tripped: - out.append(f"{inv.name} sign watchdog") - return tuple(out) - - def write_refusal(self, value: float, inv=None) -> str | None: - """Why `value` may NOT be written to `inv` right now, or None if it may. - - --- SAFETY-28: THE WRITE PATH IS GATED ON THE ALLOCATION RECORD -------- - specs §1.5 makes "any configuration in which two writers can reach one - actuator" a non-goal. Until this method that non-goal was enforced by - `len(validate.ACTUATOR_WRITE_KEYS) == 1` - there is one option key, so a - second writer is not expressible. True, and a statement about the SHAPE - OF THE OPTIONS SCHEMA rather than about the writes. Add CFG-04's - per-inverter config and there are two real writers with that length - still 1: the check stays green while the property it protects is gone. - That is this repository's named failure mode - a check that observes - something other than what it claims to observe - so the enforcement - moved here, onto the writes themselves. - - The rule is: A NUMBER REACHES THE WIRE ONLY IF THE SINGLE ALLOCATOR - PLACED IT, ON THIS TICK, FOR THIS UNIT. A second writer with arithmetic - of its own cannot satisfy that - its number is not in any record - so it - has to file a Claim and go through `resolve()`, which is the one - allocator. "Exactly one allocator per shared resource" stops being a - convention somebody can forget and becomes a thing the write path - checks. `Allocation.authorises()` holds the per-record half of the - argument. - - ⚠️ 0 W IS ALWAYS AUTHORISED, AND THAT IS THE ANSWER TO "WHAT IF THE - ALLOCATOR IS THE THING THAT FAILED". This is not a convenience exit; it - is the one value whose correctness does not depend on a split existing: - - * The hazard the non-goal names is N-times loop gain from BROADCAST - - handing every inverter the same target so each supplies it in full - (see allocator.py's opening argument, and TEST-19's measured - `N=2 gain 1.0` limit cycle). At S = 0 the broadcast and the correct - allocation COINCIDE: a_i = 1 for every unit gives every unit 0 W, - and 0 W is exactly its share. There is no over-command to make. - * It is the fail-toward-inaction direction §11.1 rule 1 already - names, and it is what layer 2 commands. `cycle()`'s two refusal - branches replace the resolution with a 0 W failsafe and then write - it through here like any other cycle; `shutdown()` and the - operator's stop button do the same. Every one of those runs while - the allocator has REFUSED - `Allocation.ok` is False and there are - no shares - so a gate that asked the allocator's permission to - command zero would deadlock the failsafe behind the very component - whose failure the failsafe exists to answer. - - A gate that can block the safety write is worse than the hole it closes, - so it cannot block it: the test for zero is first and reads nothing. - - ⚠️ AND IT IS `value == 0.0`, THE REQUESTED NUMBER - not a `failsafe=True` - argument. A flag is an assertion by the caller, which is precisely what - a second writer would pass; the value is a fact about what is going to - be written. -0.0 == 0.0 in Python, and a nan never reaches here (the - caller has already turned it into 0.0), so the predicate is total. - - ⚠️ DEV-02: THE UNIT IS AN ARGUMENT, NOT THE CONTROLLER'S N=1 VIEW OF - IT. The record holds one share PER UNIT, so "did the allocator place - this number" is a question about a NAMED actuator. Asking it with the - first inverter's name at a roster of two would authorise A's share on - B's wire and refuse B's own - the site/unit confusion this card - removes, wearing the gate's name. `_write_unit()` always passes the - unit it is about; the default is for the N=1 callers and REFUSES at - N>=2 (see `_only()`) rather than answering for the first inverter. - """ - if value == 0.0: - return None - inv = self._only() if inv is None else inv - rec = self.allocation - if rec is None: - return ("no allocation record exists yet - nothing has authorised " - f"{value:+.0f} W on {inv.name}") - return rec.authorises(inv.name, value, self.alloc_tick) - - async def write_setpoint(self, value: float, *, force: bool = False, - unit=None, last: bool = False) -> None: - """Put `value` on ONE inverter, or - with `unit=None` - on all of them. - - ⚠️ `unit=None` IS FOR A NUMBER THAT IS NOT A SHARE. The stop button, - `shutdown()` and `maint_abort()` all command 0 W to the whole site, and - 0 W is the one value that means the same thing to every inverter. A - NON-ZERO value broadcast to a roster of two IS the ARCH-01 fault - each - unit supplies it in full and the loop gain at the meter becomes N times - the per-unit gain - so it is refused below rather than trusted to the - caller. The cycle writes SHARES, one unit at a time, through the - allocator. - - ⚠️ AND THE WRITES ARE CONCURRENT, EACH UNDER ITS OWN BUDGET. See - WRITE_BUDGET_S: one hung `hass.call()` on a serialised path used to eat - a sibling's layer-1 refresh window. - """ - if unit is None: - targets = [i for i in self.inverters] - if len(targets) > 1 and is_commandable(value) and float(value) != 0.0: - # Loud, and it commands zero rather than the value asked for - - # fail toward inaction, exactly as every other refusal here. - self.log_event( - f"refusing to broadcast {float(value):+.0f} W to " - f"{len(targets)} inverters - that is the ARCH-01 fault; " - f"commanding 0 W", hint=messages.hint("all_blocked")) - _LOG.error("Refused to send %+.0f W to all %s at once, so " - "every inverter is set to 0 W. This is a software " - "fault.", float(value), - messages.count(len(targets), "inverter")) - _LOG.debug("ARCH-01: a site target handed to each unit is " - "supplied by each of them, so the gain at the meter " - "becomes N times the per-unit gain. Only 0 W may be " - "written site-wide, and shares come from the " - "allocator.") - value = 0.0 - else: - targets = [unit] - if not targets: - return - await asyncio.gather(*(self._write_unit(inv, value, force=force, - last=last) - for inv in targets)) - - async def _await_inflight(self, inv, budget_s: float) -> None: - """Wait, at most `budget_s`, for the writes already on their way to - `inv` (SAFETY-137: every driver, GoodWe too). A write still running at - the bound is left alone, not cancelled: its own WRITE_BUDGET_S ends it.""" - pending = [t for t in inv.inflight if not t.done()] - if pending: - await asyncio.wait(pending, timeout=budget_s) - - async def _release_last(self, inv) -> bool: - """`release()`, after a write already on its way to `inv` has finished - (at most half the budget is spent waiting for it), so the release is the - LAST thing the unit hears and a late write cannot undo it.""" - await self._await_inflight(inv, SETTLE_BUDGET_S) - return await self._driver(inv).release() - - async def _hand_back(self, inv, *, force: bool = False) -> bool: - """SMA-10. Give ONE unit back: exactly one `release()`, then nothing. - - True when the unit is handed back (now, or already). Never raises: a - driver that raises or hangs is logged and the unit is tried again on the - next idle write, and it cannot stop a sibling being released or zeroed. - - ⚠️ `released` IS SET BEFORE THE FIRST AWAIT. A second caller (the - heartbeat while the Stop button is mid-release) then sees it and does - nothing, so a unit gets one `release()` and not two. If the release - did not take, the flag goes back down and the unit stays un-handed - until a later idle write tries again. - - ⚠️ IT IS NOT A WRITE: no `note_write`, no `last_write`, so a hand-back - cannot be read as a link that answered. `last_write` is cleared so the - first write after control starts again is always sent. - """ - if inv.released: - return True - if not inv.driver.configured(): - return False - # After a failure the next try waits one heartbeat, so a hung release - # costs a cycle its 4 s once per heartbeat, not on every cycle. The - # Stop button and shutdown (`force`) always try. - now_m = time.monotonic() - if not force and now_m < inv.release_retry_at: - return False - inv.released = True - why = "" - try: - ok = bool(await _bounded(self._release_last(inv), - RELEASE_BUDGET_S)) - except (asyncio.TimeoutError, TimeoutError): - ok, why = False, f"took over {RELEASE_BUDGET_S:.0f} s" - except Exception as err: # noqa: BLE001 - one unit never stops the rest - ok, why = False, f"{type(err).__name__}: {err}" - if ok: - inv.last_write = None - if inv.release_fails: - _LOG.info("Handing back %s worked again after %d failed " - "tries.", inv.name, inv.release_fails) - inv.release_fails = 0 - inv.release_retry_at = 0.0 - inv.release_zero_sent = False - self.log_event(f"{inv.name}: handed back", - hint=messages.hint("handed_back", unit=inv.name)) - return True - inv.released = False - inv.release_fails += 1 - inv.release_retry_at = now_m + float(self.o.get("heartbeat_s", 10)) - _LOG.debug("Handing back %s failed (try %d): %s", inv.name, - inv.release_fails, why) - if inv.release_fails == 1: # one line per failure streak - _LOG.error("Handing back %s failed, so it is sent 0 W once and " - "handing back is tried again.", inv.name) - self.log_event(f"{inv.name}: hand-back failed", - hint=messages.hint("hand_back_failed", unit=inv.name)) - if not inv.release_zero_sent: - # ⚠️ ONCE. The unit must not keep carrying its last command, but a - # 0 W re-sent on every try would reset the inverter's own fallback - # timer for ever. The driver says what the one write is. - inv.release_zero_sent = True - try: - if await _bounded(self._driver(inv).release_fallback(), - FALLBACK_BUDGET_S): - inv.last_write = 0.0 - except Exception as err: # noqa: BLE001 - _LOG.debug("The fallback write to %s failed: %r", inv.name, err) - return False - - async def _write_unit(self, inv, value: float, *, force: bool = False, - last: bool = False) -> None: - if not inv.driver.configured(): - return - # --- SMA-10: A UNIT THAT HANDS BACK IS NOT WRITTEN WHILE THE ADD-ON IS - # IDLE. Idle is: shutting down, control stopped, or shadow mode. The - # unit is released once and then nothing is written to it - not the - # heartbeat, not the cycle's "stopped" 0 W - so its own controller keeps - # it. This is the passive half; `command_site_release()` is the active - # one, for the moment the add-on goes away. - # - # ⚠️ A SAFETY STOP IS NOT IDLE. It happens while control runs (`auto`, - # not shadow), so it falls through to the 0 W write below: the add-on's - # own decision to hold 0 W is never turned into a hand-back. - # - # ⚠️ AND CONTROL STARTING AGAIN RE-ARMS THE UNIT: the flag drops and - # `last_write` is cleared, so the first write goes out whatever it is. - # `stopping` never re-arms: a shutdown in progress stays handed back. - if inv.driver.hands_back: - if self.stopping or self.shadow or not self.auto: - await self._hand_back(inv) - return - if inv.released or inv.release_fails or inv.release_zero_sent: - # Control has the unit again: forget the hand-back, and any - # failed streak with it, so the next Stop starts clean (its own - # one 0 W, its own error line and event). - inv.released = False - inv.last_write = None - inv.release_fails = 0 - inv.release_retry_at = 0.0 - inv.release_zero_sent = False - entity = inv.driver.actuator_id() # for the log line below - - # --- SAFETY-03: THE CLAMP, AND IT IS ON THE ONLY PATH TO THE WIRE ----- - # Every write in this add-on comes through here - the cycle, the - # heartbeat, the operator's stop button and shutdown() - so no optimizer, - # maintenance or manual path can route around it. That placement is the - # first acceptance criterion, and it is why the guard is not in - # control.py: a guard the control law owns is a guard every other claimer - # bypasses. - # - # ⚠️ A NON-FINITE VALUE IS LOSS OF INPUT, NOT AN OUT-OF-RANGE ONE. §11.1 - # rule 1: command zero and keep commanding. It must not reach the clamp - # arithmetic - see is_commandable() for what a nan does to it - and it - # must not be counted as a clamp engagement, or a transport bug lands in - # the winding-loop counter. - if not is_commandable(value): - self.log_event(f"non-finite setpoint {value!r} - commanding 0 W", - hint=messages.hint("bad_value")) - _LOG.error("refusing to write a non-finite setpoint %r - commanding " - "0 W and continuing to command. This is a bug upstream, " - "not a limit.", value) - value = 0.0 - - # --- SAFETY-28: AND IT IS REFUSED HERE, NOT LOGGED SOMEWHERE ---------- - # ⚠️ ABOVE THE CLAMP AND BELOW THE NON-FINITE COERCION, and both halves - # of that placement are decisions. - # - # Below the coercion, because a nan is loss of input rather than an - # unauthorised write: rule 1 has already turned it into 0 W, which this - # gate then authorises unconditionally, so a transport bug does not get - # a second, differently-worded refusal. - # - # Above the clamp, because the question is WHO CHOSE THIS NUMBER and the - # answer is only meaningful about the number that was asked for. The - # clamp then narrows what was authorised, always toward safety, and it - # stays the last thing between a bug and the hardware. Gating the - # CLAMPED value would be worse than useless: on every cycle the clamp - # engages, the emitted watts differ from the allocator's share by - # construction, so the gate would refuse exactly the cycles SAFETY-03 - # exists for. - # - # The refusal is a SUBSTITUTION, not a return: 0 W goes on the wire in - # place of the number nothing stands behind. Returning instead would - # leave the inverter latched on its last command with the ESP32's - # heartbeat still being fed - holding an unauthorised setpoint quietly, - # which is the outcome this gate exists to prevent. - # - # ⚠️ AND IT IS ASKED ABOUT `inv`, NOT ABOUT THE SITE. The record holds - # one share per unit, so the question "did the single allocator place - # this number" is only answerable about a named actuator; DEV-02 made - # this method per-unit, and passing the first inverter here would - # authorise A's share on B's wire. - refusal = self.write_refusal(value, inv) - if refusal is not None: - self.log_event( - f"{inv.name}: WRITE REFUSED {value:+.0f} W - commanding 0 W", - hint=messages.hint("write_blocked", unit=inv.name)) - _LOG.error("Refused to send %+.0f W to %s, so it is set to 0 W " - "instead, which is a software fault. The reason: %s.", - value, inv.name, refusal) - value = 0.0 - - # ⚠️ THIS UNIT'S OWN THREE NUMBERS. `inv.max_w` is the supervised cap on - # what may be written to THIS setpoint entity and `inv.dev_min/dev_max` - # are what THIS device reported about itself - which is the whole of "the - # clamp for B uses B's numbers". Read off `self.o` these were one - # inverter's rating applied to every inverter. - result = clamp_to_rating(value, inv.max_w, inv.dev_min, inv.dev_max) - inv.clamp_last = result - if result.engaged: - # ⚠️ EVERY engagement, never deduplicated: this is the action log - # (§15), and it is a different surface from the notification, which - # IS deduplicated. The count is what says how hard the loop pushed; - # the notification only says that it did. - self.log_event(f"{inv.name}: {result.describe()}", - hint=messages.hint("write_cut", unit=inv.name)) - value = result.applied_w - - # --- SAFETY-10: AND THIS IS THE LAST THING BEFORE THE WIRE ----------- - # Shadow mode runs the whole decision path and commands nothing. The - # suppression is HERE, in the one method every write in this add-on - # reaches - the cycle, the heartbeat, the stop button, shutdown() and - # maint_abort() alike - so there is no call site that can route round - # it. app/shadow.py carries the whole argument; three things about the - # placement belong here: - # - # ⚠️ IT IS A SUBSTITUTION, NOT A RETURN, exactly like the two refusals - # above it. Returning would leave the inverter LATCHED ON ITS LAST - # COMMAND with the ESP32's heartbeat still being fed - a battery held - # at whatever it was doing when shadow mode was switched on, under a - # status page saying nothing is being commanded. That is the failure - # this add-on keeps finding, and shadow mode must not be a new way to - # reach it. `shadow.WIRE_W` is 0.0 W and it is REFRESHED on the - # ordinary heartbeat, which is also what firmware/goodwe-master.yaml's - # 30 s stale-input watchdog requires of us. - # - # ⚠️ IT IS BELOW SAFETY-28's GATE AND BELOW SAFETY-03's CLAMP, so both - # still grade the number the decision path actually produced. A shadow - # run that could not say "it would have hit the rating here" would be - # answering a different question from the one it is for. - # - # ⚠️ IT IS NOT A SECOND WRITER. No claim is filed, no transport is - # opened and no arithmetic of its own reaches the wire: one actuator, - # one writer, and this is that writer emitting the value it emits for - # every other refusal. - if self.shadow and value != shadow.WIRE_W: - # UX-10: DEBUG, because it repeats every cycle in shadow mode. The - # INFO line when shadow mode comes on says the same once. - _LOG.debug("Shadow mode: would send %+.0f W to %s, and holds " - "%+.0f W. Nothing was sent to the inverter.", - value, inv.name, shadow.WIRE_W) - value = shadow.WIRE_W - - # --- SAFETY-137: THE 0 W THAT ENDS THINGS IS THE LAST WRITE THE UNIT - # HEARS. `last` is the Stop 0 W and the shutdown 0 W (and nothing else). - # It first waits, bounded, for a write already on its way to this unit, - # so that write cannot land after it. And once shutdown has begun every - # other write (cycle, heartbeat, a safety stop) is dropped here: the - # check sits right before the write is created with no await between, - # so a write that starts after it cannot exist, and one that started - # before is in `inflight` for the wait above. The idle gate for a - # hand-back unit is higher up and does the same for those. - if last: - await self._await_inflight(inv, SETTLE_BUDGET_S) - elif self.stopping: - _LOG.debug("Shutting down, so %+.0f W to %s is not sent.", - value, inv.name) - return - changed = (inv.last_write is None or value != inv.last_write) - if not (changed or force): - return - # ⚠️ BOUNDED, AND THE BUDGET IS AC 6. Without it one inverter's hung - # transport holds this coroutine - and therefore the whole control loop, - # and therefore every OTHER inverter's heartbeat - for as long as the - # HTTP stack allows. A write abandoned here is re-issued on the next - # tick by itself: `last_write` is updated only on an ACCEPTED write, so - # `changed` is still true. - try: - _w = self._driver(inv).write(value) - # SMA-10 / SAFETY-137: kept for every driver, so a release or a last - # 0 W can wait for it (`_await_inflight`). - _w = asyncio.ensure_future(_w) - inv.inflight.add(_w) - _w.add_done_callback(inv.inflight.discard) - ok = await asyncio.wait_for(_w, timeout=WRITE_BUDGET_S) - except (asyncio.TimeoutError, TimeoutError): - ok = False - _LOG.error("Sending %+.0f W to %s (%s) took over %.0f s and was " - "dropped, so it is sent again next cycle.", - value, inv.name, entity, WRITE_BUDGET_S) - self.log_event(f"{inv.name}: write timed out after " - f"{WRITE_BUDGET_S:.0f} s - re-issuing next tick", - hint=messages.hint("write_slow", unit=inv.name)) - now = datetime.now(timezone.utc) - inv.note_write(bool(ok), now) - if ok: - inv.last_write = value - inv.last_write_at = now - - # -- the cycle ----------------------------------------------------------- - def actuator_of(self, source: str, inv=None) -> str: - """Which actuator a claim from `source` is filed on this cycle. - - `inv` is the roster entry the claim is ABOUT, for a per-inverter source. - Left out it is the first inverter, which is what every per-inverter claim - meant while there was only one. ⚠️ A per-inverter claim built inside the - per-unit loop MUST pass it, or inverter B's rating is filed on inverter A - and the arbiter bounds the wrong share - the whole defect, wearing this - method's name. - - ⚠️ THE CLASSIFICATION IS NOT HERE. `arbiter.CLAIM_SCOPE` decides whether - a source is about the grid connection or about one pack, and it carries - the reasoning for all eight; this method only supplies the roster, which - is the one thing the arbiter cannot know. Routing a claim by hand - - writing `actuator=` at a construction site - bypasses the KeyError that - stops a ninth, unclassified source being filed, so do not. - """ - return actuator_for(source, (inv or self.inverters[0]).name, self.units) - - def live_units(self) -> tuple: - """Which inverters may be commanded THIS TICK, for the allocator. - - ⚠️ THE ALLOCATOR DROPS WHAT THIS DOES NOT LIST, and the survivors then - carry the whole site target. That is a real change in what the site can - deliver, so it is reported rather than absorbed - `Allocation.dropped` - carries it and the cycle logs the transition below. A wrong answer here - is a site target divided among fewer inverters than exist, which is why - it is a method with a reason and not a field somebody can set. - - ⚠️ AND IT IS ANSWERED PER TICK, NEVER CACHED. A master goes stale - between one cycle and the next; an envelope read once at construction - over-allocates into a unit that cannot take it. - - ⚠️ AND IT ANSWERS ONE QUESTION: CAN THIS CONTROLLER PUT A NUMBER ON - THIS INVERTER RIGHT NOW. `Inverter.is_live()` carries the two ways it - cannot - no `setpoint_entity`, so there is no writer at all; or every - write REJECTED for a whole `LINK_STALE_S` window, which is layer 1's own - veto period, i.e. the point at which the firmware is about to take the - inverter away from this controller anyway. - - ⚠️ IT IS DELIBERATELY NOT "ITS SENSORS ARE MISSING". A pack whose SoC did - not answer is a different fault with a different remedy - `inputs_ok` - already stops the whole SITE at P_SAFETY for that - and dropping the unit - from the SPLIT instead would hand its share to a sibling while the site - went on regulating, which is the opposite of what a missing measurement - should cause. - - ⚠️ AT A ROSTER OF ONE, ANSWERING FALSE IS A 0 W SITE. The allocator has - nobody left in the envelope set, refuses (REFUSE_EMPTY), and main.py - substitutes the failsafe. That is the honest answer and not a - regression: the only way to reach it is a setpoint entity that has been - REJECTING every write for 30 s, on which the previous code went on - computing setpoints for an inverter it could not reach while layer 1 was - already winding it down. It says so in the action log instead. - """ - now = datetime.now(timezone.utc) - live = [] - for inv in self.inverters: - ok, why = inv.is_live(now) - if ok: - live.append(inv.name) - else: - # Level-logged at DEBUG only: `Allocation.dropped` is the - # operator-facing surface and cycle() edge-logs it. A line here - # every second would flush the 40-row action log of the context - # that explains it. - _LOG.debug("%s is not commandable this tick: %s", inv.name, why) - return tuple(live) - - def liveness_notes(self) -> list: - """Why each unit is or is not commandable, for the status page. - - ⚠️ SAFETY-37's STALE-READING LINE RIDES HERE TOO, AND IT IS A DIFFERENT - FAULT WITH A DIFFERENT REMEDY. A unit that is not commandable is dropped - and its share is carried by the survivors; a unit whose power register - has stopped following its command stops the SITE. They share this list - because they share one place on the status page - the operator asking - "why is nothing happening" needs both - and nothing downstream reads it. - """ - now = datetime.now(timezone.utc) - return [n for n in - [x for inv in self.inverters - for x in (inv.link_note(now), inv.stale_note(), - inv.refusal_note())] - if n] - - def _provider_gate(self, now: datetime) -> None: - """PRICE-01: `cheap`, the gate and the gap from the standing plan. - - The gate exists whenever the provider does: no price for now is a - closed gate, so the charge waits and does not run unpriced. The gap - flag stays False until the first refresh has finished, so a start-up - is not a gap. - """ - plan = self.fresh_tariff_plan(now) - published = None if plan is None else plan.published - if published is not None: - self._last_published = published - gate = gate_for(published, now) - self.cheap, self._price_gated = gate.cheap, True - self.tariff_words = gate.words - # Owner, 2026-10-14: the words say 'maintenance waits', so they show - # only while the maintenance charge is on. - self.price_gap = ((not gate.covered) and self.tariff_at is not None - and MaintConfig.from_options(self.o).enabled) - last = self._last_published - if gate.covered or last is None: - self.price_gap_since = None - elif last.covers(now): - # The last series still covers now, but no refresh has made it - # current for TARIFF_MAX_AGE_S: the refresh task has stopped. The - # gap began when the plan was retired. - self.price_gap_since = ( - None if self.tariff_at is None - else self.tariff_at + timedelta(seconds=TARIFF_MAX_AGE_S)) - else: - self.price_gap_since = last.last_end_before(now) - - def _static_gated(self, o: dict, now: datetime) -> bool: - """`static_gated()`, worked out once an hour: it builds the same - month-long plan as `static_status()` (about 20 ms with a profile), and - whether a fixed tariff is set up does not change from tick to tick - (options change only with a restart).""" - key = (id(o), now.strftime("%Y-%m-%d %H")) - if key != self._gated_key: - self._gated_key, self._gated = key, static_gated(o, now) - return self._gated - - def _charge_gate_open(self, inv) -> bool: - """MAINT-13: may this pack charge now, for the maintenance timeout? - - True when no price gate is set up (no price entities, no fixed tariff: - nothing holds the charge back), in a cheap window, or while the pack is - really taking charge (sun outside cheap hours). Closed only when a gate - exists, it is shut, and the pack is not charging. - """ - if not self._price_gated or self.cheap: - return True - batt = inv.batt - return batt is not None and float(batt) <= -MAINT_CHARGING_W - - async def cycle(self) -> None: - """Gather claims, resolve precedence, write the winner. - - Nothing here decides who wins - arbiter.py does, by one rule. This - method's only job is to state honestly what each strategy wants. - """ - now = datetime.now(timezone.utc) - # ⚠️ BEFORE THE FIRST `return` OF THIS METHOD, ON PURPOSE (TARIFF-11). - # It stamps that a cycle RAN, which is a different fact from any of the - # decisions the cycle may or may not reach, and the status row needs - # the two separately. - self.cycle_at = now - - # ⚠️ EACH PACK ON ITS OWN READING, NOT "the SoC". §12's recalibration - # drains and refills ONE pack and grades ONE coulomb counter, so each - # state machine is ticked with the SoC of the inverter it belongs to. A - # minimum across packs would abort a cycle on a sibling's state, and an - # average would declare a pack full that is not. The pairing is - # positional and both lists are built from the roster in `__init__`, so - # a pack cannot be graded on its neighbour's meter. - # - # ⚠️ AND `arbitrate()` RUNS FIRST, ONCE, OVER ALL OF THEM. It is the - # site's one maintenance slot - see maintenance.py - and a pack that - # does not hold it is told so by name rather than left to discover it. - # Calling `tick()` without the answer this produced is the - # two-packs-draining-at-once defect with the interlock present but not - # wired, which is why the plan is built here and not inside the loop. - # OPT-11: a battery switched off starts no cycle and is left out of the - # slot, so it cannot hold the slot from a battery that is on. One that - # is mid-cycle is stopped, with a log line (the owner's 2026-09-27 - # answer). The switch itself stops it at once (`pack_use`); this is - # the same rule for a store that says Off at start-up. - _off = ({inv.name for inv in self.inverters - if not self.pack_mode(inv).use} if self.modes_on else set()) - for inv, machine in zip(self.inverters, self.maints): - if inv.name in _off: - self._maint_stop_off(machine, now) - _on = [m for inv, m in zip(self.inverters, self.maints) - if inv.name not in _off] - _plan_on = iter(maint_arbitrate(_on, now) if _off - else maint_arbitrate(self.maints, now)) - maint_plan = [None if inv.name in _off else next(_plan_on) - for inv, _m in zip(self.inverters, self.maints)] - maint_results = [] - for inv, machine, blocked in zip(self.inverters, self.maints, maint_plan): - if blocked is None: - maint_results.append(MaintResult(IDLE, False, None, False, [])) - continue - # MAINT-13: the charge timeout counts only the minutes the pack was - # allowed to charge (see `_charge_gate_open`). - res = machine.tick(now, inv.soc, blocked_by=blocked, - gate_open=self._charge_gate_open(inv)) - for msg in res.events: - self.log_event(msg, hint=messages.hint( - "maint_failed" if res.failed else "maintenance", - phase=machine.phase)) - if res.failed: - # Said once: only the tick that failed carries `res.failed`. - multi = len(self.inverters) > 1 - slug = (unit_slugs(self.units)[self.inverters.index(inv)] - if multi else "battery") - await self.hass.call( - "persistent_notification", "create", - messages.maint_failed( - res.failed, FAIL_BACKOFF_DAYS, - unit=inv.name if multi else "", slug=slug).data()) - maint_results.append(res) - # ⚠️ CARRIED TO THE STATUS PAGE, NOT LEFT IN THE 40-LINE ACTION LOG. The - # deferral is edge-logged (it lasts as long as the other pack's cycle), - # so by the time an operator asks "why has pack B not recalibrated" the - # line that said so has scrolled off. §12's whole failure mode is a - # schedule that silently stops firing; a pack that is due, idle and - # WAITING has to be able to say so at the moment it is looked at. - self._maint_deferred = [(m.name, r.deferred) - for m, r in zip(self.maints, maint_results) - if r.deferred] - - # --- SAFETY-02, and it runs BEFORE the early return below ------------- - # ⚠️ ORDER MATTERS HERE. If this were evaluated after the "inputs missing - # but not yet stale" hold, a run of held cycles would leave - # `disagree_since` untouched across the gap and the timer would resume - # from a start time that predates it. It is evaluated every cycle, - # unconditionally, so a missing meter CLEARS the window - see watchdog.py. - # - # The value compared is the command STANDING ON THE WIRE, which is what - # this cycle's fresh meter reading is a response to. `last_write` is that - # value after the device clamp and confirmed accepted; `target` covers - # the case where nothing has been written yet (and, deliberately, the - # case where the last write was REJECTED - the inverter is then still - # latched on `last_write`, which is exactly what `last_write` holds). - # ⚠️ ONE WATCHDOG PER INVERTER, EVALUATED ON THAT INVERTER'S OWN - # STANDING COMMAND. What the watchdog concludes is "THE UNIT I AM - # DRIVING is pushing power the wrong way", and that evidence cannot be - # pinned on a sibling this controller commanded differently. - # `inv.target` is that unit's share from the last resolution, which at - # N=1 is the site target itself. - # - # ⚠️ SAFETY-30: AND WHAT IT IS COMPARED AGAINST IS DECIDED BY THE ROSTER. - # This block used to hand every unit's detector `self.grid`. There is - # ONE P1, so at N>=2 that compares a number this controller put on ONE - # actuator against a measurement that answers for ALL of them, and it is - # wrong in both directions: - # - # FALSE TRIP inverter A commanded -1500 W while the meter reads - # +1500 W is evidence of nothing when inverter B is - # discharging 3000 W exactly as instructed. Nothing is - # faulty and the highest-value check in the safety table - # fires - on a record of zero false positives. - # MISSED the converse, and it is worse. A unit commanded +1500 W - # and MEASURED at -1500 W, beside a sibling at +1500 W, - # leaves P1 exactly where a healthy site leaves it. The - # sum destroys the evidence; no threshold recovers it. - # - # So at N>=2 each unit is graded against ITS OWN measured power - - # `inv.batt`, register 0x0518, per-instance since DEV-02 - which is the - # only instrument that can answer "is THIS actuator doing what I told - # it". At N=1 §6.2's identity holds, the meter IS the view of that one - # unit, and the comparison stays the meter, byte for byte. The site's - # own question has not gone away; it is asked below, once, of the sum. - # `_arm_sign_watchdogs()` states the choice and its docstring argues it. - self._arm_sign_watchdogs() - n_units = len(self.inverters) - standing = {} - for inv in self.inverters: - was_tripped = inv.sign_wd.tripped - # ⚠️ `Inverter.standing_w()`, NOT THE EXPRESSION IT REPLACES. - # SAFETY-37's freshness gate arms off the same method, and this used - # to be the only spelling of it. See that method's docstring. - stood = inv.standing_w() - standing[inv.name] = stood - against = self.grid if n_units <= 1 else inv.batt - if inv.sign_wd.evaluate(stood, against, self.following, now) \ - and not was_tripped: - # ⚠️ REASON FIRST, FLAG SECOND, and each `set` writes the file. - # The ordering is the whole atomicity story: a crash between the - # two persists a reason nothing reads, which is harmless, where - # the other order persists a latch with no explanation for the - # operator who has to decide whether to clear it. - # - # ⚠️ AND BOTH KEYS ARE NAMESPACED TO THIS UNIT. Flat, a trip - # caused by B latched A across every restart until somebody - # pressed start, and one press cleared both. See store.py. - inv.store_set("sign_reason", inv.sign_wd.reason) - inv.store_set("sign_tripped", True) - # ⚠️ AND THE LEGACY FLAT KEYS ARE MIRRORED, WHICH IS THE OTHER - # HALF OF store.py's RULE 2. That rule keeps the flat keys "so a - # rollback still finds its latch", and it only ever covered the - # latch that existed AT MIGRATION TIME: a trip that happens - # AFTER the migration wrote nothing flat, so an operator who - # downgraded would find `sign_tripped: false` and come up - # DRIVING, into the fault. store.py used to claim the staleness - # could only fail toward a spurious latch; it could not, and - # this is what makes that sentence true. The pair is - # site-level on purpose - the version being rolled back TO - # drives exactly one actuator - and it is cleared by the same - # operator press that clears the namespaced ones. - self.store.set("sign_reason", inv.sign_wd.reason) - self.store.set("sign_tripped", True) - self.log_event(f"FAILSAFE {inv.name}: " + inv.sign_wd.reason, - hint=messages.hint("direction", unit=inv.name)) - _LOG.error("%s is set to 0 W until control is started, " - "because its power went the wrong way: %s.", - inv.name, messages.reason_code(inv.sign_wd.reason)) - _LOG.debug("Evidence for %s: %s.", inv.name, - inv.sign_wd.reason) - # ⚠️ THE SITE'S OWN STANDING COMMAND, WHICH IS THE SUM OF THE UNITS'. - # SAFETY-07 and SAFETY-18 both grade a SITE quantity - the quarter-hour - # average at the grid connection, and a meter that has stopped moving - # while the site pushes near its rail - so what they need is the total - # this controller currently has standing on the wire, not one unit's - # share of it. At the shipped roster of one the two are the same number. - site_standing = float(sum(standing.values())) - - # --- SAFETY-30: THE SITE HALF OF THE SIGN CHECK ---------------------- - # The comparison SAFETY-02 shipped, asked of the quantity it was always - # about: the TOTAL this controller has standing on the wire, against the - # meter that total is answerable for. What it catches is a fault no - # per-unit check can see, because every unit is faithfully executing its - # share of a site target that is itself pointing the wrong way - an - # inverted gain, an integrator wound past the rail, a strategy on the - # wrong side of the meter. That is the 2026-08-20 fault day, and it is - # the reason the site question survives rather than being replaced. - # - # ⚠️ ONLY AT N>=2, AND THIS BRANCH IS AC 8. At one inverter the sum of - # the commands IS that inverter's command and the loop above has already - # made exactly this comparison, at exactly these thresholds, on the - # detector whose latch, store keys, claim and banner an install has had - # since SAFETY-02 shipped. Arming this as well would be two latches for - # one fault, two banners, and the same false-positive record spent - # twice. A shipped install does not reach this block at all. - if n_units > 1: - was_site = self.site_sign_wd.tripped - if self.site_sign_wd.evaluate(site_standing, self.grid, - self.following, now) and not was_site: - # REASON FIRST, FLAG SECOND - the same atomicity ordering the - # per-unit trip uses above and SAFETY-31 uses below: a crash - # between the two must not persist a latch with no explanation - # for the operator who has to decide about clearing it. - # - # ⚠️ AND THE KEYS ARE FLAT, NOT NAMESPACED, AND NOT THE - # PRE-DEV-02 PAIR EITHER. `sign_tripped` / `sign_reason` are the - # ROLLBACK VIEW of a UNIT latch (store.py rule 2) and mirroring - # a site trip onto them would hand a downgraded add-on - which - # drives exactly one actuator - a latch taken on evidence about - # a roster it cannot have. `site_sign_*` is its own pair, for - # the same reason `circ_*` is. - self.store.set("site_sign_reason", self.site_sign_wd.reason) - self.store.set("site_sign_tripped", True) - self.log_event("FAILSAFE site: " + self.site_sign_wd.reason, - hint=messages.hint("site_direction")) - _LOG.error("Every inverter is set to 0 W until control is " - "started, because the total power went the wrong " - "way: %s.", - messages.reason_code(self.site_sign_wd.reason)) - _LOG.debug("Evidence for the site: %s.", - self.site_sign_wd.reason) - - # --- SAFETY-31, AND IT RUNS BESIDE SAFETY-02 FOR THE SAME REASON ----- - # Evaluated EVERY cycle, unconditionally, above the "inputs missing but - # not yet stale" hold below. A run of held cycles would otherwise leave - # `over_since` untouched across the gap and the window would resume from - # a start time that predates it, which is the ordering bug the sign - # watchdog's own note describes. - # - # ⚠️ THE INPUT IS MEASURED POWER, WHICH IS THE ENTIRE POINT OF THE CARD. - # `site_circulating_w` reads each `Inverter.batt` - that unit's own - # meter, holding register 0x0518. It is NOT `self.allocation`, and the - # property's docstring carries the argument: ALLOC-01's sign-coherence - # gate already makes the allocation record incapable of expressing - # circulating power, so a record-derived sensor is zero by construction - # and detects nothing. What this catches is circulation the allocator - # NEVER COMMANDED - a unit ignoring or lagging its share, a stale share - # still being executed, or HW-01's wedged power stage. - circ_w = self.site_circulating_w - was_circ = self.circ_wd.tripped - if self.circ_wd.evaluate(circ_w, now) and not was_circ: - # REASON FIRST, FLAG SECOND, and each `set` writes the file - the - # same atomicity ordering SAFETY-02 uses two blocks up, and for the - # same reason: a crash between the two must not persist a latch with - # no explanation for the operator who has to decide about it. - self.store.set("circ_reason", self.circ_wd.reason) - self.store.set("circ_tripped", True) - self._circ_announced = False - self.log_event("CIRCULATING POWER - " + self.circ_wd.reason, - hint=messages.hint("circulating")) - _LOG.error( - "Every inverter is set to 0 W until control is started, " - "because the inverters worked against each other: %s.", - messages.reason_code(self.circ_wd.reason)) - _LOG.debug("Evidence for the site: %s.", self.circ_wd.reason) - - # --- SAFETY-42, AND IT RUNS HERE FOR SAFETY-02's AND SAFETY-31's REASON - # Evaluated EVERY cycle, unconditionally, ABOVE the "inputs missing but - # not yet stale" hold below. A run of held cycles would otherwise leave - # each unit's `since` untouched across the gap and its window would - # resume from a start time that predates it - the ordering bug the sign - # watchdog's own note describes, in a third detector. - # - # ⚠️ THE OPERANDS ARE `standing` AND `inv.batt`, THE SAME PAIR SAFETY-30 - # GRADES, AND THE CONCLUSION IS A DIFFERENT ONE. SAFETY-30 asks whether - # they OPPOSE; this asks whether the second one ARRIVED. A unit sitting - # at 0 W against a +2000 W share opposes nothing - it is not pushing the - # wrong way, it is absent - so the sign gate never opens, the site sum - # still agrees with the meter in direction, circulating power is - # identically zero, and the only trace left is `reason == - # "saturated-freeze"`, which clamp.py:93-96 documents as the alarm an - # operator learns to ignore. That is this card. - # - # ⚠️ AND `delinquent()` IS CALLED ONCE, OVER THE WHOLE ROSTER, BECAUSE - # THE CHECK IS A REDUCTION ACROSS UNITS AND NOT A PER-UNIT PREDICATE. - # What separates a wedged box from a legitimately saturated site is that - # the site's shortfall is a PROPER SUBSET of the units asked to deliver. - # Called per unit it would be a shortfall test, which is the saturation - # signal again. delivery.py carries the measurement: a pack at its own - # cut-out and a wedged unit produce IDENTICAL traces at the unit and at - # the meter, so nothing computed from one unit alone can tell them - # apart. At a roster of one the reduction is empty for every input. - # - # ⚠️ EVERY NUMBER BELOW IS THE CONFIGURED ONE, NEVER A LITERAL THAT - # HAPPENS TO EQUAL IT TODAY, AND THAT IS A SHIPPED PROMISE RATHER THAN - # A STYLE RULE. `delivery.MIN_W_IS_SATURATION_W` and config.yaml's - # `delivery_hold_s` block both tell an operator, in prose, that there is - # no fourth copy of a threshold to keep in step and no way for the two - # to drift - an operator who raises `saturation_w` has told the loop a - # bigger gap is ordinary tracking, and this check moves with them BY - # CONSTRUCTION. A literal here breaks exactly that promise, silently. - # - # Both of these were once literals that no check in this repository - # could see, because every fixture sat at the shipped value: - # - # self.tuning.saturation_w -> 250.0 (-19 B) - a survivor of all - # 23 suites, because part 4's - # gaps are far above BOTH - # bms_floor=inv.bms_soc_floor -> 10.0 (-13 B) - a survivor of all - # 23 suites, because every - # fixture's cut-out WAS 10 % - # - # test_delivery.py part 4b is what stands between this call and both of - # them: it grades this reduction at a `saturation_w` and at two - # `bms_soc_floor`s that are NOT the shipped ones, and its arms are - # answered opposite ways at two configured values, so no constant can - # pass. Change an argument here to a number and read that part before - # you decide the red is wrong. - for inv in self.inverters: - # ⚠️ `self.delivery_cfg`, NOT `DeliveryConfig()`. Same promise: the - # window is `delivery_hold_s`, and part 4b's neighbours already - # grade this one at a hold that is not the shipped 185 s. - inv.delivery_wd.arm(self.delivery_cfg) - _delinquent = delinquent( - [UnitDelivery( - inv.name, standing[inv.name], inv.batt, - delivery_account( - # ⚠️ `is_live()` AT ITS OWN DEFAULT WINDOW, which is - # `LINK_STALE_S` - the SAME call `live_units()` makes for - # the allocator. It has to be: what this branch means is - # "the allocator has already dropped this unit and said so", - # and a different window here would be this check answering - # a question about a roster the allocator did not build. - # It is the ONE number here with no option behind it, so - # "graded at a changed config" is not available for it; - # what part 6 grades instead is that WIDENING the window - # changes the answer. - live=inv.is_live(now)[0], - # SAFETY-73: a refusing unit is asked 0 W on purpose, and - # one asked under PROBE_W that gives under 100 W is a - # refusal too small to call (its sibling covers the meter). - parked=inv.sign_wd.tripped or bool(inv.refused) or ( - n_units > 1 and inv.batt is not None - and abs(float(standing[inv.name])) <= _ctl.PROBE_W - and abs(float(inv.batt) - inv.idle_w) - < _ctl.REFUSED_BELOW_W), - # ⚠️ THIS UNIT'S OWN CUT-OUT. Not the shipped 10 %, and not - # the site's `peak_soc_floor` either - that one bounds a - # money-saving discharge only, and grading a pack against it - # explains a wedged unit away in a band an ordinary install - # has ten points of. - soc=inv.soc, bms_floor=inv.bms_soc_floor)) - for inv in self.inverters], - self.tuning.saturation_w) - for inv in self.inverters: - was_short = inv.delivery_wd.tripped - if inv.delivery_wd.evaluate(_delinquent.get(inv.name), now) \ - and not was_short: - # REASON FIRST, FLAG SECOND, and each `set` writes the file - - # the same atomicity ordering the three trips above use: a crash - # between the two must not persist a latch with no explanation - # for the operator who has to decide about clearing it. - # - # ⚠️ AND THERE IS NO FLAT MIRROR OF THIS PAIR, WHERE SAFETY-02 - # HAS ONE. store.py's rule 2 keeps the flat keys "so a rollback - # still finds its latch", and the version being rolled back TO - # drives exactly ONE actuator - a roster at which this check is - # inert by construction. A flat mirror would hand a downgraded - # add-on a latch taken on evidence about a roster it cannot have. - inv.store_set("delivery_reason", inv.delivery_wd.reason) - inv.store_set("delivery_tripped", True) - self._delivery_announced.discard(inv.name) - self.log_event(f"NOT DELIVERING {inv.name}: " - + inv.delivery_wd.reason, - hint=messages.hint("not_delivering", - unit=inv.name)) - _LOG.error( - "%s is not delivering while control keeps running, and " - "only stopping and starting control clears this: %s.", - inv.name, messages.reason_code(inv.delivery_wd.reason)) - _LOG.debug("Evidence for %s: %s.", inv.name, - inv.delivery_wd.reason) - _LOG.debug( - "SAFETY-42 reports and does not act: commanding a unit " - "that is not listening achieves nothing (HW-01), and the " - "only re-allocation the add-on can express would throw " - "away a partly delivering unit's output.") - - stale_after = float(self.o.get("stale_input_s", 15)) - late_s = self._readings_late(site_standing) # SAFETY-128 - self._late_zero = late_s is not None and late_s >= stale_after - # ⚠️ `any`, NOT the sole unit's. The hold exists so a single missed poll - # does not become a fault; a LATCHED inverter must still reach the claim - # list below, because its `failsafe` SET is what parks it. One tripped - # unit therefore takes the whole roster past the hold, which is the - # conservative direction: every other unit's claims are re-filed too. - # ⚠️ AND SAFETY-30's SITE LATCH TAKES THE ROSTER PAST THE HOLD TOO, for - # the same reason: its `sign_site` SET is what parks every inverter, and - # a latched site that returned early here would leave each unit's last - # share standing for the heartbeat to re-emit - i.e. the trip would stop - # acting the moment a poll was missed. - if not self.inputs_ok and not any(i.sign_wd.tripped - for i in self.inverters) \ - and not (n_units > 1 and self.site_sign_wd.tripped): - bad_for = (now - self.inputs_bad_since).total_seconds() if self.inputs_bad_since else 0.0 - if bad_for < stale_after: - # A single missed poll is not a fault. Hold, keep the heartbeat - # going, and give it a few seconds to come back. - self.reason = f"inputs missing {bad_for:.0f}s" - # UX-10: the age is rendered when the page asks, not frozen at - # this cycle's. With the meter reading gone the grid value - # stops changing, so the next cycle is up to cycle_floor_s - # away and the line used to read "0 seconds" all that time. - self.why_words = messages.why_waiting(bad_for) - self._why_waiting_since = now - timedelta(seconds=bad_for) - return - if late_s is not None and late_s < stale_after and self.inputs_ok \ - and (self.auto or self.shadow) \ - and not any(i.sign_wd.tripped for i in self.inverters) \ - and not (n_units > 1 and self.site_sign_wd.tripped): - self.reason = f"readings late {late_s:.0f}s" # SAFETY-128: hold - self.why_words = messages.why_late() - return - - claims = [] - - # --- safety limits: these bind EVERY strategy, always ---------------- - # Defence in depth: write_setpoint() clamps to the device range too. The - # duplication is deliberate - one of them is the policy, the other is the - # last thing between a bug and the hardware. - # ⚠️ PER-INVERTER, ONE PAIR PER UNIT, FROM THAT UNIT'S OWN NUMBERS. - # This loop is the difference DEV-02 makes to the claim list: the - # numbers are ONE inverter's own reported min/max and ONE inverter's own - # supervised cap, and there is no such thing as a site rating. Before - # this card there was one pair, read from one setpoint entity, filed - # once - so a second inverter's rating was never read and never bound. - # See arbiter.CLAIM_SCOPE. - for inv in self.inverters: - if inv.dev_min is not None and inv.dev_max is not None: - claims.append(Claim.limit("device", P_SAFETY, inv.dev_min, inv.dev_max, "rating", - actuator=self.actuator_of("device", inv))) - # `max_w` is the supervised cap on what may be WRITTEN to one - # setpoint entity (§11.3), not a bound on the grid connection. - claims.append(Claim.limit("supervised", P_SAFETY, -inv.max_w, inv.max_w, "max_w", - actuator=self.actuator_of("supervised", inv))) - # --- OPT-09: WHAT THIS PACK'S STATE OF CHARGE FORBIDS ------------- - # ⚠️ THE POINT OF THE CARD, AND IT IS AN ENVELOPE RATHER THAN A - # WEIGHT. Weighting an empty pack down does NOT stop it being - # commanded: `allocator._fill()` runs a deliberate last-resort pass - # over the zero-weight units when the preferred ones saturate, so - # that a preference can never manufacture a standing error at the - # meter. Only a closed envelope stops the ask, and `cap` is obeyed - # absolutely. So a pack at or under its own BMS cut-out gets - # `hi = 0` and a pack at 100 % gets `lo = 0`, and the site target - # goes to the sibling instead of being asked of a battery that - # cannot answer it. - # - # ⚠️ AT A ROSTER OF ONE THIS IS NEVER FILED, AND THAT IS THE SAME - # IDENTITY `sign_site` IS GUARDED BY RATHER THAN A SPECIAL CASE. - # `actuator_for()` routes every source to the SITE at N=1 - with one - # inverter the fabricated grid reading and the battery setpoint are - # the same number - so this interval would bound THE SITE TARGET - # there, not a share. That is a behaviour change on the live - # single-inverter install and it is the shape SAFETY-25 decided - # against on 2026-09-02 (Option A): ordinary self-consumption is not - # given an SoC floor by this card. There is also nothing for it to - # do at N=1 - no sibling to move the share to - so the whole of AC 4 - # ("at N=1 allocation is byte-identical to today") is this `if`. - # - # WHAT IT COSTS, SAID PLAINLY: at N=1 nothing here stops the loop - # discharging into the BMS cut-out. That is unchanged, it is - # SAFETY-25's deferred Option B, and the BMS itself is what stops it. - if n_units > 1: - _pe = packshare.envelope(pack_energy_of(inv)) - if _pe.binding: - claims.append(Claim.limit("pack", P_SAFETY, _pe.lo, _pe.hi, - _pe.why, - actuator=self.actuator_of("pack", inv))) - # The SITE bound, for the site-level consumers below. It is the roster - # sum: what this site can deliver, not what one of its inverters can. - max_w = self.site_max_w - - # --- safety stops ---------------------------------------------------- - # ⚠️ SAFETY-02 is claimed FIRST and unconditionally while latched. It is - # a SET at P_SAFETY, so it outranks maintenance, peak shaving and the - # loop alike - a controller pushing power the wrong way is wrong - # whatever it thinks it is doing. Re-filed EVERY cycle: claims are not - # sticky, and one filed once would lapse the next cycle and hand the - # actuator silently back to the loop that was driving the wrong way. - # - # ⚠️ AND IT IS PER-INVERTER, THOUGH ITS EVIDENCE IS SITE-WIDE. The - # watchdog compares P1 - one meter, one site - against `standing`, THE - # COMMAND THIS CONTROLLER PUT ON THIS ACTUATOR, and what it concludes is - # "the unit I am driving is pushing power the wrong way". At N>=2 that - # evidence cannot be pinned on a sibling this controller never commanded, - # so a site-wide stop would park an inverter this watchdog never graded. - # See arbiter.CLAIM_SCOPE. - for inv in self.inverters: - if inv.sign_wd.tripped: - claims.append(Claim.set("failsafe", P_SAFETY, 0.0, - "sign disagreement", - actuator=self.actuator_of("failsafe", inv))) - - # --- SAFETY-30: THE SITE SIGN TRIP, AND IT IS A SITE SET ------------ - # ⚠️ THE TWIN OF THE LOOP ABOVE, NOT A DUPLICATE OF IT. That loop files - # one `failsafe` per unit on the evidence of THAT unit's own measured - # power, and parks that unit. This files ONE claim on the SITE, because - # what tripped is the SUM of every standing command against the meter - - # a fact about the grid connection, whose offending number is the site - # target and which no single inverter owns. Parking one unit on it would - # leave the rest of the roster pushing the same way with the guard - # satisfied. See arbiter.CLAIM_SCOPE, which classifies `sign_site` and - # `failsafe` side by side and says why they differ. - # - # ⚠️ AND THE `n_units > 1` GUARD IS NOT REDUNDANT, EVEN THOUGH `cycle()` - # never arms this detector at a roster of one. The latch is RESTORED - # FROM THE STORE, so an install that ran with two inverters, tripped, - # and was then reconfigured back to one would come up with - # `site_sign_tripped: true` and would otherwise file a claim on evidence - # about a roster it no longer has. Guarded, that install comes up - # driving - which is right: the fault it latched on is not a statement - # about the site it is now. - if n_units > 1 and self.site_sign_wd.tripped: - claims.append(Claim.set("sign_site", P_SAFETY, 0.0, - "site sign disagreement", - actuator=self.actuator_of("sign_site"))) - - # --- SAFETY-31: WHAT "ACTED ON" MEANS, AND WHAT IT HONESTLY CANNOT -- - # ⚠️ A SITE SET AT P_SAFETY: STOP COMMANDING, EVERYWHERE. Read the next - # paragraph before changing it, because the obvious objection is right - # and is answered rather than ignored. - # - # THE OBJECTION. HW-01 established that commanding a wedged inverter - # achieves nothing - on 2026-09-02 the comms subsystem failed and the - # power stage went on executing its last instruction for 6 h 25 m, - # through every command this add-on sent it. If the cause of the - # circulation is a unit that has stopped listening, then a command is - # not a remedy and pretending otherwise is theatre. - # - # THE ANSWER, AND IT IS WHY THIS IS STILL AN ACTION RATHER THAN A - # NOTIFICATION. A circulating loop needs TWO participants. In every - # cause on this card's list, exactly one of them is a unit that has - # stopped listening and THE OTHER ONE IS THIS CONTROLLER - faithfully - # commanding the sibling to a share computed to sum with a number the - # wedged unit is not actually producing. Stopping the commanding half - # does two things a notification cannot: - # - # 1. IT HALVES THE LOOP. The unit that is still listening stops being - # driven into the one that is not, so the round-tripping stops on - # the side this controller owns. That is real energy and real - # cycles off a real pack, and it needs no cooperation from the - # wedged unit to take effect. - # 2. IT MAKES THE RESIDUE VISIBLE. This is the more important half. - # Circulating power hides because it NETS TO ZERO AT THE METER. - # With this controller's contribution removed, whatever the wedged - # unit is still doing stops being cancelled and appears at P1 as a - # plain net flow - where SAFETY-02's sign watchdog (which gates on - # `abs(grid_w) > 300` and could never open at a netted zero), the - # peak guard and the capacity tariff can all see it. The fault - # stops being invisible. Measured on the TEST-19 rig: the card's - # own scenario reads +0 W at the meter with 6000 W going round, and - # the shipped SignWatchdog's predicate is false on every one of - # those cycles. - # - # WHAT IT DOES NOT DO, SAID PLAINLY: it does not stop the wedged - # inverter. Nothing this add-on can send will. If the loop persists at - # the meter after this trip, the remaining actuator is a human at the - # isolator, which is what the notification says in those words. - # - # ⚠️ AND IT IS A SITE CLAIM. `arbiter.CLAIM_SCOPE` carries the argument: - # circulating power is defined over the roster and is identically zero - # for any one unit, so there is no attribution to file this per-unit on - - # and parking the wrong one of the two would leave the loop running with - # the guard satisfied. - if self.circ_wd.tripped: - claims.append(Claim.set("circulation", P_SAFETY, 0.0, - "circulating power", - actuator=self.actuator_of("circulation"))) - - # SITE, both of them, and the two reasons are why. "stopped" is the - # operator switching control off for the whole site; "inputs missing" is - # the SITE's own telemetry gone - the meter this controller regulates - # against. Neither is about a pack, and both must stop every inverter. - # ⚠️ SAFETY-10: `and not self.shadow`, AND IT IS THE ONE FAILSAFE THIS - # CARD CHANGES. `P_SAFETY` out-ranks every other claim, so leaving the - # stop claim in while shadow mode is engaged would make the recorded - # decision "stopped" on every cycle - a shadow run that answers the - # wrong question, which is the same as no shadow run. The actuator ends - # at the same number either way, and the substitution in `_write_unit()` - # that replaces it is STRICTLY STRONGER than this claim: a claim can be - # out-ranked by a higher priority, and the wire gate cannot be - # out-ranked by anything. - if not self.auto and not self.shadow: - claims.append(Claim.set("safety", P_SAFETY, 0.0, "stopped", - actuator=self.actuator_of("safety"))) - elif not self.inputs_ok: - if self.target != 0.0: - self.log_event("inputs missing - commanding 0 W", - hint=messages.hint("inputs_missing")) - claims.append(Claim.set("safety", P_SAFETY, 0.0, "inputs missing", - actuator=self.actuator_of("safety"))) - elif late_s is not None: - claims.append(Claim.set("safety", P_SAFETY, 0.0, "readings late", - actuator=self.actuator_of("safety"))) - - # --- SAFETY-07: the quarter-peak projection guard -------------------- - # ONE `lo` limit at P_PEAK, and peakguard.py carries the whole argument. - # What is decided HERE and nowhere else is what the guard is allowed to - # see and what it is allowed to ask for: - # - # ⚠️ `frozen` IS EVALUATED ON THIS CYCLE'S STANDING COMMAND, NOT ON - # `self.freeze_wd.active`. The watchdog object is advanced at the END of - # cycle() (check_meter_frozen), so reading its level here would grade - # this quarter against the PREVIOUS cycle's conjunction - one cycle of - # lag, in a guard whose entire job is to act inside a 900 s quarter. - # `standing` is the value SAFETY-02 already computed above for exactly - # this meaning: the command on the wire that this meter reading is a - # response to. The predicate itself is freeze.py's shipped - # `looks_frozen()`, not a copy of it - see loop_is_following() on what a - # transcribed safety predicate costs. - # - # ⚠️ `achievable_w` BOUNDS THE FLOOR SO THIS CLAIM CANNOT CONTRADICT THE - # SAFETY LIMITS ABOVE. `lo > hi` in the arbiter is a CONTRADICTION and - # resolves to 0 W - the battery parked, in the one minute of the month it - # should be discharging hardest. maintenance_charge_w had to learn the - # same lesson (config.yaml, validate.py rule 6); this claim is built so - # the config cannot express it. - # - # ⚠️ AND IT IS FILED EVERY CYCLE, unconditionally, like SAFETY-02's. A - # claim is not sticky. Filed once and skipped next cycle, the floor - # lapses and the actuator goes silently back to whatever was pushing the - # peak. Which of the higher-priority claims outranks it is arbiter.py's - # business, not this block's: a maintenance DRAIN or HOLD owns the - # setpoint at P_MAINTENANCE, and a maintenance CHARGE is only ever a - # P_MAINT_SHAPE limit (40), bound by this floor. A floor above the drain - # rate still wins (SAFETY-78 at N>=2, `_peak_over_drain()` at N=1), and - # so does a floor over a HOLD (`_peak_over_hold()`, SAFETY-86). - # - # ⚠️ AND IT IS NOT RUN AT ALL WITHOUT P1. `meter_source: off` is the - # legacy single-entity path: there is no telegram stream, so - # `p1.averager` has no open block, so the guard would be BLIND on every - # cycle forever - and blind means "no charging". That is not a - # conservative default, it is a controller that silently stops charging - # on every install that has not opted in to P1 yet; test_clamp.py's - # export case caught it doing exactly that. The billed quantity simply - # is not measured on that path, and the honest report is NOT COVERED - - # the same answer, for the same reason, that the status page already - # gives for SAFETY-18 on a transport that cannot see `unchanged_s`. - # OPT-15: with battery modes on, the quarter `now` is in, even before - # its first sample (DECISIONS/OPT-11-battery-modes.md). - self._peak_proj = (None if not self.p1_enabled - else self.peak.project(self.p1.averager, now, - roll=self.modes_on)) - # OPT-15 x SAFETY-81: see `check_peak_saturated()`. - self._peak_rolled = (self._peak_proj is not None - and self._peak_proj.block_start is not None - and self._peak_proj.block_start - != self.p1.averager.block_start) - _reading = self.peak.peak(now) if self.p1_enabled else None - # SAFETY-90: seconds a meter gap left uncounted are counted, so the - # guard goes on after the readings return. - self._peak_proj = self._fill_peak_gaps(self._peak_proj, now, _reading) - # SAFETY-91: at N>=2 the quarter's edge is graded on the next quarter, - # so a HOLD's ceiling does not lapse for a cycle onto a held battery. - if self._peak_proj is not None and len(self.inverters) > 1: - self._peak_proj = next_quarter(self._peak_proj, - self.p1.averager.max_hold_s) - self.peak_guard = None if not self.p1_enabled else peakguard.decide( - self._peak_proj, - # ⚠️ THE SITE SUM. The guard sizes a floor from what the battery is - # ALREADY removing from the meter, and the meter sees every - # inverter. One unit's power here would size the floor from a - # fraction of the discharge already happening. - batt_w=self.site_batt_w, - cap_w=float(self.o.get("peak_cap_w", 3500)), - margin_w=self.peak_margin_w, - reading=_reading, - # ⚠️ SUMMED FROM THE PER-UNIT CONJUNCTION, WHICH IS AC 4. Each - # unit contributes `min(its max_w, |its own device bounds|)`, so - # inverter B's rating bounds inverter B. Conjoining the SUMS instead - # would let one unit's device range cap the whole site. - achievable_w=self.site_rating_w, - # ⚠️ SAFETY-24. `pack_floor_soc` IS A MEASURED READING AND MAY BE None, - # and it is handed over as None rather than defaulted here. An early - # draft of the stage-5 loop read SoC as `| float(100)` and thereby - # invented a full battery (NOTES.md 4.4b); a full battery is - # precisely the value that disarms this floor. decide() treats None - # as floor-limited, which is the direction that costs a shave rather - # than the pack. - # ⚠️ THE EMPTIEST PACK, not an average - see `pack_floor_soc`. A - # floor that grades a discharge permission against the mean lets the - # emptier pack be driven below the level this option exists to - # protect. None stays None: `decide()` treats it as floor-limited, - # which costs a shave rather than a pack. - soc=self.pack_floor_soc, - # ⚠️ SAFETY-32. THE SAME OPTION, REDUCED OVER THE PACKS' OWN - # CUT-OUTS. `peak_soc_floor` is still one site-wide EMS floor and is - # still read from that one key with CFG-03's one mirror behind it; - # what `binding_soc_floor()` adds is the conjunction with each pack's - # OWN `bms_soc_floor`, so the floor this site is graded against can - # never be below the deepest cut-out on the roster. MAXIMUM here - # pairs with the MINIMUM in `pack_floor_soc`: both reductions move - # the verdict towards refusing a shave and away from spending a pack. - # Under any config rule 8 accepts it IS the option, for every pack - - # asserted over the whole schema range in test_peakguard.py part 12 - # rather than assumed, because "another rule refuses that" is a claim - # about rule ordering and sim/inject.py does not run rule 8 at all. - soc_floor=peakguard.binding_soc_floor(self.packs, float(self.o.get( - "peak_soc_floor", - peakguard.PEAK_OPTION_DEFAULTS["peak_soc_floor"]))), - max_hold_s=self.p1.averager.max_hold_s, - # ⚠️ SAFETY-20. The device range goes in TOO, and this call site is - # the one that needed it most: `standing` is `last_write`, i.e. the - # value AFTER `clamp_to_rating()` applied `[dev_min, dev_max]`, so - # grading it against a rail derived from bare `max_w` compares a - # device-clipped number to a ceiling the device cannot reach. - frozen=looks_frozen(getattr(self.p1_source, "unchanged_s", None), - site_standing, max_w, self.freeze_wd.cfg, - dev_min=self.site_dev_bound("dev_min"), - dev_max=self.site_dev_bound("dev_max")), - ) - # SAFETY-87: at N>=2 a battery at or under its own reserve gives - # nothing for the peak, and the others carry the guard's need. - if self.peak_guard is not None: - self.peak_guard = self._peak_on_able(self.peak_guard, - maint_results) - self.peak_guard = self._peak_landing(self.peak_guard) - self.peak_guard = peakguard.cap_floor( # SAFETY-128 - self.peak_guard, self.answer.peak_cap(site_standing)) - # SITE, and peakguard.claim() says so on the object it builds. The - # quantity is the 15-minute average OFFTAKE AT THE GRID CONNECTION, - # which is what the capacity tariff bills; there is one quarter-hour - # peak per site, not one per pack. ⚠️ IT IS ALSO THE `lo` HALF OF - # SAFETY-25 §0c's table - a site `lo` at this stage, which is what the - # deferred loop reserve's per-inverter `hi` must never be able to cross. - peak_claim = (peakguard.claim(self.peak_guard) - if self.peak_guard is not None else None) - if peak_claim is not None: - claims.append(peak_claim) - # ⚠️ EDGE-LOGGED, not level-logged. The action log holds 40 lines; a - # guard that appended one every 15 s for a whole quarter would push the - # cause of the event off the end of the log that is meant to explain it. - # SAFETY-03 logs every engagement because a clamp engagement IS the - # count that matters there; here the count is the seconds, and the - # engagement's own reason line already carries them. - engaged_now = self.peak_guard is not None and self.peak_guard.engaged - if engaged_now != self._peak_engaged: - self._peak_engaged = engaged_now - if self.peak_guard is not None: - _pg = self.peak_guard - self.log_event(_pg.explain(), hint=messages.hint( - "peak_off" if not _pg.engaged else - "peak_blind" if _pg.blind else - "peak_on" if _pg.within_aim else - "peak_reserve" if _pg.floor_limited else - "peak_saturated" if _pg.saturated else "peak_on")) - - # --- OPT-04: price arbitrage (§10.1 priority 3) ---------------------- - # ONE `set` claim at P_ARBITRAGE, and app/arbitrage.py carries the whole - # argument. What is decided HERE and nowhere else is what the strategy - # is allowed to see: - # - # ⚠️ IT IS PLACED AFTER THE PEAK BLOCK BECAUSE IT READS ITS CONCLUSION. - # `engaged_now` is this cycle's peak verdict, computed ~20 lines up. - # Evaluated before it, this would hand the strategy the PREVIOUS cycle's - # answer - one cycle of lag on the interlock that implements §9.1's - # "peak shaving outranks arbitrage", inside a 900 s quarter. - # - # ⚠️ AND THE THIRD STATE IS NOT A TIDINESS. Without P1 the guard is not - # CLEAR, it never RAN, and `None` says so. arbitrage.decide() refuses on - # it, because charging at max_w creates the billed quantity while - # nothing is measuring the quarter it lands in. `False` here would be - # this line asserting a measurement that was never taken - the defect - # `PeakReading` and `quarter_ceiling_w()` both exist to remove. - # - # ⚠️ THE THREE-STATE COLLAPSE LIVES IN arbitrage.guard_state(), NOT - # HERE, and that is not tidiness. It is the same lesson - # `shaping_suspended()` records: inline, this expression was reachable - # by no check, and mutating it back to a bare `engaged_now` left every - # suite in this repository green while a `meter_source: off` install - # traded blind. Read guard_state() before touching this line. - # - # ⚠️ NO FETCH ON THIS PATH. `fresh_tariff_plan()` is an attribute read - # and an age comparison; the HTTPS call lives in run_tariff_refresh(). - # See TARIFF_REFRESH_S: a supplier's TLS timeout here would be a - # supplier able to push this add-on towards layer 1's 30 s veto. - # - # ⚠️ AND THE UNCERTAINTY SET IS NOT EMPTY BY DEFAULT. §11.4's - # no-weather row widens the threshold, and this add-on carries no - # weather forecast at all - §8.1's PV forecast is not built. Passing - # `frozenset()` would be main.py asserting a forecast is healthy when - # there is not one, which is exactly what static_tariff's `uncertainty` - # argument has no default in order to prevent. - # ⚠️ TARIFF-11: BOTH ATTRIBUTES, AND `arb_at` IS WHAT MAKES THE ROW - # HONEST. Reaching this line is the only proof that this cycle got as - # far as the arbitrage step; the early return at the input hold above - # leaves BOTH standing at whatever the last completed cycle left, and - # `arb_at` is then the age the status row reports rather than a - # decision presented as current. - self.arb, self.arb_at = None, now - self.arb_headroom_w = None - self.room_charge = False - # OPT-11 P3: with battery modes on, each battery's mode decides who - # trades (`_mode_roles()`, `_mode_trade()`, below, which read the - # same headroom), and this site-wide trade is not run. - site_trade = arbitrage.enabled(self.o) and not self.modes_on - if site_trade or self.modes_on: - # SAFETY-47. HOISTED OUT OF THE CALL, NOT COPIED. One evaluation of - # the shipped expression feeds both the sizing below and - # `arbitrage.sized_from_meter()` in `_shadow_settle()`, so the - # caveat on the recorded watts can never be answered from a - # different cycle's guard than the watts were. - # SAFETY-125: a late meter reading's seconds count, as the bill. - self.arb_headroom_w = peakguard.charge_room_w(self.peak_guard, - self._peak_proj) - if site_trade: - floor_pct, ceiling_pct = arbitrage.soc_bounds(self.o) - charge_w, discharge_w = self.trade_power_w(floor_pct, ceiling_pct) - self.arb = arbitrage.decide( - self.fresh_tariff_plan(now), now, - peak_guard_active=arbitrage.guard_state(self.peak_guard), - # SAFETY-45. THE SAME GUARD'S SECOND ANSWER, AND THE CONTINUOUS - # ONE. `guard_state()` is a switch and it was the whole loop: - # the guard engaged on a 5 W floor, the trade was refused - # outright, the loop took the actuator, the meter fell, the - # guard released and the trade came back AT max_w. Measured on - # TEST-23 stage 3 at the shipped peak_cap_w/max_w: 28 charge - # onsets an hour, grid -456 <-> +3200 W. This is the watts the - # billed quarter can still afford, so the buy leg is CLAMPED - # instead - the shape control.maintenance_charge_floor() has - # always given a maintenance charge, off the MEASURED guard - # rather than off the optional peak_forecast_entity. - # ⚠️ SAME ORDERING ARGUMENT AS THE LINE ABOVE: this reads the - # peak block's conclusion, ~50 lines up, so it must stay after - # it. Evaluated earlier it would size this quarter's trade from - # the previous cycle's quarter. - charge_headroom_w=self.arb_headroom_w, - # The emptiest pack again, and for the sell side that is the - # right reduction. ⚠️ THE BUY SIDE WANTS THE FULLEST, and there - # is one `soc` argument - `pack_floor_soc` names that residual - # rather than hiding it; a per-pack charge ceiling is CFG-04's, - # and at the shipped roster of one the two reductions are the - # same number. - soc=self.pack_floor_soc, - min_spread_eur_kwh=arbitrage.threshold_eur_kwh(self.o), - uncertainty=frozenset({Uncertainty.NO_WEATHER}), - # OPT-09. PER-PACK SIZING. Not `max_w` - the site rating - on - # both sides any more: the trade is sized to the packs whose own - # state of charge permits that direction, so it can never ask - # for more than the roster can take. `trade_power_w()` carries - # the argument, including which of the two SoC bounds belongs - # here and which belongs on the envelope. ⚠️ AT N=1 BOTH SIDES - # ARE `max_w` EXACTLY, whenever the trade is permitted at all: - # the one pack that passed the gate is the whole roster. - # ⚠️ AND ON THE SELL SIDE THIS IS A NO-OP TODAY on any roster, - # because `soc=` below is the EMPTIEST pack, so a sell is - # refused outright whenever any pack is at or under the floor - - # i.e. whenever this sum could be smaller than the site rating. - # It becomes reachable the day that gate becomes per-pack; - # `test_packshare.py` part 9 grades it directly rather than - # letting an unreachable branch go ungraded. - charge_w=charge_w, discharge_w=discharge_w, - soc_floor_pct=floor_pct, soc_ceiling_pct=ceiling_pct) - # SITE, and arbitrage.claim() says so on the object it builds. It - # buys and sells at the grid against a day-ahead price: the price is - # a property of the connection and the energy crosses the meter. - arb_claim = arbitrage.claim(self.arb) - if arb_claim is not None: - claims.append(arb_claim) - self.room_charge = self.arb.action == arbitrage.CHARGE - # Edge-logged, for the peak guard's reason: the action log holds 40 - # lines and a trade lasts a whole hour, so a line per cycle would - # flush the context that explains it. The transition is what an - # operator needs - "it started buying at 03:00", not 240 copies. - if self.arb.action != self._arb_action: - self._arb_action = self.arb.action - self.log_event(self.arb.explain(), hint=messages.hint( - "trade_charge" if self.arb.action == arbitrage.CHARGE else - "trade_give" if self.arb.action == arbitrage.DISCHARGE - else "trade_off")) - - # --- maintenance ----------------------------------------------------- - # ⚠️ ONE PASS PER PACK, AND `arbitrate()` IS WHY THE LIST STAYS SHORT. - # At most one machine is out of IDLE on any tick, so at most one of - # these branches fires and the claim list is the shape it has always - # been. The loop is not a widening of what maintenance may ask for; it - # is what makes the ONE claim it does file land on the pack that is - # actually being recalibrated, whichever roster slot that is. - for inv, result in zip(self.inverters, maint_results): - if result.owns_setpoint: - # PER-INVERTER. §12's monthly recalibration is a PACK procedure - - # drain THIS pack to its floor, charge THIS pack full, - # recalibrate THIS pack's coulomb counter. Two packs recalibrate - # on two schedules. See arbiter.CLAIM_SCOPE. - # - # ⚠️ FILED ON THE PACK WHOSE STATE MACHINE PRODUCED IT - `inv`, - # the roster entry this `result` was ticked from - and that is - # the whole of MAINT-05 at this line. It used to be - # `self.maint_unit`, which was `inverters[0]` flatly, because - # there was one FSM and its history had nowhere else to live. - # Pack B's drain filed on pack A is one pack being commanded for - # another's procedure while the pack that is actually draining - # stays under the loop: the site would move the right total and - # recalibrate nothing. - # - # ⚠️ AND IT STAYS `SCOPE_UNIT`. Two FSMs mean two claims on two - # actuators, which the allocator consumes as per-unit intervals; - # ARCH-01 is explicit that this must never become a site claim, - # because per-inverter constraints filed site-wide are the - # cross-inverter `lo > hi` contradiction at arbiter.py:114. - claims.append(Claim.set("maintenance", P_MAINTENANCE, - float(result.setpoint_w or 0.0), result.phase, - actuator=self.actuator_of("maintenance", inv))) - self.sat_count = 0 - elif result.charge_only: - # Money outranks the maintenance schedule: while the quarter-hour - # projection is over the cap, the charge-only shaping is simply not - # claimed, so the loop can discharge and shave the peak. When a - # dedicated peak-shaving strategy arrives it will claim SET at - # P_PEAK and outrank this limit without any code here changing. - # ⚠️ AND SAFETY-07 IS THE OTHER HALF OF THIS CONDITION, NOT A - # SECOND MECHANISM. The shaping is `hi <= 0`; the peak guard's - # claim is `lo >= 0`. Both are limits, arbiter.py applies EVERY - # limit at or above the winner's priority, and most restrictive - # wins - so a peak event during a maintenance charge window files - # `lo > hi`, which is a CONTRADICTION and resolves to 0 W. The - # battery would park in the exact quarter it should be shaving. - # Priority does not save it: clause 2 has no notion of a - # higher-priority limit overriding a lower one, and it should not - - # "most restrictive" is what makes the safety bounds unconditional. - # - # So the higher-priority claimant SUPPRESSES the lower one rather - # than out-voting it, which is what this branch already did for - # `peak_forecast_entity`. That entity is optional and empty on a - # default install, so until now the suspension could not fire on the - # site that needed it. `self.peak_guard` is measured from the meter - # and is always there. - # - # ⚠️ THE CONJUNCTION LIVES IN peakguard.py, NOT HERE, and that is - # not tidiness. It was inline, and a reviewer mutated it back to its - # historical broken form - re-gated on `peak_forecast_entity` alone - # - and every suite in this repository stayed green while a default - # install parked at 0 W in the quarter that sets the month's bill. - # Read shaping_suspended() before touching this: both terms are - # there, and why neither is sufficient alone. - # - # ⚠️ ONE SUSPENSION FLAG FOR THE SITE, NOT ONE PER PACK, AND THE - # INTERLOCK IS WHAT MAKES THAT TRUE. The quantity it edge-logs is - # a peak event at the grid connection, and `arbitrate()` allows - # at most one pack to be in CHARGE at a time, so this branch can - # run at most once per tick. Were two packs ever allowed to - # charge together, this flag would have to become per-pack - and - # so would the reasoning above it. - if peakguard.shaping_suspended( - self.peak_guard, self.peak_fc, self.peak_aim_w()): - # Edge-logged: level-logging here would write one line per - # cycle for as long as the event lasts and flush the 40-line - # action log of the very context that explains it. - if not self._maint_shape_suspended: - self._maint_shape_suspended = True - self.log_event("peak at risk - maintenance charge shaping " - "suspended so the peak claim is not " - "contradicted", - hint=messages.hint("maint_paused")) - else: - self._maint_shape_suspended = False - hi = 0.0 - reason = "charge-only" - if self.cheap: - # ⚠️ CFG-03. `self.maint.cfg.charge_w`, NOT A SECOND READ - # OF `self.o`. This line used to re-open the options dict - # with its own literal fallback, so the rate the shaping - # asked for and the rate the state machine drained at - # could be different numbers from the same install - and, - # with the key absent, they were. The Controller already - # parsed this once in __init__; asking the object that - # owns it cannot drift from it. Every pack's machine - # holds the same `MaintConfig` instance, so this is the - # rate the pack in front of us is charging at. - floor = maintenance_charge_floor( - self.maint.cfg.charge_w, - self.peak_fc, self.peak_aim_w()) - floor = self._charge_headroom(floor, claims) - if floor > 0: - hi, reason = -floor, "cheap-window charge" - # PER-INVERTER, like the SET above and for the same reason - - # the shaping is about the pack being charged, which is `inv`. - claims.append(Claim.limit("maintenance", P_MAINT_SHAPE, hi=hi, - reason=reason, - actuator=self.actuator_of("maintenance", - inv))) - - # --- OPT-11: each battery's mode, a soft unit limit at P_MODE --------- - # Filed only with battery modes on, and never on a battery in any - # maintenance phase: maintenance at 60/40 outranks the mode. The range - # always holds 0 W (packmode.mode_range()). pre_resolve() keeps it - # apart from the hard limits, and it gives way to the peak guard's - # site floor (P_PEAK) only as far as the floor needs, so the two never - # meet in a `lo > hi` (arbiter._unit_modes()). - # P3: the range is the switch's, narrowed by the battery's role in - # the price runs this tick (`modetrade.decide()`); both hold 0 W. - if self.modes_on: - tick = self._mode_roles(now, maint_results) - for inv, result in zip(self.inverters, maint_results): - if result.phase != IDLE: - continue - pm = self.pack_mode(inv) - lo, hi = packmode.mode_range(pm, inv.max_w) - rlo, rhi = tick.ranges.get(inv.name, (lo, hi)) - lo, hi = max(lo, rlo), min(hi, rhi) - claims.append(Claim.limit("mode", P_MODE, lo, hi, pm.key, - actuator=self.actuator_of("mode", - inv))) - - # --- the grid-following loop ----------------------------------------- - # ⚠️ SAFETY-10: `or self.shadow`. The loop is the leg a shadow run most - # needs and the one that is switched off by `auto_start: false`, so - # without this an install in `auto` shadow mode would record every - # strategy's decision and a permanent silence where the grid-following - # loop should be. It is safe because the loop's `prev_w` is - # `self.target`, which the end of this method re-seeds to what is - # actually standing on the wire. - # SAFETY-52: a refusal learned while control ran does not survive a - # stop or a start (shadow mode keeps the loop running when stopped). - if bool(self.auto) != self._refusal_auto: - self._refusal_auto = bool(self.auto) - self._refusal_end("control started" if self.auto - else "control stopped") - for inv in (self.inverters if len(self.inverters) > 1 else ()): - self._unit_refusal_end(inv, "control started" if self.auto - else "control stopped") - # SAFETY-73: each unit's own refusal, engaged and ended on its own - # reading, before the loop reads `self.target` (an end reseeds it). - _probing = {} - if len(self.inverters) > 1 and self.inputs_ok: - self._unit_refusals() - _probing = {inv.name: self._unit_probe(inv) - for inv in self.inverters if inv.refused} - # --- SAFETY-73: each refusing unit's own P_SAFETY claim --------------- - # A hard unit limit that always intersects (OPT-11's P_MODE layer sits - # inside it): closed in the refused direction, so the allocator hands - # the share to the others within their own limits. During its probe it - # is a pin at PROBE_W and the others carry the rest. Filed here, before - # the loop, so OPT-11's loop bound sees it. Unit claims only, and still - # the last unit claims filed, so every unit's claim order is as before. - for inv in self.inverters: - if not inv.refused: - continue - if _probing.get(inv.name): - claims.append(Claim.set("refused", P_SAFETY, - inv.refused * _ctl.PROBE_W, - _ctl.PROBING, - actuator=self.actuator_of("refused", - inv))) - else: - claims.append(Claim.limit("refused", P_SAFETY, - *_refused_interval(inv.refused), - _ctl.REFUSED, - actuator=self.actuator_of("refused", - inv))) - # --- SAFETY-78: a pinned drain is a floor under the site target ----- - # After every unit claim, so the floor is what the pin really places. - drain = self._drain_floor(claims, maint_results) - if drain is not None: - claims.append(Claim.limit("drain", P_MAINTENANCE, lo=drain, - reason="maintenance drain", - actuator=self.actuator_of("drain"))) - self._peak_over_drain(claims, maint_results) - # --- SAFETY-86: while a HOLD gives, the site stays at the peak floor -- - # So the loop never asks for watts the hold keeps back. - hold_hi = self._peak_over_hold(claims, maint_results) - if hold_hi is not None: - claims.append(Claim.limit("hold", P_MAINTENANCE, hi=hold_hi, - reason="maintenance hold", - actuator=self.actuator_of("hold"))) - # --- SAFETY-91: a drain rises before a held battery gives ------------ - self._drain_rise(claims, maint_results) - # --- SAFETY-84: a cheap-window charge is a ceiling over the site ---- - charge = self._charge_ceiling(claims) - if charge is not None: - claims.append(Claim.limit("charge", P_MAINT_SHAPE, hi=charge, - reason="maintenance charge", - actuator=self.actuator_of("charge"))) - # --- OPT-11 P3: the site trade, after every unit claim -------------- - # Sized from what the batteries may place with their modes and hard - # limits (the loop bound), so none is asked for watts it may not give. - mode_trade, trade_was = False, self._mode_trade_was - if self.modes_on: - mode_trade = self._mode_trade(claims, now) - self.room_charge = self.room_charge or ( - mode_trade and self.arb.action == arbitrage.CHARGE) - self._mode_trade_was = mode_trade - self._charge_track(claims, maint_results) - _live96 = set(self.live_units()) - self._loop_start = {} - if (self.auto or self.shadow) and self.inputs_ok: - # ⚠️ prev is the ARBITER's last output, not the loop's own last - # wish. If something outranked the loop, that is what the hardware - # actually did, and the controller must track reality or it jumps - # the moment it regains control. - # - # ⚠️ The integrator has to track the same reality, and it is no - # longer prev_w, so it needs saying out loud: if the arbiter did not - # give the loop what it asked for last cycle, the loop's - # accumulated error belongs to a command that never happened. - # Re-seed from what the hardware was actually told. This is the - # failsafe case too - every layer-1 stop resolves to 0 W, so - # entering failsafe re-seeds the integrator to zero and the first - # cycle after release starts from zero instead of dumping the whole - # stale period as power. - moved = self.loop_w is None or self.target != self.loop_w - if moved: - self.i_w = self.target - # OPT-11 P3: a run edge (a mode trade ended) reseeds the loop, and - # OPT-15 holds it there until the meter shows the step. - if trade_was and not mode_trade: - self._reseed_run_edge(claims, now) - moved = False - loop_grid = self._edge_grid(mode_trade or moved, now) - # SAFETY-52: another writer overrode the loop, so a refusal learned - # against the loop's own ask may no longer describe the wire. A gap - # (`loop_w` None: blind or stopped) keeps it: the stale-reading stop - # is what seeds it, and dropping it there restarts the ~70 s cycle. - # SAFETY-107: it ends only if compute() no longer finds it against - # that writer's ask (`_refusal_update()`). A held refusal makes the - # loop ask 0 W, so any claim that binds differs from it every cycle. - rejudged = 0 - if self.loop_w is not None and self.target != self.loop_w: - rejudged = self.batt_refused - # SAFETY-96: a battery that dropped out of the split leaves the - # loop's start point (SAFETY-93's own if its charge ended too). - self._reseed_drop(_live96) - # SAFETY-93: a charge that ended leaves the loop's start point. - self._reseed_charge_end(maint_results) - # SAFETY-95: then a drain that ended, last (it reads the start - # the others left). - self._reseed_drain_end(maint_results, _live96) - # No probe while it is judged afresh (the loop does not hold the wire). - probe = False if rejudged else self._refusal_probe() - if len(self.inverters) > 1: - probe = any(_probing.values()) - # ⚠️ `actual_w` IS THE SITE SUM AND THAT IS DEV-02's OTHER HALF. - # The anti-windup test inside compute() is - # `abs(prev_w - actual_w) > saturation_w`, and `prev_w` is the SITE - # target. Handed ONE inverter's power at a roster of two it compares - # a site number against a unit number, permanently trips the - # saturation freeze and leaves a standing grid error - measured on - # admin/goodwe's two-master rig at up to 510 W of split-dependence - # (gain 0.2; 250 W at 0.4, 50 W at 0.6) while the allocator's shares - # summed to S in every run. With the sum, every split is - # bit-identical at every gain the schema accepts. That is why the - # per-unit readings became per-instance and THIS one became site - # level: the two halves of §6.2's identity break in opposite - # directions. See `site_batt_w` and test_alloc.py part 8. - site_batt = self.site_batt_w - # SAFETY-103: what each battery can be doing (its reading may be - # older than the meter). - self._track_reads() - # SAFETY-96: a battery the loop cannot move counts at its command, - # so its own power does not freeze the loop (the meter has it). - site_batt += self._held_out_w(_live96) - # TEL-10. ⚠️ ONE NAME FOR THE COMMAND THE LOOP WAS MEASURED - # AGAINST. `self.target` is reassigned further down this method, so - # a `decision.i_w - self.target` written at publish time would - # subtract a DIFFERENT cycle's command and call the answer a lead. - # The published lead is built from the value `compute()` was - # actually handed, on the line that hands it over. - loop_prev = self.target - decision = compute( - prev_w=loop_prev, - # SAFETY-95: a drain's tail is not the loop's to chase. - # OPT-15: `loop_grid` is the grid, or the target while a run - # edge is held. - grid_w=(self._drain_grid_w(_live96) if self._drain_tail - else loop_grid), - actual_w=site_batt, - tuning=self.tuning, - sat_count=self.sat_count, - i_w=self.i_w, - # SAFETY-52 at one inverter only: with several, OPT-09's pack - # limit already closes an empty battery's discharge end. - # SAFETY-73: at N>1 the site law holds 0 W only while every - # unit refuses the same way. Otherwise None, the old law. - refused=(0 if rejudged else self.batt_refused) - if len(self.inverters) == 1 - else self._site_refused(), - probe=probe, - # SAFETY-94: at N=1 the engage also needs the reading to have - # given nothing for the whole span, as at N>1. - gave_nothing=(bool(self._gave_nothing(self.inverters[0])) - if len(self.inverters) == 1 else None), - # SAFETY-97: "gives nothing" is centred on the idle reading. - idle_w=self._site_idle_w(), - hold=self.answer.hold, hold_w=self.answer.hold_w, # SAFETY-128 - # OPT-11: None unless battery modes are on. SAFETY-85: or while - # maintenance holds a battery at N>=2, so the loop does not - # wind past what the others can give and jump when it ends. - bound=(self.loop_bound(claims) if self.modes_on or ( - len(self.inverters) > 1 - and any(r.phase != IDLE for r in maint_results)) - else None), - ) - if decision.frozen and self.sat_count < self.tuning.saturation_cycles: - self.log_event(f"saturation freeze ({self.target:.0f} W vs " - f"{site_batt:.0f} W)", - hint=messages.hint("not_keeping_up")) - self.sat_count = decision.sat_count - self.i_w = decision.i_w - self.loop_w = decision.target_w - self._loop_decision = decision - if len(self.inverters) == 1: - self._refusal_update(decision, loop_prev, site_batt, probe, - rejudged) - # --- TEL-10 ------------------------------------------------------ - # ⚠️ THE INTEGRATOR HAS NEVER LEFT THIS PROCESS, AND THAT IS WHAT - # THE CARD IS. `self.i_w` is carried between cycles and published - # nowhere - no entity, no attribute, no log line - so the only way - # anyone has ever asked what it was doing is to RECONSTRUCT it from - # the grid trace and a replay. That reconstruction reproduced about - # a third of the engagements it was checked against and was thrown - # away; a card that has to be argued from a discarded reconstruction - # is a card that cannot be argued. - # - # Three rows, and the third is not derivable from the first two by - # anyone reading the dashboard afterwards: - # - # `loop_i` the integrator AFTER this cycle - `Decision.i_w`, - # which its own docstring says is the value BEFORE - # the output clamp, the slew limit and quantisation. - # It is therefore NOT `setpoint` and must never be - # published from it. - # `loop_lead` how far the integrator stands AHEAD of the command - # it was computed against. This is the quantity - # SAFETY-48 bounds, and `integrator_max_w / slew_w` - # is the number of cycles it takes to unwind. - # `loop_reason` `compute()`'s OWN reason string - `deadband`, - # `i-clamped`, `clamped`, `slew-limited`, - # `saturated-freeze`, `freeze-released`, `tracking`. - # - # ⚠️ AND `loop_reason` IS NOT `self.reason`. `self.reason` is the - # ARBITER's sentence (`resolution.explain()`, e.g. "loop -> 1200 W") - # and it does not carry the loop's own word at all: the Claim filed - # below takes `decision.reason` and `Resolution.explain()` prints the - # winner's NAME, not the winner's reason. The status page's "Why" - # row is the arbiter's sentence and stays that way. - self.loop_i_w = decision.i_w - self.loop_i_lead = decision.i_w - loop_prev - self.loop_reason = decision.reason - # --- SAFETY-03 --------------------------------------------------- - # ⚠️ READ THE BOOLEANS, NOT `decision.reason`. On a default install - # the integrator bound is what bites and the output clamp is - # unreachable (control.py says so), and `reason` is then overwritten - # by whichever of slew-limiting or the saturation freeze ran after - # it - so a string test is silent on the two cases a winding loop - # most often presents as. These flags are set where the clamp - # happens and nothing downstream touches them. - # SAFETY-40: every number comes from THIS decision, at clamp time, - # never from `self.target` after slew/freeze/arbiter rewrote it. - self.loop_clamped = ( - decision.i_clamped or decision.clamped, - loop_clamp_note(decision), - decision.clamped, - ) - self.loop_clamp_facts = ( - (messages.Clamp(None, decision.requested_w, decision.clamped_w, - "rating"),) if decision.clamped else ()) - # SITE. compute() regulates `grid_w` - the P1 measurement - to - # zero. Its subject is the meter, and §6.2's architecture is ONE - # integrator on P1 whose output is then SPLIT. This is the claim the - # allocator exists to divide. - claims.append(Claim.set("loop", P_LOOP, decision.target_w, decision.reason, - actuator=self.actuator_of("loop"))) - else: - # Stopped or blind: no accumulation may survive the outage. - self.i_w = 0.0 - self.loop_w = None - self._live_was = frozenset(_live96) - # TEL-10, and it is the same zero the line above writes rather than - # a second opinion about it. ⚠️ `not-running` rather than a stale - # `tracking`: a reason row that keeps repeating the last word the - # loop said while the loop is not running is a row that reads as - # health, which is the failure `publish()`'s own None-dropping note - # is about one field over. - self.loop_i_w = 0.0 - self.loop_i_lead = 0.0 - self.loop_reason = "not-running" - # A loop that is not running cannot be winding. Clearing this here - # rather than letting the last value stand is what makes the alarm - # de-assert when control is stopped. - self.loop_clamped = (False, "", False) - self.loop_clamp_facts = () - self._loop_decision = None - - # SAFETY-28. A new resolution is a new tick, and the previous record is - # stale from this line onwards. Incremented BEFORE resolve() so that the - # record resolve() builds is stamped with the tick it is for. - self.alloc_tick += 1 - # ⚠️ `weights=` IS OPT-09, AND ITS ABSENCE WAS THE CARD. ARCH-01 left the - # allocator one free parameter and ALLOC-01 built the machinery that - # consumes it (`allocator._fill`); this line is the first thing that has - # ever passed one. Without it every unit weighed 1.0 and the split was - # a fixed 50/50 regardless of what either pack could do. - # - # ⚠️ A METHOD, NOT A DICT. The weighting is by ENERGY HEADROOM and is - # therefore direction-dependent, and the direction is the sign of the - # site target - which stage 2 chooses inside `resolve()`. See - # `pack_weights()` and `packshare.weights()`; the arbiter calls it once, - # between stage 2 and stage 3. - # - # ⚠️ AND IT IS A PREFERENCE, NOT A PERMISSION. Nothing about the site's - # ability to DELIVER rests on this argument - a weight cannot stop a - # unit being commanded and cannot move a failing unit's load to its - # sibling. The `pack` claim filed above is the half that constrains. - _live = self.live_units() - while True: - resolution = resolve(claims, units=self.units, live=_live, - weights=self.pack_weights, tick=self.alloc_tick, - reserve=self._held_back()) - # SAFETY-73: a probe pin stands only while the resolved site target - # asks at least PROBE_W its way. Below that a sibling would carry - # the opposite direction (circulation), so the pin goes back to the - # closed limit and the split is resolved once more. - _void = [k for k, c in enumerate(claims) - if c.source == "refused" and c.kind == "set" - and c.value * resolution.target_w < _ctl.PROBE_W ** 2] - if not _void: - break - for k in _void: - claims[k] = Claim.limit( - "refused", P_SAFETY, - *_refused_interval(1 if claims[k].value > 0 else -1), - _ctl.REFUSED, actuator=claims[k].actuator) - self.allocation = resolution.allocation - if self.modes_on: - self._mode_fault_log(resolution) - # --- THE TWO REFUSALS, AND THEY ARE NOT THE SAME REFUSAL -------------- - # Both do the same thing - REPLACE the resolution with a 0 W failsafe - # which is then written like any other cycle at - # `write_setpoint(self.target)` below. Nothing is skipped. 0 W is the - # fail-toward-inaction direction: the setpoint is commanded to zero - # rather than left wherever the last cycle put it. They differ in WHO - # refused and therefore in what an operator should do about it, so they - # are two branches with two messages and not one with a vague one. - # - # ⚠️ AND NEITHER MAY BE LEFT UNGRADED. PR #40's reviewer replaced the - # first of these with `if False:` and the whole 17-file suite stayed - # green, because at the shipped roster of one it was unreachable. - # test_peakguard.py part 10h grades both, on real cycles. - # - # 1. THE ALLOCATOR REFUSED. Before ALLOC-01 this fired on every N>=2 - # cycle, because there was no allocator and the obvious placeholder - - # hand the site target to each inverter - IS the ARCH-01 fault. There - # is an allocator now and that trigger is gone; the branch is not, - # because refusing is still right when no safe split exists at all: a - # mis-routed claim (so the number to divide may itself be wrong), no - # inverter left in the envelope set, or a split that could only be - # made by commanding one pack to charge while another discharges. - # `allocator.plan()` carries the argument for each. - if not resolution.allocated: - self.log_event("ARBITER: " + resolution.allocation.explain(), - hint=messages.hint("split")) - resolution = Resolution(0.0, "failsafe", None, False, - resolution.considered, - unit_bounds=resolution.unit_bounds, - shares={}, allocated=False, - scope_errors=resolution.scope_errors, - allocation=resolution.allocation, - winner_priority=resolution.winner_priority) - # 2. THE ALLOCATOR SUCCEEDED AND THIS CONTROLLER CANNOT DELIVER IT. - # ⚠️ RE-AIMED BY DEV-02, NOT DELETED, AND THE DIFFERENCE MATTERS. - # Under ALLOC-01 this fired whenever the split named any inverter but - # the single one this controller could write, because there was one - # `setpoint_entity`. There is a writer per inverter now, so that - # trigger is gone - and the INSTINCT is not, because a roster entry - # can still have no writer: an inverter configured with no - # `setpoint_entity` of its own is an inverter this controller cannot - # put a number on. Writing the site target to the ones it CAN reach - # would over-command them by exactly the missing unit's share - - # not the broadcast fault, but the same shape of over-command. - # Commanding a partial site is a worse instruction than commanding - # nothing, and "nothing" here means 0 W and says so. - # - # ⚠️ IT IS NOT THE SAME EVENT AS A DEAD LINK, WHICH IS WHY IT IS NOT - # FOLDED INTO `live_units()`. A unit whose writes are being rejected - # is DROPPED and its share is carried by the survivors - a real, and - # announced, change in what the site can deliver. A unit with no - # writer configured at all is a CONFIGURATION that cannot be - # delivered, and the site stops rather than silently running at part - # strength on a roster somebody wrote down wrong. - elif {u for u in resolution.shares if not self._can_write(u)}: - undeliverable = ", ".join( - sorted(u for u in resolution.shares if not self._can_write(u))) - self.log_event( - f"ARBITER: the site target was allocated across " - f"{len(resolution.shares)} inverters and this controller has no " - f"setpoint entity for {undeliverable} - refusing to command a " - f"partial site", hint=messages.hint("no_setpoint")) - # ⚠️ `shares={}`, NOT THE SHARES IT REFUSED TO DELIVER, AND SINCE - # DEV-02 THAT IS LOAD-BEARING RATHER THAN TIDY. The write loop below - # commands each inverter `shares.get(name, 0.0)`, so carrying the - # split through a refusal would write the very numbers this branch - # just declined - and, worse, would write NOTHING at all when they - # equal what is already standing, because an unchanged value is not - # re-sent. The record the operator needs survives on - # `self.allocation`, which is assigned above and untouched here. - resolution = Resolution(0.0, "failsafe", None, False, - resolution.considered, - unit_bounds=resolution.unit_bounds, - shares={}, allocated=True, - scope_errors=resolution.scope_errors, - allocation=resolution.allocation, - winner_priority=resolution.winner_priority) - # 3. AC 6: A DROPPED INVERTER IS NEVER SILENT. The survivors carry its - # share, which is a real change in what the site can deliver, and an - # operator who is not told reads a working site. Edge-triggered on - # the SET of dropped units, not level-triggered, because the action - # log is a log of events (§15) and a stale link would otherwise write - # a line every second for as long as it lasts. - _dropped = tuple(u for u, _why in (self.allocation.dropped - if self.allocation else ())) - if _dropped != self._dropped_last: - for _u, _why in (self.allocation.dropped if self.allocation else ()): - self.log_event(f"ALLOCATOR: {_u} dropped from the split " - f"({_why}) - the remaining inverter(s) now carry " - f"its share of the site target", - hint=messages.hint("unit_dropped", unit=_u)) - if self._dropped_last and not _dropped: - self.log_event("ALLOCATOR: every inverter is back in the split", - hint=messages.hint("units_back")) - self._dropped_last = _dropped - # 3b. OPT-09 / IF-04: WATTS NOBODY COULD TAKE ARE NEVER SILENT EITHER. - # `unmet_w` is the site target the envelopes could not absorb. It is - # NOT a broken allocation - `Allocation`'s own docstring says why - # fusing it with `ok` would let one saturated inverter park the whole - # site - but it IS the site failing to deliver what the loop asked - # for, and before this card nothing anywhere reported it. It is the - # state a closed envelope produces when BOTH packs are at their - # limits: the ask has nowhere left to go, and an operator watching a - # standing grid error needs the reason rather than the symptom. - # Edge-triggered on the VALUE, for `_dropped` reason. - _unmet = int(self.allocation.unmet_w if self.allocation else 0) - if _unmet != self._unmet_last: - if _unmet: - self.log_event( - f"ALLOCATOR: {_unmet:+d} W of the site target could not be " - f"placed on any inverter - {self.allocation.explain()}", - hint=messages.hint("unmet", w=_unmet)) - else: - self.log_event("ALLOCATOR: the whole site target fits again", - hint=messages.hint("unmet_gone")) - self._unmet_last = _unmet - if resolution.scope_errors: - # A claim reached the arbiter on an actuator its source's scope does - # not permit. It is a BUG in the filing site, not a state to survive: - # a per-inverter constraint in the site list is the `lo > hi` this - # card removes, and a site constraint on one unit is a bound the - # other unit never gets. Loud, every cycle, and it does not change - # the resolution - the arbiter already routed by `actuator`. - _LOG.error("A limit was filed on the wrong inverter, which is a " - "software fault. %s.", " / ".join(resolution.scope_errors)) - if resolution.contradiction: - self.log_event("ARBITER CONTRADICTION - commanding 0 W, see the log", - hint=messages.hint("clash")) - # --- SAFETY-02's arming gate ------------------------------------------ - # Was the number about to go on the wire chosen by the grid-following - # loop, or by a strategy that commands against the meter on purpose? - # Only the former is expected to agree in sign with P1 - without this, - # every maintenance grid charge trips the failsafe within three minutes. - # - # ⚠️ THE EXPRESSION LIVES IN watchdog.py, NOT HERE, and that is not - # tidiness. It was inline, test_watchdog.py held a transcription of it, - # and the P_PEAK case meant to force whoever lands peak shaving to come - # and change an expectation did not: editing this line alone to - # `winner in ("loop", "peak")` left every suite green while the watchdog - # went blind for every peak event. Read loop_is_following() before - # touching the gate - the forward hazard and the reasoning are there. - self.following = loop_is_following(resolution, self.loop_w) - self.target = resolution.target_w - self.reason = resolution.explain() - # UX-08: the same answer in plain words, for the page's "Why" line. - # `reason` stays the technical record the log and the checks read. - # UX-10: `why_key()` maps a safety winner to its claim's reason, and - # every key it can return has words in messages.WHY_WINNER. - _why = why_key(resolution.winner, claims) - if _why == "inputs missing" and not resolution.contradiction: - # UX-11: past the hold, say which reading is missing. - self.why_words = messages.why_missing(self.missing_reading(), - stale_after) - else: - self.why_words = messages.why( - _why, resolution.target_w, resolution.bound_by, - contradiction=resolution.contradiction, - raised=why_raised(resolution, claims)) - # --- DEV-02: EACH INVERTER IS TOLD ITS OWN SHARE --------------------- - # ⚠️ ITS OWN SHARE, NEVER THE SITE TARGET. `resolution.shares` is the - # allocator's answer and `sum(shares) + unmet_w == round(target_w)` is - # an integer identity, so handing each unit its entry is what makes the - # gain at the meter a CONVEX COMBINATION of the per-unit gains. Handing - # each unit `self.target` is the ARCH-01 fault: each supplies it in - # full, the gain becomes N times the per-unit gain, and on the - # two-master rig that is 4000 W peak-to-peak forever at gain 1.0 with - # not one guard firing. - # - # ⚠️ AT N=1 THIS IS BYTE-IDENTICAL. The allocator's pass-through returns - # `{inverter-a: target_w}` as an unrounded float, so the number written - # is `self.target` exactly, as it always was. - # - # ⚠️ AND A UNIT NOT IN `shares` IS COMMANDED 0 W, not left standing. - # That is the dropped-link case: the inverter holds its last command - # FOREVER, so "not in the split" must mean zero on the wire, not - # silence. The write is the same clamped, budgeted path as every other. - # SAFETY-85, before the writes: the wire still holds last cycle's. - self._loop_alarm_input(resolution) - writes = [] - for inv in self.inverters: - inv.target = float(resolution.shares.get(inv.name, 0.0)) - writes.append(self.write_setpoint(inv.target, unit=inv)) - await asyncio.gather(*writes) - - # --- SAFETY-03, and its boundary is the WRITE ------------------------ - # ⚠️ NOT THE SAME BOUNDARY AS SAFETY-18's BELOW, THOUGH THE CALLS ABUT. - # This one reads `self.clamp_last`, which is None until write_setpoint() - # has actually run, so it has to follow the write. The one below grades - # `self.target`, which is assigned further up - see check_output_clamp() - # and check_meter_frozen() for each. Two guards, two orderings, adjacent - # lines: do not "tidy" them into one rule. - # - # Moving it BELOW the other guards is harmless - nothing between here and - # the end of cycle() writes `self.clamp_last`. Moving it above the write - # is not, and test_clamp.py part 6 fails on exactly that: it grades the - # evidence, not the line number, so a rename or a move into a helper that - # still runs after the write keeps it green. (TEST-11.) - await self.check_output_clamp() - - # --- SAFETY-18, and its boundary is the ASSIGNMENT -------------------- - # ⚠️ THE BOUNDARY IS `self.target = resolution.target_w` ABOVE, NOT - # write_setpoint(). This comment used to say "the command that has just - # gone on the wire", which is wrong twice over and was corrected by - # TEST-06's reviewer: `check_meter_frozen()` grades `self.target` - the - # arbiter's resolved intent - and `write_setpoint()` clamps only a local - # `value` and can skip the write entirely, so that number may never have - # gone anywhere. - # - # What both terms of the conjunction must describe is the SAME moment: - # the command this cycle resolved, against how long the meter that chose - # it has been standing still. Evaluated before - # `self.target = resolution.target_w` it would grade the PREVIOUS - # cycle's command against THIS cycle's meter - the one combination that - # was true of neither moment. Moving it between the assignment and - # write_setpoint() is therefore harmless; moving it above the assignment - # is not, and test_freeze.py part 5 fails on exactly that. - await self.check_meter_frozen() - - # --- PRICE-01: no price for now, said once and taken down once -------- - # Not a safety check, so it is one of the cheap ones: an attribute test - # and, on a change only, one Home Assistant call. - await self.check_price_gap() - await self.check_fixed_note() - - # --- SAFETY-31's alarm, and its boundary is the LATCH, not a number --- - # Unconstrained where the two above are not: it grades - # `self.circ_wd.tripped`, which was advanced near the top of this method - # beside SAFETY-02 and which nothing since has touched. It is called on - # EVERY cycle rather than only on the cycle that trips, because its - # second job is re-raising the alarm after a restart into an existing - # trip - see its docstring on why that shares one code path with the - # fresh trip instead of getting its own. - await self.check_circulating() - - # --- SAFETY-42's alarm, and its boundary is the LATCH, like SAFETY-31's - # It grades `inv.delivery_wd.tripped`, which was advanced near the top - # of this method beside SAFETY-02 and SAFETY-31 and which nothing since - # has touched. Called on EVERY cycle rather than only on the cycle that - # trips, because its second job is re-raising the alarm after a restart - # into an existing trip - see its docstring on why that shares one code - # path with the fresh trip instead of getting its own. - await self.check_not_delivering() - - # --- SAFETY-07's alarm, and it is NOT the engagement ------------------ - # Its boundary is unconstrained: it grades `self.peak_guard`, which this - # method assigned above and nothing since has touched. - await self.check_peak_saturated() - - # --- SAFETY-24's alarm, and it is the OTHER way the money gets spent -- - # Same boundary argument as check_peak_saturated(): it grades - # `self.peak_guard`, which cycle() assigned above and nothing since has - # touched. Kept as its own method rather than folded into that one, - # because the two states are mutually exclusive and want OPPOSITE - # operator actions - saturation says "shed load, the inverter is already - # flat out"; this says "the pack is at its floor and this quarter is not - # being shaved at all". - await self.check_peak_floor_limited() - - # --- TARIFF-01, and it is LAST on purpose ----------------------------- - # Banking a quarter is bookkeeping about a moment that has already - # happened; a slow SD card must never sit between the meter and the - # setpoint. Its position is unconstrained in the way SAFETY-03's and - # SAFETY-18's are not - it grades neither `target` nor `standing` and - # reads only `self.p1`, which no line in this method writes. - self.peak.sync(self.p1) - - # --- SAFETY-10, AND IT IS LAST FOR A REASON THAT IS NOT TIDINESS ----- - # Every guard above has now read `self.target` - the resolved intent - - # and SAFETY-18 in particular grades exactly that. Re-seeding before - # them would hand each one a 0 W that no decision produced. Re-seeding - # AFTER them hands the NEXT cycle, and the sign watchdogs, what is - # actually standing on the wire. See `_shadow_settle()`. - self._shadow_settle(resolution) - - def _shadow_settle(self, resolution) -> None: - """SAFETY-10. Record the decision, then re-seed the carried command. - - TWO JOBS, AND THEY ARE IN THIS ORDER BECAUSE THE SECOND DESTROYS THE - FIRST'S EVIDENCE. - - 1. THE RECORD. A shadow run is only worth running if it answers "what - would it have done, and why". `self.shadow_would_w` and - `Resolution.explain()` are that answer, and the action log gets one - line per CHANGE OF DECISION rather than one per cycle - the log - holds 40 rows, and a level-logged shadow run would flush the context - of its own findings inside four minutes at a 15 s cycle floor. The - same edge rule the peak guard and the arbitrage strategy already - use, for the same reason. - - 2. THE RE-SEED. `self.target` and each `inv.target` are set back to - `shadow.WIRE_W` - what the write gate actually put on the wire. - - ⚠️ WHY THE RE-SEED IS A SAFETY PROPERTY AND NOT BOOKKEEPING. Three - machines read the carried command as a statement about the HARDWARE: - - * `compute(prev_w=self.target, ...)` - the loop's slew limiter and - its integrator. Left holding a shadow decision, the first cycle - after shadow mode is turned off would slew from a base that never - existed: up to a full `slew_w` step onto a battery sitting at 0 W. - Re-seeded, the exit is safe BY CONSTRUCTION and needs no separate - transition code - the carried command already equals the standing - one. - * `Inverter.standing_w()`, which is what SAFETY-02/30's sign - watchdogs grade. Fed a shadow decision they would compare a number - against a meter that never saw it, disagree for as long as the - decision asked for power, and LATCH A TRIP THAT SURVIVES INTO LIVE - OPERATION AND A RESTART. Shadow mode would manufacture the failsafe - it exists to help debug. ⚠️ THIS ONE IS ALREADY HELD BY THE WIRE - GATE - `standing_w()` prefers `last_write`, and that is the 0.0 W - the gate accepted - so the re-seed is the SECOND rung, covering - the fallback before any write has been accepted. Two rungs - answering one question is MUTATION.md's masking shape, and the - mutation that reproduces the hazard has to defeat BOTH: driven - singly, dropping this line leaves the detector inert and names - nothing about the latch. Measured. - * SAFETY-42's delivery watchdog compares `inv.target` against what - the pack is producing. A share nothing was told to produce is a - delinquency report on every cycle of every shadow run. - - ⚠️ AND EVERY CYCLE'S DECISION IS THEREFORE COMPUTED FROM WHERE THE - PLANT REALLY IS, not from a counterfactual plant that drifts further - from reality every tick. "What would this controller command NOW, - given this meter and a battery at 0 W" is a true statement about the - present; "what would the eleventh cycle of a run that never happened - have commanded" is not a statement about anything. - """ - engaged = self.shadow - if engaged != self._shadow_was: - # ⚠️ `first` EXISTS SO A LIVE INSTALL'S FIRST CYCLE IS SILENT. The - # edge is against `None` on cycle one, and an install that comes up - # CONTROLLING has nothing to report - a "shadow mode off" line at - # every start is one more row of boilerplate in a 40-row log, and - # it was measured pushing a real clamp episode's context out of - # test_clamp.py part 2's ring. Coming up IN shadow mode is the - # other direction and it is always worth a line: it is the log an - # operator reads to find out why nothing is being commanded. - first = self._shadow_was is None - self._shadow_was = engaged - if engaged: - self.log_event( - "SHADOW MODE ON - " + shadow.why( - self.o, control_started=self.auto) - + f"; inverter held at {shadow.WIRE_W:.0f} W", - hint=messages.hint("shadow_on")) - # UX-10: INFO. It follows a setting or a button press, and - # no person has to act on it. - _LOG.info( - "Shadow mode is on, so every inverter stays at %.0f W and " - "nothing the add-on decides is sent. %s.", shadow.WIRE_W, - shadow.why(self.o, control_started=self.auto)) - elif not first: - self.log_event( - "Shadow mode off: the add-on controls the battery again, " - f"starting from {shadow.WIRE_W:.0f} W", - hint=messages.hint("shadow_off")) - _LOG.info( - "Shadow mode is off, so the add-on controls the battery " - "again, starting from %.0f W.", shadow.WIRE_W) - if not engaged: - self.shadow_would_w = None - self.shadow_sized_from_meter = False - self._shadow_winner = None - return - self.shadow_would_w = float(resolution.target_w) - # SAFETY-47. ⚠️ NO LOGIC HERE, DELIBERATELY. All three rungs - the - # arbiter's winner, the leg being a CHARGE, and the headroom having - # been MEASURED - live inside `arbitrage.sized_from_meter()`, which - # says why, including why it is NOT keyed on whether the trade was - # capped. A rung written at a call site is a rung no check can reach - # with the other two clear, which is TEST-16's rule. - self.shadow_sized_from_meter = arbitrage.sized_from_meter( - self.arb, self.arb_headroom_w, winner=resolution.winner) - # ⚠️ THE WINNER AND THE ROUNDED WATTS, NOT THE WATTS ALONE. A decision - # that moves from the loop to the peak guard at the same number is a - # different decision and the operator needs the line; a loop target - # that wanders by a watt is not, and 15 s of those would be the whole - # log. - # ⚠️ SAFETY-47 ADDS THE CAVEAT FLAG TO THE EDGE. The same winner at the - # same watts with and without the caveat are two different claims about - # the same number, and an edge key blind to that would print the first - # one and silently keep it standing. It cannot flood: the flag only - # moves when arbitrage starts or stops owning the resolution, or when - # the guard starts or stops measuring the quarter, and both of those - # move the winner or the watts as well on every cycle measured. - edge = (resolution.winner, round(float(resolution.target_w)), - self.shadow_sized_from_meter) - if edge != self._shadow_winner: - self._shadow_winner = edge - self.log_event(shadow.log_line( - would_w=resolution.target_w, reason=resolution.explain(), - sized_from_meter=self.shadow_sized_from_meter), - hint=messages.hint("shadow_decision", - sw=resolution.target_w)) - self.target = shadow.WIRE_W - for inv in self.inverters: - inv.target = shadow.WIRE_W - - def _loop_alarm_input(self, resolution) -> None: - """SAFETY-85. The loop's clamp counts only on a cycle the loop decided - (a rating may cut it). A battery another owner set to discharge counts - when it gave less than it was told for `saturation_cycles` cycles in a - row. DECISIONS/SAFETY-85-no-false-not-keeping-up.md.""" - d = self._loop_decision - if d is None: - self._short_run = 0 - self._asked_hist = {} - self._wire_lost, self._handback = False, None - return - unmet = self.allocation.unmet_w if self.allocation is not None else 0 - cut = (resolution.bound_by or "").split("(")[0] - owns = (resolution.winner == "loop" and not d.held and not unmet - and (resolution.target_w == d.target_w - or cut in ("device", "supervised"))) - # Graded against the least that stood on the wire (0 W in shadow - # mode) over SHORT_CYCLES cycles and SHORT_SPAN_S seconds. - now, asked = self._now_mono, {} - for inv in self.inverters: - h = self._asked_hist.setdefault(inv.name, []) - h.append((now, inv.standing_w())) - while len(h) > SHORT_CYCLES and ( - now is None or h[0][0] is None - or now - h[0][0] > SHORT_SPAN_S): - h.pop(0) - asked[inv.name] = min(w for _t, w in h) - others = [inv for inv in self.inverters if not owns - or allocator.pin_w(resolution.unit_bounds.get(inv.name)) - is not None] - short = [(inv, asked[inv.name], inv.batt) for inv in others - if inv.batt is not None - and delivery_short(asked[inv.name], inv.batt, - self.tuning.saturation_w)] - self._short_run = self._short_run + 1 if short else 0 - settling = self._settling(owns, now) - if owns and self.loop_clamped[0] and not ( - settling and not self.loop_clamped[2]): - return - engaged = self._short_run >= self.tuning.saturation_cycles - named = len(self.inverters) > 1 - self.loop_clamped = (engaged, shortfall_note( - [(inv.name if named else None, a, g) for inv, a, g in short]) - if engaged else "", False) - self.loop_clamp_facts = () - - def _settling(self, owns, now) -> bool: - """SAFETY-119: does the loop's bound on this cycle count? Not within - a settle after another owner handed the wire back: its integrator is - re-seeded from that owner's command and kicked by a meter that does - not show it yet. SAFETY-121: the settle is HANDBACK_CYCLES cycles and - SHORT_SPAN_S after the hand-back, so a bound that outlasts it counts - at any cycle length; losing the wire restarts it. Across all - hand-backs the bound is hidden on at most ROLLING_BOUND_CYCLES cycles - in any ROLLING_S, so a bound that never outlasts a settle is counted - too. DECISIONS/SAFETY-121-bound-every-quarter.md.""" - def aged(t0, span): - return now is None or t0 is None or now - t0 >= span - - if not owns: - self._wire_lost, self._handback = True, None - return False - if self._wire_lost: - self._wire_lost, self._handback = False, (now, 0) - if self._handback is None: - return False - tc, n = self._handback - n += 1 - self._handback = (tc, n) - if aged(tc, SHORT_SPAN_S) and n >= HANDBACK_CYCLES: - self._handback = None - return False - if self.loop_clamped[0] and not self.loop_clamped[2]: - kept = tuple(t for t in self._hidden if now is None or ( - t is not None and now - t < ROLLING_S)) - if len(kept) >= ROLLING_BOUND_CYCLES: - self._hidden = kept - return False - self._hidden = kept + (now,) - return True - - async def check_output_clamp(self) -> None: - """SAFETY-03. Alarm whenever a clamp actually engaged this cycle. - - Runs AFTER write_setpoint() for the same reason SAFETY-18 does: the - clamp is arithmetic done inside the write, so before the write there is - nothing yet to report. - - ⚠️ PUBLISHING IS NOT IN THE WRITE PATH. The clamp itself is synchronous - inside write_setpoint(); this - the awaits, the notification, anything - that can block on Home Assistant - is out here. A stalled supervisor must - never be able to delay or drop a frame. - - ⚠️ THIS IS NOT A TRIP. No claim is filed, nothing is latched, 0 W is not - commanded and `publish()` still reports "running". §11.2's action for - this row is "clamp and alarm", and the clamped value is written and the - loop keeps running. Turning this into a trip means coming here and - changing that deliberately, not discovering it in the field. - """ - # ⚠️ THE EVIDENCE IS PER UNIT AND THE ALARM IS NOT. `clamp_last` moved - # onto the Inverter because a clamp on B says nothing about A; the - # ClampWatchdog stayed one per controller because clamp.py's own - # docstring says so - it is an anti-flood counter over an EVENT BUS, not - # a property of a device, and one notification per inverter per cycle is - # the flood it exists to remove. So: any unit that clamped is an - # engagement, and the reason NAMES the unit. - clamped_units = [inv for inv in self.inverters - if inv.clamp_last is not None and inv.clamp_last.engaged] - engaged_write = bool(clamped_units) - engaged_loop, loop_note, loop_bug = self.loop_clamped - engaged = engaged_write or engaged_loop - # SAFETY-40: only an over-rating is a bug; the integrator bound is not. - bug = engaged_write or loop_bug - if engaged_write: - _named = len(self.inverters) > 1 - reason = write_clamp_note([(inv.name if _named else None, - inv.clamp_last) - for inv in clamped_units]) - facts = [messages.Clamp(inv.name if _named else None, - inv.clamp_last.requested_w, - inv.clamp_last.applied_w, - inv.clamp_last.bound) - for inv in clamped_units] - else: - reason = loop_note if engaged else "" - facts = self.loop_clamp_facts if engaged else () - fired = self.clamp_wd.note(engaged, reason, datetime.now(timezone.utc), - bug=bug, facts=facts) - - # --- THE ACTION LOG, AND IT IS COALESCED PER EPISODE ------------------ - # Every engagement is recorded, but consecutive ones are recorded by - # UPDATING one row's count rather than inserting a row each. - # - # ⚠️ THAT IS NOT COSMETIC, AND IT WAS FOUND THE HARD WAY. `log_event()` - # keeps 40 rows; a winding loop clamps on every cycle, so a row per - # engagement flushes the whole ring within 40 cycles - and the first - # thing it evicted, in test_freeze.py, was SAFETY-18's "METER FROZEN?" - # row. A guard whose log drowns out the other guards' logs has moved the - # flood rather than removed it. The count here is `clamp_wd.engagements`, - # so nothing is lost: the row says exactly how many, and the number is - # read off the counter rather than off the number of rows. - # - # This lives here rather than only in write_setpoint() because on a - # default install the actuator-side clamp is unreachable - compute() has - # already bounded the integrator - so the only engagements that exist are - # loop-side ones. Measured: 60 cycles of the §10.3 runaway produce 0 - # write-path engagements and 2 loop-side ones. - if engaged and not engaged_write: - tag = f"{CLAMP_REASON} episode {self.clamp_wd.episodes}" - row = (f"{tag}: " - f"{messages.count(self.clamp_wd.engagements, 'engagement')}" - f" - {reason}") - if self.events and tag in self.events[0]: - stamp = self.events[0].split(" ", 1)[0] - self.events[0] = f"{stamp} {row}" - else: - self.log_event(row, hint=messages.hint( - "power_too_high" if bug else "not_keeping_up")) - if not fired: - return - if not self.clamp_wd.bug: - # SAFETY-40: the integrator bound is anti-windup, not a bug - a - # WARNING and a plainly titled notice, same cadence. Its OWN id, so - # it can never replace a BUG SIGNAL notice still on screen. - _LOG.warning("The battery gives less than asked: %s. Held back %s " - "so far.", messages.reason_code(self.clamp_wd.reason), - messages.times(self.clamp_wd.engagements)) - _LOG.debug("Evidence: %s.", self.clamp_wd.reason) - _LOG.debug("A short hold after a large load or solar step is " - "normal. If it lasts, check that the battery follows " - "its commands.") - await self.hass.call("persistent_notification", "create", - messages.loop_bound().data()) - return - _LOG.error( - "Power request too high, a software fault: %s. Cut back %s so " - "far, control runs on.", messages.reason_code(self.clamp_wd.reason), - messages.times(self.clamp_wd.engagements)) - _LOG.debug("Evidence: %s.", self.clamp_wd.reason) - _LOG.debug( - "SAFETY-03: silently clipping this is how a winding integrator " - "reached 14 768 W on this project before. The clamp makes every " - "dashboard read a legal number while the thing producing it goes " - "on climbing. This is an alarm, not a trip.") - # A fixed notification_id, for the reason check_meter_frozen() gives - - # and a DIFFERENT one from every other alarm this add-on raises, because - # a clamp is not a frozen meter and neither is a saturation freeze. - # UX-08: the words are messages.output_clamp()'s; the numbers are the - # ones `reason` was written from (ClampWatchdog.facts), asked first. - await self.hass.call("persistent_notification", "create", - messages.output_clamp(self.clamp_wd.facts, - shadow=self.shadow).data()) - - async def check_peak_saturated(self) -> None: - """SAFETY-07. Alarm ONLY when the guard has run out of inverter. - - ⚠️ AN ENGAGEMENT IS NOT AN ALARM, AND THE DIFFERENCE IS §10.3's DOCTRINE - READ CAREFULLY. "Treat an out-of-range computed setpoint as a bug signal - - clamp it, then alarm" is SAFETY-03's rule and it is right there: the - loop computing 14 768 W is a WINDING INTEGRATOR, a defect, and clipping - it silently is what let it keep climbing behind a dashboard full of legal - numbers. A peak floor above the inverter's rating is not a defect. It is - a house load bigger than the inverter - 2026-08-20 15:45 ran ~5900 W - against a 5000 W unit - and alarming on the ordinary case is how an - operator learns to dismiss the notification that matters. So an - engagement is an ordinary control action: it goes to the §15 action log - and the status page, and no further. - - What DOES earn the operator's attention is saturation: the guard asked - for more discharge than the inverter can give, so the quarter is going - over the ceiling anyway and the controller has already done everything - available to it. That is the one state where the money is going to be - spent and a human is the only remaining actuator. - - SAFETY-81: `g.saturated` alone is not enough. It is graded against the - aim, and a 1 s meter spike, noise or the last seconds of a quarter set - it while the quarter lands on target; `peakguard.load_too_high()` must - agree too, for `ALARM_HOLD_S`. The battery reading it gets is the lower - of this cycle's and the last one's - see there. - - Edge-triggered, and de-asserting arms it again - the same shape as - FreezeWatchdog's `evaluate()`, and for the same reason: one notification - per episode, not one per cycle. SAFETY-81: the notification and action - log line at most once per quarter; the ERROR line once per episode. - """ - g = self.peak_guard - batt, prev = self.site_batt_w, self._peak_batt_prev - if batt is None: - # Unknown, not "fine": the hold below neither grows nor restarts. - return - self._peak_batt_prev = batt - if prev is not None: - batt = min(float(batt), float(prev)) - p = self._peak_proj - # OPT-15 x SAFETY-81: until the new quarter's first sample the old - # projection read "no seconds left" (not high), which restarted the - # hold; a rolled one (battery modes on) is not graded then, so a - # persistent overload is still notified once per quarter. - high = bool( - g is not None and g.saturated and p is not None - and p.block_start is not None and not self._peak_rolled - and peakguard.load_too_high( - p, batt_w=batt, ceiling_w=g.ceiling_w, - achievable_w=self.site_rating_w)) - # SAFETY-81: and for ALARM_HOLD_S, on the projection's clock. - saturated = False - if high: - t = p.block_start + timedelta(seconds=float(p.elapsed_s)) - if self._peak_high_since is None: - self._peak_high_since = t - saturated = ((t - self._peak_high_since).total_seconds() - >= peakguard.ALARM_HOLD_S) - else: - self._peak_high_since = None - was, self._peak_saturated = self._peak_saturated, saturated - if not saturated or was: - return - _LOG.error( - "Switch off large loads, the battery alone cannot keep this " - "15-minute period under the peak limit: %s.", - messages.reason_code(g.reason)) - _LOG.debug("Evidence: %s.", g.reason) - # SAFETY-81: notified once per quarter; a later episode is logged only. - if p.block_start == self._peak_alarm_block: - return - self._peak_alarm_block = p.block_start - self.log_event("PEAK_GUARD_SATURATED - " + g.reason, - hint=messages.hint("peak_saturated")) - # A fixed notification_id, and a DIFFERENT one from every other alarm - # here - check_meter_frozen() gives the reasoning. A saturated peak guard - # is not a frozen meter and is not an out-of-range setpoint. - await self.hass.call("persistent_notification", "create", - messages.peak_saturated( - g.ceiling_w, shadow=self.shadow).data()) - - async def check_peak_floor_limited(self) -> None: - """SAFETY-24. Alarm when the EMS SoC floor stops the guard shaving. - - ⚠️ FAILING TO SHAVE MUST NOT BE SILENT, AND THAT IS THE WHOLE POINT. - The guard exists for one euro figure - the capaciteitstarief bills the - month's single worst quarter - so a cycle in which it CHOSE not to shave - is a cycle in which money is being spent on purpose. Under-shaving - quietly would leave the operator with a bill and a status page full of - green. - - The distinction from check_peak_saturated() is the operator's action, - which is why these are two notifications and not one: - - saturated the guard asked for everything the inverter has and it - was not enough. SHED LOAD - the controller has already - done all it can, and it is still discharging. - floor-limited the guard asked for NOTHING, because the pack is at or - under the EMS floor, or its SoC could not be read. - Nothing is being discharged for this quarter at all. - (SAFETY-87, N>=2: or the batteries above their - reserve give all they can and it is not enough.) - - They cannot both be true: peakguard.decide()'s floor-limited branch - returns before the `achievable_w` clamp that sets `saturated`. - - ⚠️ SAFETY-25 - AND THE MESSAGE SAYS WHAT THE FLOOR IS NOT. Read on its - own, "the capacity-peak guard has run out of battery" invites exactly - one wrong inference: that the pack is now being held at - `peak_soc_floor`. It is not. `peak_soc_floor` bounds THIS GUARD only; - the grid-following loop has no SoC floor at all and, on the committed - 2026-08-20 replay, is being granted discharge in EVERY cycle that raises - this notification. An operator who reads the alarm and relaxes because - "the EMS has a 20 % reserve" has been misled by us, so the alarm carries - the correction itself rather than leaving it to DOCS.md. - - Edge-triggered, and de-asserting arms it again - FreezeWatchdog's shape, - for FreezeWatchdog's reason: one notification per episode, not one per - cycle for a quarter of an hour. - """ - g = self.peak_guard - limited = bool(g is not None and g.floor_limited) - if limited and (g.floor_w or 0.0) > 0.0: - limited = self._reserve_short(g) - else: - self._reserve_batt_prev = self._reserve_high_since = None - # SAFETY-126: nothing can give, so it alarms at once, but only - # when the quarter really misses the aim (`_peak_landing()`). - limited = limited and not g.within_aim - was, self._peak_floor_limited = self._peak_floor_limited, limited - if not limited or was: - return - # No prefix: `reason` already opens with PEAK_GUARD_FLOOR_LIMITED, and - # a second copy is the kind of stutter that makes a 40-line action log - # read like boilerplate. The saturated path needs its prefix because its - # reason carries the word in the middle of a sentence, not at the front. - self.log_event(g.reason, hint=messages.hint("peak_reserve")) - _LOG.error( - "Switch off large loads, the peak guard may not draw the battery " - "lower: %s.", messages.reason_code(g.reason)) - _LOG.debug("Evidence: %s.", g.reason) - # A fixed notification_id, and a DIFFERENT one from every other alarm - # here - check_meter_frozen() gives the reasoning. A battery at its - # energy floor is not a saturated inverter and is not a frozen meter, - # and an operator who has to dismiss three identical-looking cards - # learns to dismiss the one that mattered. - # ⚠️ SAFETY-25's sentence must render on the unreadable-SoC branch too, - # where `soc_floor` is a number but naming it would invite the reader to - # think the pack is AT it. `decide()` guards its own reason string the - # same way; a f-string that formats a None here would turn the one - # notification that matters into a traceback. - # SAFETY-32/87: which battery is at its reserve, each graded on its own - # floor (`g.held`). At a roster of one no battery is named. - # ⚠️ SAFETY-25's sentence (the reserve binds the peak guard only) is - # part of messages.peak_reserve() on every branch, the unreadable-SoC - # one included. - await self.hass.call("persistent_notification", "create", - messages.peak_reserve( - g.ceiling_w, soc_unread=g.soc is None, - floor_unknown=(g.soc is not None - and g.soc_floor is None), - packs=(g.held if len(self.inverters) > 1 - else ()), - others=(g.floor_w or 0.0) > 0.0).data()) - - def _reserve_short(self, g) -> bool: - """SAFETY-87: the batteries that can still give, at full power, miss - the limit (`load_too_high()` on `g.able_w`), for ALARM_HOLD_S, as - SAFETY-81 grades 'Load too high'.""" - p, batt = self._peak_proj, self.site_batt_w - if batt is None: - return self._peak_floor_limited - prev, self._reserve_batt_prev = self._reserve_batt_prev, batt - if prev is not None: - batt = min(float(batt), float(prev)) - if not (p is not None and p.block_start is not None - and peakguard.load_too_high(p, batt_w=batt, - ceiling_w=g.ceiling_w, - achievable_w=g.able_w)): - self._reserve_high_since = None - return False - t = p.block_start + timedelta(seconds=float(p.elapsed_s)) - if self._reserve_high_since is None: - self._reserve_high_since = t - return ((t - self._reserve_high_since).total_seconds() - >= peakguard.ALARM_HOLD_S) - - async def check_circulating(self) -> None: - """SAFETY-31 + SAFETY-34. The alarm, and it must survive a restart. - - ⚠️ THE LATCH IS NOT THE ALARM. `circ_tripped` in `/data/state.json` - survives everything, but nothing looks at a JSON file at 3 a.m. What the - operator sees is a `persistent_notification`, and THAT IS IN MEMORY: a - Home Assistant restart deletes it while the fault runs on. This is not a - hypothetical - it is precisely how the 2026-09-02 outage went unseen for - 6 h 25 m with the detector correct the whole time (SAFETY-34). - - So the durable half and the visible half are joined HERE, and the join - is `_circ_announced`: a per-PROCESS flag, deliberately not persisted. - The latch says "this site is tripped"; the flag says "this process has - put that in front of a human". A restart clears the flag and keeps the - latch, so the notification is RE-RAISED on the first cycle after every - add-on start. A Core-only restart does NOT restart the add-on, so it is - also re-asserted every REANNOUNCE_S (SAFETY-34). - - ⚠️ ONE CODE PATH FOR BOTH, ON PURPOSE. A fresh trip and a restart into - an existing trip raise the alarm through these same lines. Two paths - would be two chances for the restart one to rot unnoticed, and the - restart one is the case nobody exercises by hand. - """ - if not self.circ_wd.tripped: - return - if self._circ_announced and not self._reannounce_due("goodwe_circulating_power"): - return - # Set BEFORE the await. `hass.call()` can raise or hang, and a retry - # every cycle for a broker that is down would be an alarm storm on the - # event bus on top of a site that is already stopped. The latch is - # already durable and the log line above already fired; this surface is - # best-effort by design. - self._circ_announced = True - self._announced_mono["goodwe_circulating_power"] = _mono() - names = self.units - pos, neg = opposing([inv.batt for inv in self.inverters], - min_w=self.circ_wd.cfg.min_w / 2.0) - # A fixed notification_id, and a DIFFERENT one from every other alarm - # this add-on raises - check_meter_frozen() gives the reasoning. - await self.hass.call("persistent_notification", "create", - messages.circulating( - [names[i] for i in pos] if pos and neg else (), - [names[i] for i in neg] if pos and neg else (), - ).data()) - - def _reannounce_due(self, notification_id: str) -> bool: - """SAFETY-34: has this latched alarm gone REANNOUNCE_S without being re-asserted?""" - t = self._announced_mono.get(notification_id) - return t is None or _mono() - t >= REANNOUNCE_S - - async def check_not_delivering(self) -> None: - """SAFETY-42 + SAFETY-34. The alarm, and it must survive a restart. - - ⚠️ THE LATCH IS NOT THE ALARM, and this guard has nothing BUT the alarm. - `unit//delivery_tripped` in `/data/state.json` survives everything, - but nothing looks at a JSON file at 3 a.m. What the operator sees is a - `persistent_notification`, and THAT IS IN MEMORY: a Home Assistant - restart deletes it while the fault runs on. That is precisely how the - 2026-09-02 outage went unseen for 6 h 25 m with the detector correct the - whole time (SAFETY-34), and it matters more here than anywhere else in - this file, because SAFETY-02 and SAFETY-31 at least leave a stopped site - for somebody to notice. This one leaves a site that looks like it is - working and is quietly delivering one unit less than it has. - - So the durable half and the visible half are joined HERE, and the join - is `_delivery_announced`: a per-PROCESS set of unit names, deliberately - not persisted. The latch says "this unit is tripped"; membership says - "this process has put that in front of a human". A restart empties the - set and keeps the latch, so the notification is RE-RAISED on the first - cycle after every add-on start, and re-asserted every REANNOUNCE_S - because a Core-only restart does not restart the add-on (SAFETY-34). - - ⚠️ ONE CODE PATH FOR BOTH, ON PURPOSE - `check_circulating()`'s - argument. A fresh trip and a restart into an existing trip raise the - alarm through these same lines; two paths would be two chances for the - restart one to rot unnoticed, and the restart one is the case nobody - exercises by hand. - - ⚠️ AND ONE NOTIFICATION ID PER UNIT. Every other alarm in this file has - a single fixed id because its subject is the site; this one's subject is - a named box, and two wedged inverters must produce two cards rather than - one replacing the other. The id is built from the same `unit_slugs()` - TEL-07 announces the MQTT entities under, so the card and the entity an - operator correlates it with carry the same token. - """ - names = self.units - slugs = unit_slugs(names) - for inv, slug in zip(self.inverters, slugs): - nid = f"goodwe_not_delivering_{slug}" - if not inv.delivery_wd.tripped: - continue - if inv.name in self._delivery_announced and not self._reannounce_due(nid): - continue - # Added BEFORE the await, for `check_circulating()`'s reason: - # `hass.call()` can raise or hang, and a retry every cycle for a - # broker that is down would be an alarm storm on the event bus. The - # latch is already durable and the log line already fired; this - # surface is best-effort by design. - self._delivery_announced.add(inv.name) - self._announced_mono[nid] = _mono() - await self.hass.call("persistent_notification", "create", - messages.not_delivering(inv.name, slug).data()) - - async def check_price_gap(self) -> None: - """PRICE-01. One notification when no price covers now, gone when one does. - - `price_gap` is worked out on the tick from the stored plan. A gap - raises the notification once: the flag is set BEFORE the await, for - `check_circulating()`'s reason (a Home Assistant call can raise or - hang, and a retry every cycle would be a storm). When the gap ends the - same notification is taken down. Control is not touched either way: the - maintenance charge waits because its gate is shut (`_provider_gate`), - and nothing here decides that. - """ - if self.price_gap and not self._price_gap_announced: - self._price_gap_announced = True - await self.hass.call("persistent_notification", "create", - messages.no_prices(*self._gap_args()).data()) - elif not self.price_gap and self._price_gap_announced: - self._price_gap_announced = False - await self.hass.call("persistent_notification", "dismiss", - messages.prices_back().data()) - - async def check_fixed_note(self) -> None: - """PRICE-01 G1. At the first cycle only: one INFO line when a - `static_profile` is set beside `price_service` (it is the plan's last - fallback, not a fault, so no notification), and a dismiss of the card an - earlier build raised, which is harmless when absent.""" - if self._fixed_note_said: - return - self._fixed_note_said = True - if fixed_tariff_beside_service(self.o): - _LOG.info(messages.FIXED_TARIFF_LOG) - try: - await self.hass.call("persistent_notification", "dismiss", - messages.fixed_tariff_card_gone().data()) - except Exception: # noqa: BLE001 - housekeeping never stops a cycle - _LOG.debug("Could not take down the old fixed-tariff card.") - - def _gap_args(self) -> tuple: - """`(since, now)` in Brussels time for the gap's words. `since` is None - when no price was ever published.""" - now = brussels(datetime.now(timezone.utc)) - if self.price_gap_since is None: - return None, now - return brussels(self.price_gap_since), now - - async def check_meter_frozen(self) -> None: - """SAFETY-18. Alarm on a meter that answers forever without changing. - - Notification only - no claim, no latch, no 0 W. freeze.py carries the - reasoning and the euro figure; DOCS.md carries the exposure this does - NOT close. - - ⚠️ getattr, not an attribute access: `unchanged_s` exists only on - `homewizard_local`, and `p1_source` is None until amain() builds the - transport. Every other meter_source hands the predicate None and gets - False, which is the honest answer - see the transport note in freeze.py. - """ - unchanged = getattr(self.p1_source, "unchanged_s", None) - # SITE, all three inputs: one meter, the SITE target the arbiter - # resolved, and the rail the SITE could stand at - which is the summed - # per-unit conjunction, so a small inverter B lowers the site rail rather - # than being graded against inverter A's. - fired = self.freeze_wd.evaluate(unchanged, self.target, - self.site_max_w, - datetime.now(timezone.utc), - dev_min=self.site_dev_bound("dev_min"), - dev_max=self.site_dev_bound("dev_max")) - if not fired: - return - self.log_event("METER FROZEN? " + self.freeze_wd.reason, - hint=messages.hint("meter_frozen")) - _LOG.error( - "The meter shows the same value while the battery is asked for " - "full power, and control still follows it, so check the meter: " - "%s.", messages.reason_code(self.freeze_wd.reason)) - _LOG.debug("Evidence: %s.", self.freeze_wd.reason) - _LOG.debug( - "SAFETY-18: nothing else stops this. The meter still answers, so " - "its age is fresh, the firmware watchdog is fed and the arbiter " - "only bounds the magnitude. Kept up for a quarter of an hour, it " - "sets the month's billed capacity peak.") - # ⚠️ A fixed notification_id, so a second episode REPLACES the first - # rather than stacking. An operator who has to dismiss eleven identical - # notifications learns to dismiss the twelfth without reading it. - await self.hass.call("persistent_notification", "create", - messages.meter_frozen(unchanged).data()) - - # -- tasks --------------------------------------------------------------- - # -- OPT-04: the background tariff refresh ------------------------------- - def fresh_tariff_plan(self, now): - """The stored plan if it is still current, else None. NEVER a stale one. - - ⚠️ THIS IS THE ONE PLACE THE AGE IS JUDGED, and it is public for - `loop_is_following()`'s reason: a check has to be able to assert on the - shipped expression rather than on a transcription that drifts. Both - terms are required - a plan with no timestamp is one nothing stored, and - a timestamped plan older than TARIFF_MAX_AGE_S is a reading from a task - that has stopped answering. - """ - if self.tariff_plan is None or self.tariff_at is None: - return None - if (now - self.tariff_at).total_seconds() > TARIFF_MAX_AGE_S: - return None - return self.tariff_plan - - async def run_tariff_refresh(self) -> None: - """Resolve the tariff off the control path, forever. NEVER on the tick. - - ⚠️ IT CATCHES EVERYTHING AND KEEPS GOING, for MqttPublisher's reason: - a supplier's outage, a certificate expiry, a malformed feed - all of it - is pricing, and the battery does not care. What it must never do is - raise out of here and take the task down, because then the plan freezes - at its last value and looks current forever. That is what - `fresh_tariff_plan()`'s age bound is the backstop for, and this is the - half that keeps the task alive. ⚠️ THE BOUND IS NO LONGER A BACKSTOP - ONLY: since TARIFF-12 it is also the serve-stale window an outage runs - on, and it is consulted below on every refresh. - - ⚠️ AND A FAILURE DOES NOT CLEAR THE PLAN - WHICH IS A CLAIM ABOUT WHAT - `resolve_tariff()` RETURNS, NOT ABOUT WHAT IT RAISES (TARIFF-12). This - paragraph was enforced by the `except` below alone, and the `except` - below is the one path a supplier outage never takes. `load_prices()` - says so in its own words - it "RETURNS, NEVER RAISES, for every failure - a site can actually have" - because a degradation arriving as a - traceback into the planning tick would stop the controller regulating - over an expired certificate. So a dead feed is a RETURN: the `try` - succeeds, `_degrade()` hands back a §11.4 plan, and the assignment used - to overwrite the good one unconditionally. Measured in a 40 h soak with - `static_profile` unset (the shipped default, and the normal state of a - dynamic-tariff site): the FIRST failed fetch replaced a complete 48 h - plan with `TariffPlan(no_data, None, "none")` - 0 points - 27 minutes - after the last good one, and `TARIFF_MAX_AGE_S` governed nothing. A - transient blip cost the same as a 90-minute outage. - - ⚠️ SO THE QUESTION IS ASKED ONCE, AFTER THE ATTEMPT, FROM THE EVIDENCE - THAT EXISTS - FCST-06's answer, in this file. The evidence is - `plan.from_feed` (did this attempt observe the feed) and - `fresh_tariff_plan(now)` (is an observation still current). A - degradation replaces a standing observation only once that observation - has aged out, so `TARIFF_MAX_AGE_S` is now the serve-stale window it - reads like rather than a bound nothing could reach. - - ⚠️ AND A §11.4 STATIC FALLBACK DOES NOT REPLACE A FRESH PROVIDER PLAN - EITHER, although it carries real prices. Every point `_degrade()` - builds is `provisional=True`, so `firm_points()` is empty, - `arbitrage()` refuses and `cheap_now()` is False - everything a - consumer may act on is already off. A day-ahead price for a given hour - does not change once published, so a plan fetched half an hour ago is - exactly as true about that hour as one fetched now. The fallback is - less actionable and no more current; it takes over when the observation - retires, which is what §11.4 is for. The reverse is not symmetrical: a - standing plan that is ITSELF a degradation is replaced by a fresh one, - or an outage would freeze the operator's static profile at the window - it was generated for. - - ⚠️ AND NOTHING HERE READS `arbitrage_enabled`, WHICH TARIFF-10 MAKES - WORTH SAYING. Since that card this task also runs on a site with a - provider configured and trading DISARMED, so "keep the plan" is a - decision about what the add-on has LOOKED UP, not about what it may - trade on. It is also strictly downstream of `resolve_tariff()`: the - §8.3 carry into `price_history` happens on the `series` branch inside - that call, before this decision exists, so which of two plans is kept - cannot add or lose a recorded day. - - ⚠️ AND `tariff_at` DOES NOT MOVE ON A KEPT PLAN. It is the moment the - fetch that produced the standing plan happened, and - `fresh_tariff_plan()` judges the age from it - re-stamping it here - would be this task asserting the feed answered when it did not, and the - plan would "freeze at its last value and look current forever", which - is the hazard the paragraph above this one names. An unmoved - `tariff_at` is also the only thing that tells a kept plan from a - freshly fetched one, so it is what the check asserts. - """ - horizon = float(price_option(self.o, "price_horizon_h")) - while not self.stopping: - now = datetime.now(timezone.utc) - try: - plan = await resolve_tariff( - self.o, now, now + timedelta(hours=horizon), now=now, - history=self.price_history, watch=self.price_watch) - standing = self.fresh_tariff_plan(now) - # Three terms, and each of them is the only false one in some - # check: the feed answered (replace), nothing current stands - # (take the degradation - this is what makes the age bound - # govern), or what stands is itself a degradation (replace). - keep = (not plan.from_feed - and standing is not None and standing.from_feed) - if keep: - _LOG.warning( - "The price update was incomplete, so the plan from %s " - "is kept until it is %s old. The update held %s.", - messages.when(brussels(self.tariff_at)), - messages.duration(TARIFF_MAX_AGE_S), plan.words) - else: - self.tariff_plan, self.tariff_at = plan, now - _LOG.info("tariff refreshed: %s", plan.words) - except Exception as err: # noqa: BLE001 - # ⚠️ NOT THE OUTAGE PATH - see the docstring. `load_prices()` - # returns on every failure a site can have, so what reaches - # here is something nobody expected, and the plan is kept for - # the same reason and on the same terms. - _LOG.warning( - "The price update failed (%s), so the plan from %s is kept " - "until it is %s old, and trading stops then.", - err, messages.when(brussels(self.tariff_at)), - messages.duration(TARIFF_MAX_AGE_S)) - with contextlib.suppress(asyncio.TimeoutError): - await asyncio.wait_for(self.stop_event.wait(), - timeout=TARIFF_REFRESH_S) - - async def run_control(self) -> None: - # ⚠️ EACH INVERTER'S RATING FROM ITS OWN ENTITY, WHICH IS AC 4. There - # was one read of one `setpoint_entity` here, so a second inverter's - # rating was never read at all and its clamp, its freeze rail and the - # peak guard's `achievable_w` were all the first one's numbers. - # Concurrently, for `read_inputs()`'s reason: a slow ESPHome on one unit - # must not delay the controller's start on every other. - async def _limits(inv): - if inv.driver.configured(): - inv.dev_min, inv.dev_max = await self._driver(inv).limits() - await asyncio.gather(*(_limits(inv) for inv in self.inverters)) - entity = self.o.get("setpoint_entity", "") - # ⚠️ THIS USED TO WARN AND CARRY ON, and that was the bug CFG-01 - # exists to remove: a max_w above the device's rating meant - # write_setpoint() silently clamped and the configured ceiling was - # never the real one. - # - # amain() already ran this gate before anything started. It runs - # AGAIN here for one case the gate cannot cover: ESPHome is often - # not up yet when the add-on boots, so hass.limits() returned - # (None, None) and the range checks were skipped rather than - # guessed at. This is the first moment the device's real rating is - # known. If it conflicts, refuse now - stopping deterministically - # through the normal shutdown, which commands 0 W on the way out. - # - # ⚠️⚠️ AND THE `if entity:` THAT USED TO WRAP THE WHOLE BLOCK WAS A - # READER THAT FAILED PERMISSIVE - CFG-04's own hazard, in this file. - # `entity` is the FLAT `setpoint_entity`, which a per-inverter config - # leaves blank (validate rule 9(e) requires it), so on the very config - # this add-on now supports the entire re-check was SKIPPED: no - # inverter's `max_w` was ever graded against the device it is written - # to, and the skip was silent. The flat gate still guards the flat - # rules, because they read flat options and one device's range; the - # per-unit rule runs unconditionally, off the roster, and grades each - # unit against ITS OWN ESPHome. At one inverter `validate_unit_ranges()` - # skips the unit the flat call already graded, so nothing is reported - # twice and the N=1 path is unchanged. - problems = [] - if entity: - _first = self.inverters[0] - problems += validate_startup_config(self.o, _first.dev_min, - _first.dev_max) - problems += validate_unit_ranges(self.inverters, skip_entity=entity) - if problems: - refuse(problems) - self.refused = problems - self.log_event("REFUSED: " + problems[0], - hint=messages.hint("refused")) - # Signal, then return WITHOUT entering the loop. amain() wakes - # on this, runs the normal wind-down (which commands 0 W, or hands - # back a unit whose driver does: SMA-10) and re-raises - # ConfigRefused afterwards, so the exit code is 78 and the - # inverter is left at zero rather than latched. - self.stop_event.set() - return - - last_grid = object() - heartbeat = float(self.o.get("heartbeat_s", 10)) - # ⚠️ SAFETY-12. The floor is a DEADLINE ON THE GAP BETWEEN CYCLES, not a - # second scheduler running alongside the arrival trigger. Every cycle - # resets it, whichever trigger fired, so on a healthy changing meter it - # never elapses and not one existing cycle moves - and therefore no - # change to the per-cycle gain the tuning was measured against. - # - # That is true twice over, and the second reason is the sturdier one: - # the combined cycle rate is max(arrival rate, 1/floor), never the sum. - # At the defaults 1/15 s is strictly slower than the ~1/5 s arrival - # rate, so even a floor that raced the arrivals could not push the loop - # past its nominal healthy rate. The re-tune is unreachable by - # construction, not merely by the reset. ⚠️ That argument holds only - # while floor > the meter's update interval - which is why the schema - # minimum of 5 s deserves the second look validate.py has not given it - # yet: 5 s IS the reference meter's interval, i.e. the one configurable - # value that would double the cycle rate. - # - # Why it has to exist, and it is not only about latency: `self.grid != - # last_grid` alone means a meter that repeats a value runs NO control - # cycles at all. The heartbeat below keeps re-emitting the last command - # and the firmware keeps putting it on the wire, so every indicator - # reads healthy - and, worse, the `inputs missing -> 0 W` claim lives - # INSIDE cycle(), so on a repeating meter THAT SAFETY CLAIM CANNOT FIRE. - # Demonstrated in test_loop.py: constant meter, SoC entity dies at t=4 s, - # and the pre-fix controller holds 220 W through the whole outage with - # the status line still reading "loop -> 220 W". Layer 1 does not cover - # it on a `meter_source: off` install either - no P1 age sensor is - # published, so the firmware has nothing to veto on. Measured on the rig - # during TEL-05: 70 s at a literally constant 350.0 W, 14 arrivals, zero - # cycles. - # - # This is NOT a freeze detector, and deliberately so - see - # HomeWizardLocalSource.unchanged_s for why one cannot be built here (at - # the converged -10 W target a 1 Wh register needs ~6 minutes to move, - # so any freeze threshold false-trips at the exact operating point we - # run at). Nothing here decides whether a repeated reading is true. It - # only stops "the number is the same" from meaning "do not think". - # - # ⚠️ THE 15 s DEFAULT HAS A CEILING IT DOES NOT OWN. It is under - # validate.FIRMWARE_INGEST_VETO_S (30 s) and under meter_max_age_s on - # purpose, so the loop re-decides at least twice inside any window in - # which layer 1 might otherwise be the only thing deciding. If the - # firmware's veto ever moves, this default moves with it - it is not - # independently justified at 15. - floor = float(self.o.get("cycle_floor_s", 15)) - last_cycle = None - while not self.stopping: - await self.read_inputs() - now_mono = asyncio.get_running_loop().time() - # A cycle is one meter update, exactly as on the reference install - - # or the floor elapsing, whichever comes first. - overdue = last_cycle is None or (now_mono - last_cycle) >= floor - if self.grid != last_grid or overdue: - last_grid = self.grid - last_cycle = now_mono - # ⚠️ The FULL cycle, not a degraded one. A floor cycle runs the - # same law on the same inputs as an arrival cycle, because in P1 - # mode the freshness question is already answered upstream and - # answered harder: past `meter_max_age_s` (30 s) p1.net_w is - # None, which is "inputs missing", which becomes a P_SAFETY 0 W - # claim. So a floor cycle cannot run the PI on a 60 s old - # figure, because at 60 s there is no figure. - # - # ⚠️ THAT GUARANTEE IS TRANSPORT-CONDITIONAL, and saying so - # matters more than the guarantee: with `meter_source: off`, - # read_inputs() takes self.grid straight from hass.number() with - # NO age gate at all, so a Home Assistant entity that has gone - # quiet reads as a current value on that path with or without - # this change. Running the full law is still the right choice - # there - the alternative is a degraded second law reasoning - # about an age nobody measured - but the floor does not make - # that path fresh, and nothing here should be read as claiming - # it does. And the integrator - # advances per CYCLE, not per second (control.py), so bounding - # the gap bounds the accumulation: at most one extra - # gain x error per floor interval, under the same - # integrator_max_w as every other cycle. A second, gentler - # control law for floor cycles would be a second set of - # dynamics nobody can test on this hardware. - await self.cycle() - # ⚠️ The heartbeat is not an optimisation. The ESP32 treats silence - # longer than ~30 s as "the controller is gone" and zeroes the - # inverter. Refreshing the SAME value is what proves we are alive. - # - # ⚠️ ONE DEADLINE PER INVERTER, AND THE REFRESHES GO OUT TOGETHER. - # This was ONE `last_beat` and ONE serialised write, so a hung - # `hass.call()` to inverter A consumed inverter B's ~30 s layer-1 - # budget and the firmware zeroed a healthy sibling. Now each unit - # owns its own deadline, each write is dispatched CONCURRENTLY and - # each is bounded by WRITE_BUDGET_S - so the worst a hung A can do - # to B is delay B's NEXT beat by the budget, which is why the budget - # plus the schema's largest `heartbeat_s` has to stay under layer - # 1's veto. That inequality is graded, not asserted. - # - # ⚠️ AND EACH UNIT REFRESHES ITS OWN SHARE, `inv.target`, never the - # site target. A heartbeat that re-emitted the site number would be - # the broadcast fault arriving through the back door, once every - # `heartbeat_s`, on a path with no allocator in it. - await self.send_heartbeats(asyncio.get_running_loop().time(), - heartbeat) - self.publish() - self.loop_pass_mono = time.monotonic() - await asyncio.sleep(1) - - async def send_heartbeats(self, loop_now: float, heartbeat_s: float) -> None: - """Refresh every inverter whose own deadline has come. AC 6 lives here. - - ⚠️ IT IS A METHOD RATHER THAN FIVE LINES INSIDE `run_control()` FOR ONE - REASON: the acceptance criterion is "a hung write to A cannot consume - B's layer-1 budget - verified by injecting the hang", and a check cannot - inject a hang into the middle of a `while not self.stopping` loop that - also sleeps, reads inputs and cycles. Inline, the only thing a test - could grade was its OWN gather of `write_setpoint()` calls - which is a - check on the fixture, and a serialised shipped loop survived it. - Measured: the mutation that replaced the concurrent dispatch with a - `for` loop passed the whole suite while this block was inline. - - `loop_now` is the caller's monotonic clock, the same discipline every - watchdog in this add-on takes its clock by. - """ - due = [inv for inv in self.inverters - if loop_now - inv.last_beat >= heartbeat_s] - if not due: - return - # ⚠️ THE DEADLINE MOVES BEFORE THE WRITE, NOT AFTER IT. Moved after, a - # unit whose write hangs would have its deadline advanced late every - # time and would drift into being re-sent on every tick; and a unit - # whose write RAISED would never have it advanced at all. - for inv in due: - inv.last_beat = loop_now - # ⚠️ CONCURRENTLY. In series, every inverter behind a hung one waits out - # that one's whole budget before its refresh is even attempted - and - # before this card, with no budget at all, it waited out the HTTP - # stack's timeout. That is one inverter's transport fault pushing a - # healthy sibling towards layer 1's ~30 s veto. - await asyncio.gather(*( - self.write_setpoint(inv.target, force=True, unit=inv) - for inv in due)) - - def publish(self) -> None: - # ⚠️ SITE TOTALS, AND THE KEYS DO NOT MOVE. These entities are already - # discovered and already on every dashboard (TEL-07 keeps their - # `unique_id`s), so `battery` stays the number the meter sees the - # battery doing - the SUM - and `soc` stays the one a floor is graded - # against - the EMPTIEST pack. At the shipped roster of one both are - # inverter A's own readings, unchanged. Per-inverter entities are - # TEL-07's, not a key rename here. - values = { - "setpoint": self.target, - "grid": self.grid, - "battery": self.site_batt_w, - "soc": self.pack_floor_soc, - "phase": self.maint.phase, - # ⚠️ SAFETY-02's alarm surface, and it is deliberately an existing - # one. IF-01/IF-02 own `ems/event/failsafe` and the `failsafe active` - # binary sensor and neither is built yet; inventing a bespoke topic - # here would be a surface to migrate later. This sensor is already - # discovered, already on every dashboard, and "failsafe" is - # additive to its vocabulary rather than a change to it. - # SAFETY-30 adds the site sign latch to the same vocabulary, for - # the reason the note above gives: "failsafe" is additive to a - # sensor that already exists and is already on every dashboard, and - # a P_SAFETY stop that did not reach it would be a site at 0 W - # reporting "running". - "status": ("failsafe" if any(i.sign_wd.tripped - for i in self.inverters) - or (self.site_sign_wd.tripped - and len(self.inverters) > 1) - or self.circ_wd.tripped - # SAFETY-10: "shadow" is its own value and not a - # flavour of "stopped". A fleet dashboard reporting a - # shadow install as `running` would be calling a - # battery nobody is controlling healthy; one reporting - # it as `stopped` would lose the fact that the decision - # path is live and being recorded. ⚠️ BELOW `failsafe`: - # a latch that is up is up, and shadow does not clear it. - else "shadow" if self.shadow - else "running" if self.auto else "stopped"), - # SAFETY-31. ⚠️ MEASURED, not the allocation record - see - # `site_circulating_w`. `publish()` drops None values, so a cycle - # with a missing per-unit reading leaves the last figure standing - # rather than publishing a zero that would read as health. - "circulation": (None if self.site_circulating_w is None - else round(self.site_circulating_w)), - # TEL-10. The loop's own three, written from the fields `cycle()` - # recorded and not re-derived here - the page and the publisher run - # on their own tasks and `self.target` has moved on by the time - # either of them looks (SAFETY-47's note on `sized_from_meter`, one - # field up, is the same hazard). - "loop_i": round(self.loop_i_w, 1), - "loop_lead": round(self.loop_i_lead, 1), - "loop_reason": self.loop_reason, - } - # --- TEL-11 ---------------------------------------------------------- - # ⚠️ THE KEY IS PRESENT WITH THE VALUE `None` WHEN THERE IS NO READING, - # AND ABSENT ENTIRELY WHEN THERE IS NO SOURCE. Those are two different - # states and the publisher treats them as two: `mqtt.ABSENT_AS_UNKNOWN` - # turns the first into HA's own `None` payload, so the entity's state - # goes to `unknown` and the recorder records a GAP - which is how a - # reader of a week of history tells "no PV reported" from "PV reported - # 0 W". The second never reaches the broker at all, because an install - # that never set `pv_entity` or `pv_entities` has no such entity - # announced. ⚠️ TEL-12: AND THE ROW IS STILL ONE NUMBER. At a roster of - # three it is the SITE total, `None` unless EVERY entity answered - see - # `pv.total()`, whose note is where the decision not to publish a - # partial sum is argued. This line did not have to change for that, and - # that is the point: TEL-11's `None`-is-an-absence rule already covered - # it, one layer up. - # - # ⚠️ AND THE GATE IS `optional_keys()`, THE SAME EXPRESSION THE - # ANNOUNCEMENT USES. Written as a second predicate here the two could - # disagree, and both directions are bad - an announced entity nothing - # feeds, or a topic nothing declared. `announced_units()` two blocks - # down is the same discipline for the roster. - if "pv" in optional_keys(self.o): - values["pv"] = (None if self.pv_w is None - else round(self.pv_w, 1)) - # ⚠️ ONLY when P1 ingestion is actually running. The ESP32's stale-input - # watchdog subscribes to sensor.goodwe_p1_sample_age - see the entity-id - # note in mqtt.py; the composed name is not the object_id - and forces layer-1 - # failsafe once it reaches max_age_s. With meter_source off there is no - # ingester feeding it, so published_age_s would be time-since-startup - # climbing without bound - i.e. every existing install would cross the - # threshold within 30 s and pin its inverter at 0 W forever. Publishing - # nothing leaves the entity non-existent, which is the status quo and - # what has_state() in the firmware is checking for. - if self.p1_enabled: - # Recomputed here, once a second, on purpose - see P1Ingest. - values["p1_age"] = round(self.p1.published_age_s, 1) - # TEL-07. THE PER-UNIT ROWS, AND THE EMPTY LIST IS THE GATE. - # - # ⚠️ THERE IS NO `if len(self.inverters) > 1` HERE, DELIBERATELY. - # `announced_units()` answers `[]` at a roster of one, `zip` then yields - # nothing, and the values dict comes out byte-identical to what shipped - - # so the condition that decides what is ANNOUNCED is the same expression - # that decides what is PUBLISHED. Written as a second predicate, the two - # could disagree, and both directions are bad: an announced entity - # nothing feeds (the hazard `omit` exists for) or, at N=1, a published - # topic nothing announced, which AC 4 forbids outright. - # - # ⚠️ AND THE SITE ROWS ABOVE DO NOT MOVE. `battery` stays the SUM and - # `soc` stays the EMPTIEST pack; these are additions beside them, not a - # re-pointing of them, because those two ids are on the live install's - # dashboards and in its automations. - names = announced_units([inv.name for inv in self.inverters]) - for inv, slug in zip(self.inverters, unit_slugs(names)): - values[unit_state_key(slug, "setpoint")] = inv.target - values[unit_state_key(slug, "battery")] = inv.batt - values[unit_state_key(slug, "soc")] = inv.soc - values[unit_state_key(slug, "sign_latch")] = ( - "tripped" if inv.sign_wd.tripped else "clear") - # OPT-11 P2: each battery's mode and switch; nothing while modes are off. - values.update(self.mode_values()) - self.mqtt.publish(values) - async def shutdown(self) -> None: """Deterministic wind-down. Do not skip this.""" self.stopping = True @@ -7218,1064 +1022,22 @@ class Controller: await self.command_site_release() self.mqtt.close() - async def command_site_release(self) -> None: - """SMA-10. The add-on is going away (Stop, shutdown, restart, task - death, a config refusal): every unit that hands back is given back, and - every other unit is held at 0 W exactly as `command_site_zero()` does. - - ⚠️ THE SAFETY STOPS AND REFUSALS DO NOT COME HERE. A sign trip, a - refused write, a missing reading, another writer: those are the add-on's - own decisions and hold 0 W through `write(0)` for EVERY unit, handed-back - drivers included. `command_site_zero()` is that, and it is unchanged. A - unit the add-on has just declared it cannot trust must not be handed to - something else that will then do what it likes with the battery. - - ⚠️ A ROSTER WITH NO HAND-BACK UNIT IS `command_site_zero()`, line for - line: GoodWe's release is its 0 W write, so Stop keeps today's write - and today's heartbeat. - - ⚠️ ONE UNIT'S FAILURE IS ITS OWN. `_hand_back()` never raises and is - bounded by RELEASE_BUDGET_S; the units run concurrently, so the whole - call takes no longer than its slowest bound. - """ - if not any(inv.driver.hands_back for inv in self.inverters): - await self.command_site_zero(last=True) - return - self.target = 0.0 - for inv in self.inverters: - inv.target = 0.0 - await asyncio.gather(*( - self._hand_back(inv, force=True) if inv.driver.hands_back - else self._write_unit(inv, 0.0, force=True, last=True) - for inv in self.inverters)) - - async def command_site_zero(self, *, last: bool = False) -> None: - """Every inverter to 0 W, and every inverter's TARGET to 0 W with it. - - ⚠️ THE SECOND HALF IS NOT BOOKKEEPING, AND IT IS A HAZARD DEV-02 - CREATED. Before this card the heartbeat re-emitted `self.target`, so - zeroing that one scalar was enough: the stop button set it and the next - refresh carried the zero. The heartbeat now re-emits `inv.target` - it - has to, or it would broadcast the site number - so a stop that zeroed - only `self.target` would leave each unit's LAST SHARE standing, and the - very next heartbeat (up to `heartbeat_s` later, and before any cycle has - run) would put it back on the wire. The operator would have pressed - stop, watched the inverter go to zero, and seen it resume seconds later. - Both must move together, which is why this is one method with a reason - and not two lines repeated at three call sites. - - ⚠️ AND 0 W IS THE ONE VALUE THAT MAY BE WRITTEN SITE-WIDE. It means the - same thing to every inverter; a non-zero site-wide write is the ARCH-01 - broadcast fault, and `write_setpoint()` refuses it. - """ - self.target = 0.0 - for inv in self.inverters: - inv.target = 0.0 - await self.write_setpoint(0.0, force=True, last=last) - - # -- UI ------------------------------------------------------------------ - def checks(self, when: datetime | None = None) -> list: - """The status rows. `when` is the reference time for anything billed by - the calendar - today's month when it is None, which is what the live - page means; `status_payload()` calls this with no argument. - - ⚠️ IT EXISTS SO THE PEAK ROW CAN BE GRADED (TEST-17). Every other peak - query already takes it - `PeakStore.peak()`, `PeakTracker.peak()`, - `headroom_w()`, `warning_frac()` - and the row built from them was the - one thing that could only be read against `datetime.now()`. A suite - that banks an August quarter then asks this page what the peak is goes - green in August and red in September, which is what happened at 00:00 - on 2026-09-01: TARIFF-01's own section 10, red on a calendar boundary, - on a commit nobody had touched for a day. - """ - o = self.o - out = [] - # SAFETY-61. First, so a stalled loop is the headline: the heartbeat is - # sent from this loop, so past layer 1's veto the inverter is at 0 W. - if self.loop_pass_mono is None: - out.append({"ok": True, "warn": False, "id": "controller", - "text": messages.row_controller_starting()}) - else: - _pass_age = time.monotonic() - self.loop_pass_mono - if _pass_age > FIRMWARE_INGEST_VETO_S: - out.append({"ok": False, "warn": False, "id": "controller", - "text": messages.row_controller_stalled( - _pass_age, FIRMWARE_INGEST_VETO_S)}) - else: - out.append({"ok": True, "warn": False, "id": "controller", - "text": messages.row_controller_ran(_pass_age)}) - # SAFETY-112. The headline unless control has stalled: while the - # Supervisor gives 502 (Home Assistant not yet RUNNING) no reading or - # write gets through, and the rows below that need it follow from it. - if OUTAGE.waiting(): - out.insert(1 if out[0]["ok"] is False else 0, - {"ok": False, "warn": False, "id": "home_assistant", - "banner": messages.banner_ha_waiting(), - "text": messages.row_ha_waiting()}) - if self.p1_enabled: - age = self.p1.published_age_s - if (self.p1.stale and self.p1.age_s() is None - and age <= self.p1.max_age_s): - # UX-10: no reading yet since the start, still inside the - # limit. Amber, not red: it is not a fault yet, but control - # waits for it. Red at 0 s contradicted the limit the row - # prints. Past the limit it is the red row below, as before. - out.append({"ok": False, "warn": True, "id": "meter", - "text": messages.row_meter_waiting( - self.p1.max_age_s)}) - elif self.p1.stale: - # The last error is on the add-on log's WARNING line (p1.py). - out.append({"ok": False, "warn": False, "id": "meter", - "text": messages.row_meter_stale( - age, self.p1.max_age_s)}) - else: - # ⚠️ unchanged_s is REPORTED, never thresholded and never folded - # into the age - see HomeWizardLocalSource.unchanged_s for why - # (at the converged -10 W this controller aims for, a 1 Wh - # register needs ~6 minutes to move, so any limit false-trips at - # the exact operating point we target). The whole argument for - # leaving it unthresholded is that a human interprets it, which - # requires a human being able to see it - so here it is. getattr: - # only homewizard_local has one, and p1_source is None until - # amain() builds the transport. - unchanged = getattr(self.p1_source, "unchanged_s", None) - out.append({"ok": True, "warn": False, "id": "meter", - "text": messages.row_meter( - self.p1.net_w, age, self.p1.parse_errors, - unchanged)}) - # SAFETY-18. Reported in both states, for the reason SAFETY-02 is: - # a detector nobody can see is armed is a detector nobody trusts - # when it fires. ok=False/warn=False so the banner goes red - this - # is an alarm, and the banner is the loudest surface we own. It - # changes NOTHING about control; see check_meter_frozen(). - if self.freeze_wd.active: - # The figures are in `freeze_wd.reason`, on the log and the - # event list (check_meter_frozen()). - out.append({"ok": False, "warn": False, "id": "meter_frozen", - "text": messages.row_meter_frozen()}) - elif getattr(self.p1_source, "unchanged_s", None) is None: - # Not "armed". Every transport but homewizard_local is invisible - # to this check, and saying "armed" there would be a lie the - # status page tells on behalf of a guard that cannot run. - out.append({"ok": False, "warn": True, "id": "freeze_check", - "text": messages.row_freeze_off("source")}) - elif rail_unreachable(self.site_max_w, - dev_min=self.site_dev_bound("dev_min"), - dev_max=self.site_dev_bound("dev_max")): - # SAFETY-20, and THE SECOND REASON TO USE THIS ROW RATHER THAN A - # NEW MECHANISM. The transport case above and this one are the - # same statement - "the conjunction cannot be evaluated here" - - # and an operator does not need to learn two vocabularies for - # it. What differs is only which term is missing: there, - # `unchanged_s`; here, a rail the command could ever stand at. - _no_rating = (not self.site_max_w - or not is_commandable(self.site_max_w)) - out.append({"ok": False, "warn": True, "id": "freeze_check", - "text": messages.row_freeze_off( - "rating" if _no_rating else "range")}) - else: - # ⚠️ SAFETY-20. THE RAIL PRINTED HERE IS THE RAIL THE PREDICATE - # USES, device range included. This row used to interpolate - # `rail_w(max_w)` while `looks_frozen()` graded a command the - # device had already clipped below it, so on any install whose - # inverter is smaller than its configured ceiling the page named - # a number the command could never reach and called it `armed`. - # Both the row and the predicate now read the same three inputs. - _rail = rail_w(self.site_max_w, - dev_min=self.site_dev_bound("dev_min"), - dev_max=self.site_dev_bound("dev_max")) - # And when the device is what set that number, SAY SO - the - # operator configured `max_w` and is owed the reason the guard - # is armed somewhere else. - # ⚠️ Either bound may be None on its own - `hass.limits()` - # reads `min` and `max` independently and returns None for - # whichever attribute is missing or unparseable - so this - # renders whatever is there rather than formatting a None. - # UX-08: "the inverter's own limit" says the device set it; which - # inverter and its range are DOCS and the settings, not entity ids. - out.append({"ok": True, "warn": False, "id": "freeze_check", - "text": messages.row_freeze_on( - self.freeze_wd.cfg.hold_s, _rail, - own_limit=_rail < rail_w(self.site_max_w))}) - - # TARIFF-01. The month's billed peak, and - the load-bearing half - - # a DIFFERENT row when the store could not answer. "no peak yet" is - # a normal state on the 1st; "unreadable" is a broken instrument, and - # a status page that spelled them the same way would let a 0 W read - # look like a quiet month right up until SAFETY-07 shaved nothing. - # UX-08: in plain words. The store's state at start is on the INFO - # line `capacity-tariff peak store: ...` and `_pk.explain()` on the - # log; the coverage figure (TARIFF-13) is a row of its own. - _pk = self.peak.peak(when) - if _pk.is_unreadable: - out.append({"ok": False, "warn": True, "id": "month_peak", - "text": messages.row_month_peak_unreadable()}) - else: - # §9.1's "warning entity at 80 %", as a status row rather than - # a second entity - see the constructor on not doubling up. - _frac = self.peak.warning_frac(when) or 0.0 - _ok = _frac < 0.8 - out.append({"ok": _ok, "warn": not _ok, "id": "month_peak", - "text": (messages.row_month_peak_none() - if not _pk.is_observed else - messages.row_month_peak( - _pk.peak_w, - brussels(_pk.quarter_start), - _frac))}) - out.append({"ok": True, "warn": False, "id": "periods_measured", - "text": messages.row_periods_measured( - self.peak.recorded)}) - - # SAFETY-07. Three rows, not one, because "idle" and "cannot see" - # are opposite states and a page that spelled them the same way - # would show a green line over a guard that is switched off. `None` - # is a fourth state on purpose: before the first cycle the guard has - # concluded nothing, and saying "idle" then would be a claim about a - # decision that has not been taken. - _pg = self.peak_guard - if _pg is None: - out.append({"ok": True, "warn": True, "id": "peak_guard", - "text": messages.row_peak_guard_waiting()}) - elif _pg.saturated and not _pg.within_aim: - out.append({"ok": False, "warn": False, "id": "peak_guard", - "runs": True, - "text": messages.row_peak_saturated(_pg.ceiling_w)}) - elif _pg.floor_limited and ( - not ((_pg.floor_w or 0.0) > 0.0 or _pg.within_aim) - or self._peak_floor_limited): - # SAFETY-24. NOT ok, like saturation: in both states the money - # is going to be spent and a human is the only actuator left. A - # separate row from saturation because the two ask for opposite - # things - see check_peak_floor_limited(). - # - # ⚠️ SAFETY-25. THE SCOPE SENTENCE IS PART OF THE ROW, NOT A - # DOCS FOOTNOTE. This is the one line an operator reads at the - # exact moment the guard stops discharging, and read alone it - # says "the battery is being held at peak_soc_floor" - which is - # false, and measurably so: on the committed evening replay the - # loop goes on discharging in EVERY cycle this row is showing. - # A floor that binds one consumer and not the other is worse - # than no floor if the page does not say which. - # - # ⚠️ AND IT CARRIES ITS OWN `banner`. status_payload() renders - # the FIRST not-ok/not-warn row as the page's headline, so - # without this the loudest element on the page would be a - # 550-character paragraph that the row three lines below - # repeats verbatim. The banner is the short form; the row keeps - # the whole sentence, because the row is where an operator - # reads what the floor does and does not bound. Shortening the - # ROW instead would be weakening AC 3. - # UX-08: the same three branches, and the same pack naming, as - # check_peak_floor_limited()'s notification. The figures stay in - # `_pg.reason`, on the log and the event list. - # SAFETY-87: `runs`, control goes on (status_payload()). - out.append({"ok": False, "warn": False, "id": "peak_guard", - "runs": True, - "banner": messages.banner_peak_reserve(), - "text": messages.row_peak_reserve( - _pg.ceiling_w, soc_unread=_pg.soc is None, - floor_unknown=(_pg.soc is not None - and _pg.soc_floor is None), - packs=(_pg.held if len(self.inverters) > 1 - else ()), - others=(_pg.floor_w or 0.0) > 0.0)}) - elif _pg.blind: - out.append({"ok": False, "warn": True, "id": "peak_guard", - "text": messages.row_peak_guard_blind( - peakguard.blind_kind(_pg.blind))}) - elif self.peak_unmeasured_s > 0.0: - # SAFETY-90: the start of this quarter came before the first - # reading, and the guard counts it as high use. - out.append({"ok": False, "warn": True, "id": "peak_guard", - "text": messages.row_peak_guard_unmeasured()}) - elif _pg.engaged: - out.append({"ok": False, "warn": True, "id": "peak_guard", - "text": messages.row_peak_guard_on( - _pg.floor_w or 0.0, _pg.ceiling_w, - shadow=self.shadow)}) - elif _pg.projected_w is not None: - # SAFETY-125: "under" only when it is; over the limit at this - # rate, a grid charge is cut back to the quarter's room. - out.append({"ok": True, "warn": False, "id": "peak_guard", - "text": messages.row_peak_guard_idle( - _pg.projected_w, _pg.ceiling_w, - month_peak=(_pg.ceiling_from - == peakguard.CEILING_MONTH_PEAK), - cut=self.room_charge and not self.shadow)}) - else: - out.append({"ok": True, "warn": False, "id": "peak_guard", - "text": _pg.explain()}) - else: - # ⚠️ OUTSIDE the `p1_enabled` block, and that placement is the point. - # SAFETY-07 is NOT COVERED on the legacy single-entity path - the - # quarter-hour average is measured from P1 telegrams and this path - # has none - and a row that only rendered where the guard runs would - # leave the one install that is unprotected showing nothing at all. - # Same answer, same reason, as the freeze detector's NOT COVERED row - # a few lines up. - out.append({"ok": False, "warn": True, "id": "peak_guard", - "text": messages.row_peak_guard_off()}) - - # ⚠️ ONE PAIR OF ROWS PER INVERTER, NAMED. A single "battery SoC" row on - # a site with two packs is a page that shows one pack and calls it the - # site. The label keeps its exact wording at a roster of one, because - # that is what an existing install reads. - rows = [] - for inv in self.inverters: - unit = None if len(self.inverters) == 1 else inv.name - rows.append((messages.LABEL_SOC, unit, inv.soc, - inv.driver.soc_source())) - rows.append((messages.LABEL_BATTERY, unit, inv.batt, - inv.driver.batt_source())) - if not self.p1_enabled: - # In P1 mode the check above replaces this one; leaving both in - # would report "no entity configured" for a meter_entity that is - # correctly unused, i.e. a permanent false NOT READY. - rows.insert(0, (messages.LABEL_GRID, None, self.grid, - o.get("meter_entity"))) - # UX-08: the rows name the setting, never the entity id (STYLE.md). - for label, unit, value, entity in rows: - if not entity: - out.append({"ok": False, "warn": False, "id": "sensor", - "text": messages.row_sensor_unset(label, unit)}) - elif value is None: - # ⚠️ SAFETY-56. THIS ROW ASSERTED A FALSE FACT ABOUT A NAMED - # ENTITY, WHICH IS THE WORST THING A DIAGNOSTIC CAN DO. It read - # " is missing or not numeric" for ANY None, and one of - # the ways this value becomes None is SAFETY-37's freshness gate - # withholding a reading that is present, numeric and updating - - # `Freshness.reading()` returns None BY DESIGN there. On the - # live site on 2026-09-21 the operator opened Developer Tools on - # the entity this row named, found it working, and had every - # reason to conclude the diagnostics were broken. - # - # ⚠️ AND IT IS FIXED BY SAYING LESS, NOT BY LOOKING HARDER. The - # row could ask `inv.batt_fresh.stale` - it is on the same - # object at the same moment - but this loop also renders the - # grid and SoC rows, which have no gate, and a branch per row - # would be a second place where "why is this None" is decided. - # The gate already has a surface of its own: `stale_note()` - # rides `liveness_notes()` a few rows below with the whole - # STALE_READING sentence in it, so the operator's discriminator - # is "is that row there?" and this row's job is only to stop - # pre-empting the answer. Same reason the wording is not shared - # with `freshness._grade()`: that one is a log line about a - # BEHAVIOUR, this one is a banner about an ENTITY. - out.append({"ok": False, "warn": False, "id": "sensor", - "text": messages.row_sensor_unusable(label, unit)}) - else: - out.append({"ok": True, "warn": False, "id": "sensor", - "text": messages.row_sensor(label, value, unit)}) - - for inv in self.inverters: - unit = None if len(self.inverters) == 1 else inv.name - if not inv.driver.configured(): - out.append({"ok": False, "warn": False, "id": "control", - "text": messages.row_control_unset(unit)}) - elif inv.dev_max is None: - out.append({"ok": False, "warn": False, "id": "control", - "text": messages.row_control_missing(unit)}) - else: - out.append({"ok": True, "warn": False, "id": "control", - "text": messages.row_control(inv.dev_min, - inv.dev_max, unit)}) - - # DEV-02. Whether this controller can still put a number on each - # inverter, and it is reported in the ONE state that matters: a unit - # `live_units()` has stopped listing has had its share handed to its - # siblings, or - at a roster of one - has taken the site to 0 W. A - # dropped link that shows nothing on the page reads as a healthy site. - # Red only for a unit that is no longer live; the rest are amber. - # The same notes, in the same order, as `liveness_notes()`. - _now = datetime.now(timezone.utc) - for inv in self.inverters: - for note, red in ((inv.link_note(_now), not inv.is_live(_now)[0]), - (inv.stale_note(), False), - (inv.refusal_note(), False)): - if note: - out.append({"ok": False, "warn": not red, "text": note}) - if self.answer.late_seen: # SAFETY-128 - out.append({"ok": False, "warn": True, "id": "late", - "text": messages.row_readings_late( - self.answer.shown_s, self._late_zero)}) - - # SAFETY-03. Red while an over-rating clamp is engaged (amber for the - # integrator bound, SAFETY-40), and the engagement COUNT is shown even - # after it clears - a row that vanishes with the condition takes the - # evidence with it. Reported only when there is something to report: - # unlike the freeze detector this guard has no "not covered" state, it - # runs on every write on every transport. - # UX-07 item 1 / UX-08: each count is shown under ITS alarm's name - - # over-rating cuts as "Power request too high", integrator-bound cycles - # as "Battery is not keeping up" - never the two summed under one. - _cw = self.clamp_wd - if _cw.active and _cw.bug: - out.append({"ok": False, "warn": False, "id": "power_too_high", - "banner": messages.banner_power_too_high(), - "text": messages.row_power_too_high( - _cw.facts, _cw.over_rating, shadow=self.shadow)}) - elif _cw.active: - # SAFETY-40: the integrator bound alone is amber, not red. - out.append({"ok": False, "warn": True, "id": "not_keeping_up", - "text": messages.row_not_keeping_up( - _cw.bound_episodes)}) - # No over-rating in THIS episode (`bug` would be set), so any count - # is from an earlier one: keep that software-fault evidence shown. - if _cw.over_rating: - out.append({"ok": False, "warn": True, "id": "power_too_high", - "text": messages.row_before( - messages.T_OUTPUT_CLAMP, _cw.over_rating)}) - else: - if _cw.over_rating: - out.append({"ok": False, "warn": True, "id": "power_too_high", - "text": messages.row_before( - messages.T_OUTPUT_CLAMP, _cw.over_rating)}) - if _cw.bound_episodes: - out.append({"ok": False, "warn": True, "id": "not_keeping_up", - "text": messages.row_before( - messages.T_LOOP_BOUND, _cw.bound_episodes)}) - - for inv in self.inverters: - if inv.last_write_ok is False: - out.append({"ok": False, "warn": False, "id": "write", - "text": messages.row_write_refused( - None if len(self.inverters) == 1 - else inv.name)}) - - # SAFETY-02. Reported in both states: a watchdog nobody can see is armed - # is a watchdog nobody trusts when it fires. - # ⚠️ ONE ROW PER INVERTER, because there is one watchdog per inverter - # and a trip on B leaves A commanding. A single row would have to pick - # one of them to describe, and the honest answer at a roster of two is - # both. At a roster of one the wording is unchanged. - # ⚠️ AND SINCE SAFETY-30 THE ROW SAYS WHAT THE UNIT WAS COMPARED - # AGAINST, because at a roster of two that is no longer the meter and a - # row that still said "the command opposed the meter" would send an - # operator to look at P1 for a fault that is visible only on one - # inverter's own power sensor. `sign_wd.against` is the same string the - # trip sentence uses, so the two cannot drift apart. - for inv in self.inverters: - unit = None if len(self.inverters) == 1 else inv.name - # ⚠️ ADDED ONLY WHEN THERE IS SOMETHING TO DISAMBIGUATE. At the - # shipped roster of one the two sentences below are the ones that - # have always been on the page, word for word - AC 8 is about what - # an operator sees as much as about what the detector computes, and - # "opposed a meter reading" would be a gratuitous change to a line - # somebody has learned to recognise. At N>=2 the noun is load- - # bearing: the row would otherwise send them to look at P1 for a - # fault that is visible only on one inverter's own power sensor. - # UX-08: at N>=2 `unit` is set, and the row says "its own power". - # The figures stay in `sign_wd.reason`, on the log and event list. - if inv.sign_wd.tripped: - out.append({"ok": False, "warn": False, "id": "direction", - "text": messages.row_direction_trip(unit)}) - else: - held = inv.sign_wd.held_s(datetime.now(timezone.utc)) - out.append({"ok": True, "warn": False, "id": "direction", - "text": messages.row_direction_check( - held, inv.sign_wd.cfg.hold_s, unit)}) - - # --- SAFETY-30: the SITE row ----------------------------------------- - # ⚠️ ONLY AT N>=2, and the absence at N=1 is the honest report rather - # than a missing row. With one inverter the site comparison and the row - # above are the same sentence about the same actuator; printing it twice - # would advertise two guards where there is one, which is how an - # operator learns to skim the list. - if len(self.inverters) > 1: - if self.site_sign_wd.tripped: - out.append({"ok": False, "warn": False, "id": "site_direction", - "text": messages.row_site_direction_trip()}) - else: - _sheld = self.site_sign_wd.held_s(datetime.now(timezone.utc)) - out.append({"ok": True, "warn": False, "id": "site_direction", - "text": messages.row_site_direction_check( - _sheld, self.site_sign_wd.cfg.hold_s)}) - - # --- SAFETY-31 ----------------------------------------------------- - # ⚠️ SITE-LEVEL, WHERE THE ROWS ABOVE ARE PER-INVERTER, and the row says - # so. There is one circulating figure for the site; naming an inverter - # here would invite the operator to clear "the other one". - _circ = self.site_circulating_w - if self.circ_wd.tripped: - out.append({"ok": False, "warn": False, "id": "circulating", - "text": messages.row_circulating_trip()}) - elif len(self.inverters) <= 1: - # AC 5. At the shipped roster the quantity is identically zero for - # every value of every reading, so "armed" would be a claim to be - # watching something that cannot happen. Say what is true instead. - out.append({"ok": True, "warn": False, "id": "circulating", - "text": messages.row_one_inverter( - messages.CHECK_CIRCULATING)}) - else: - held = self.circ_wd.held_s(datetime.now(timezone.utc)) - out.append({"ok": True, "warn": False, "id": "circulating", - "text": messages.row_circulating_check( - _circ, held, self.circ_wd.cfg.hold_s)}) - - # --- SAFETY-42 ------------------------------------------------------- - # ⚠️ PER INVERTER, AND WARN RATHER THAN BAD, WHICH IS THE ONE PLACE THE - # "reports, does not act" DECISION IS VISIBLE TO AN OPERATOR. Every - # other latched row in this list means the site is at 0 W and a red - # cross is the truth. This one means the site is STILL RUNNING and is - # quietly short by one unit's share; rendering it as a hard failure - # would say the controller had stopped, which it has not. It is not "ok" - # either - `ok: False` with `warn: True` is this list's caution, and a - # caution is what a fault nobody is acting on actually is. - if len(self.inverters) > 1: - for inv in self.inverters: - if inv.delivery_wd.tripped: - out.append({"ok": False, "warn": True, "id": "delivery", - "text": messages.row_not_delivering(inv.name)}) - else: - _dheld = inv.delivery_wd.held_s(datetime.now(timezone.utc)) - out.append({"ok": True, "warn": False, "id": "delivery", - "text": messages.row_delivery_check( - inv.name, _dheld, - inv.delivery_wd.cfg.hold_s)}) - else: - # AC 5, and the same honesty `circulating power: n/a` uses one block - # up. At one inverter the reduction this check is has no proper - # subset to find, for EVERY input, so "armed" would be a claim to be - # watching something that cannot happen. - out.append({"ok": True, "warn": False, "id": "delivery", - "text": messages.row_one_inverter("Delivery check")}) - - if not o.get("estop_fitted", False): - out.append({"ok": False, "warn": True, "id": "estop", - "text": messages.row_no_estop()}) - else: - out.append({"ok": True, "warn": False, "id": "estop", - "text": messages.row_estop_fitted()}) - - if not o.get("peak_forecast_entity"): - # ok=False + warn=True renders as a caution, not a pass. A check that - # is both is a check nobody reads. - out.append({"ok": False, "warn": True, "id": "peak_forecast", - "text": messages.row_no_peak_forecast()}) - elif getattr(self, "_peak_fc_fault", None) is not None: - out.append({"ok": False, "warn": True, "id": "peak_forecast", - "text": messages.row_peak_forecast_unit( - self._peak_fc_fault)}) - # OPT-17: a forecast summed from several entities names, by position, - # each member with no usable reading. A caution: control goes on. - gaps = getattr(self, "solar_fc_gaps", ()) - for day, ents in (("today", getattr(self, "fc_entities", ())), - ("tomorrow", - getattr(self, "fc_tomorrow_entities", ()))): - gone = [i for d, i, _e, _w in gaps if d == day] - if gone: - out.append({"ok": False, "warn": True, "id": "solar_forecast", - "text": messages.row_forecast_gap( - day, gone, len(ents))}) - # --- TEL-11 ---------------------------------------------------------- - # ⚠️ NO ROW AT ALL WHEN THE ROSTER IS EMPTY, AND THAT IS A DELIBERATE - # DIFFERENCE FROM THE PEAK-FORECAST CAUTION DIRECTLY ABOVE. That one - # nags because an unset forecast entity leaves a MONEY GUARD without an - # input; this one is pure instrumentation, and a permanent caution on - # every install that never asked for a PV channel is exactly the - # "no warning spam, no degraded status row" the card forbids. - # - # ⚠️ AND WHEN IT IS SET, A FAILED READ IS `ok=False, warn=True` - a - # CAUTION, never `bad`. `status_payload()` builds "NOT READY" from rows - # that are neither ok nor warn, and a telemetry channel that could put a - # battery site into NOT READY would be observability with a foot in the - # control path. The reason comes from `pv.watts()` rather than being - # re-derived here, so the page cannot disagree with the reading. - # - # TEL-12 kept 0.11.0's single-entity sentences word for word. UX-08 - # replaced them on purpose (DECISIONS/UX-08-short-notifications.md), so - # a `tools/tel11_pv_trace.py` compare against a pre-UX-08 tree shows - # these rows as changed telemetry; the control documents stay equal. - roster = self.pv_roster - if roster: - # UX-08: sources are numbered in the order of the settings list, - # never named by entity id (STYLE.md). The per-source figures and - # units are what `pv.total()` returns; they stay in `pv_parts`. - flip = pv_read.inverted(self.o) - n_src = len(roster) - if self.pv_w is None and n_src == 1: - out.append({"ok": False, "warn": True, "id": "pv", - "text": messages.row_pv_none(self.pv_why)}) - elif self.pv_w is None: - # ⚠️ THE ROW THAT SAYS THERE IS NO TOTAL, AND IT SAYS IT IN - # THOSE WORDS - and which sources are missing, by position. - out.append({"ok": False, "warn": True, "id": "pv", - "text": messages.row_pv_partial( - [i + 1 for i, (_e, watt, _y) - in enumerate(self.pv_parts) if watt is None], - n_src)}) - else: - out.append({"ok": True, "warn": False, "id": "pv", - "text": messages.row_pv( - self.pv_w, n_src, - n_src == 1 and roster[0] in flip)}) - # ⚠️ AND WHEN BOTH KEYS ARE SET, WHICH ONE WON IS STATED. `pv.py`'s - # `entities()` makes `pv_entities` REPLACE `pv_entity`, which is the - # rule an operator upgrading from 0.11.0 is most likely to trip - # over. A CAUTION and never a `bad` row: telemetry must not stop - # control. - if pv_read.entity_is_ignored(self.o): - out.append({"ok": False, "warn": True, "id": "pv", - "text": messages.row_pv_single_ignored()}) - # TEL-14: a sign that looks reversed, per entity rather than on the - # total - see `pv.NEGATIVE_W` and DECISIONS/TEL-14-pv-sign.md §3. - for i, (ent, watt, _y) in enumerate(self.pv_parts): - if watt is not None and watt < pv_read.NEGATIVE_W: - out.append({"ok": False, "warn": True, "id": "pv", - "text": messages.row_pv_negative( - i + 1, n_src, watt, ent in flip)}) - _inv_list = [str(x or "").strip() - for x in (self.o.get("pv_invert_entities") or [])] - for ent in pv_read.stray_inverts(self.o): - out.append({"ok": False, "warn": True, "id": "pv", - "text": messages.row_pv_stray( - _inv_list.index(ent) + 1)}) - return out - - def status_payload(self, lang: str = "en") -> dict: - checks = self.checks() - bad = [c for c in checks if not c["ok"] and not c["warn"]] - # SAFETY-87: a red row with `runs` (the peak alarms) is an alarm while - # control goes on, so it neither reads "Not ready" nor holds the page. - runs = [c for c in bad if c.get("runs")] - bad = [c for c in bad if not c.get("runs")] - running_alarm = waiting = False - # --- SAFETY-10, AND IT IS FIRST IN THE CASCADE ----------------------- - # "The battery is NOT being controlled" is the one sentence on this - # page that may never be displaced by another condition. A banner that - # can be out-ranked does not STATE a thing plainly; it states it - # whenever nothing else is happening, which is the half of the time - # nobody needs telling. - # - # ⚠️ AND IT CARRIES A STANDING LATCH RATHER THAN HIDING ONE. The three - # `bad` branches below all say some version of "held at 0 W", which is - # still true in shadow mode - but an operator who turns shadow mode off - # with a latch up gets a battery that will not move and a page that - # never mentioned it. `shadow.banner()` names the latch and goes red - # for it, so nothing this cascade would have said is lost. - _shadow = shadow.banner(self.o, control_started=self.auto, - latched=self.shadow_latches()) - if _shadow is not None: - level, banner = _shadow - elif self.circ_wd.tripped: - # ⚠️ ABOVE THE SIGN FAILSAFE, and the order is a decision. Both are - # latched P_SAFETY stops, so the site is at 0 W either way and the - # banner can only carry one sentence. This one goes first because it - # is the fault the operator has NO OTHER WAY of learning about: a - # sign disagreement is visible at the meter and on every dashboard - # in the house, and circulating power is visible nowhere at all. - level, banner = "bad", messages.banner_circulating() - elif self.site_sign_wd.tripped and len(self.inverters) > 1: - # SAFETY-30's site half, ABOVE the per-unit rows below and below - # circulating power above, and the ordering is the same argument - # both times: the banner carries one sentence, so it carries the one - # that says the widest true thing. A site sign trip means EVERY - # inverter is parked and the fault is in what the site was asking - # for, not in one device - naming a unit here would send an operator - # to swap the wrong box. - level, banner = "bad", messages.banner_site_direction() - elif any(i.sign_wd.tripped for i in self.inverters): - # Outranks "Not ready": nothing is missing, something went wrong. - # At a roster of one the unit was graded against the meter; at N>=2 - # against its own power, so the banner says so - see checks() on - # why the noun is load-bearing rather than cosmetic. - level, banner = "bad", messages.banner_direction( - len(self.inverters) > 1) - elif bad: - # ⚠️ `banner` IF THE ROW OFFERS ONE, `text` OTHERWISE. A row may - # need to say more to an operator reading the checks list than fits - # in the one line at the top of the page - SAFETY-25's floor-limited - # row is the case that forced this - and a headline that is a full - # paragraph, repeated verbatim by the row underneath it, is a - # headline nobody reads. UX-08: without the key, the banner takes - # the row's first sentence, so it stays a headline. - level, banner = "bad", messages.banner_not_ready(bad[0]) - # SAFETY-112: nothing to do but wait, so Home says that instead - # of "Needs you now". Only when it IS the headline: a safety stop - # above outranks it and still needs a person. - waiting = bad[0].get("id") == "home_assistant" - elif not self.auto: - level, banner = "warn", messages.banner_stopped() - elif runs: - level, running_alarm = "bad", True - banner = runs[0].get("banner") or messages.headline_bi( - runs[0]["text"]) - elif any(i.delivery_wd.tripped for i in self.inverters): - # ⚠️ SAFETY-42, AND IT IS A `warn` BANNER RATHER THAN A `bad` ONE, - # WHICH IS THE WHOLE "reports, does not act" DECISION IN ONE LINE. - # Every `bad` banner above means the site is at 0 W; this one means - # the site is STILL RUNNING and quietly short by one unit's share, - # and a red headline would say the controller had stopped. - # - # ⚠️ BUT IT MUST DISPLACE "Running — holding grid at zero", AND THAT - # IS NOT COSMETIC. That sentence is a claim the site cannot make - # while a unit is absent - the loop is saturated and the meter is - # short - and "the page reads healthy while the fault runs" is - # precisely the shape this whole card exists to remove. It sits - # BELOW "Stopped" because a stopped site is the more urgent fact and - # the banner carries one sentence. - level, banner = "warn", messages.banner_not_delivering( - [i.name for i in self.inverters if i.delivery_wd.tripped]) - elif self.maint.phase != IDLE: - # ⚠️ THE PACK IS NAMED ONLY WHEN THERE IS MORE THAN ONE. At a roster - # of one this is the string it has always been, character for - # character; at two, "Maintenance: drain" without a name is a - # banner an operator cannot act on, because the remedy is at one - # device and the site has two. - level, banner = "warn", messages.banner_maintenance( - self.maint.phase, - self.maint_unit.name if len(self.inverters) > 1 else "") - else: - level, banner = "ok", messages.banner_running() - - def w(v): - return "—" if v is None else f"{v:,.0f} W".replace(",", " ") - - # ⚠️ THE EARLIEST ACROSS THE PACKS, NOT THE FIRST PACK'S. One date on a - # site with two schedules has to be the one that comes first, or the row - # says "2026-10-01" while a pack recalibrates tomorrow. `None` means - # "never run, due now" and has to win over any date, so it is tested for - # rather than sorted with. At a roster of one this is that pack's own - # date, unchanged. - _now = datetime.now(timezone.utc) - _dues = [m.next_due(_now) for m in self.maints] - _waits = [u for u in (m.backoff_until(_now) for m in self.maints) if u] - next_due = None if any(d is None for d in _dues) else min(_dues) - rows = [ - ("Grid", w(self.grid)), - ("Battery", w(self.site_batt_w)), - # SAFETY-31, and it belongs DIRECTLY UNDER the two figures it is not - # derivable from. "Grid 0 W, Battery 0 W, Circulating 6000 W" is the - # whole card in three rows: both of the numbers an operator normally - # reads say the site is idle, and the third says 6 kW is going round - # between the packs. Only shown at N>=2 - at one inverter it is - # identically zero and a permanent "0 W" row would be noise. - *(() if len(self.inverters) <= 1 - else ((("Circulating", w(self.site_circulating_w)),))), - # TEL-11, and ONLY when a source is configured - see `checks()`. - # `w(None)` renders "—", which is how this row says "no reading" - # rather than "0 W". It sits beside Grid and Battery because the - # question it answers is the one those two cannot: at "Grid 0 W, - # Battery 0 W" the site is either becalmed or throwing away every - # watt it makes, and only this row separates them. - *(() if not self.pv_roster else ((("Solar production", - w(self.pv_w)),))), - ("Battery level", "—" if self.pack_floor_soc is None - else f"{self.pack_floor_soc:g} %"), - ("Power request", w(self.target)), - # SAFETY-10, and it sits BETWEEN the two rows it reconciles. - # "Commanded 0 W" above and a "Why" below that explains a trade is - # the exact pair an operator would otherwise have to guess at; this - # row is what makes the two of them consistent, and it is rendered - # in EVERY state - including `off`, where it says the battery IS - # being controlled - because a surface whose ABSENCE is how you - # learn something is a surface you have to already know about. - ("Shadow mode", shadow.words( - self.o, control_started=self.auto, - would_w=self.shadow_would_w, - # SAFETY-47. THE FLAG THE CYCLE RECORDED, NOT ONE DERIVED HERE - # - the page runs on its own task and `self.peak_guard` has - # moved on. See `Controller.__init__`. - sized_from_meter=self.shadow_sized_from_meter, - reason=self.why_words)), - ("Why", self.why_words), - ("Maintenance phase", self.maint.phase if len(self.inverters) <= 1 - else f"{self.maint.phase} ({self.maint_unit.name})"), - # ⚠️ ONLY WHEN A PACK IS ACTUALLY WAITING, so a one-inverter status - # page - where `_maint_deferred` is empty on every tick - carries - # exactly the rows it carried before. - *((("Maintenance waiting", "; ".join(f"{n}: {why}" - for n, why in self._maint_deferred)),) - if self._maint_deferred else ()), - # MAINT-13: only while a failed cycle waits, so a site with nothing - # failed carries exactly the rows it carried before. - *((("Maintenance paused", messages.row_maint_waits( - min(_waits).strftime("%Y-%m-%d"))),) if _waits else ()), - ("Maintenance due", "now" if next_due is None else next_due.strftime("%Y-%m-%d")), - ("Cheap window", "yes" if self.cheap else "no"), - ("Tariff", self.tariff_words), - # PRICE-01: only while no price covers now. - *((("Prices", messages.row_no_prices(*self._gap_args())),) - if self.price_gap else ()), - # FCST-04. WHAT §8.3 HAS TO CARRY FORWARD, which is the difference - # between a 48-hour plan and a 12-hour one on a weekday morning. - # It is its own row rather than a clause of "Tariff" because it - # answers a different question: "Tariff" says what the plan IS, and - # this says what the plan could still be filled from if the feed is - # late again tomorrow. - ("Price history", self.price_history.words), - # OPT-04. The strategy's own sentence, not a re-derivation of it - - # every refusal it can make already carries a reason a human can - # act on, and "Arbitrage: no" would throw all of them away. - # - # ⚠️ TARIFF-10 RE-READ THIS STRING AND LEFT IT ALONE UNDER A - # COMMENT THAT WAS FALSE, AND TARIFF-11 IS THAT CORRECTION. The - # claim was that `self.arb is None` **if and only if** - # `arbitrage.enabled(self.o)` was False. Only the forward direction - # holds: `cycle()` returns at the input hold (`bad_for < - # stale_input_s`, default 15 s) BEFORE it reaches `self.arb = None` - # at all, so on an armed site `self.arb` is `__init__`'s None at - # startup and the PREVIOUS cycle's decision during a later hold - - # and the row rendered `off (arbitrage_enabled)` on a site whose - # `arbitrage_enabled` is `true`. `arbitrage_row()` reads the option - # instead of inferring it, and separates "trading is off" from "no - # decision was reached this cycle"; `cycle_at` and `arb_at` are what - # make the second one an observation rather than a guess. - # OPT-11 P3: with battery modes on the modes trade, whatever the - # switch says, so the row reports their decision. - ("Arbitrage", arbitrage_row( - on=arbitrage.enabled(self.o) or self.modes_on, - decision=self.arb, - decided_at=self.arb_at, cycle_at=self.cycle_at, - now=datetime.now(timezone.utc), why=self.why_words)), - ] - held = level == "bad" and not running_alarm - # UX-46. The rows were built in English with their Dutch beside them - # (`messages.Bi`); the page's language is chosen once, here, for the - # Home sentences, the checks list, the rows that carry one and the - # banner. A plain str (no Dutch twin) stays as it is. - checks = [dict(c, text=messages.pick(c["text"], lang)) for c in checks] - rows = [(k, messages.pick(v, lang)) for k, v in rows] - banner = messages.pick(banner, lang) - out = { - "banner": banner, "level": level, "rows": rows, "checks": checks, - "hint": self.hint, - # The action log itself, newest first. The page does not show it - # (UX-08 2d), but an installer can still read it in the `status` - # JSON, because several events (a dropped inverter's reason, the - # peak guard's projection) are written nowhere else. - "events": list(self.events), - } - # UX-13 P1: the Home screen's structured half. Read-only, and it may - # never cost the page its rows: a fault here is logged and the old - # fields are served alone (the page then shows the installer details). - try: - out.update(homeview.build(self, level=level, checks=checks, - lang=lang, held=held, waiting=waiting)) - except Exception: # noqa: BLE001 - # Once per process at ERROR: the page polls every 3 s. - if not getattr(self, "_home_failed", False): - self._home_failed = True - _LOG.exception("Home view could not be built, so the page " - "shows the plain status rows only") - else: - _LOG.debug("Home view failed again", exc_info=True) - out["home_error"] = True - return out - - def forecast_payload(self, lang: str = "en") -> dict: - """UX-54: the Forecast tab's data. Built on request, from what the - control cycle already holds; no Home Assistant call. Today's blocks are - Home's own, so `status_payload()` is built first and read.""" - try: - return dayview.build(self, self.status_payload(lang=lang), - datetime.now(timezone.utc), lang) - except Exception: # noqa: BLE001 - if not getattr(self, "_forecast_failed", False): - self._forecast_failed = True - _LOG.exception("The Forecast tab could not be built") - else: - _LOG.debug("The Forecast tab failed again", exc_info=True) - return {"ok": False} - - async def handle_action(self, what: str, *, unit=None, value=None): - now = datetime.now(timezone.utc) - if what in ("pack_use", "pack_mode", "pack_sell"): - return self._pack_action(what, unit, value, now) - if what == "auto_toggle": - self.auto = not self.auto - self.store.set("auto", self.auto) - self.log_event("control started" if self.auto else "control stopped", - hint=messages.hint("control_started" if self.auto - else "control_stopped")) - if self.auto: - # ⚠️ THE ONLY WAY OUT OF A SIGN-DISAGREEMENT TRIP, on purpose. - # It clears on a deliberate human start, not on the condition - # going away - the condition ALWAYS goes away, because the trip - # commands 0 W and a 0 W command cannot disagree with anything. - # An operator pressing start has, at minimum, looked at the - # banner that says why. - # - # ⚠️ IT CLEARS EVERY INVERTER'S LATCH, AND SAYS SO PER INVERTER. - # One button is what the UI has and one button is what §15's - # banner tells the operator to press; what must not happen is a - # press that clears A while B stays latched with nothing on the - # page changing. Each latch is cleared under its OWN key, so an - # install that had only B tripped comes back with only B's - # history cleared. - for inv in self.inverters: - if not inv.sign_wd.tripped: - continue - inv.sign_wd.reset() - inv.store_set("sign_tripped", False) - inv.store_set("sign_reason", "") - self.log_event(f"sign-disagreement failsafe cleared by " - f"operator on {inv.name}", - hint=messages.hint("stop_cleared", - unit=inv.name)) - # ⚠️ AND THE PRE-DEV-02 FLAT KEYS GO WITH THEM, UNCONDITIONALLY. - # This is what makes `flat True + namespaced False` MEAN - # something, and it is the reason `_grade_store_migration()` can - # run on every start instead of only on the start that migrates. - # - # Without it the flat key is a fossil that says `true` forever - # on any install that ever tripped, so a guard comparing against - # it would re-arm the failsafe on every restart for the rest of - # the install's life - which is why that guard used to be gated - # on `rep.ran`, and why the gate then swallowed the rollback - # ROUND TRIP: migrate, downgrade, trip during the downgrade - # window (the old code writes only the flat key), upgrade again - # -> `rep.ran` is False, the guard never runs, and the - # controller comes up UNLATCHED while /data/state.json says - # `sign_tripped: true`. That is store.py's own header sentence, - # rebuilt by the version marker. - # - # Cleared here, the two spellings can only disagree one way: the - # flat key is newer than the namespaced one, which means it was - # written by a version that did not know about namespaces - i.e. - # a trip inside a downgrade window. Unconditional rather than - # inside the loop because an operator pressing START is - # declaring the whole site clear, and the fossil belongs to no - # unit in particular. - self.store.set("sign_tripped", False) - self.store.set("sign_reason", "") - # SAFETY-30's SITE latch, cleared by the SAME press and for the - # same reason the per-unit ones are: the condition always goes - # away on its own, because the trip commands 0 W everywhere and - # a site commanding zero cannot oppose anything. Only a human - # who has read the banner can say the site is clear. - # - # ⚠️ UNCONDITIONAL, LIKE THE FLAT PAIR ABOVE, AND NOT GUARDED ON - # THE ROSTER. An install that ran with two inverters, tripped, - # and was then reconfigured back to one would otherwise carry - # `site_sign_tripped: true` in its file forever, with no roster - # that can reach the code which clears it - and would re-arm the - # moment a second inverter was configured again. - if self.site_sign_wd.tripped: - self.log_event("site sign-disagreement failsafe cleared " - "by operator", - hint=messages.hint("site_stop_cleared")) - self.site_sign_wd.reset() - self.store.set("site_sign_tripped", False) - self.store.set("site_sign_reason", "") - # SAFETY-31, cleared by the SAME press and for the same reason: - # the condition always goes away on its own, because the trip - # commands 0 W everywhere and two inverters at zero cannot - # oppose. Only a human who has read the banner can say the site - # is clear. - # - # ⚠️ AND `_circ_announced` GOES WITH IT. It is the "has a human - # been shown this" flag; leaving it True through a clear would - # mean the NEXT trip in this process latched, stopped the site, - # and raised no notification at all. - if self.circ_wd.tripped: - self.circ_wd.reset() - self.store.set("circ_tripped", False) - self.store.set("circ_reason", "") - self.log_event("circulating-power trip cleared by operator", - hint=messages.hint("site_stop_cleared")) - self._circ_announced = False - # SAFETY-42, cleared by the SAME press, and for a reason that is - # NOT the one above. The other three latches are cleared here - # because their trip removed its own evidence - a site commanding - # 0 W cannot oppose anything - so only a human can say the fault - # is gone. This one commands nothing, so its evidence is still - # standing and it could in principle clear itself. It does not: - # a unit that stopped delivering for minutes and then resumed is - # an INTERMITTENT fault, and a detector that erased its own - # record of that would be the least useful thing in this file. - # ⚠️ AND `_delivery_announced` GOES WITH IT, like - # `_circ_announced`: leaving a name in it through a clear would - # mean the NEXT trip on that unit latched and raised no - # notification at all. - for inv in self.inverters: - if inv.delivery_wd.tripped: - self.log_event(f"not-delivering report on {inv.name} " - f"cleared by operator", - hint=messages.hint( - "not_delivering_cleared", - unit=inv.name)) - inv.delivery_wd.reset() - inv.store_set("delivery_tripped", False) - inv.store_set("delivery_reason", "") - self._delivery_announced = set() - if not self.auto: - # ⚠️ THE WHOLE SITE, TARGETS INCLUDED - see command_site_zero(). - # Zeroing `self.target` alone would leave each unit's last share - # standing for its next heartbeat to re-emit, which an operator - # would read as the stop button not working. - # SMA-10: the Stop button is the add-on going quiet, so a unit - # that hands back is given back; every other unit is zeroed. - await self.command_site_release() - return {"auto": self.auto} - if what in ("maint_start", "maint_abort") and unit is not None: - # MAINT-11: the operator named the battery. A request with no unit - # falls through to the branches below, unchanged. - return await self._maint_unit_action(what, unit, now) - if what == "maint_start": - # ⚠️ WHICH PACK, BECAUSE THERE ARE NOW SEVERAL AND THE BUTTON HAS - # ONE LABEL. `_maint_button()` answers it: the pack that holds the - # site's maintenance slot if one does - which is what "start" - # already meant at a roster of one, where pressing it mid-drain - # re-entered DRAIN - and otherwise the pack that has gone longest - # without a cycle, which is the same pack `arbitrate()` would have - # picked on its own. At N=1 both branches are `maints[0]` and this - # is the shipped call, byte for byte. - # - # This is the bare request (no unit). A request naming a battery - # was handled above by `_maint_unit_action()` (MAINT-11). - _m = self._maint_button(now) - for msg in _m.force_start(now): - self.log_event(msg, hint=messages.hint("maintenance", - phase=_m.phase)) - return {"phase": self.maint.phase} - if what == "maint_abort": - # Aborts the pack that is actually cycling - `_maint_button()` again - # - and then zeroes the SITE, which is what it always did. - _m = self._maint_button(now) - for msg in _m.abort(now, "operator"): - self.log_event(msg, hint=messages.hint("maintenance", - phase=_m.phase)) - await self.command_site_zero() - return {"phase": self.maint.phase} - return None - - -# MAINT-13: a battery power reading at or below minus this many W is a pack -# that is taking charge. -MAINT_CHARGING_W = 50.0 # SAFETY-61. Exit status when the control task dies; 70 is sysexits(3) # EX_SOFTWARE. See DECISIONS/SAFETY-61-control-task-death.md. EXIT_CONTROL_DIED = 70 -async def _bounded(awaitable, budget_s: float): - """SMA-10. `await awaitable`, but give up after `budget_s` and do NOT wait - for it to wind down. `asyncio.wait_for` waits for the cancelled task to - finish, so a driver that ignores its cancellation would hold the whole - shutdown; this abandons it. Raises `asyncio.TimeoutError` at the bound.""" - task = asyncio.ensure_future(awaitable) - done, _ = await asyncio.wait({task}, timeout=budget_s) - if not done: - task.cancel() - # a result or error that arrives later has nobody to read it - task.add_done_callback(lambda t: t.cancelled() or t.exception()) - raise asyncio.TimeoutError - return task.result() - - class ControlTaskDied(RuntimeError): """The control task ended while nothing had asked it to stop.""" def mode_announcement(opts, store) -> tuple: - """OPT-11 P2: `(modes, retract)` for the MQTT publisher at start-up. - - The config topics announced are kept in the store, so turning modes off - removes exactly those (`mqtt.mode_configs()`). An install that never - turned modes on gets nothing, and its store is not written. - """ + """OPT-11 P2: `(modes, retract)` for the MQTT publisher at start-up. The + config topics announced are kept in the store, so turning modes off removes + exactly those (`mqtt.mode_configs()`); an install that never turned modes + on gets nothing, and its store is not written. + (DECISIONS/MAIN-orchestration-archive.md)""" modes = packmode.MODES if packmode.enabled(opts) else () stored = store.data.get(MODE_CONFIGS_KEY) keep, retract = mode_configs(roster_names(opts), modes, stored) @@ -8307,11 +1069,8 @@ DOCS_LINK_TIMEOUT_S = 3 async def docs_link_facts(session, token: str) -> dict: """`{slug, ha_version}` from the Supervisor, each None when unreadable. - - `GET /addons/self/info` and `GET /info` are on the Supervisor's bypass - list for an add-on's own token, so they need no role (see selfconfig.py). Asked together with a 3 s budget: a link may never hold up control start. - """ + (DECISIONS/MAIN-orchestration-archive.md)""" async def ask(url, field): """`(value, why)`: the field, or None and a short reason (UX-09).""" try: @@ -8400,8 +1159,8 @@ async def amain() -> None: # Startup self-check: prove we can actually reach the Core API before # anything tries to control an inverter with it. A 401 here is a - # permissions/token problem, not a configuration mistake, and saying so - # explicitly saves an installer from re-checking entity ids for an hour. + # permissions/token problem, not a configuration mistake. + # (DECISIONS/MAIN-orchestration-archive.md) import os as _os _tok = _os.environ.get("SUPERVISOR_TOKEN", "") _LOG.info("supervisor token: %s (%d chars); env has: %s", @@ -8416,23 +1175,17 @@ async def amain() -> None: _LOG.error("core api probe failed: %s", _e) # UX-09: the Details link in every notification needs this add-on's - # slug and Home Assistant's version (see messages.docs_url()). Both - # are best effort: without them the link falls back to the hostname, - # or to naming the section only. + # slug and Home Assistant's version (see messages.docs_url()); both are + # best effort. (DECISIONS/MAIN-orchestration-archive.md) messages.set_site(**await docs_link_facts(session, _tok)) # ⚠️ THE STARTUP GATE (CFG-01). Nothing below this line may run on a - # configuration validate.py rejects - specs §1.5: a config the system - # cannot honour is refused at startup, not survived at runtime. - # - # It sits HERE, before the broker, before the web server and before any - # task exists, so a refusal cannot leave half a controller running with - # a UI in front of it. Reading the device range is the one thing the - # validator cannot do for itself; (None, None) when ESPHome has not come - # up yet is not a refusal - run_control() re-checks once the real rating - # is known. See validate.py for where the line is drawn and why. - # SMA-2. The flat options are the one-inverter shape, so it is the - # GoodWe driver's, asked without a Controller (none exists yet). + # configuration validate.py rejects (specs §1.5). It sits HERE, before + # the broker, web server and any task; (None, None) from an ESPHome not + # yet up is not a refusal (run_control() re-checks). + # (DECISIONS/MAIN-orchestration-archive.md) + # SMA-2: the flat options are the GoodWe driver's (no Controller yet). + # DECISIONS/SMA-2-driver-seam.md. _sp = str(opts.get("setpoint_entity", "") or "").strip() _drv = GoodWeEsphomeDriver(setpoint_entity=_sp).bind(hass) _dev_min = _dev_max = None @@ -8440,10 +1193,10 @@ async def amain() -> None: _dev_min, _dev_max = await _drv.limits() _LOG.info("setpoint device %s reports range %s…%s W", _sp, _dev_min, _dev_max) _problems = validate_startup_config(opts, _dev_min, _dev_max) - # UX-15: a new install names no inverter. When that is the ONLY - # refusal it serves the setup wizard in setup-only mode, which builds - # nothing that commands and returns when stopped. Any other refusal - # still exits 78 (DECISIONS/UX-15-setup-only-mode.md). + # UX-15: a new install names no inverter. When that is the ONLY refusal + # it serves the setup wizard in setup-only mode, which builds nothing + # that commands and returns when stopped; any other refusal still exits + # 78. DECISIONS/UX-15-setup-only-mode.md if _problems and setuponly.applies(opts, _problems): await setuponly.serve( opts, HomeAssistant(session, read_only=True), store, @@ -8453,11 +1206,10 @@ async def amain() -> None: refuse(_problems) raise ConfigRefused(_problems) - # ⚠️ Status publishing must NEVER be able to stop the controller. A - # broken broker, a missing library, an API change in paho - all of it is - # observability, and the battery does not care. Caught broadly and on - # purpose: this crashed the add-on once already (paho 1.x vs 2.x) and - # took the control loop down with it. + # ⚠️ Status publishing must NEVER be able to stop the controller: + # caught broadly and on purpose (a paho 1.x/2.x change once crashed the + # add-on and took the control loop with it). + # (DECISIONS/MAIN-orchestration-archive.md) broker = None try: # OPT-11 P2: each battery's switch and mode list, only while @@ -8472,15 +1224,13 @@ async def amain() -> None: omit=() if is_enabled(opts) else ("p1_age",), # TEL-11. ⚠️ THE SHIPPED PREDICATE, NOT A SECOND READING OF THE # OPTION - `Controller.publish()` gates the row on this same - # call. An install with no PV roster announces exactly - # what it announced before: no topic, no entity, no row. + # call; an install with no PV roster announces exactly what it + # did before. (DECISIONS/MAIN-orchestration-archive.md) include=optional_keys(opts), - # TEL-07. ⚠️ THE NAMES, NOT A ROSTER. `build_roster()` here - # would construct a SECOND set of `Inverter`s off the same - # Store, minutes before `Controller.__init__` constructs the - # real ones; `roster_names()` is the naming rule on its own and - # is what `build_roster()` itself reads. At a roster of one this - # announces nothing new - see `announced_units()`. + # TEL-07. ⚠️ THE NAMES, NOT A ROSTER: `build_roster()` here + # would build a SECOND set of `Inverter`s off the Store; + # `roster_names()` is the naming rule on its own. + # (DECISIONS/MAIN-orchestration-archive.md) units=roster_names(opts), modes=_modes, retract=_retract, @@ -8515,19 +1265,12 @@ async def amain() -> None: control_task_done, controller=controller, stop=stop, died=died)) tasks = [control] - # OPT-04. The tariff refresh runs as its OWN long-lived task, for the - # reason P1 ingestion does and then some: `resolve_tariff()` may open an - # HTTPS connection to a supplier, and the control tick is what feeds the - # ESP32 heartbeat. A fetch on that path is a supplier's TLS timeout able - # to push this add-on towards layer 1's 30 s veto. See TARIFF_REFRESH_S. - # - # ⚠️ STARTED FOR A PROVIDER, FOR ARMED TRADING OR FOR BATTERY MODES: - # see `tariff_refresh_wanted()` above and DECISIONS/TARIFF-10 and - # TARIFF-24 for why each term is there. - # - # ⚠️ IT DOES NOT ARM ANYTHING. Fetching a price and trading on one are - # two decisions; this is the first, and `cycle()`'s - # `if arbitrage.enabled(self.o):` is still the only gate on the second. + # OPT-04. The tariff refresh runs as its OWN task (`resolve_tariff()` + # may fetch over HTTPS, and the tick feeds the ESP32 heartbeat). + # Started for a provider, armed trading or battery modes + # (`tariff_refresh_wanted()`). ⚠️ IT DOES NOT ARM ANYTHING: + # `arbitrage.enabled()` in cycle() is the only gate on trading. + # (DECISIONS/MAIN-orchestration-archive.md) if tariff_refresh_wanted(opts): tasks.append(asyncio.create_task(controller.run_tariff_refresh())) @@ -8566,11 +1309,9 @@ def main() -> None: except KeyboardInterrupt: pass except ConfigRefused: - # ⚠️ No traceback, on purpose. The banner refuse() already printed says - # everything an operator needs, and a stack trace on top of it would say - # "this crashed" - the exact confusion AC3 is about. 78 is sysexits(3) - # EX_CONFIG, so even a script reading the exit status can tell a bad - # config from a bug. + # ⚠️ No traceback, on purpose: the banner refuse() printed says + # everything. 78 is sysexits EX_CONFIG, so a script can tell a bad + # config from a bug. (DECISIONS/MAIN-orchestration-archive.md) raise SystemExit(78) except ControlTaskDied: # No second traceback: control_task_done() logged it at the death. diff --git a/goodwe_controller/app/modetrade.py b/goodwe_controller/app/modetrade.py index 899105a..75f6c58 100644 --- a/goodwe_controller/app/modetrade.py +++ b/goodwe_controller/app/modetrade.py @@ -36,6 +36,10 @@ Rules that keep this safe (tests: test_modes_p3.py, test_price_run_fixes.py): makes the other batteries stop giving power, so a few watts of charge flipping on and off would swing the house between them and the grid (measured on the 2026-09-09 replay: 13 flips in 4 minutes at 3.5 kW); + SAFETY-135: the first such stop in a period holds the charge RESTART_S + only, a second one to the period's end (at most one restart), and in a + period's first YOUNG_S s no charge starts while the batteries' give is + still falling (`wait`); * selling needs selling on for that battery, the sell run, a price >= 0 now, and the battery above `arbitrage_soc_floor`; it stops there. The peak guard never stops a sell (section 9.1: discharge is never capped); @@ -52,7 +56,9 @@ Rules that keep this safe (tests: test_modes_p3.py, test_price_run_fixes.py): the probe (none: PROBE_W alone), so a probe never places charge on a battery in a maintenance phase or on one that rests; * no grid charge while another battery drains for its monthly cycle - (`draining`, SAFETY-78): it would charge against the drain. + (`draining`, SAFETY-78): it would charge against the drain; nor while + one is in its maintenance CHARGE (`maint_charging`, MAINT-24): the cheap + night's room is that pack's. """ from dataclasses import dataclass @@ -69,6 +75,18 @@ PRICE_MODES = (LEFTOVER_SOLAR, CHEAP_HOURS) # would stop covering the house for less than they give. START_W = 500.0 +# SAFETY-135: how long the first stop in a period holds the charge, how long +# a period is young, and how far back a give may not be on the meter yet. +# DECISIONS/SAFETY-135-young-period.md +RESTART_S = 60.0 +YOUNG_S = 60.0 +GAVE_S = 15.0 +# SAFETY-135: the plain status words for `wait` (UX-08). +WAIT_WORDS = { + "wait": "battery modes: grid charge paused, it tries again in a minute", + "settle": "battery modes: grid charge waits for the meter to catch up", +} + @dataclass(frozen=True) class Pack: @@ -164,7 +182,8 @@ def energy(packs, floor_pct, ceiling_pct, done_charge=(), done_sell=(), def decide(runs, now, packs, *, charge_ok, sell_ok, trade_why, price_now, headroom_w, floor_pct, ceiling_pct, house_w, charging_now=False, blocked=False, done_charge=(), done_sell=(), - targets=None, draining=False) -> Tick: + targets=None, draining=False, wait=None, + maint_charging=False) -> Tick: """This tick's ranges, roles and site ask. `runs` is the kept `priceruns.RunPlan` or None (no fresh prices). @@ -177,7 +196,11 @@ def decide(runs, now, packs, *, charge_ok, sell_ok, trade_why, price_now, it going); `blocked` that the guard or the headroom stopped a charge in this 15-minute period. `targets` is the day plan (`charge_to()`). `draining` says a battery drains for its monthly cycle, so none may - charge from the grid (why "cycle"). + charge from the grid (why "cycle"). `wait` ("wait" or "settle", the + why) says no charge may start yet (SAFETY-135). `maint_charging` says a + battery is in its maintenance CHARGE phase: no grid charge for the others + either, same why, but a refusal probe goes on (MAINT-24, + DECISIONS/MAINT-24-charge-first.md). """ plan_on = runs is not None and runs.on in_cheap = plan_on and runs.cheap.holds(now) and runs.charge_useful() @@ -189,6 +212,10 @@ def decide(runs, now, packs, *, charge_ok, sell_ok, trade_why, price_now, if in_cheap else [] if ch and draining: ch, why = [], "cycle" + elif ch and maint_charging: + # MAINT-24: a refusal probe (PROBE_W alone, OPT-20) may go on. + ch = [p for p in ch if p.refused < 0] + why = None if ch else "cycle" charging = False if ch: need = 0.0 if charging_now else START_W @@ -198,6 +225,8 @@ def decide(runs, now, packs, *, charge_ok, sell_ok, trade_why, price_now, why = trade_why elif headroom_w is None or not headroom_w > need: why = "headroom" + elif wait and not charging_now: + why = wait else: charging = True se = sellers(packs, floor_pct, done_sell) if in_sell and not charging \ diff --git a/goodwe_controller/app/rows.py b/goodwe_controller/app/rows.py new file mode 100644 index 0000000..a44c305 --- /dev/null +++ b/goodwe_controller/app/rows.py @@ -0,0 +1,83 @@ +"""Module functions for the status rows and the Why line. + +Moved unchanged from app/main.py (MAINT-21). DECISIONS/MAIN-orchestration.md.""" + +from .arbiter import ACTUATOR_SITE, SET +from . import control as _ctl +from . import messages + + +def why_raised(resolution, claims) -> bool: + """F2 (OPT-11 P1 test): did the limit that bound the site target push it + ABOVE what the winner asked (the peak floor asking for more power)? Then + the Why line must not say "held back". False when nothing bound it.""" + if not resolution.bound_by or resolution.contradiction: + return False + asked = next((c.value for c in sorted( + (c for c in claims if c.kind == SET + and c.actuator == ACTUATOR_SITE and c.source == resolution.winner), + key=lambda c: c.priority, reverse=True)), None) + return asked is not None and resolution.target_w > float(asked) + + +def why_key(winner: str, claims) -> str: + """The key of `messages.WHY_WINNER` for a resolution's winner. "safety" and + "failsafe" stand for several causes, so their own claim reason is the + key ("stopped", "inputs missing", "sign disagreement", or "unsplit" when + this module refuses to split the power).""" + if winner == "loop": + # SAFETY-52: a loop holding a refused direction says so. + return next((c.reason for c in claims if c.source == "loop" + and c.reason in (_ctl.REFUSED, _ctl.PROBING)), winner) + if winner in ("safety", "failsafe"): + return next((c.reason for c in claims + if c.source == winner and c.kind == "set"), + "no claim was made" if not any( + c.kind == "set" for c in claims) else "unsplit") + return winner + + +def tariff_plan_row(plan, tick_words: str, *, age_s, horizon_h: float, + provider: bool, max_age_s: float) -> str: + """The *Tariff* status row: the 30 s tick's sentence AND the provider plan + (TARIFF-11): two sources, two clocks, and the row says so. The plan is + stamped with its own age from `tariff_at` (not moved on a kept plan, + TARIFF-12), up to TARIFF_MAX_AGE_S (5400 s); `age_s` is the caller's + measurement. "No plan" is said aloud on a site that configured a provider. + DECISIONS/MAIN-orchestration.md.""" + # UX-08: plain words, every figure kept. The tick's sentence is "now"; the + # plan carries its own age. + if plan is None: + if not provider: + return tick_words + return (f"{tick_words}. No price plan: none yet, or the last one is " + f"over {max_age_s:.0f} s old") + return (f"{tick_words}. Price plan from {age_s:.0f} s ago, for " + f"{horizon_h:.0f} hours ahead: {plan.words}") + + +def arbitrage_row(*, on: bool, decision, decided_at, cycle_at, now, + why: str) -> str: + """The *Arbitrage* status row: three states (TARIFF-11): off (not armed), + armed with no decision this cycle (`why` is the loop's reason), or a + decision with its age. + `on` is read from the options, never inferred from `decision is None`: + `cycle()` returns at the input hold before `self.arb = None`, so the old + row named an option that was ON. The age is always printed, even 0. + DECISIONS/MAIN-orchestration.md.""" + # UX-08: plain words; the setting is named by its label. + if not on: + return (f"Off, “{messages.LABELS['arbitrage_enabled']}” is not " + f"switched on") + if decided_at is None: + return (f"On, but no decision yet, because control has not got that " + f"far. Control says: {why or 'no reason recorded'}") + age = (now - decided_at).total_seconds() + stale = cycle_at is not None and decided_at < cycle_at + head = (f"On, no decision this cycle ({why or 'no reason recorded'}), " + f"the last one {age:.0f} s ago: " if stale else + f"On, decided {age:.0f} s ago: ") + if decision is None: + return (f"On, no decision this cycle ({why or 'no reason recorded'}) " + f"and none before") + return head + decision.explain() diff --git a/goodwe_controller/app/settle.py b/goodwe_controller/app/settle.py new file mode 100644 index 0000000..41a7ab4 --- /dev/null +++ b/goodwe_controller/app/settle.py @@ -0,0 +1,74 @@ +"""SAFETY-136: on a slow meter, follow the meter gently until the last move shows. + +A meter whose usual gap between readings is over 3.75 s (a 4-5 s meter), read +through Home Assistant, can be 10-15 s late. The loop then answers the same error again at each cycle +and overshoots. After a move of MOVE_W or more the loop therefore runs at +WAIT_SHARE of its gain until the meter has fallen SHOWN of the move, or for at +most WAIT_CYCLES cycles. Off for a meter with a usual gap of 3.75 s or less, so those sites run as +before. DECISIONS/SAFETY-136-slow-meter-settle.md. +""" + +from collections import deque +from dataclasses import replace + +from .lateness import M_FIT_S, M_ROWS + +# A meter is slow when its readings come further apart than this (the usual +# gap, over the last 60 s and at least 5 readings): the fast meter fit's own +# limit (SAFETY-128), 3.75 s. +SLOW_GAP_S = M_FIT_S / M_ROWS +SLOW_ROWS = 5 +# A move this big is waited for (above the house noise of about 80 W). +MOVE_W = 150.0 +# The meter has shown a move once it fell by this share of it. +SHOWN = 0.5 +# Meanwhile the loop runs at this share of its gain. +WAIT_SHARE = 0.5 +# Wait at most this many cycles (10 s at a 5 s meter). +WAIT_CYCLES = 2 + + +class Settle: + def __init__(self): + self.pend = None # (meter at the move, the move in W, cycles waited) + self._n = None # readings taken in so far + self._at = deque() # when the last ones arrived, over M_FIT_S + + def arrive(self, now, n): + """Each read: `n` is the count of meter readings taken in. A reading + counts when it arrives, not when its value changes, so a steady load on + a 1 s meter is not a slow meter.""" + if n != self._n: + self._n = n + self._at.append(now) + while self._at and self._at[0] < now - M_FIT_S: + self._at.popleft() + + def slow(self): + """The usual gap between readings is over SLOW_GAP_S.""" + ts = list(self._at) + if len(ts) < SLOW_ROWS: + return False + gaps = sorted(b - a for a, b in zip(ts, ts[1:])) + return gaps[len(gaps) // 2] > SLOW_GAP_S + + def reset(self): + self.pend = None + + def tuning(self, tuning, grid_w, slow): + """The tuning for this cycle: `tuning`, or with the gain cut while the + last move has not shown on the meter (`grid_w`).""" + p = self.pend + if p is None: + return tuning + g0, move, waited = p + if not slow or (g0 - grid_w) / move >= SHOWN or waited >= WAIT_CYCLES: + self.pend = None + return tuning + self.pend = (g0, move, waited + 1) + return replace(tuning, gain=tuning.gain * WAIT_SHARE) + + def moved(self, grid_w, prev_w, new_w, slow): + """After a cycle: start waiting if the loop moved by MOVE_W or more.""" + if slow and self.pend is None and abs(new_w - prev_w) >= MOVE_W: + self.pend = (float(grid_w), float(new_w - prev_w), 0) diff --git a/goodwe_controller/app/ui_text/en.json b/goodwe_controller/app/ui_text/en.json index 12859a8..3fd2f34 100644 --- a/goodwe_controller/app/ui_text/en.json +++ b/goodwe_controller/app/ui_text/en.json @@ -430,6 +430,7 @@ "give": "Tomorrow: gives power at {at}, {eur} per kWh.", "give_would": "Tomorrow: would give power at {at}, {eur} per kWh." }, + "cycle_backoff": "{name}: the monthly cycle waits until {day} {month}.", "cycle_waits": "{name} waits its turn for the monthly cycle.", "no_prices_yet": "No prices yet, maintenance waits.", "no_prices_since": "No prices since {at}, maintenance waits.", diff --git a/goodwe_controller/app/ui_text/nl.json b/goodwe_controller/app/ui_text/nl.json index 75cd441..10315ff 100644 --- a/goodwe_controller/app/ui_text/nl.json +++ b/goodwe_controller/app/ui_text/nl.json @@ -365,6 +365,7 @@ "no_level": "Nu geen handel op prijs: een laadniveau is onbekend." }, "tomorrow_trade": {"grid": "Morgen: laadt om {at}, {eur} per kWh.", "grid_would": "Morgen: zou laden om {at}, {eur} per kWh.", "give": "Morgen: levert stroom om {at}, {eur} per kWh.", "give_would": "Morgen: zou stroom leveren om {at}, {eur} per kWh."}, + "cycle_backoff": "{name}: de maandelijkse cyclus wacht tot {day} {month}.", "cycle_waits": "{name} wacht zijn beurt af voor de maandelijkse cyclus.", "no_prices_yet": "Nog geen prijzen, onderhoud wacht.", "no_prices_since": "Geen prijzen sinds {at}, onderhoud wacht.", diff --git a/goodwe_controller/config.yaml b/goodwe_controller/config.yaml index 6df5b74..1311c24 100644 --- a/goodwe_controller/config.yaml +++ b/goodwe_controller/config.yaml @@ -1,5 +1,5 @@ name: GoodWe RS485 Controller -version: "0.21.0" +version: "0.22.0" slug: goodwe_controller description: >- Drives a GoodWe ES/BP battery inverter over its RS485 EMS port by sending it a diff --git a/goodwe_controller/test_arbitrage.py b/goodwe_controller/test_arbitrage.py index 9a6e436..e128a26 100644 --- a/goodwe_controller/test_arbitrage.py +++ b/goodwe_controller/test_arbitrage.py @@ -109,6 +109,8 @@ from app.validate import validate_startup_config UTC = timezone.utc HERE = os.path.dirname(os.path.abspath(__file__)) +sys.path.insert(0, os.path.join(HERE, "tools")) +import main_files # noqa: E402 # PRICE-02: `TariffPlan.arbitrage(now=...)` is required. This instant is before every # point these fixtures build, so no period has ended and the whole series counts. @@ -779,9 +781,7 @@ check("...and cycle() calls it rather than inlining the conjunction, so a " "mutation back to a bare `engaged_now` is red rather than silent", "arbitrage.guard_state(self.peak_guard)" in ast.get_source_segment( - open(os.path.join(HERE, "app", "main.py"), encoding="utf-8").read(), - _fn(open(os.path.join(HERE, "app", "main.py"), - encoding="utf-8").read(), "cycle"))) + main_files.source(), _fn(main_files.source(), "cycle"))) # --------------------------------------------------------------------------- # @@ -907,8 +907,8 @@ check("a ZERO headroom does not cap a DISCHARGE. §9.1: 'discharge and export " # above calls decide() itself - and a required keyword-only parameter that no # caller fills is a TypeError only on the one path a suite does not run. Same # pin, same reason, as `weights=` in test_packshare.py part 10. -_S45_MAIN = open(os.path.join(HERE, "app", "main.py"), encoding="utf-8").read() -_S45_MAIN_TREE = ast.parse(_S45_MAIN) +_S45_MAIN = main_files.source() +_S45_MAIN_TREE = main_files.tree(_S45_MAIN) _s45_calls = [n for n in ast.walk(_S45_MAIN_TREE) if isinstance(n, ast.Call) and ast.unparse(n.func).endswith("arbitrage.decide")] @@ -2215,8 +2215,7 @@ print() print("8. the background refresh - the tick must never await a fetch") -_MAIN_SRC = derived(lambda: open(os.path.join(HERE, "app", "main.py"), - encoding="utf-8").read()) +_MAIN_SRC = derived(main_files.source) _cycle = derived(lambda: _fn(_MAIN_SRC, "cycle")) _refresh = derived(lambda: _fn(_MAIN_SRC, "run_tariff_refresh")) _read_inputs = derived(lambda: _fn(_MAIN_SRC, "read_inputs")) diff --git a/goodwe_controller/test_clamp.py b/goodwe_controller/test_clamp.py index f651a2d..e5713e3 100644 --- a/goodwe_controller/test_clamp.py +++ b/goodwe_controller/test_clamp.py @@ -1969,9 +1969,11 @@ print("9. SAFETY-40: the integrator bound is not a BUG SIGNAL, and the numbers " # The fixtures are chosen so the numbers the old text used DIFFER from the true # ones (MUTATION.md habit 4); the PRECONDITION checks pin that. import logging +sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "tools")) # noqa: E402 +import main_files # noqa: E402 import app.main as _main_mod -_real_compute = _main_mod.compute +_real_compute = main_files.live.compute class _LogCap(logging.Handler): @@ -1995,7 +1997,7 @@ def s40_run(grid, cycles, track, **over): cap = _LogCap() lg = logging.getLogger("goodwe") lg.addHandler(cap) - _main_mod.compute = spy + main_files.live.compute = spy async def go(): hass = _Hass(grid, track=track) @@ -2024,7 +2026,7 @@ def s40_run(grid, cycles, track, **over): try: hass, c, red = asyncio.run(go()) finally: - _main_mod.compute = _real_compute + main_files.live.compute = _real_compute lg.removeHandler(cap) return ticks, hass, c, red, cap.records @@ -2104,8 +2106,7 @@ check("...and its ERROR says it is a software fault and that control keeps " any(x.levelno == logging.ERROR and "software fault" in x.getMessage() and "control runs on" in x.getMessage() for x in log_o) and "reached 14 768 W on this project" in - open(os.path.join(os.path.dirname(os.path.abspath(__file__)), "app", - "main.py"), encoding="utf-8").read()) + main_files.source()) check("...under the over-rating title, quoting a tick's own asked and sent " "numbers in that order, with a red status row", clamp_notes(hass_o) diff --git a/goodwe_controller/test_defaults_pin.py b/goodwe_controller/test_defaults_pin.py index c8acc21..2d43e5c 100644 --- a/goodwe_controller/test_defaults_pin.py +++ b/goodwe_controller/test_defaults_pin.py @@ -149,9 +149,15 @@ print("2. the mirrors, DISCOVERED from the tree rather than listed here") # `app/` for module-level assignments whose name ends in OPTION_DEFAULTS and # grades whatever it finds, so the seventh is covered on the commit that # introduces it. That is the property the six hand-written pins cannot have. -MODULES = sorted(p.name for p in APP.glob("*.py")) +sys.path.insert(0, str(HERE / "tools")) +import main_files # noqa: E402 + +# MAINT-21: app/main.py stands for itself and the files split from it. +MODULES = sorted(p.name for p in APP.glob("*.py") + if p.name == "main.py" or p.name not in main_files.files()) TREES = {name: ast.parse(io.open(APP / name, encoding="utf-8").read(), name) for name in MODULES} +TREES["main.py"] = main_files.tree() MIRROR = {} # schema key -> (module, table name, value) TABLES = [] diff --git a/goodwe_controller/test_delivery.py b/goodwe_controller/test_delivery.py index 2688c84..3f6715a 100644 --- a/goodwe_controller/test_delivery.py +++ b/goodwe_controller/test_delivery.py @@ -1272,6 +1272,9 @@ check("the operator's START press is the only way out, and it clears the " print() print("8b. SAFETY-34: a Core-only restart - same add-on process, HA's memory wiped") +import os # noqa: E402 +sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "tools")) # noqa: E402 +import main_files # noqa: E402 import app.main as _main_mod # noqa: E402 @@ -1283,8 +1286,8 @@ async def _core_restart(): _c = asyncio.run(_core_restart()) -_real_mono, _clock = _main_mod._mono, [_main_mod._mono()] -_main_mod._mono = lambda: _clock[0] +_real_mono, _clock = main_files.live._mono, [main_files.live._mono()] +main_files.live._mono = lambda: _clock[0] try: _c.hass = _DeliveryHass(b_soc=50.0) asyncio.run(_c.check_not_delivering()) @@ -1295,7 +1298,7 @@ try: _late = [x for x in _c.hass.calls if "not_delivering" in str(x[2].get("notification_id", ""))] finally: - _main_mod._mono = _real_mono + main_files.live._mono = _real_mono check("SAFETY-34: the latch tripped in this process", _c.inverters[1].delivery_wd.tripped) check("SAFETY-34: inside REANNOUNCE_S the same process does not re-raise", diff --git a/goodwe_controller/test_inverter.py b/goodwe_controller/test_inverter.py index 4b7281e..217c7fc 100644 --- a/goodwe_controller/test_inverter.py +++ b/goodwe_controller/test_inverter.py @@ -75,6 +75,9 @@ from pathlib import Path from named_absence import first, given, nth, present +import os # noqa: E402 +sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "tools")) # noqa: E402 +import main_files # noqa: E402 from app import main as app_main from app.inverter import LINK_STALE_S, UNIT_A, Inverter, build_roster from app.main import WRITE_BUDGET_S, Controller @@ -88,8 +91,10 @@ from app.arbiter import P_LOOP, P_SAFETY, Claim, resolve fails = [] HERE = Path(__file__).resolve().parent -MAIN_SRC = io.open(HERE / "app" / "main.py", encoding="utf-8").read() -MAIN_AST = ast.parse(MAIN_SRC) +sys.path.insert(0, str(HERE / "tools")) +import main_files # noqa: E402 +MAIN_SRC = main_files.source() +MAIN_AST = main_files.tree(MAIN_SRC) CTRL = [n for n in MAIN_AST.body if isinstance(n, ast.ClassDef) and n.name == "Controller"][0] @@ -1097,8 +1102,8 @@ check("...and it is below hass.py's own 10 s HTTP timeout, so the budget is " # is healthy. The budget is shortened for the run - the shipped value is graded # above - because a 4 s wait per case is 8 s of suite time to measure something # that is already a ratio. -_REAL_BUDGET = app_main.WRITE_BUDGET_S -app_main.WRITE_BUDGET_S = 0.30 +_REAL_BUDGET = main_files.live.WRITE_BUDGET_S +main_files.live.WRITE_BUDGET_S = 0.30 async def _hung_heartbeat(): @@ -1124,18 +1129,18 @@ async def _hung_heartbeat(): _c6, _h6, _elapsed, _t0 = run(_hung_heartbeat()) _b_at = [t - _t0 for e, _v, t in _h6.write_at if e == "number.sp_b"] print(f" A hangs forever, B is healthy: the pair took {_elapsed:.2f} s " - f"(budget {app_main.WRITE_BUDGET_S:.2f} s); B's write reached the wire " + f"(budget {main_files.live.WRITE_BUDGET_S:.2f} s); B's write reached the wire " f"{(_b_at[0] if _b_at else float('nan')):.3f} s in; wire saw " f"{_h6.writes}") check("⚠️ AC 6. B'S WRITE REACHED THE WIRE WHILE A WAS STILL HANGING. That is " "the whole criterion: a hung write to A cannot consume B's layer-1 " "budget, because B's write was never behind A's in a queue", _h6.writes == [("number.sp_b", 700.0)] - and bool(_b_at) and _b_at[0] < app_main.WRITE_BUDGET_S / 2.0) + and bool(_b_at) and _b_at[0] < main_files.live.WRITE_BUDGET_S / 2.0) check("...and the pair returned in about ONE budget rather than in two, which " "is what says the writes were concurrent and not merely bounded. Two " "bounded writes in series is still a sibling waiting for a corpse", - _elapsed < app_main.WRITE_BUDGET_S * 1.9) + _elapsed < main_files.live.WRITE_BUDGET_S * 1.9) check("...and the hung inverter is recorded as having FAILED its write, so " "`last_write` is not advanced and the next tick re-issues it by itself", _c6.inverters[0].last_write is None @@ -1176,7 +1181,7 @@ check("⚠️ AND THE DEFECT IS REPRODUCED BESIDE THE FIX. Written in series, B' "every inverter behind the hung one, and with the unbounded write this " "card replaces it was the HTTP stack's timeout - which is what put a " "healthy sibling within reach of layer 1's veto", - _ser_b_at >= app_main.WRITE_BUDGET_S) + _ser_b_at >= main_files.live.WRITE_BUDGET_S) # AND THE DEADLINE ITSELF IS PER UNIT - graded through the shipped method, for # the reason the experiment above is: a `due` list computed in this file is a @@ -1219,7 +1224,7 @@ check("...and the heartbeat re-emits each unit's OWN share rather than the " # heartbeat is not the only place a hung inverter can hold the loop: every cycle # writes every unit's share, and in series that is the same defect at the cycle # rate rather than at the heartbeat rate. -app_main.WRITE_BUDGET_S = 0.30 +main_files.live.WRITE_BUDGET_S = 0.30 async def _hung_cycle(): @@ -1248,17 +1253,17 @@ check("⚠️ AND A REAL CYCLE DELIVERS B'S SHARE WHILE A HANGS. This is the sam "`cycle()` go out together, so a hung inverter costs the loop one budget " "and costs its siblings nothing", _h6c.writes and _h6c.writes[0][0] == "number.sp_b" - and bool(_cyc_b) and _cyc_b[0] < app_main.WRITE_BUDGET_S / 2.0 - and _cyc_elapsed < app_main.WRITE_BUDGET_S * 1.9) + and bool(_cyc_b) and _cyc_b[0] < main_files.live.WRITE_BUDGET_S / 2.0 + and _cyc_elapsed < main_files.live.WRITE_BUDGET_S * 1.9) check("...and the share B was told is the allocator's, not the site target - " "the hung sibling does not turn the cycle into a broadcast", _h6c.writes[0][1] == float(_c6c.allocation.shares["inverter-b"]) and _h6c.writes[0][1] != _c6c.target) -app_main.WRITE_BUDGET_S = _REAL_BUDGET +main_files.live.WRITE_BUDGET_S = _REAL_BUDGET check("...and the shipped budget is restored after the experiments, so nothing " "below runs against a 0.3 s one", - app_main.WRITE_BUDGET_S == WRITE_BUDGET_S) + main_files.live.WRITE_BUDGET_S == WRITE_BUDGET_S) # ⚠️ AND THE OPERATOR'S STOP HAS TO MOVE THE SAME TWO THINGS. This is a hazard diff --git a/goodwe_controller/test_maint10.py b/goodwe_controller/test_maint10.py index 6025c00..4a109c9 100644 --- a/goodwe_controller/test_maint10.py +++ b/goodwe_controller/test_maint10.py @@ -22,6 +22,7 @@ from pathlib import Path sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "tools")) +import main_files # noqa: E402 import app.main as M # noqa: E402 from app import maintenance as MT # noqa: E402 from app.maintenance import ( # noqa: E402 @@ -367,7 +368,7 @@ def amain_zone(zone_body, env_tz): M.load_options = lambda: {"setpoint_entity": "number.sp"} M.HomeAssistant = lambda session, **kw: _Hass() - M.validate_startup_config = lambda *a, **k: [] + main_files.live.validate_startup_config = lambda *a, **k: [] M.mode_announcement = lambda opts, store: ((), ()) M.Controller = _controller M.aiohttp.ClientSession = lambda *a, **k: _Session(zone_body) diff --git a/goodwe_controller/test_maint13.py b/goodwe_controller/test_maint13.py index 2e76f48..f510b57 100644 --- a/goodwe_controller/test_maint13.py +++ b/goodwe_controller/test_maint13.py @@ -520,9 +520,11 @@ check("a fixed tariff set up counts as a gate: outside its cheap hours a pack " "that is not charging is closed, inside them it is open", c._price_gated is True and c._charge_gate_open(c.inverters[0]) is c.cheap) +sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "tools")) # noqa: E402 +import main_files # noqa: E402 import app.main as main_mod # noqa: E402 -_real_gated, _calls = main_mod.static_gated, [] -main_mod.static_gated = lambda o, now: _calls.append(now) or _real_gated(o, now) +_real_gated, _calls = main_files.live.static_gated, [] +main_files.live.static_gated = lambda o, now: _calls.append(now) or _real_gated(o, now) try: c._gated_key = None read(c) @@ -530,7 +532,7 @@ try: read(c) c._static_gated(c.o, datetime.now(UTC) + timedelta(hours=1)) finally: - main_mod.static_gated = _real_gated + main_files.live.static_gated = _real_gated check("...worked out once an hour, not on every tick (3 reads in one hour = 1 " f"build; a new hour = 1 more): {len(_calls)} builds", len(_calls) == 2 and c._price_gated is True) diff --git a/goodwe_controller/test_maint24.py b/goodwe_controller/test_maint24.py new file mode 100644 index 0000000..273cf98 --- /dev/null +++ b/goodwe_controller/test_maint24.py @@ -0,0 +1,257 @@ +"""Runnable check for MAINT-24. `python3 test_maint24.py` + +A started maintenance charge at N=2 must get the cheap night. On the live site +(2026-11-08..11) battery B's grid charge (battery modes) took the night, and +A's own charge was switched off or sized at 200-450 W: its pause and its floor +compared the peak forecast with `cap - margin`, not with this month's peak +that the guard and B's trade aim at (SAFETY-80), and its floor counted its own +charge in the forecast (SAFETY-111). + +All on the real Controller through `cycle()` (the lagged N=2 replay, tools/ +opt20_scen.py): cheap window, house 3000 W, cap 3500 / margin 50, a month peak +of 6000 W banked (aim 5950 W), a peak forecast that follows the grid. + +1. A in maintenance CHARGE, B a Cheap hours charger: A charges at the room under + the month aim (half of it: the forecast holds A's own charge, SAFETY-111 + stays on its card), B files no grid trade, B's why is "cycle", every quarter is at or + under the month aim. +2. Forecast above 3450 W but under the month aim: shaping is not paused and A + gives nothing. A real peak (house over the month aim) still pauses it. +3. The mirror: B in maintenance CHARGE, A the charger. +4. modetrade.decide(): `maint_charging` files no charge, why "cycle"; solar + roles stay. +5. Unchanged: N=1 with no forecast entity, the SAFETY-78 drain, battery modes + off (digests printed on release/1.0 02eac3b). +Mutations: DECISIONS/MAINT-24-charge-first.md. +Read MUTATION.md before you report a survivor. +""" + +import logging +import os +import sys +from types import SimpleNamespace + +HERE = os.path.dirname(os.path.abspath(__file__)) +sys.path.insert(0, HERE) +sys.path.insert(0, os.path.join(HERE, "tools")) +logging.disable(logging.WARNING) + +import opt11p3_replay as rp # noqa: E402 +import opt20_scen as sc # noqa: E402 +from app import modetrade, packmode, tariff # noqa: E402 +from app.maintenance import DRAIN, MaintResult # noqa: E402 + +fails = [] + + +def check(name, cond): + print(f" {'ok ' if cond else 'FAIL'} {name}") + if not cond: + fails.append(name) + + +A, B = sc.A, sc.B +MONTH_PEAK = 6000.0 +AIM = MONTH_PEAK - 50.0 # the guard's aim this month +DRAIN_R = MaintResult(DRAIN, True, 2000.0, False, []) + + +def scen(*, a=None, b=None, soc=(49.0, 30.0), house_w=3000.0, peak=MONTH_PEAK, + fc=True, n=2, variant="p3_ch_sell", choice=None, hours=0.75): + """`a` / `b`: that pack's forced maintenance result (or None). `peak`: the + banked month peak or None. `fc`: a peak forecast entity that follows the + grid. Returns (rows, stats, controller).""" + rows = [] + extra = {"cycle_cost_threshold_eur": 0.10} + + def patch(c): + for i, res in enumerate((a, b)): + if res is not None and i < len(c.maints): + c.maints[i].tick = ( + lambda now, soc_, blocked_by=None, gate_open=True, + res=res: res) + if peak is not None: + orig_peak = c.peak.peak + + def peak_(now): + r = orig_peak(now) + return tariff.PeakReading(tariff.OBSERVED, + getattr(r, "month", ""), peak) + c.peak.peak = peak_ + orig = c.cycle + susp = [] + c._m24_susp = susp + + async def cyc(): + c.cheap = True + if fc and c.grid is not None: + c.peak_fc = float(c.grid) + await orig() + susp.append(bool(c._maint_shape_suspended)) + c.cycle = cyc + + def cb(c, h, now, pr): + sh = dict(c.allocation.shares) if c.allocation is not None \ + and c.allocation.shares else {} + rows.append(dict( + now=now, grid=h.grid(), shares=sh, + action=getattr(c.arb, "action", None), + reason=getattr(c.arb, "reason", None) or "", + roles=dict(c.mode_tick.roles) if c.mode_tick else {}, + why=c.mode_tick.why if c.mode_tick else None, + p={u: p.p for u, p in h.plants.items()})) + + stats, c = rp.run(variant, [(sc.UTC0.timestamp() - 10, house_w)], sc.WPTS, + sc.at(2.0), 3600 * hours, check=cb, lag=sc.LAG, n=n, + soc0={"a": soc[0], "b": soc[1]}, + choice=choice or sc.CH_CH, refuse=(), patch=patch, + extra=extra) + return rows, stats, c + + +def mean(rows, u): + r = rows[len(rows) // 6:] + return sum(x["p"][u] for x in r) / len(r) + + +def worst_quarter(stats): + return max(a[0] / a[1] for a in stats["quarters"].values()) + + +CH = sc.MAINT_CHARGE + +# ============================================================================ # +print("1. A in maintenance CHARGE, B a charger in the cheap window") +rows, st, c = scen(a=CH) +ma, mb = mean(rows, "a"), mean(rows, "b") +last = rows[-1] if rows else {} +print(f" A {ma:+.0f} W, B {mb:+.0f} W, worst quarter {worst_quarter(st):.0f}" + f" W, why {last.get('why')}, roles {last.get('roles')}") +check("A charges at (5950 - 3000) / 2 = 1475 W, not 0 or a few hundred W", + -1500.0 <= ma <= -1440.0) +check("B files no grid trade: no trade action in the run, B near 0 W", + all("CHARGE" not in str(r["action"]) for r in rows) and mb > -50.0) +check("roles: B does not charge, and the why is 'cycle'", + all(r["roles"].get(B) != "charge" for r in rows) + and last.get("why") == "cycle") +check("every quarter at or under the month aim", + worst_quarter(st) <= AIM + 1.0) +check("A never gives back while there is no real peak", + max(r["p"]["a"] for r in rows) <= 0.0) +check("the shaping was never paused", not any(c._m24_susp)) + +# ============================================================================ # +print("\n2. forecast between 3450 W and the month aim; a real peak") +rows2, st2, c2 = scen(a=CH, house_w=3800.0) +ma2 = mean(rows2, "a") +print(f" house 3800: A {ma2:+.0f} W, worst quarter " + f"{worst_quarter(st2):.0f} W") +check("forecast 4900 W (over 3450, under 5950): no pause, A charges " + "(5950 - 3800) / 2 = 1075 W and gives nothing", + not any(c2._m24_susp) and -1100.0 <= ma2 <= -1040.0 + and max(r["p"]["a"] for r in rows2) <= 0.0 + and worst_quarter(st2) <= AIM + 1.0) +rows3, st3, c3 = scen(a=CH, house_w=6500.0) +print(f" house 6500: paused {sum(c3._m24_susp)}/{len(c3._m24_susp)} " + f"cycles, A max {max(r['p']['a'] for r in rows3):+.0f} W") +check("a real peak (house over the month aim) still pauses the shaping " + "(SAFETY-07)", sum(c3._m24_susp) > len(c3._m24_susp) // 2) +rows4, st4, c4 = scen(a=CH, house_w=3000.0, peak=None) +print(f" no banked peak: A {mean(rows4, 'a'):+.0f} W, worst quarter " + f"{worst_quarter(st4):.0f} W") +check("no banked peak: the aim is cap - margin (3450 W) as before, so A " + "charges (3450 - 3000) / 2 = 225 W, B does not trade, the quarter " + "stays under 3450 W", + -240.0 <= mean(rows4, "a") <= -210.0 and not any(c4._m24_susp) + and all("CHARGE" not in str(r["action"]) for r in rows4) + and worst_quarter(st4) <= 3450.0 + 1.0) + +# ============================================================================ # +print("\n3. the mirror: B in maintenance CHARGE, A the charger") +rowsm, stm, cm = scen(b=CH, soc=(30.0, 49.0)) +mam, mbm = mean(rowsm, "a"), mean(rowsm, "b") +lastm = rowsm[-1] if rowsm else {} +print(f" A {mam:+.0f} W, B {mbm:+.0f} W, worst quarter " + f"{worst_quarter(stm):.0f} W, why {lastm.get('why')}") +check("B charges at 1475 W, A files no grid trade, why 'cycle'", + -1500.0 <= mbm <= -1440.0 and mam > -50.0 + and all("CHARGE" not in str(r["action"]) for r in rowsm) + and lastm.get("why") == "cycle" + and all(r["roles"].get(A) != "charge" for r in rowsm)) +check("...every quarter at or under the month aim", + worst_quarter(stm) <= AIM + 1.0) + +# ============================================================================ # +print("\n4. modetrade.decide(maint_charging=)") +_runs = SimpleNamespace(on=True, cheap=SimpleNamespace(holds=lambda n: True), + charge_useful=lambda: True, give_at=lambda n: None, + sell=None) + + +def _dec(packs, **kw): + args = dict(charge_ok=True, sell_ok=True, trade_why=None, price_now=0.1, + headroom_w=3000.0, floor_pct=20.0, ceiling_pct=95.0, + house_w=800.0) + args.update(kw) + return modetrade.decide(_runs, sc.UTC0, packs, **args) + + +_pa = modetrade.Pack(A, True, packmode.CHEAP_HOURS, False, 2500.0, 50.0, 10.0, + idle=False) +_pb = modetrade.Pack(B, True, packmode.CHEAP_HOURS, False, 2500.0, 30.0, 10.0) +_off = _dec([_pa, _pb]) +_on = _dec([_pa, _pb], maint_charging=True) +_dr = _dec([_pa, _pb], draining=True) +check("without it B is the charger (as before)", + _off.action == modetrade.CHARGE and _off.roles[B] == modetrade.CHARGE) +check("with it: no charge, why 'cycle', B keeps a hold role, no ask", + _on.action is None and _on.why == "cycle" and _on.ask_w == 0.0 + and _on.roles[B] == modetrade.HOLD) +check("same answer as the SAFETY-78 drain", _on == _dr) +_pr = modetrade.Pack(B, True, packmode.CHEAP_HOURS, False, 2500.0, 30.0, 10.0, + refused=-1, probing=True) +_tp = _dec([_pa, _pr], maint_charging=True) +check("a refusal probe beside the maintenance charge goes on: PROBE_W alone " + "(OPT-20); beside a drain it does not", + _tp.action == modetrade.CHARGE and _tp.ask_w == -modetrade.PROBE_W + and _dec([_pa, _pr], draining=True).action is None) +check("a probe does not carry a normal charger along", + _dec([_pa, _pr, modetrade.Pack("inverter-c", True, packmode.CHEAP_HOURS, + False, 2500.0, 30.0, 10.0)], + maint_charging=True).ask_w == -modetrade.PROBE_W) +check("it files nothing outside a cheap run (why None)", + _dec([_pa, _pb], maint_charging=True, + ).why == "cycle" and modetrade.decide( + SimpleNamespace(on=False), sc.UTC0, [_pa, _pb], charge_ok=True, + sell_ok=True, trade_why=None, price_now=0.1, headroom_w=3000.0, + floor_pct=20.0, ceiling_pct=95.0, house_w=800.0, + maint_charging=True).why is None) + +# ============================================================================ # +print("\n5. unchanged: N=1 (no forecast entity), the drain, modes off") +d1 = sc.digest(scen(a=CH, n=1, fc=False, peak=None, soc=(49.0, 30.0))[0]) +dd = sc.digest(scen(a=DRAIN_R, soc=(60.0, 30.0), peak=None, fc=False)[0]) +dm = sc.digest(scen(a=CH, variant="modes_off", peak=None, fc=False)[0]) +AT_BASE = { + "n1": "44816d132984ecd64d5a2510223debe102f29decd1d5127ae2b255b45dbf8bd4", + "drain": "8fd86d0816626ee5ae86bc973cb0121b1b5108e56c3b0fdd4b4be6c1f403f748", + "off": "a007f962793611bce15b11f576a76aa52063adcfde82b2a2dc0b0c075b60e60b", +} +got = {"n1": d1, "drain": dd, "off": dm} +for k in AT_BASE: + print(f" {k} {'same' if got[k] == AT_BASE[k] else 'DIFFERS'} " + f"{got[k][:16]}") +check("N=1 with A in maintenance charge and no forecast entity: shares, " + "grid, trade, roles and plant powers equal release/1.0 02eac3b", + got["n1"] == AT_BASE["n1"]) +check("the SAFETY-78 drain beside a charger: equal to 02eac3b", + got["drain"] == AT_BASE["drain"]) +check("battery modes off: equal to 02eac3b", got["off"] == AT_BASE["off"]) + +print() +if fails: + print(f"{len(fails)} FAILED:") + for f in fails: + print(f" - {f}") + sys.exit(1) +print("all checks passed") diff --git a/goodwe_controller/test_maint25.py b/goodwe_controller/test_maint25.py new file mode 100644 index 0000000..715341f --- /dev/null +++ b/goodwe_controller/test_maint25.py @@ -0,0 +1,162 @@ +"""Runnable check for MAINT-25. `python3 test_maint25.py` + +After a failed monthly cycle the add-on waits 7 days (MAINT-13, `backoff_until`). +The Home plan ignored that and drew a cycle at the start hour every night of +the wait. Through the plan builder (`status()` as in test_home.py), N=1 and N=2: +during the back-off no cycle run is drawn and a short line says when it waits +until, in English and Dutch; after 7 days the run is drawn again; a cycle +completed after the failure ends the back-off. +Read MUTATION.md before you report a survivor. +""" + +import asyncio +import os +import sys +from datetime import datetime, timedelta, timezone + +HERE = os.path.dirname(os.path.abspath(__file__)) +sys.path.insert(0, HERE) + +from app import homeview # noqa: E402 +from app.main import Controller # noqa: E402 + +fails = [] + + +def check(name, cond): + print(f" {'ok ' if cond else 'FAIL'} {name}") + if not cond: + fails.append(name) + + +class _Store: + def __init__(self): + self.data = {} + + def set(self, k, v): + self.data[k] = v + + def get(self, k, d=None): + return self.data.get(k, d) + + def set_time(self, k, v): + self.data[k] = v.isoformat() + + def get_time(self, k): + v = self.data.get(k) + return None if v is None else datetime.fromisoformat(v) + + +class _Pub: + enabled = False + + def publish(self, _v): + pass + + def close(self): + pass + + +class _Hass: + session = None + token = "" + + async def limits(self, _e): + return (-5000.0, 5000.0, 1.0) + + async def number(self, _e, invert=False): + return None + + async def state(self, _e): + return None + + async def set_number(self, _e, _v): + return True + + async def call(self, *_a): + return True + + async def states(self): + return [] + + +NOW = datetime(2026, 9, 27, 9, 40, tzinfo=timezone.utc) +ONE = {"setpoint_entity": "number.sp", "meter_entity": "sensor.grid", + "soc_entity": "sensor.soc", "batt_entity": "sensor.batt", + "meter_source": "off", "max_w": 5000, "shadow_mode": "off", + "maintenance_enabled": True, "maintenance_start_hour": 12} +TWO = dict(ONE, inverters=[ + {"name": "Battery A", "setpoint_entity": "number.a", "soc_entity": + "sensor.soc_a", "batt_entity": "sensor.batt_a", "max_w": 2500, + "capacity_kwh": 9.6}, + {"name": "Battery B", "setpoint_entity": "number.b", "soc_entity": + "sensor.soc_b", "batt_entity": "sensor.batt_b", "max_w": 2500, + "capacity_kwh": 5.4}]) + + +def make(opts, failed=None, done=None): + c = Controller(dict(opts), _Hass(), _Store(), _Pub(), stop=asyncio.Event()) + c.auto = True + for inv in c.inverters: + inv.soc, inv.batt, inv.last_write = 50.0, 0.0, 0.0 + inv.dev_min, inv.dev_max = -5000.0, 5000.0 + c.grid = 10.0 + m = c.maints[0] + if failed is not None: + m.store.set_time("last_failed", failed) + if done is not None: + m.store.set_time("last_completed", done) + return c + + +def plan(c, lang=None): + s = c.status_payload() + s.update(homeview.build(c, level=s["level"], checks=s["checks"], now=NOW, + **({} if lang is None else {"lang": lang}))) + p = s["plan"] + return [r for r in p["runs"] if r["kind"] == "cycle"], p["lines"] + + +D = timedelta(days=1) +print("1. a cycle failed 1 day ago (N=2: Battery A failed, B never ran)") +runs, lines = plan(make(TWO, failed=NOW - D)) +print(" ", [r["from"] for r in runs], lines) +check("the run tonight is B's, not A's (A waits out the back-off)", + len(runs) == 1 and not any("Battery A waits its turn" in x for x in lines)) +check("a plain line says Battery A waits until 3 October", + any("Battery A: the monthly cycle waits until 3 October." == x + for x in lines)) + +print("\n2. N=1") +runs1, lines1 = plan(make(ONE, failed=NOW - D)) +check("no cycle run is drawn, one line says when it waits until", + runs1 == [] and any("waits until 3 October" in x for x in lines1)) +runs1b, lines1b = plan(make(ONE)) +check("without a failure the run is drawn (non-vacuous)", + len(runs1b) == 1 and not any("waits until" in x for x in lines1b)) + +print("\n3. after the 7 days, and after a cycle that completed") +runs2, lines2 = plan(make(ONE, failed=NOW - timedelta(days=7, hours=1))) +check("7 days and an hour after the failure the run is drawn again, no line", + len(runs2) == 1 and not any("waits until" in x for x in lines2)) +runs3, lines3 = plan(make(ONE, failed=NOW - D, done=NOW - D / 2)) +check("a cycle completed after the failure ends the back-off (the run is " + "not drawn only if it is no longer due)", + not any("waits until" in x for x in lines3)) +runs3b, lines3b = plan(make(ONE, failed=NOW - 2 * D, done=NOW - 3 * D)) +check("a completion BEFORE the failure does not end it", + runs3b == [] and any("waits until" in x for x in lines3b)) + +print("\n4. Dutch") +_, lnl = plan(make(ONE, failed=NOW - D), lang="nl") +print(" ", lnl) +check("the Dutch line says it plainly", + any("de maandelijkse cyclus wacht tot 3 oktober" in x for x in lnl)) + +print() +if fails: + print(f"{len(fails)} FAILED:") + for f in fails: + print(f" - {f}") + sys.exit(1) +print("all checks passed") diff --git a/goodwe_controller/test_messages.py b/goodwe_controller/test_messages.py index c007134..a4e5a3c 100644 --- a/goodwe_controller/test_messages.py +++ b/goodwe_controller/test_messages.py @@ -241,6 +241,27 @@ check("the output-clamp alarm quotes asked before sent", # ============================================================================== # print("\n2. no notification is worded outside app/messages.py") APP = HERE / "app" +sys.path.insert(0, str(HERE / "tools")) +import main_files # noqa: E402 + + +class _AppFile: + """An app/*.py file. `main.py` stands for itself and the files split from + it (MAINT-21), so every scan below still sees the Controller whole.""" + + def __init__(self, path): + self.name, self.stem, self._path = path.name, path.stem, path + + def read_text(self, encoding="utf-8"): + if self.name == "main.py": + return main_files.source() + return self._path.read_text(encoding=encoding) + + +def _app_py(): + split = set(main_files.files()) - {"main.py"} + return [_AppFile(f) for f in sorted(APP.glob("*.py")) + if f.name not in split] # UX-08 2d: a refusal is counted as it is SHOWN. A placeholder that names a @@ -318,7 +339,7 @@ def notification_calls(tree): bad_calls, n_calls = [], 0 -for f in sorted(APP.glob("*.py")): +for f in _app_py(): for call in notification_calls(ast.parse(f.read_text(encoding="utf-8"))): n_calls += 1 payload = call.args[2] if len(call.args) > 2 else None @@ -368,13 +389,13 @@ def _module_constants(tree): _MODCONST = {f.stem: _module_constants(ast.parse(f.read_text(encoding="utf-8"))) - for f in sorted(APP.glob("*.py"))} + for f in _app_py()} def collect(): """(kind, where, text) for every user-facing literal of a ratcheted kind.""" out = [] - for f in sorted(APP.glob("*.py")): + for f in _app_py(): if f.name == "messages.py": continue tree = ast.parse(f.read_text(encoding="utf-8")) @@ -543,7 +564,7 @@ for key, text in messages.hint_samples(): p = row_problems(messages.GREEN, text) check(f"hint {text!r}{' - ' + '; '.join(p) if p else ''}", not p) _calls, _bare = 0, [] -for f in sorted(APP.glob("*.py")): +for f in _app_py(): for node in ast.walk(ast.parse(f.read_text(encoding="utf-8"))): if (isinstance(node, ast.Call) and ast.unparse(node.func).endswith("log_event")): @@ -1012,7 +1033,7 @@ def _static(spec): the named file (placeholders count as one word, as in part 3).""" fname, kind, name = spec out = [] - for f in ([APP / fname] if fname != "*" else sorted(APP.glob("*.py"))): + for f in ([_AppFile(APP / fname)] if fname != "*" else _app_py()): tree = ast.parse(f.read_text(encoding="utf-8")) for node in ast.walk(tree): if kind == "call" and isinstance(node, ast.Call) and node.args \ @@ -1201,7 +1222,7 @@ def scan_log_lines(files, text=None, data=None, long_ok=None, long_seen=None): _FILES = [(f.name, ast.parse(f.read_text(encoding="utf-8"))) - for f in sorted(APP.glob("*.py"))] + for f in _app_py()] _long_seen = set() _unknown, _stale, _bad = scan_log_lines(_FILES, long_seen=_long_seen) for k, sample, p in _bad: @@ -1415,7 +1436,7 @@ def _captured(logger_name, fn): def _level_of(fname, words_in_line): """The level of the log call in `fname` whose literal holds the words.""" - tree = ast.parse((APP / fname).read_text(encoding="utf-8")) + tree = ast.parse(_AppFile(APP / fname).read_text(encoding="utf-8")) for node in ast.walk(tree): if isinstance(node, ast.Call) and node.args \ and re.search(r"_LOG\.\w+$", ast.unparse(node.func)): @@ -1561,7 +1582,7 @@ check(f"a socket Home Assistant closed is a plain ConnectionResetError, which " # words. The keys are found in the code: each `Claim.set(source, ..., reason)` # through main.why_key(), plus main.py's own refusal to split ("unsplit"). _SOURCES = {} -for _f in sorted(APP.glob("*.py")): +for _f in _app_py(): _tree = ast.parse(_f.read_text(encoding="utf-8")) _consts = _module_constants(_tree) for _n in ast.walk(_tree): @@ -1781,7 +1802,7 @@ check(f"...and in the action log, which an installer reads at the default " and any(e.endswith(messages.NO_REASON_SAVED) for e in _rs_ev)) # UX-11 item 4: the action log's clamp count and the shadow-off entry. -_main_src = (APP / "main.py").read_text(encoding="utf-8") +_main_src = _AppFile(APP / "main.py").read_text(encoding="utf-8") check("the action log counts 'engagements' with a real plural and the " "shadow-off entry is plain, not 'engagement(s)' or 'SHADOW MODE OFF -'", "engagement(s)" not in _main_src and "SHADOW MODE OFF" not in _main_src diff --git a/goodwe_controller/test_modes.py b/goodwe_controller/test_modes.py index 7f31f9b..026d16a 100644 --- a/goodwe_controller/test_modes.py +++ b/goodwe_controller/test_modes.py @@ -32,6 +32,7 @@ sys.path.insert(0, os.path.join(HERE, "tools")) import opt11_identity as rig # noqa: E402 from named_absence import nth, present # noqa: E402 +import main_files # noqa: E402 import app.main as app_main # noqa: E402 from app import homeview, messages, packmode # noqa: E402 from app.control import MODE_BOUND # noqa: E402 @@ -62,24 +63,24 @@ def store_with(**modes): def spy_claims(): """Record every claim list main.py's own `resolve` is handed.""" - seen, real = [], app_main.resolve + seen, real = [], main_files.live.resolve def _spy(claims, **kw): seen.append(list(claims)) return real(claims, **kw) - app_main.resolve = _spy - return seen, lambda: setattr(app_main, "resolve", real) + main_files.live.resolve = _spy + return seen, lambda: setattr(main_files.live, "resolve", real) def spy_bounds(): """Record the `bound` main.py hands `compute()` on every cycle.""" - seen, real = [], app_main.compute + seen, real = [], main_files.live.compute def _spy(*a, **kw): seen.append(kw.get("bound", "absent")) return real(*a, **kw) - app_main.compute = _spy - return seen, lambda: setattr(app_main, "compute", real) + main_files.live.compute = _spy + return seen, lambda: setattr(main_files.live, "compute", real) def flat(t): diff --git a/goodwe_controller/test_modes_p3.py b/goodwe_controller/test_modes_p3.py index ecb13cd..668e9c8 100644 --- a/goodwe_controller/test_modes_p3.py +++ b/goodwe_controller/test_modes_p3.py @@ -472,15 +472,36 @@ _sw = [(UTC0.timestamp() + 60 * k, 2000.0 if k % 2 else 3900.0) ROWS_W, _, _ = run_day("p3_ch_sell", hours=1.5, house=_sw, soc0={"a": 60.0, "b": 30.0}) _per_q = {} +_ev_q = {} # SAFETY-135: per period, the charge's starts and stops for a_, b_ in zip(ROWS_W, ROWS_W[1:]): - if a_["action"] != arbitrage.CHARGE and b_["action"] == arbitrage.CHARGE: + on_a, on_b = (a_["action"] == arbitrage.CHARGE, + b_["action"] == arbitrage.CHARGE) + if on_a != on_b: + q = int(b_["now"].timestamp() // 900) + _ev_q.setdefault(q, []).append((on_b, b_["now"].timestamp())) + if not on_a and on_b: q = int(b_["now"].timestamp() // 900) _per_q[q] = _per_q.get(q, 0) + 1 + + +def _one_restart(ev): + """At most one start after a stop in the period, RESTART_S or more after + it; a second stop is the last change of the period.""" + re = [(t0, t1) for (s0, t0), (s1, t1) in zip(ev, ev[1:]) + if not s0 and s1] + stops, late = 0, False + for on, _t in ev: + stops += 0 if on else 1 + late = late or (on and stops >= 2) + return (len(re) <= 1 and not late + and all(t1 - t0 >= modetrade.RESTART_S - 1 for t0, t1 in re)) print(f" house swinging 2.0/3.9 kW each minute: charge starts per period " f"{sorted(_per_q.values())}") check("a charge the peak guard or the headroom stopped stays off for the " - "rest of that 15-minute period (at most one start per period)", - _per_q and max(_per_q.values()) == 1) + "rest of that 15-minute period, after at most one restart RESTART_S or " + "more after the first stop; a second stop latches (SAFETY-135)", + _per_q and max(_per_q.values()) <= 2 + and all(_one_restart(ev) for ev in _ev_q.values())) # At the floor: B starts the sale just above it. ROWS_F, _, _ = run_day("p3_ch_sell", start_h=18.75, hours=1.5, diff --git a/goodwe_controller/test_modes_p4.py b/goodwe_controller/test_modes_p4.py index 698be67..ed0c389 100644 --- a/goodwe_controller/test_modes_p4.py +++ b/goodwe_controller/test_modes_p4.py @@ -37,6 +37,7 @@ sys.path.insert(0, os.path.join(HERE, "tools")) logging.disable(logging.WARNING) from named_absence import nth, present # noqa: E402 +import main_files # noqa: E402 import opt11p3_replay as rp # noqa: E402 from app import arbitrage, dayplan, homeview, modetrade, packmode # noqa from app import priceruns, solarfc, validate # noqa: E402 @@ -64,11 +65,16 @@ print("1. no usable forecast: byte-identical to 5a4cdc2 (P3 option A)") # OPT-15 head: a charge end now holds the loop at the house's level (F2). With # that hold and its reseed switched off they equal 5a4cdc2's again; the others # (no charge) never moved. +# SAFETY-135: n1_ch re-pinned. A first guard stop no longer latches, so while +# the charge waits its reason reads "(peak)" where the latch said +# "(headroom)"; no command moves. With SAFETY-135 off it is OPT-15's pin +# again (checked below). +N1_CH_OPT15 = "97893a54f8a8e3f36ad24f100973b3ff35766527e7287a6ae30cc1c8941bac02" BASE_DIGESTS = { "n1_ls": "13f11c330263c91625acde7628426ff16dae3a9af99aebeef3051dc5b5a884ea", "n1_ch": - "97893a54f8a8e3f36ad24f100973b3ff35766527e7287a6ae30cc1c8941bac02", + "5d529f516307e4da4dca48714ee891332a2eea5e1b1763f0f1e049cfb0819a0a", "n2_sf_ls": "9424e1837b805a6a31293a28b8fbad6ba611ea0bfe3240d636d68d62dc5e9f22", "n2_ch_ls": @@ -80,7 +86,7 @@ BASE_DIGESTS = { "n1_ls_fc_down": "13f11c330263c91625acde7628426ff16dae3a9af99aebeef3051dc5b5a884ea", "n1_ch_fc_down": - "97893a54f8a8e3f36ad24f100973b3ff35766527e7287a6ae30cc1c8941bac02", + "5d529f516307e4da4dca48714ee891332a2eea5e1b1763f0f1e049cfb0819a0a", "n2_sf_ls_fc_down": "9424e1837b805a6a31293a28b8fbad6ba611ea0bfe3240d636d68d62dc5e9f22", "n2_ch_ls_fc_down": @@ -97,6 +103,38 @@ for k, v in BASE_DIGESTS.items(): check(f"{k}: pinned digest (5a4cdc2; OPT-15 for the _ch ones)", got.get(k) == v) check("every scenario is pinned", set(got) == set(BASE_DIGESTS)) + + +class _Every: + """SAFETY-135 off: a stop period equal to every period, so every guard + stop latches as before.""" + + def __eq__(self, other): + return True + + def __ne__(self, other): + return False + + +def _s135_off_digest(scn): + from app import main as _m + real = _m.Controller.__init__ + + def init(self, *a, **k): + real(self, *a, **k) + self._charge_stop = (_Every(), float("-inf")) + young, restart = modetrade.YOUNG_S, modetrade.RESTART_S + _m.Controller.__init__ = init + modetrade.YOUNG_S = modetrade.RESTART_S = 0.0 + try: + return ident.p3.digest(ident.run(**ident.SCENARIOS[scn])[0]) + finally: + _m.Controller.__init__ = real + modetrade.YOUNG_S, modetrade.RESTART_S = young, restart + + +check("n1_ch with SAFETY-135 off is OPT-15's pin: only the reason word moved", + _s135_off_digest("n1_ch") == N1_CH_OPT15) for k in [k for k in got if k.endswith("_fc_down")]: check(f"{k}: a set but unavailable forecast equals no forecast", got[k] == got[k[:-len('_fc_down')]]) @@ -777,7 +815,7 @@ check("battery modes off: the forecast sensor is never read", READS[0] == 0) print("7. the Batteries screen and the Simple view") rows, st_, c = run_day(SF_LS, fc=1.0, soc0={"a": 60.0, "b": 30.0}, hours=0.6) -rp.m.datetime = datetime +main_files.live.datetime = datetime sb = homeview.solar_block(c, c.solar_fc.at) check("the forecast line names the forecast, what is counted and when", sb["line"].startswith("Solar still to come today:") @@ -812,14 +850,14 @@ check("a lost forecast says so: no forecast, Leftover solar solar only", c._charge_latch = latch # the latch ends at its end time; this replay ran in September, so ask at a # moment inside it -_real_dt = rp.m.datetime -rp.m.datetime = type("_DT", (datetime,), {"now": classmethod( +_real_dt = main_files.live.datetime +main_files.live.datetime = type("_DT", (datetime,), {"now": classmethod( lambda cls, tz=None: latch[0] - timedelta(hours=1))}) check("OPT-34: with a charge under way (B charged in this run), the level " "stays: plan_targets() gives it (the line: test_opt34.py)", latch is not None and c.plan_targets() is not None and B in c.plan_targets() and c.plan_targets()[B] == c._plan_targets[B]) -rp.m.datetime = _real_dt +main_files.live.datetime = _real_dt check("the Why line wins over 'saves its power' only while holding", homeview.battery_why(modes_on=True, mode="leftover_solar", off=False, reading=True, phase="idle", shadow=False, diff --git a/goodwe_controller/test_opt20.py b/goodwe_controller/test_opt20.py index 889d8fd..39f0816 100644 --- a/goodwe_controller/test_opt20.py +++ b/goodwe_controller/test_opt20.py @@ -248,11 +248,14 @@ print("\n4. battery modes on, no probe: byte-identical to release/1.0 bf9019e") # now counts those seconds, so ch_ch's quarters land on 3450.0 W where they # landed 1.3-1.4 W over it (bf9019e: 15fc25dd...), and ch_ch_maint's first, # partial quarter charges a little less at its end (bf9019e: e46e3c66...). +# MAINT-24 moved ch_ch_maint again: B no longer grid-charges beside A's +# maintenance charge, and A's charge is no longer paused (release/1.0 02eac3b: +# e56eddab...). AT_BASE = { "sf_ch": "422d6578a7decf1ae3749edd1898ff3cd0541d904c95f636cdd9b1de8c1a07c9", "ch_ch": "2b5879ec95810c39a5f0f82c04b9f8e358ea03ddce4ba187cc2b7e0885dfcbfa", "ch_ch_maint": - "e56eddabdb785f81793e7afa525f8e6da237b0b2165860aa8e0f8a6499b275a9", + "df86a451a3b2d365ca5d35b772cd1eb8502d164e6b63e6844b5cfb82f15aeb46", } _got = sc.no_probe_digests() for _k in AT_BASE: @@ -260,8 +263,8 @@ for _k in AT_BASE: f"{_got[_k][:16]}") check("with no refusal every share, grid, trade sentence, role and plant " "power of a scripted cheap run equals bf9019e's (A Solar first, A " - "charging, A in maintenance charge; the last two as SAFETY-125 moved " - "them)", _got == AT_BASE) + "charging, A in maintenance charge; the last two as SAFETY-125 and " + "MAINT-24 moved them)", _got == AT_BASE) print() if fails: diff --git a/goodwe_controller/test_opt27.py b/goodwe_controller/test_opt27.py index 7f3809d..3670f12 100644 --- a/goodwe_controller/test_opt27.py +++ b/goodwe_controller/test_opt27.py @@ -46,6 +46,7 @@ logging.disable(logging.WARNING) import opt11p3_replay as rp # noqa: E402 from named_absence import first, nth, present # noqa: E402 +import main_files # noqa: E402 import app.main as m # noqa: E402 from app import homeview, modetrade, solarfc # noqa: E402 from app.main import Controller # noqa: E402 @@ -404,14 +405,14 @@ def drive27(o, sensors, *, pre, start, minutes=20, restart=None, async def go(): c, hass = build(store) - real_dt, real_hv = m.datetime, homeview.datetime + real_dt, real_hv = main_files.live.datetime, homeview.datetime class _DT(real_dt): @classmethod def now(cls, tz=None): return clock[0] if tz is None else clock[0].astimezone(tz) - m.datetime = homeview.datetime = _DT + main_files.live.datetime = homeview.datetime = _DT task = None try: for t_pre in pre: @@ -477,7 +478,7 @@ def drive27(o, sensors, *, pre, start, minutes=20, restart=None, await task except asyncio.CancelledError: pass - m.datetime, homeview.datetime = real_dt, real_hv + main_files.live.datetime, homeview.datetime = real_dt, real_hv return c return asyncio.run(go()), rows, pre_rows diff --git a/goodwe_controller/test_opt34.py b/goodwe_controller/test_opt34.py index fdb4698..3db53fc 100644 --- a/goodwe_controller/test_opt34.py +++ b/goodwe_controller/test_opt34.py @@ -61,6 +61,7 @@ sys.path.insert(0, os.path.join(HERE, "tools")) logging.disable(logging.WARNING) import opt11p3_replay as rp # noqa: E402 +import main_files # noqa: E402 import app.main as m # noqa: E402 from app import homeview, solarfc # noqa: E402 from app.main import Controller # noqa: E402 @@ -348,14 +349,14 @@ def run_night(spec): async def go(): cur = store - real_dt, real_hv = m.datetime, homeview.datetime + real_dt, real_hv = main_files.live.datetime, homeview.datetime class _DT(real_dt): @classmethod def now(cls, tz=None): return clock[0] if tz is None else clock[0].astimezone(tz) - m.datetime = homeview.datetime = _DT + main_files.live.datetime = homeview.datetime = _DT try: # TEST-37: built under the scenario's clock, not the real one: # Controller.__init__ checks a stored latch's end against now(). @@ -420,7 +421,7 @@ def run_night(spec): out["soc"] = (hass.plants["a"].soc, hass.plants["b"].soc) out["latch"] = getattr(c, "_charge_latch", None) is not None finally: - m.datetime, homeview.datetime = real_dt, real_hv + main_files.live.datetime, homeview.datetime = real_dt, real_hv return out return asyncio.run(go()) @@ -722,7 +723,7 @@ from types import SimpleNamespace # noqa: E402 from app import modetrade, priceruns # noqa: E402 CLOCK = [at(4, 1, 0)] -_dt0 = m.datetime +_dt0 = main_files.live.datetime class _FixedDT(_dt0): @@ -731,7 +732,7 @@ class _FixedDT(_dt0): return CLOCK[0] if tz is None else CLOCK[0].astimezone(tz) -m.datetime = homeview.datetime = _FixedDT +main_files.live.datetime = homeview.datetime = _FixedDT _tmp = tempfile.mkdtemp(prefix="o34-") lc = Controller(dict(opts()), rp.Hass(("a", "b"), lambda t: 300.0, {"a": 40.0, "b": 40.0}), @@ -858,7 +859,7 @@ lc._charge_latch = (at(4, 6, 10), {A: 80.0}, at(4, 1, 0)) lt, _s = latch_step(None, resting, None, now=at(4, 6, 5), runs=r3) check("F4: a run that starts AT the bell (06:00-09:00) does carry it on, " "to its end + one slot", lt is not None and lt[0] == at(4, 9, 15)) -m.datetime = homeview.datetime = _dt0 +main_files.live.datetime = homeview.datetime = _dt0 print() if fails: diff --git a/goodwe_controller/test_opt36.py b/goodwe_controller/test_opt36.py index 331f6ed..1b1d3da 100644 --- a/goodwe_controller/test_opt36.py +++ b/goodwe_controller/test_opt36.py @@ -49,6 +49,7 @@ logging.disable(logging.WARNING) from named_absence import nth, present # noqa: E402 import ux54_scenarios as S # noqa: E402 import opt11p3_replay as rp # noqa: E402 +import main_files # noqa: E402 import app.main as m # noqa: E402 from app import dayplan, homeview, modetrade, packmode # noqa: E402 from app import priceruns, solarfc, uitext # noqa: E402 @@ -662,14 +663,14 @@ def run_night(spec): for d in ("2026-10-31", "2026-11-01", "2026-11-02")}) async def go(): - real_dt, real_hv = m.datetime, homeview.datetime + real_dt, real_hv = main_files.live.datetime, homeview.datetime class _DT(real_dt): @classmethod def now(cls, tz=None): return clock[0] if tz is None else clock[0].astimezone(tz) - m.datetime = homeview.datetime = _DT + main_files.live.datetime = homeview.datetime = _DT try: for t_pre in EVENING: clock[0] = t_pre @@ -722,7 +723,7 @@ def run_night(spec): out["soc"] = (hass.plants["a"].soc, hass.plants["b"].soc) out["latch"] = getattr(c, "_charge_latch", None) is not None finally: - m.datetime, homeview.datetime = real_dt, real_hv + main_files.live.datetime, homeview.datetime = real_dt, real_hv return out return asyncio.run(go()) diff --git a/goodwe_controller/test_packshare.py b/goodwe_controller/test_packshare.py index 561e9ad..b4e3893 100644 --- a/goodwe_controller/test_packshare.py +++ b/goodwe_controller/test_packshare.py @@ -34,6 +34,8 @@ import sys from datetime import datetime, timedelta, timezone from math import inf from pathlib import Path +sys.path.insert(0, str(Path(__file__).resolve().parent / "tools")) +import main_files # noqa: E402 from app import arbitrage, packshare from named_absence import first, nth, present @@ -1132,8 +1134,7 @@ check("...and misfiling it ON THE SITE is caught and REFUSED, not consumed. A " # main.py's own AST, the way test_peakguard.py part 12i pins the arguments of # `arbitrage.decide()`, and for the same reason: a call site that stopped # passing it is invisible to every fixture. -_main_src = (Path(__file__).resolve().parent / "app" / "main.py").read_text( - encoding="utf-8") +_main_src = main_files.source() _resolve_calls = [n for n in ast.walk(ast.parse(_main_src)) if isinstance(n, ast.Call) and isinstance(n.func, ast.Name) and n.func.id == "resolve"] @@ -1158,9 +1159,7 @@ check("⚠️ MAIN.PY ACTUALLY PASSES `weights=`, AND IT PASSES THE METHOD RATHE # cycle's value, and logs. What it does NOT grade is the sentence it logs or # that a real cycle reaches it; that is stated here rather than implied. _cycle_src = first( - f for cls in ast.walk(ast.parse( - (Path(__file__).resolve().parent / "app" / "main.py") - .read_text(encoding="utf-8"))) + f for cls in ast.walk(main_files.tree()) if isinstance(cls, ast.ClassDef) and cls.name == "Controller" for f in cls.body if isinstance(f, (ast.FunctionDef, ast.AsyncFunctionDef)) and f.name == "cycle") diff --git a/goodwe_controller/test_peak_margin.py b/goodwe_controller/test_peak_margin.py index 19f09d9..e0e00f2 100644 --- a/goodwe_controller/test_peak_margin.py +++ b/goodwe_controller/test_peak_margin.py @@ -22,6 +22,7 @@ import sys HERE = os.path.dirname(os.path.abspath(__file__)) sys.path.insert(0, os.path.join(HERE, "tools")) +import main_files # noqa: E402 import safety79_identity as rig # noqa: E402 from named_absence import nth, present # noqa: E402 @@ -207,9 +208,8 @@ check("...and the user-facing peak notice built from the decision's limit " # ============================================================================ # print("\n4. each call site in main.py") -with open(os.path.join(HERE, "app", "main.py"), encoding="utf-8") as f: - _src = f.read() -_tree = ast.parse(_src) +_src = main_files.source() +_tree = main_files.tree(_src) def calls(name): @@ -245,14 +245,16 @@ print(f" decide(cap_w={kw(_d, 'cap_w')}, margin_w={kw(_d, 'margin_w')})") print(f" shaping_suspended(..., {arg(_s, 2)})") print(f" maintenance_charge_floor(..., {arg(_m, 2)})") print(f" PeakTracker(cap_w={kw(_t, 'cap_w')})") +# MAINT-24: the maintenance forecast checks get the guard's own aim, cap - +# margin with this month's peak in (`maint_aim`), not the plain cap - margin. check("test_call_sites: the guard gets the real cap AND the margin; the " - "forecast checks get cap - margin; the month-peak tracker gets the " - "real cap", + "forecast checks get the guard's aim, cap - margin and the month " + "peak (MAINT-24); the month-peak tracker gets the real cap", len(_dec) == 1 and "peak_cap_w" in kw(_d, "cap_w") and kw(_d, "margin_w") == "self.peak_margin_w" and len(_shape) == 1 and len(_maint) == 1 - and arg(_s, 2) == "self.peak_aim_w()" - and arg(_m, 2) == "self.peak_aim_w()" + and arg(_s, 2) == "maint_aim" and arg(_m, 2) == "maint_aim" + and "maint_aim = peakguard.quarter_target_w(" in _src and len(_tracker) == 1 and kw(_t, "cap_w") == 'float(opts.get("peak_cap_w", 3500))') check("test_aim_w: `peak_aim_w()` is cap - margin, and the forecast sizing " diff --git a/goodwe_controller/test_peakguard.py b/goodwe_controller/test_peakguard.py index 42e2f52..f64701b 100644 --- a/goodwe_controller/test_peakguard.py +++ b/goodwe_controller/test_peakguard.py @@ -135,6 +135,9 @@ from app.arbiter import ( ) from app.control import Tuning, compute, peak_at_risk from app.freeze import FreezeWatchdogConfig, looks_frozen, rail_w +import os # noqa: E402 +sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "tools")) # noqa: E402 +import main_files # noqa: E402 from app import main as app_main from app.inverter import Inverter, build_roster from app.main import Controller @@ -1295,7 +1298,7 @@ print(" the wiring's own mutations - a default install, maintenance charging") # `peak_at_risk()` answers False forever. That is the whole point - it is the # configuration on which the old suspension could not fire. MAINT_CHARGING = {"phase": "charge"} -_mainsrc = (HERE / "app" / "main.py").read_text(encoding="utf-8") +_mainsrc = main_files.source() def maint_cycle(tag, want_floor_w=LIVE_MAX_W * 0.3, **kw): @@ -2709,7 +2712,7 @@ CLAIM_SOURCES = {"device", "supervised", "failsafe", "safety", "peak", # silent gap in the scan. CLAIM_BUILDERS = {"peak_claim": "peak", "arb_claim": "arbitrage"} -_main_tree = ast.parse((HERE / "app" / "main.py").read_text(encoding="utf-8")) +_main_tree = main_files.tree() _cycle_def = first(( f for cls in ast.walk(_main_tree) @@ -2762,7 +2765,7 @@ def cycle_claims(run): call site and nowhere else. """ seen = [] - real = app_main.resolve + real = main_files.live.resolve def _spy(claims, **kw): # ⚠️ `**kw` PASSES THE ROSTER THROUGH UNREAD, AND THAT IS THE WHOLE @@ -2776,11 +2779,11 @@ def cycle_claims(run): seen.append(list(claims)) return real(claims, **kw) - app_main.resolve = _spy + main_files.live.resolve = _spy try: out = run() finally: - app_main.resolve = real + main_files.live.resolve = real return out, (seen[-1] if seen else []) @@ -4977,7 +4980,11 @@ check("⚠️ AND THE SECOND CONSUMER OF THE SAME REDUCTION. `arbitrage.decide() # written, at every roster length, in every configuration, and with no fixture # required. _APP_SRC = {p.stem: p.read_text(encoding="utf-8") - for p in sorted((HERE / "app").glob("*.py"))} + for p in sorted((HERE / "app").glob("*.py")) + if p.name == "main.py" or p.name not in main_files.files()} +# MAINT-21: main.py and the files split from it, the mixins read as Controller. +_APP_SRC["main"] = re.sub(r"^class \w+Mixin:", "class Controller:", + main_files.source(), flags=re.M) _ROSTER_OPTION = "inverters" # the ONE seed. Everything else is closure. _WRAPPERS = {"list", "tuple", "sorted", "enumerate", "zip", "reversed", "filter", "iter", "set", "dict"} diff --git a/goodwe_controller/test_price_history.py b/goodwe_controller/test_price_history.py index 33827f9..ce04bff 100644 --- a/goodwe_controller/test_price_history.py +++ b/goodwe_controller/test_price_history.py @@ -118,6 +118,8 @@ from app.static_tariff import resolve_tariff UTC = timezone.utc HERE = os.path.dirname(os.path.abspath(__file__)) +sys.path.insert(0, os.path.join(HERE, "tools")) +import main_files # noqa: E402 # PRICE-02: `TariffPlan.arbitrage(now=...)` is required. This instant is before every # point these fixtures build, so no period has ended and the whole series counts. @@ -2015,8 +2017,8 @@ check("...so calling it without one is a TypeError, not a quiet regression", transport=transport_for(_body_today), now=NOW)), TypeError)) -_MAIN = open(os.path.join(_APP, "main.py"), encoding="utf-8").read() -_main_tree = ast.parse(_MAIN) +_MAIN = main_files.source() +_main_tree = main_files.tree(_MAIN) _refresh = first((n for n in ast.walk(_main_tree) if isinstance(n, ast.AsyncFunctionDef) and n.name == "run_tariff_refresh"), "run_tariff_refresh in main.py") diff --git a/goodwe_controller/test_price_run_fixes.py b/goodwe_controller/test_price_run_fixes.py index a623f7f..af2d99e 100644 --- a/goodwe_controller/test_price_run_fixes.py +++ b/goodwe_controller/test_price_run_fixes.py @@ -6,7 +6,8 @@ with the lagged model (`Lag`: command dead time, meter and battery reading age, the P1 debounce, 1 s cycles), which reproduces all three on 5a4cdc2. 1. F1: a quarter edge while charging does not stop the charge (the guard - projects the quarter `now` is in), and a real guard stop still latches. + projects the quarter `now` is in), and a real guard stop still holds it + (SAFETY-135: one restart a minute later, then a second stop latches). At two inverters SAFETY-91's `next_quarter()` already does that for the guard; at one inverter only the rolled projection does. 2. F2: the export overshoot at a charge end stays within 0.15 x rating in @@ -252,7 +253,8 @@ check("two inverters: SAFETY-91 already holds the edge (no stop with the old " "projection), and rolling it changes no banked quarter", not stops(ROWS1O) and banked(C1O, ROWS1O) == banked(C1, ROWS1)) -# 1c. A real guard stop still latches, and the 500 W minimum stays. +# 1c. A real guard stop holds the charge (SAFETY-135: one restart after +# RESTART_S, a second stop latches), and the 500 W minimum stays. # House: 800 W; 3700 W at 02:20-02:21; 3000 W from 02:26 (headroom 450 W # in the next quarter); 2850 W from 02:40 (600 W). ROWS2, C2 = run(1.9, 0.9, lag=LAG, steps=[ @@ -266,11 +268,24 @@ _after2 = [r for r in ROWS2 if _first and r["now"] > _first["now"] print(f" guard stop at " f"{_first['now'].astimezone(L).strftime('%H:%M:%S') if _first else None}" f" ({_first['reason'][:40] if _first else ''})") -check("a mid-quarter 3.7 kW load stops the charge for the peak and it stays " - "off for the rest of that quarter, the house back at 800 W", +# SAFETY-135: the first guard stop in a quarter holds the charge RESTART_S, +# then it may start once more; a second stop latches to the quarter's end. +_hold2 = [r for r in _after2 + if (r["now"] - _first["now"]).total_seconds() < modetrade.RESTART_S] +_on2 = [b for a, b in zip(_after2, _after2[1:]) + if a["action"] != arbitrage.CHARGE and b["action"] == arbitrage.CHARGE] +_off2 = [b for a, b in zip(_after2, _after2[1:]) + if a["action"] == arbitrage.CHARGE and b["action"] != arbitrage.CHARGE] +print(f" after it: {len(_on2)} restart(s), {len(_off2)} more stop(s)") +check("a mid-quarter 3.7 kW load stops the charge for the peak; it stays off " + "for RESTART_S, then starts again at most once that quarter, and a " + "second stop holds it off to the quarter's end (SAFETY-135)", _first is not None and _first["now"].astimezone(L).minute == 20 and ("peak" in _first["reason"] or "headroom" in _first["reason"]) - and _after2 and all(r["action"] is None for r in _after2)) + and _hold2 and all(r["action"] is None for r in _hold2) + and len(_on2) <= 1 and len(_off2) <= 1 + and not any(r["action"] == arbitrage.CHARGE for r in _after2 + if _off2 and r["now"] >= _off2[0]["now"])) _starts = [b for a, b in zip(ROWS1 + ROWS2, (ROWS1 + ROWS2)[1:]) if a["action"] != arbitrage.CHARGE and b["action"] == arbitrage.CHARGE] diff --git a/goodwe_controller/test_price_service.py b/goodwe_controller/test_price_service.py index bfe94ae..6b0d1c6 100644 --- a/goodwe_controller/test_price_service.py +++ b/goodwe_controller/test_price_service.py @@ -44,6 +44,8 @@ import tempfile from datetime import date, datetime, timedelta, timezone from named_absence import nth +sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "tools")) # noqa: E402 +import main_files # noqa: E402 from app import main as _main from app import messages, price as P, price_chain as C from app.price import ( @@ -686,8 +688,8 @@ def controller(clock, o, tmp=None): return ctl -_REAL_DT, _REAL_GET = _main.datetime, P.https_get -_real_resolve = _main.resolve_tariff +_REAL_DT, _REAL_GET = main_files.live.datetime, P.https_get +_real_resolve = main_files.live.resolve_tariff class Wired: @@ -701,7 +703,7 @@ class Wired: self.refreshes = 0 def __enter__(self): - _main.datetime = FakeDT + main_files.live.datetime = FakeDT P.https_get = self.net W = self @@ -709,12 +711,12 @@ class Wired: r = await _real_resolve(*a, **k) W.refreshes += 1 return r - _main.resolve_tariff = counting + main_files.live.resolve_tariff = counting return self def __exit__(self, *exc): - _main.datetime, P.https_get = _REAL_DT, _REAL_GET - _main.resolve_tariff = _real_resolve + main_files.live.datetime, P.https_get = _REAL_DT, _REAL_GET + main_files.live.resolve_tariff = _real_resolve async def refresh(self, now=None): if now is not None: diff --git a/goodwe_controller/test_pv.py b/goodwe_controller/test_pv.py index ad71ba7..090575a 100644 --- a/goodwe_controller/test_pv.py +++ b/goodwe_controller/test_pv.py @@ -692,7 +692,13 @@ def touches(src: str) -> bool: or "from .pv import" in src -_touch = sorted(f.name for f in APP if touches(f.read_text(encoding="utf-8"))) +sys.path.insert(0, str(HERE / "tools")) +import main_files # noqa: E402 + +# MAINT-21: the files split from app/main.py are counted as main.py. +_SPLIT = set(main_files.files()) - {"main.py"} +_touch = sorted({"main.py" if f.name in _SPLIT else f.name for f in APP + if touches(f.read_text(encoding="utf-8"))}) print(f" {len(APP)} modules under app/; TEL-11 material is in: {_touch}") check(f"PRECONDITION: the scan found the whole package, not a subset - " f"{len(APP)} modules", len(APP) >= 25 and "control.py" in diff --git a/goodwe_controller/test_refusal.py b/goodwe_controller/test_refusal.py index a396727..04ddf02 100644 --- a/goodwe_controller/test_refusal.py +++ b/goodwe_controller/test_refusal.py @@ -142,8 +142,11 @@ def run(load, cut, dur, cap=lambda t: 1e9, old=False, events=None): **LIVE), hass, _Store(), _Pub(), stop=asyncio.Event()) c.auto = True c.dev_min, c.dev_max = -LIVE["max_w"], LIVE["max_w"] + import os # noqa: E402 + sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "tools")) # noqa: E402 + import main_files # noqa: E402 import app.main as m - real, real_dt = m.compute, m.datetime + real, real_dt = main_files.live.compute, main_files.live.datetime clock = [0.0] class _DT(real_dt): @@ -153,9 +156,9 @@ def run(load, cut, dur, cap=lambda t: 1e9, old=False, events=None): def now(cls, tz=None): return BASE + timedelta(seconds=clock[0]) - m.datetime = _DT + main_files.live.datetime = _DT if old: - m.compute = lambda *a, **k: real(*a, **dict(k, refused=None)) + main_files.live.compute = lambda *a, **k: real(*a, **dict(k, refused=None)) rows, trips, was = [], 0, False try: t = 0.0 @@ -174,7 +177,7 @@ def run(load, cut, dur, cap=lambda t: 1e9, old=False, events=None): hass.cmd, c.i_w, c.loop_reason, c.batt_refused)) t += TICK finally: - m.compute, m.datetime = real, real_dt + main_files.live.compute, main_files.live.datetime = real, real_dt return rows, trips, c return asyncio.run(go()) diff --git a/goodwe_controller/test_refusal_units.py b/goodwe_controller/test_refusal_units.py index 4366a7a..a6e689b 100644 --- a/goodwe_controller/test_refusal_units.py +++ b/goodwe_controller/test_refusal_units.py @@ -50,6 +50,9 @@ from app import control from app.control import PROBE_EVERY_S, PROBE_S, PROBE_W from app.main import Controller from app.arbiter import P_LOOP, P_PEAK, P_SAFETY, Claim, resolve +import os # noqa: E402 +sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "tools")) # noqa: E402 +import main_files # noqa: E402 import app.main as m fails = [] @@ -177,7 +180,7 @@ def run(load, cut, dur, *, soc=None, jitter=False, old=False, events=None, c.auto = True if old: _off(c) - real_dt = m.datetime + real_dt = main_files.live.datetime clock = [0.0] class _DT(real_dt): @@ -185,7 +188,7 @@ def run(load, cut, dur, *, soc=None, jitter=False, old=False, events=None, def now(cls, tz=None): return BASE + timedelta(seconds=clock[0]) - m.datetime = _DT + main_files.live.datetime = _DT rows = [] trips = {u: 0 for u in UNITS} was = {u: False for u in UNITS} @@ -211,7 +214,7 @@ def run(load, cut, dur, *, soc=None, jitter=False, old=False, events=None, db=c.inverters[1].delivery_wd.tripped)) t += dt finally: - m.datetime = real_dt + main_files.live.datetime = real_dt return rows, trips, c return asyncio.run(go()) diff --git a/goodwe_controller/test_rehearse.py b/goodwe_controller/test_rehearse.py index ded905a..4387c72 100644 --- a/goodwe_controller/test_rehearse.py +++ b/goodwe_controller/test_rehearse.py @@ -73,6 +73,7 @@ def check(name, cond): print("1. the harness's own preconditions") # --------------------------------------------------------------------------- # sys.path.insert(0, str(HERE / "tools")) +import main_files # noqa: E402 import rehearse_roster as RR # noqa: E402 check("the tool refuses rather than passing when it cannot run: its four exit " @@ -210,6 +211,11 @@ def mutant_tree(edits) -> str: dest / "tools" / "predeploy_check.py") shutil.copyfile(HERE / "config.yaml", dest / "config.yaml") for rel, old, new in edits: + if rel == "app/main.py": + # MAINT-21: app/main.py stands for the files split from it. + where = [n for n in main_files.files() if (dest / "app" / n) + .read_text(encoding="utf-8").count(old) == 1] + rel = f"app/{where[0]}" if len(where) == 1 else rel path = dest / rel text = path.read_text(encoding="utf-8") hits = text.count(old) diff --git a/goodwe_controller/test_safety107.py b/goodwe_controller/test_safety107.py index e3f7516..e58c71f 100644 --- a/goodwe_controller/test_safety107.py +++ b/goodwe_controller/test_safety107.py @@ -35,6 +35,7 @@ logging.disable(logging.WARNING) import opt11_identity as rig # noqa: E402 import safety79_identity as s79 # noqa: E402 import app.main as app_main # noqa: E402 +import main_files # noqa: E402 from app import control # noqa: E402 from app.arbiter import Claim, P_ARBITRAGE # noqa: E402 from app.main import Controller # noqa: E402 @@ -61,7 +62,7 @@ def run(n=1, *, plant, house, dur=QUARTER, tick=5.0, maint=True, (a writer above the loop), or None.""" log, rows, now = [], [], [0.0] real_power, real_tick = rig._Hass.power, rig.TICK - real_log, real_resolve, real_c = (Controller.log_event, app_main.resolve, + real_log, real_resolve, real_c = (Controller.log_event, main_files.live.resolve, rig.Controller) def power(self, u): @@ -108,7 +109,7 @@ def run(n=1, *, plant, house, dur=QUARTER, tick=5.0, maint=True, extra.update(s79.P1, peak_cap_w=cap) db = os.path.join(tempfile.mkdtemp(prefix="s107-"), "tariff.db") rig._Hass.power, rig.TICK = power, tick - Controller.log_event, app_main.resolve = log_event, resolve + Controller.log_event, main_files.live.resolve = log_event, resolve rig.Controller = functools.partial(real_c, peak_db_path=db) try: _, c = rig.run(n, extra=extra, dur=dur, load=house, @@ -117,7 +118,7 @@ def run(n=1, *, plant, house, dur=QUARTER, tick=5.0, maint=True, store=s79.store_charging(n) if maint else rig._Store()) finally: rig._Hass.power, rig.TICK = real_power, real_tick - Controller.log_event, app_main.resolve = real_log, real_resolve + Controller.log_event, main_files.live.resolve = real_log, real_resolve rig.Controller = real_c return rows, log, c diff --git a/goodwe_controller/test_safety118.py b/goodwe_controller/test_safety118.py index 30058a6..e9cb1a9 100644 --- a/goodwe_controller/test_safety118.py +++ b/goodwe_controller/test_safety118.py @@ -17,8 +17,11 @@ Mutating a module this file grades? Read MUTATION.md first (purge __pycache__). import asyncio import logging -from pathlib import Path +import os # noqa: E402 +import sys # noqa: E402 +sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "tools")) # noqa: E402 +import main_files # noqa: E402 from app import main as _main from app import messages, pv, validate from app.main import Controller @@ -217,7 +220,7 @@ check(f"one read of the forecast entity per read_inputs() ({h.reads})", print("4. maintenance headroom and the charge-only clamp use watts") seen = [] -_real = _main.maintenance_charge_floor +_real = main_files.live.maintenance_charge_floor def spy(charge_w, fc, cap): @@ -226,7 +229,7 @@ def spy(charge_w, fc, cap): return out -_main.maintenance_charge_floor = spy +main_files.live.maintenance_charge_floor = spy try: def cycle(fc, **kw): c, h = make(fc, store={"phase": "charge"}, @@ -264,7 +267,7 @@ try: check("no unit: forecast unused, clamp in place, as with the option empty", clamp(st(6000)) is False) finally: - _main.maintenance_charge_floor = _real + main_files.live.maintenance_charge_floor = _real print("5. validator and strings") def notes(unit, key="peak_forecast_entity"): @@ -367,7 +370,8 @@ check("pv.unit_fault: None for a good unit and for a missing reading (has_readin pv.unit_fault(st(1, "kW")) is None and pv.unit_fault(None) is None and pv.unit_fault(st("unavailable")) is None and pv.unit_fault(st(1)) == "" and pv.unit_fault(st(1, "kWh")) == "kWh") -src = (Path(__file__).parent / "app" / "main.py").read_text(encoding="utf-8") +# MAINT-21: main.py and the files split from it (the forecast read is in ctl_inputs). +src = main_files.source() check("the size rule is gone from main.py", "abs(raw) < 50" not in src) print() diff --git a/goodwe_controller/test_safety119.py b/goodwe_controller/test_safety119.py index 069ddc6..91e1204 100644 --- a/goodwe_controller/test_safety119.py +++ b/goodwe_controller/test_safety119.py @@ -59,6 +59,7 @@ logging.disable(logging.WARNING) import opt11_identity as rig # noqa: E402 import safety79_identity as s79 # noqa: E402 import safety84_identity as s84 # noqa: E402 +import main_files # noqa: E402 import app.main as app_main # noqa: E402 from app import messages # noqa: E402 from app.main import Controller # noqa: E402 @@ -413,8 +414,8 @@ _rg = {t: never(t, hw, seed=1, delay=0) for t, hw in RIG.items()} _rg_old = {t: never(t, hw, fix=False, seed=1, delay=0) for t, hw in RIG.items()} # SAFETY-119 as merged (bee7431) at 5 s: a settle of 12 cycles, budget 8. -_rg_119 = patched(app_main, "HANDBACK_CYCLES", app_main.SHORT_CYCLES)( - lambda: patched(app_main, "ROLLING_BOUND_CYCLES", 8)( +_rg_119 = patched(main_files.live, "HANDBACK_CYCLES", app_main.SHORT_CYCLES)( + lambda: patched(main_files.live, "ROLLING_BOUND_CYCLES", 8)( lambda: never(5.0, 5100.0, seed=1, delay=0))) for _t in _rg: print(f" rig shape, {_t:.0f} s meter, house {RIG[_t]:.0f} W: per " @@ -464,10 +465,10 @@ check("...every command the same as without the fix; without it the false " # the rig's shape (1 s, house 5050 W, seed 1). rig.TICK = 2.0 _q25 = (run(house(25), delay=2), - patched(app_main, "ROLLING_BOUND_CYCLES", 8)( + patched(main_files.live, "ROLLING_BOUND_CYCLES", 8)( lambda: run(house(25), delay=2))) rig.TICK = 1.0 -_m14 = patched(app_main, "ROLLING_BOUND_CYCLES", 14)( +_m14 = patched(main_files.live, "ROLLING_BOUND_CYCLES", 14)( lambda: never(1.0, 5050.0, seed=1, delay=0)) _m11 = never(1.0, 5050.0, seed=1, delay=0) print(f" 2 s, quarter edge, seed 25: {notes(_q25[0][1])}, budget 8 " @@ -480,7 +481,7 @@ check("...the budget's margins: 11 is silent at 2 s seed 25 and warns every " and every_quarter(_m11[1]) and not every_quarter(_m14[1])) check("the rule is the one the sweep chose. Changing it means re-running " "the sweep in DECISIONS/SAFETY-121-bound-every-quarter.md", - app_main.HANDBACK_CYCLES == 4 and app_main.ROLLING_BOUND_CYCLES == 11 + main_files.live.HANDBACK_CYCLES == 4 and main_files.live.ROLLING_BOUND_CYCLES == 11 and app_main.ROLLING_S == 900.0 and app_main.SHORT_SPAN_S == 22.0) # A start, or a blind cycle, is not a hand-back: the loop at its rail after diff --git a/goodwe_controller/test_safety123.py b/goodwe_controller/test_safety123.py index 2708594..00827cd 100644 --- a/goodwe_controller/test_safety123.py +++ b/goodwe_controller/test_safety123.py @@ -37,6 +37,7 @@ sys.path.insert(0, os.path.join(HERE, "tools")) logging.disable(logging.WARNING) import opt11_identity as rig # noqa: E402 +import main_files # noqa: E402 import app.main as M # noqa: E402 from app import dayplan, modetrade, packmode, priceruns, solarfc # noqa: E402 from app.price import PricePoint, PriceProduct, PriceRead, brussels # noqa @@ -492,13 +493,13 @@ for iso in ("2027-03-27T21:00:05+00:00", "2027-03-27T23:45:05+00:00", "2027-03-28T00:00:05+00:00"): now = datetime.fromisoformat(iso) c, hass = controller(MODES["Leftover solar"], now) - real_dt = M.datetime + real_dt = main_files.live.datetime class _DT(real_dt): @classmethod def now(cls, tz=None, _n=now): return _n if tz is None else _n.astimezone(tz) - M.datetime = _DT + main_files.live.datetime = _DT try: async def one(): await c.read_inputs(now_mono=0.0) @@ -510,7 +511,7 @@ for iso in ("2027-03-27T21:00:05+00:00", "2027-03-27T23:45:05+00:00", except Slow: ok = False finally: - M.datetime = real_dt + main_files.live.datetime = real_dt check(f"a whole control cycle at {iso[:16]}Z (three forecast sensors a " "day) returns with a day plan", ok) diff --git a/goodwe_controller/test_safety125.py b/goodwe_controller/test_safety125.py index 0769255..9ca5fa2 100644 --- a/goodwe_controller/test_safety125.py +++ b/goodwe_controller/test_safety125.py @@ -48,6 +48,7 @@ logging.disable(logging.WARNING) import opt11_identity as rig # noqa: E402 import opt11p3_replay as rp # noqa: E402 import safety84_identity as s84 # noqa: E402 +import main_files # noqa: E402 import app.main as m # noqa: E402 import app.p1 as p1mod # noqa: E402 from named_absence import first, nth, present # noqa: E402 @@ -164,14 +165,14 @@ def drive(o, *, peak=None, late=0.0, minutes=31, every=0, start=None, c.inverters[0].dev_min, c.inverters[0].dev_max = -5000.0, 5000.0 c.inverters[1].dev_min, c.inverters[1].dev_max = -4600.0, 4600.0 c.auto = True - real = m.datetime, homeview.datetime, p1mod.time + real = main_files.live.datetime, homeview.datetime, p1mod.time clock, simt = [t0], [0.0] class _DT(real[0]): @classmethod def now(cls, tz=None): return clock[0] if tz is None else clock[0].astimezone(tz) - m.datetime = homeview.datetime = _DT + main_files.live.datetime = homeview.datetime = _DT p1mod.time = types.SimpleNamespace(monotonic=lambda: 1e6 + simt[0]) real_load = _price.load_prices, _st.load_prices _price.load_prices = _st.load_prices = _no_fetch @@ -223,7 +224,7 @@ def drive(o, *, peak=None, late=0.0, minutes=31, every=0, start=None, await task except asyncio.CancelledError: pass - m.datetime, homeview.datetime, p1mod.time = real + main_files.live.datetime, homeview.datetime, p1mod.time = real _price.load_prices, _st.load_prices = real_load return c c = asyncio.run(go()) diff --git a/goodwe_controller/test_safety126.py b/goodwe_controller/test_safety126.py index 5d3275c..87834da 100644 --- a/goodwe_controller/test_safety126.py +++ b/goodwe_controller/test_safety126.py @@ -43,6 +43,7 @@ sys.path.insert(0, os.path.join(HERE, "tools")) import opt11p3_replay as rp # noqa: E402 from named_absence import first, nth, present # noqa: E402 +import main_files # noqa: E402 import app.main as m # noqa: E402 import app.p1 as p1mod # noqa: E402 from app import homeview, messages, peakguard, tariff # noqa: E402 @@ -179,14 +180,14 @@ def drive(o, *, modes=OWNER, socs=(10.0, 10.0), house=600.0, minutes=46, c.inverters[0].dev_min, c.inverters[0].dev_max = -5000.0, 5000.0 c.inverters[1].dev_min, c.inverters[1].dev_max = -4600.0, 4600.0 c.auto = True - real = m.datetime, homeview.datetime, p1mod.time + real = main_files.live.datetime, homeview.datetime, p1mod.time clock, simt = [t0], [0.0] class _DT(real[0]): @classmethod def now(cls, tz=None): return clock[0] if tz is None else clock[0].astimezone(tz) - m.datetime = homeview.datetime = _DT + main_files.live.datetime = homeview.datetime = _DT p1mod.time = types.SimpleNamespace(monotonic=lambda: 1e6 + simt[0]) real_load = _price.load_prices, _st.load_prices _price.load_prices = _st.load_prices = _no_fetch @@ -237,7 +238,7 @@ def drive(o, *, modes=OWNER, socs=(10.0, 10.0), house=600.0, minutes=46, await task except asyncio.CancelledError: pass - m.datetime, homeview.datetime, p1mod.time = real + main_files.live.datetime, homeview.datetime, p1mod.time = real _price.load_prices, _st.load_prices = real_load return c out["c"] = asyncio.run(go()) diff --git a/goodwe_controller/test_safety129.py b/goodwe_controller/test_safety129.py index 08c96df..89d904b 100644 --- a/goodwe_controller/test_safety129.py +++ b/goodwe_controller/test_safety129.py @@ -38,6 +38,7 @@ logging.disable(logging.WARNING) import safety128_rig as R # noqa: E402 import app.main as app_main # noqa: E402 from app import lateness # noqa: E402 +from app import settle # noqa: E402 fails = [] @@ -58,6 +59,17 @@ def no_gate(fn): app_main.Controller._readings_late = real +def no_settle(fn): + """`fn()` without SAFETY-136's gentler loop: the tree this card was written + against (with it the same run exports -645 W, not -1 325 W).""" + real = settle.Settle.moved + settle.Settle.moved = lambda self, *a, **k: None + try: + return fn() + finally: + settle.Settle.moved = real + + def run_late(**kw): """Run the rig; (rig, seconds the verdict stood, first second it stood).""" dur = kw.pop("dur") @@ -91,7 +103,7 @@ for units, house in ((AB, 1800.0), (A, 1500.0)): if len(units) == 2: old = R.Rig(house=house, lag_s=30.0, lag_on=ON, lag_off=ON + 300.0, units=units, p1_s=5.0) - no_gate(lambda: old.run(ON + 300.0)) + no_settle(lambda: no_gate(lambda: old.run(ON + 300.0))) check(f"{n}: without the gate the export goes below -1 kW", grid_min(old.rows, ON, ON + 300.0) < -1000.0) diff --git a/goodwe_controller/test_safety135.py b/goodwe_controller/test_safety135.py new file mode 100644 index 0000000..342f691 --- /dev/null +++ b/goodwe_controller/test_safety135.py @@ -0,0 +1,324 @@ +"""Runnable check for SAFETY-135: a young 15-minute period does not cost the +night charge the whole period. `python3 test_safety135.py` + +The REAL Controller (tools/opt11p3_replay.py, read_inputs + cycle, battery +modes, the peak guard on a P1 meter) with TEST-23-like lag: 1 s cycles, +readings 1 s old, a 5 s old meter in part 2. "Off" is the same run with +every measured stop latching and no wait for a falling give: the tree before +this card. +DECISIONS/SAFETY-135-young-period.md. + +1. A peak-bound night charge; a period starts with a 4 s kettle spike. The + guard cuts at once, and the charge resumes in that period (off: it stays + off to the period's end). The period stays at or under the aim. +2. A cheap run starts at 01:00 right after a give run, with a 5 s meter: no + start-then-cut within 60 s (off: one), and no period over the aim. +3. A real over-aim load: the guard and the charge stop on the same cycle as + off, and the charge stays off while the load is on. +4. The SAFETY-136 rig run C/s5b (house 1 800 W, an oven 2 kW 45 s in every + 105 s, A Leftover solar 5 kW, B Cheap hours 4.6 kW): the charge starts at + about 01:00:32 and the guard cuts it about 60 s later on the oven. It + starts again 60 s after that cut (off: never in that period). +5. Repeated spikes in one period: at most one restart, and none sooner than + RESTART_S after the first stop. + +Mutations (MUTATION.md, purged copies) are listed in the pull request. +""" + +import logging +import os +import sys +from datetime import datetime, timedelta, timezone + +HERE = os.path.dirname(os.path.abspath(__file__)) +sys.path.insert(0, HERE) +sys.path.insert(0, os.path.join(HERE, "tools")) +logging.disable(logging.WARNING) + +import opt11p3_replay as rp # noqa: E402 +from app import arbitrage, modetrade, packmode # noqa: E402 +from named_absence import nth, present # noqa: E402 + +fails = [] + + +def check(name, cond): + print(f" {'ok ' if cond else 'FAIL'} {name}") + if not cond: + fails.append(name) + + +L = timezone(timedelta(hours=1)) +D0 = datetime(2026, 11, 3, tzinfo=L) +UTC0 = D0.astimezone(timezone.utc) +# Local quarters: dear 00:00-01:00 (a give run), cheap 01:00-07:00, 0.30 else. +PRICES = [0.40 if q < 4 else 0.10 if q < 28 else 0.30 for q in range(96)] * 2 +WPTS = [(UTC0 + timedelta(minutes=15 * i), 900, p) + for i, p in enumerate(PRICES)] +AIM = rp.PEAK_CAP - 50 +CH = {"a": (True, packmode.CHEAP_HOURS, False), + "b": (True, packmode.CHEAP_HOURS, False)} +T1 = D0 + timedelta(hours=1) # 01:00 local, the cheap edge +RESTART = getattr(modetrade, "RESTART_S", 60.0) # 60.0 on older trees + + +class _Every: + """A period that equals every period: `_charge_stop` set to it makes + every measured stop latch, as before this card.""" + + def __eq__(self, other): + return True + + def __ne__(self, other): + return False + + +def _off(c): + # With RESTART_S 0 (see `off()`) nothing waits; every guard stop latches. + c._charge_stop = (_Every(), float("-inf")) + + +def off(fn): + """`fn()` with SAFETY-135 off: every measured stop latches and no start + waits for a falling give, as on the tree before this card.""" + names = [n for n in ("YOUNG_S", "RESTART_S") if hasattr(modetrade, n)] + real = {n: getattr(modetrade, n) for n in names} + OFF[0] = True + for n in names: # RESTART_S 0: no wait at a period's end + setattr(modetrade, n, 0.0) + try: + return fn() + finally: + OFF[0] = False + for n in names: + setattr(modetrade, n, real[n]) + + +OFF = [False] + + +def run(house_w, start, secs, meter_s=1.0, *, choice=None, soc0=None, + limits=None, rating=None): + """Rows per cycle and the Controller, for `house_w(seconds since 01:00)`.""" + t0 = start.timestamp() + house = [(t0 + k, house_w(t0 + k - T1.timestamp())) + for k in range(int(secs) + 5)] + rows = [] + + def cb(c, h, now, pr): + g = c.peak_guard + rows.append(dict(now=now, s=now.timestamp() - T1.timestamp(), + grid=h.grid(), + charge=getattr(c.arb, "action", None) + == arbitrage.CHARGE, + engaged=g is not None and g.engaged, + reason=getattr(c.arb, "reason", None) or "")) + was = rp.RATING + if rating is not None: + rp.RATING = rating + try: + _st, c = rp.run("p3_ch_sell", house, WPTS, + start.astimezone(timezone.utc), secs, check=cb, + soc0=soc0 or {"a": 30.0, "b": 30.0}, + choice=choice or CH, limits=limits, + n=len(choice or CH), + patch=_off if OFF[0] else None, + extra={"slew_w": 0, "cycle_cost_threshold_eur": 0.03}, + lag=rp.Lag(meter_s=meter_s)) + finally: + rp.RATING = was + return rows, c + + +def banked(c, frm): + """The add-on's own P1 period averages from `frm` (seconds after 01:00).""" + return [b.offtake_avg_w for b in c.p1.blocks + if b.start.timestamp() - T1.timestamp() >= frm] + + +def flaps(rows, frm, to): + """Charge starts in [frm, to) s that stopped again within 60 s.""" + out = [] + for i in range(1, len(rows)): + r = rows[i] + if frm <= r["s"] < to and r["charge"] and not rows[i - 1]["charge"]: + if any(not x["charge"] for x in rows[i:] + if x["s"] - r["s"] <= 60): + out.append(r["s"]) + return out + + +# ============================================================================ # +print("1. a 4 s spike at the start of a peak-bound night charge's period") + + +def spike(s): + return 2800.0 + (2500.0 if s >= 1800 and (s - 1800) % 900 < 4 else 0.0) + + +R1, C1 = run(spike, T1 + timedelta(minutes=20), 1560) +R1o, C1o = off(lambda: run(spike, T1 + timedelta(minutes=20), 1560)) + + +def period(rows, frm): + return [r for r in rows if frm <= r["s"] < frm + 900] + + +for tag, rows, c in (("on", R1, C1), ("off", R1o, C1o)): + p = period(rows, 1800) + cut = next((r["s"] - 1800 for r in p if r["engaged"]), None) + on = sum(r["charge"] for r in p) + print(f" {tag}: guard cut at +{cut} s, charging {on} of {len(p)} s, " + f"period {banked(c, 1800)[:1]}") +_p = period(R1, 1800) +_cut = next((i for i, r in enumerate(_p) if r["engaged"]), None) +check("the spike trips the guard in the period's first seconds and the " + "charge stops there", + _cut is not None and _p[_cut]["s"] - 1800 <= 5 + and not _p[_cut]["charge"]) +_back = [r["s"] - 1800 for r in _p[(_cut or 0):] if r["charge"]] +check("the charge resumes in the same period, within 90 s of its start", + _back and _back[0] <= 90) +_po = period(R1o, 1800) +check("off, the same spike keeps the charge off to the period's end (the " + "defect this card fixes)", + any(r["engaged"] for r in _po[:5]) + and not any(r["charge"] for r in _po[10:])) +check("every period with the charge is at or under the aim (lag allows 2 W)", + banked(C1, 0) and max(banked(C1, 0)) <= AIM + 2.0) + +# ============================================================================ # +print("\n2. a cheap run at 01:00 right after a give run, 5 s meter") +for house in (2400.0, 3000.0): + def flat(s, w=house): + return w + R2, C2 = run(flat, T1 - timedelta(minutes=5), 1260, meter_s=5.0) + R2o, C2o = off(lambda: run(flat, T1 - timedelta(minutes=5), 1260, + meter_s=5.0)) + f2, f2o = flaps(R2, 0, 900), flaps(R2o, 0, 900) + p2, p2o = banked(C2, 0)[:1], banked(C2o, 0)[:1] + on2 = sum(r["charge"] for r in period(R2, 0)) + on2o = sum(r["charge"] for r in period(R2o, 0)) + print(f" house {house:.0f} W: on flaps {f2} charging {on2} s period " + f"{p2}; off flaps {f2o} charging {on2o} s period {p2o}") + check(f"house {house:.0f} W: no charge start is cut within 60 s in the " + f"01:00 period", not f2) + check(f"house {house:.0f} W: the 01:00 period is at or under the aim " + f"(lag allows 2 W)", p2 and p2[0] <= AIM + 2.0) + check(f"house {house:.0f} W: the charge still runs in the 01:00 period", + on2 >= 800) + if house == 3000.0: + check("off, the 3 000 W house starts on the young period and is cut " + "within 60 s (the defect this card fixes)", bool(f2o)) + +# ============================================================================ # +print("\n3. a real over-aim load still cuts on the same cycle") + + +def load(s): + return 2800.0 + (4000.0 if 1820 <= s < 2120 else 0.0) + + +R3, C3 = run(load, T1 + timedelta(minutes=20), 1500) +R3o, C3o = off(lambda: run(load, T1 + timedelta(minutes=20), 1500)) + + +def first(rows, key, val, frm): + return next((r["s"] for r in rows if r["s"] >= frm and r[key] == val), + None) + + +_g, _go = first(R3, "engaged", True, 1800), first(R3o, "engaged", True, 1800) +_s, _so = first(R3, "charge", False, 1800), first(R3o, "charge", False, 1800) +print(f" guard cut at {_g} s (off {_go} s), charge stop at {_s} s " + f"(off {_so} s)") +check("the guard cuts on the same cycle as off, and the charge stops on it", + _g is not None and _g == _go and _s == _so == _g) +check("the charge stays off while the load is on", + not any(r["charge"] for r in R3 if _g <= r["s"] < 2120)) +check("every period is at or under the aim (lag allows 2 W)", + banked(C3, 0) and max(banked(C3, 0)) <= AIM + 2.0) + +# ============================================================================ # +print("\n4. the SAFETY-136 rig run C/s5b: start at 01:00:32, oven cut a minute " + "later") +# The rig's house (s5b.ctl.json), in seconds from 01:00: 1 800 W, an oven of +# 2 000 W for 45 s in every 105 s from 00:30 to 01:05:45, 3 000 W 00:56-00:58. + + +def s5b(s): + w = 1800.0 + if -1800 <= s < 345 and (s + 1800) % 105 < 45: + w += 2000.0 + if -240 <= s < -120: + w += 3000.0 + return w + + +S5B = dict(choice={"a": (True, packmode.LEFTOVER_SOLAR, False), + "b": (True, packmode.CHEAP_HOURS, False)}, + soc0={"a": 53.6, "b": 27.4}, limits={"b": (-4600.0, 4600.0)}, + rating=5000.0) +R4, C4 = run(s5b, T1 - timedelta(minutes=5), 1260, **S5B) +R4o, C4o = off(lambda: run(s5b, T1 - timedelta(minutes=5), 1260, **S5B)) + + +def edges(rows, frm): + """(start s, stop s) lists of the charge in the period from `frm`.""" + p = period(rows, frm) + on = [round(b["s"] - frm) for a, b in zip(p, p[1:]) + if b["charge"] and not a["charge"]] + of = [round(b["s"] - frm) for a, b in zip(p, p[1:]) + if a["charge"] and not b["charge"]] + return on, of + + +_on4, _of4 = edges(R4, 0) +_on4o, _of4o = edges(R4o, 0) +print(f" on: starts {_on4}, stops {_of4}, period {banked(C4, 0)[:1]}; " + f"off: starts {_on4o}, stops {_of4o}, period {banked(C4o, 0)[:1]}") +check("off, as on the rig: the charge starts about 30 s in, the guard cuts " + "it about a minute later, and it stays off to the period's end", + len(_on4o) == 1 and 25 <= _on4o[0] <= 40 and len(_of4o) == 1 + and 80 <= _of4o[0] <= 100) +check("the same start and the same cut as off (the cut is not delayed)", + _on4[:1] == _on4o[:1] and _of4[:1] == _of4o[:1]) +_cut4 = nth(_of4, 0, "the guard's cut in s5b") +check("the charge starts again in that period, 60 s or more after the cut, " + "once only", + present(_cut4) and len(_on4) == 2 and _on4[1] - _cut4 >= RESTART - 1) +check("the period is at or under the aim (lag allows 2 W)", + banked(C4, 0) and banked(C4, 0)[0] <= AIM + 2.0) + +# ============================================================================ # +print("\n5. repeated spikes in one period: one restart, not too soon") +_SP = (0, 20, 40, 62, 80, 300, 500) + + +def spikes(s): + return 2800.0 + (2500.0 if any(0 <= s - 1800 - k < 4 for k in _SP) + else 0.0) + + +for n_ch in (CH, {"a": CH["a"]}): + R5, C5 = run(spikes, T1 + timedelta(minutes=20), 1560, choice=n_ch, + soc0={k: 30.0 for k in n_ch}) + _on5, _of5 = edges(R5, 1800) + print(f" N={len(n_ch)}: starts {_on5}, stops {_of5}, " + f"period {banked(C5, 1800)[:1]}") + check(f"N={len(n_ch)}: at most one restart in the period, none sooner " + f"than RESTART_S after the first stop, and the last stop latches", + _of5 and len(_on5) <= 1 and len(_of5) == len(_on5) + 1 + and all(t - _of5[0] >= RESTART - 1 for t in _on5)) + check(f"N={len(n_ch)}: the period is at or under the aim (lag allows " + f"2 W)", banked(C5, 1800) and banked(C5, 1800)[0] <= AIM + 2.0) + _w = [r["reason"] for r in period(R5, 1800) if not r["charge"]] + check(f"N={len(n_ch)}: the wait says it in plain words (UX-08)", + any("tries again in a minute" in x for x in _w) + and not any("(young)" in x or "(wait)" in x for x in _w)) + +print() +if fails: + print(f"FAILED: {len(fails)}") + sys.exit(1) +print("all SAFETY-135 checks passed") diff --git a/goodwe_controller/test_safety136.py b/goodwe_controller/test_safety136.py new file mode 100644 index 0000000..5f3a957 --- /dev/null +++ b/goodwe_controller/test_safety136.py @@ -0,0 +1,263 @@ +"""Runnable check for SAFETY-136: a calmer loop on a slow meter. +`python3 test_safety136.py` + +With a 5 s meter and Home Assistant readings 10-15 s late the loop answers the +same error again at each cycle and overshoots: with an oven, a kettle and hob, +or a step the export was 3-10 times that of a meter with no lag. After a move +of 150 W or more `app/settle.py` now runs the loop at half its gain (at most +2 cycles) until the meter shows half of it. It is off for a meter under 4 s. +DECISIONS/SAFETY-136-slow-meter-settle.md. + +The REAL Controller on TEST-23's plant (tools/safety128_rig.py). "Off" is the +same run with `Settle.moved` doing nothing: the tree before this card. + +1. `Settle` alone. +2. 5 s meter, readings 10 s late: oven, kettle and hob, a step down and a step + up export clearly less than with it off. +3. 5 s meter, no lag: the same houses are no worse than a small margin. +4. 1 s and 2 s meters: the commands are those of the run with it off, and the + loop never waits. +5. The slow meter is told by its observed interval, at 4 s and 5 s. + +Mutations (MUTATION.md, purged copies) are listed in the pull request. +""" + +import logging +import os +import sys + +HERE = os.path.dirname(os.path.abspath(__file__)) +sys.path.insert(0, HERE) +sys.path.insert(0, os.path.join(HERE, "tools")) +logging.disable(logging.WARNING) + +import safety128_rig as R # noqa: E402 +from app.control import Tuning # noqa: E402 +from named_absence import nth, present # noqa: E402 +from app import settle # noqa: E402 +from app.lateness import MeterFit # noqa: E402 + +fails = [] + + +def check(name, cond): + print(f" {'ok ' if cond else 'FAIL'} {name}") + if not cond: + fails.append(name) + + +def off(fn): + """`fn()` with the settle wait off: the tree before this card.""" + real = settle.Settle.moved + settle.Settle.moved = lambda self, *a, **k: None + try: + return fn() + finally: + settle.Settle.moved = real + + +def oven(t): + return 1800.0 + (2000.0 if (t >= 300.0 and (t - 300.0) % 105 < 45) else 0.0) + + +def kettle(t): + w = 600.0 + if t % 400 < 120: + w += 2200 + if t >= 900 and t % 90 < 30: + w += 1500 + return w + + +def step(t): + return 1800.0 if t < 320.0 else 300.0 + + +def stepup(t): + return 300.0 if t < 320.0 else 2500.0 + + +# name: (house, noise, run length, lag end) +HOUSES = {"oven": (oven, 80.0, 900.0, 900.0), + "kettle": (kettle, 80.0, 1500.0, 1500.0), + "step": (step, 50.0, 700.0, 600.0), + "stepup": (stepup, 50.0, 700.0, 600.0)} +ON = 300.0 + + +def wh(rows, t0, t1, sign): + """Export (sign -1) or import (sign +1) energy in Wh over [t0, t1).""" + return sum((-min(r[1], 0.0) if sign < 0 else max(r[1], 0.0)) + for r in rows if t0 <= r[0] < t1) / 3600.0 + + +def run(name, lag, p1_s=5.0, units=("a", "b"), dur=None): + house, noise, length, lag_off = HOUSES[name] + r = R.Rig(house=house, noise=noise, p1_s=p1_s, units=units, lag_s=lag, + lag_on=ON, lag_off=lag_off) + waits = [] + r.run(dur or length + 20.0, + lambda rig, c, t: waits.append(1) if c.settle.pend else None) + return r, len(waits) + + +# --------------------------------------------------------------------------- # +print("1. Settle alone") +T = Tuning() +s = settle.Settle() +check("no move: the tuning is untouched", s.tuning(T, 500.0, True) is T) +s.moved(500.0, 0.0, 100.0, True) +check("a move under 150 W is not waited for", s.pend is None) +s.moved(500.0, 0.0, 600.0, False) +check("a meter that is not slow is not waited for", s.pend is None) +s.moved(500.0, 0.0, 600.0, True) +check("a move of 600 W is waited for: half the gain", + s.tuning(T, 500.0, True).gain == T.gain * 0.5) +check("the meter fell 200 W of 600 W: still half the gain", + s.tuning(T, 300.0, True).gain == T.gain * 0.5) +check("two cycles waited: the third has the whole gain", + s.tuning(T, 300.0, True) is T and s.pend is None) +s.moved(500.0, 0.0, 600.0, True) +check("the meter went the other way by half the move: the wait stands", + s.tuning(T, 800.0, True).gain == T.gain * 0.5) +s.reset() +s.moved(500.0, 0.0, -600.0, True) +check("a move down, the meter rose half the move: the whole gain", + s.tuning(T, 800.0, True) is T) +s.reset() +s.moved(500.0, 0.0, 600.0, True) +check("the meter fell half the move: the whole gain at once", + s.tuning(T, 200.0, True) is T and s.pend is None) +s.moved(500.0, 0.0, -600.0, True) +check("a move down is waited for too", + s.tuning(T, 500.0, True).gain == T.gain * 0.5) +s.reset() +check("reset ends the wait", s.pend is None) +s.moved(500.0, 0.0, 600.0, True) +check("a meter that turns out not to be slow ends the wait", + s.tuning(T, 500.0, False) is T and s.pend is None) +check("the numbers are pinned", + (settle.MOVE_W, settle.SHOWN, settle.WAIT_SHARE, settle.WAIT_CYCLES) + == (150.0, 0.5, 0.5, 2)) + +# --------------------------------------------------------------------------- # +print("\n2. 5 s meter, readings 10 s late") +tot_on = tot_off = 0.0 +for name, (_h, _n, length, lag_off) in HOUSES.items(): + a, waited = run(name, 10.0) + b, _w = off(lambda: run(name, 10.0)) + ea, eb = wh(a.rows, ON, lag_off, -1), wh(b.rows, ON, lag_off, -1) + tot_on, tot_off = tot_on + ea, tot_off + eb + print(f" {name}: export {ea:.1f} Wh, off {eb:.1f} Wh, waited {waited} s") + check(f"{name}: waits at some point", waited > 0) + check(f"{name}: exports at most 75 % of the run with it off", + ea <= 0.75 * eb) +print(f" sum: {tot_on:.1f} Wh, off {tot_off:.1f} Wh") +check("the four together export at most 65 % of the run with it off", + tot_on <= 0.65 * tot_off) + +# --------------------------------------------------------------------------- # +print("\n2b. Another writer overrides the loop: the wait ends") +halved = [] +real_tuning = settle.Settle.tuning + + +def watch_tuning(self, tuning, grid_w, slow): + r = real_tuning(self, tuning, grid_w, slow) + halved.append(r is not tuning) + return r + + +settle.Settle.tuning = watch_tuning +try: + mark = [] + + def bump(rig, c, t): + # right after a cycle that started a wait, another writer moves the + # command, so the next cycle sees `target != loop_w` + if not mark and c.settle.pend and t > 330.0: + mark.append(len(halved)) + c.target = c.target + 300.0 + + r = R.Rig(house=oven, noise=80.0, p1_s=5.0, lag_s=10.0, lag_on=ON, + lag_off=900.0) + r.run(500.0, bump) +finally: + settle.Settle.tuning = real_tuning +nxt = nth(halved, mark[0] if mark else 10 ** 6) +check("the cycle after an override has the whole gain", + bool(mark) and present(nxt) and nxt is False) + +# --------------------------------------------------------------------------- # +print("\n3. 5 s meter, no lag") +for name in ("oven", "kettle", "step", "stepup"): + _h, _n, length, lag_off = HOUSES[name] + a, _w = run(name, 0.0) + b, _w = off(lambda: run(name, 0.0)) + ea, eb = wh(a.rows, ON, lag_off, -1), wh(b.rows, ON, lag_off, -1) + ia, ib = wh(a.rows, ON, lag_off, 1), wh(b.rows, ON, lag_off, 1) + print(f" {name}: export {ea:.1f} Wh (off {eb:.1f}), import {ia:.1f} Wh " + f"(off {ib:.1f})") + check(f"{name}: export at most 6 Wh over the run with it off", + ea <= eb + 6.0) + check(f"{name}: import at most 1 Wh over the run with it off", + ia <= ib + 1.0) + +# --------------------------------------------------------------------------- # +print("\n4. 1 s and 2 s meters") +for p1 in (1.0, 2.0): + for lag in (0.0, 10.0): + for units in (("a", "b"), ("a",)): + a, waited = run("oven", lag, p1_s=p1, units=units, dur=700.0) + b, _w = off(lambda: run("oven", lag, p1_s=p1, units=units, + dur=700.0)) + same = ([(r[0], r[1], r[2]) for r in a.rows] + == [(r[0], r[1], r[2]) for r in b.rows]) + check(f"{p1:.0f} s meter, {lag:.0f} s late, N={len(units)}: " + f"same commands, never waits", same and waited == 0) + +# --------------------------------------------------------------------------- # +print("\n5. The slow meter is told by its observed interval") +s = settle.Settle() +for k in range(30): + s.arrive(float(k), k) +check("a reading each second is not a slow meter", not s.slow()) +s = settle.Settle() +for k in range(30): + s.arrive(5.0 * k, k) +check("a reading every 5 s is a slow meter", s.slow()) +s = settle.Settle() +for k in range(4): + s.arrive(5.0 * k, k) +check("fewer than 5 readings in a minute tell nothing", not s.slow()) +s = settle.Settle() +for k in range(30): + s.arrive(5.0 * k, 0 if k else 1) +check("the same count again is no new reading", not s.slow()) +for p1, expect in ((1.0, False), (2.0, False), (3.0, False), (4.0, True), + (5.0, True), (10.0, True)): + r = R.Rig(house=1800.0, p1_s=p1) + seen = [] + r.run(120.0, lambda rig, c, t: seen.append(c.settle.slow())) + last = nth(seen, -1) + check(f"{p1:.0f} s meter: slow is {expect}", + present(last) and last is expect) +# A 1 s meter on a house that changes every 5 s repeats its value 4 times in 5. +# Where every reading arrives (the rig, a polled meter) it is not slow; where +# Home Assistant sends a reading only when the value changes (ha_signed) the +# same meter is slow (T3 of the review; DECISIONS). +s, m, h = settle.Settle(), MeterFit(), settle.Settle() +for k in range(60): + s.arrive(float(k), k) + h.arrive(float(k), k // 5) + m.add(float(k), 0.0, 1800.0 + 100.0 * (k // 5)) +check("every reading arrives, value changes every 5 s: not slow (the value " + "fit says slow)", not s.slow() and m.slow()) +check("the same meter through Home Assistant on change (a reading per " + "change): slow", h.slow()) + +print() +if fails: + print(f"{len(fails)} FAILED: " + ", ".join(fails)) + sys.exit(1) +print("all checks passed") diff --git a/goodwe_controller/test_safety85.py b/goodwe_controller/test_safety85.py index ed70653..9e4798f 100644 --- a/goodwe_controller/test_safety85.py +++ b/goodwe_controller/test_safety85.py @@ -38,6 +38,7 @@ logging.disable(logging.WARNING) import opt11_identity as rig # noqa: E402 import safety79_identity as s79 # noqa: E402 import safety84_identity as s84 # noqa: E402 +import main_files # noqa: E402 import app.main as app_main # noqa: E402 from app import clamp, messages # noqa: E402 from app.main import Controller # noqa: E402 @@ -202,7 +203,7 @@ check("⭐ N=2, A in its HOLD and B, which the loop drives, gives nothing: the " check("...it starts no earlier than the saturation cycles allow (3 x 5 s)", all(e.split(" ", 1)[0] >= "11:10:10" for c in (_c1, _c2) for e in c.events if "OUTPUT_CLAMP" in e)) -_quiet = patched(app_main, "delivery_short", lambda *a: False)( +_quiet = patched(main_files.live, "delivery_short", lambda *a: False)( lambda: run(1, "drain", 1000.0, 20000, dur=1200.0, cut=gone(600, 1200))) check("non-vacuous: without the delivery rule the N=1 drain that gives " "nothing is silent (the loop's clamp never reaches its rail here)", @@ -214,7 +215,7 @@ check("a dip of two cycles is not an alarm", warned(_dip[1]) == (0, 0, 0)) print("\n3. control coming back from maintenance does not jump") END = {"maintenance_hold_min": 10} _bounds = [] -_real_compute = app_main.compute +_real_compute = main_files.live.compute def _spy_compute(*a, **kw): @@ -222,11 +223,11 @@ def _spy_compute(*a, **kw): return _real_compute(*a, **kw) -app_main.compute = _spy_compute +main_files.live.compute = _spy_compute try: _h2 = run(2, "hold", 4500.0, 20000, dur=900.0, extra=END) finally: - app_main.compute = _real_compute + main_files.live.compute = _real_compute _h2_old = no_bound(lambda: run(2, "hold", 4500.0, 20000, dur=900.0, extra=END)) _h1 = run(1, "hold", 4500.0, 20000, dur=900.0, extra=END) @@ -380,8 +381,8 @@ def lag_runs(): _lag = lagging(lag_runs) -_lag_old = patched(app_main, "SHORT_CYCLES", 1)( - lambda: patched(app_main, "SHORT_SPAN_S", 0.0)( +_lag_old = patched(main_files.live, "SHORT_CYCLES", 1)( + lambda: patched(main_files.live, "SHORT_SPAN_S", 0.0)( lambda: lagging(lag_runs))) _lag_dead = lagging(lambda: run(1, "drain", 1000.0, 20000, dur=900.0, cut=gone(600, 900))) @@ -432,7 +433,7 @@ def both_ways(asked, given, margin): _tp = taper(charge_runs) -_tp_old = patched(app_main, "delivery_short", both_ways)( +_tp_old = patched(main_files.live, "delivery_short", both_ways)( lambda: taper(charge_runs)) print(f" a charge that tapers: {[warned(c) for _r, c in _tp]}, grading " f"charges too {[warned(c) for _r, c in _tp_old]}") diff --git a/goodwe_controller/test_safety87.py b/goodwe_controller/test_safety87.py index 71c70c6..d2be66c 100644 --- a/goodwe_controller/test_safety87.py +++ b/goodwe_controller/test_safety87.py @@ -38,6 +38,7 @@ import types HERE = os.path.dirname(os.path.abspath(__file__)) sys.path.insert(0, HERE) sys.path.insert(0, os.path.join(HERE, "tools")) +import main_files # noqa: E402 logging.disable(logging.WARNING) import opt11_identity as rig # noqa: E402 @@ -703,8 +704,11 @@ check("⭐ the reserve alarm is graded on the real limit, not the aim: a " _runs_src = {} for _f in ("main.py", "homeview.py"): - with open(os.path.join(HERE, "app", _f), encoding="utf-8") as _fh: - _src = _fh.read() + if _f == "main.py": + _src = main_files.source() + else: + with open(os.path.join(HERE, "app", _f), encoding="utf-8") as _fh: + _src = _fh.read() for _part in _src.split('out.append({')[1:]: if '"runs": True' in _part.split("})", 1)[0]: _runs_src.setdefault(_f, []).append( diff --git a/goodwe_controller/test_safety91.py b/goodwe_controller/test_safety91.py index cd7ce12..6f477bb 100644 --- a/goodwe_controller/test_safety91.py +++ b/goodwe_controller/test_safety91.py @@ -127,16 +127,17 @@ def without_fix(fn): """release/1.0 8c438ab: held only for the peak, a drain stays pinned, the quarter's edge is not rolled over.""" real = (Controller._held_back, Controller._drain_rise) + import main_files # noqa: E402 import app.main as m - real_nq = m.next_quarter + real_nq = main_files.live.next_quarter Controller._held_back = lambda self: self._peak_reserve() Controller._drain_rise = lambda self, claims, results: None - m.next_quarter = lambda p, max_hold_s: p + main_files.live.next_quarter = lambda p, max_hold_s: p try: return fn() finally: Controller._held_back, Controller._drain_rise = real - m.next_quarter = real_nq + main_files.live.next_quarter = real_nq def cmd(r): diff --git a/goodwe_controller/test_safety94.py b/goodwe_controller/test_safety94.py index 512834c..bae8300 100644 --- a/goodwe_controller/test_safety94.py +++ b/goodwe_controller/test_safety94.py @@ -37,6 +37,7 @@ logging.disable(logging.CRITICAL) import safety94_rig as rig # noqa: E402 import app.inverter as app_inverter # noqa: E402 +import main_files # noqa: E402 import app.main as app_main # noqa: E402 from app import control # noqa: E402 from app.freshness import BOUNDS, Freshness # noqa: E402 @@ -59,19 +60,19 @@ class Before94(Freshness): def without_fix(fn): """Run `fn` with the gate's old clock and the old refusal evidence.""" - real_f, real_c = app_inverter.Freshness, app_main.compute - real_p = app_main.REFUSED_PROGRESS_W + real_f, real_c = app_inverter.Freshness, main_files.live.compute + real_p = main_files.live.REFUSED_PROGRESS_W real_l = app_main.Controller._readings_late # SAFETY-128: that tree had no late-readings gate either. app_main.Controller._readings_late = lambda self, standing_w: None app_inverter.Freshness = Before94 - app_main.compute = lambda *a, **k: real_c(*a, **dict(k, gave_nothing=None)) - app_main.REFUSED_PROGRESS_W = float("inf") + main_files.live.compute = lambda *a, **k: real_c(*a, **dict(k, gave_nothing=None)) + main_files.live.REFUSED_PROGRESS_W = float("inf") try: return fn() finally: - app_inverter.Freshness, app_main.compute = real_f, real_c - app_main.REFUSED_PROGRESS_W = real_p + app_inverter.Freshness, main_files.live.compute = real_f, real_c + main_files.live.REFUSED_PROGRESS_W = real_p app_main.Controller._readings_late = real_l @@ -315,7 +316,7 @@ check("compute(): a frozen loop at SETTLE_CYCLES reading -20 W engages with " and control.compute(**args, gave_nothing=False).refused == 0) # The evidence restarts on progress towards the ask, not on jitter. -print(f" REFUSED_PROGRESS_W {app_main.REFUSED_PROGRESS_W:.0f} W, span " +print(f" REFUSED_PROGRESS_W {main_files.live.REFUSED_PROGRESS_W:.0f} W, span " f"{app_main.REFUSED_SPAN_S:.0f} s") @@ -356,7 +357,7 @@ check("a command that swaps direction every cycle is never evidence, and a " not any(flap) and 1 in away and away.index(1) == 22) check("REFUSED_PROGRESS_W is under the band's width and over the live " "readings' rest wander (25 W)", - 25.0 < app_main.REFUSED_PROGRESS_W < 2 * control.REFUSED_BELOW_W) + 25.0 < main_files.live.REFUSED_PROGRESS_W < 2 * control.REFUSED_BELOW_W) print() if fails: diff --git a/goodwe_controller/test_safety95.py b/goodwe_controller/test_safety95.py index acc1965..a1fdab7 100644 --- a/goodwe_controller/test_safety95.py +++ b/goodwe_controller/test_safety95.py @@ -36,6 +36,7 @@ logging.disable(logging.WARNING) import opt11_identity as rig # noqa: E402 import safety79_identity as s79 # noqa: E402 +import main_files # noqa: E402 from app import main as app_main, packmode # noqa: E402 from app.arbiter import Claim, P_MAINTENANCE, P_SAFETY # noqa: E402 from app.main import Controller # noqa: E402 @@ -149,13 +150,13 @@ def run(n, house, *, store, extra=None, soc=None, reject=None, dead=None, for i in c.inverters: i.dev_min, i.dev_max = -5000.0, 5000.0 c.auto = True - real_dt, clock = app_main.datetime, [0.0] + real_dt, clock = main_files.live.datetime, [0.0] class _DT(real_dt): @classmethod def now(cls, tz=None): return rig.BASE + timedelta(seconds=clock[0]) - app_main.datetime = _DT + main_files.live.datetime = _DT rows = [] try: t = 0.0 @@ -182,7 +183,7 @@ def run(n, house, *, store, extra=None, soc=None, reject=None, dead=None, else g.floor_w)) t += 2.0 finally: - app_main.datetime = real_dt + main_files.live.datetime = real_dt return rows, c return asyncio.run(go()) diff --git a/goodwe_controller/test_sma10_two_idle_states.py b/goodwe_controller/test_sma10_two_idle_states.py index b395333..d338938 100644 --- a/goodwe_controller/test_sma10_two_idle_states.py +++ b/goodwe_controller/test_sma10_two_idle_states.py @@ -32,6 +32,7 @@ from pathlib import Path HERE = Path(__file__).resolve().parent sys.path.insert(0, str(HERE / "tools")) +import main_files # noqa: E402 fails = [] @@ -336,7 +337,7 @@ def run(coro): return asyncio.run(coro) -_real_time = M.time +_real_time = main_files.live.time class _FakeTime: @@ -891,9 +892,9 @@ check("the units that raised, failed or hung are NOT marked handed back, so " for i in (1, 2, 4))) fb_raise.mode = "ok" FT.t = _real_time.monotonic() + 11.0 # one heartbeat later -M.time = FT +main_files.live.time = FT run(c.send_heartbeats(60_000.0, 10.0)) -M.time = _real_time +main_files.live.time = _real_time check("...and the next idle write (a heartbeat later) retries the one that " "raised (now answers): released, and the healthy unit is not released a " "second time", @@ -955,7 +956,7 @@ for mode in ("false", "raise", "hang"): # the cadence and the log, over N failed retries on a clock we move c, h, f = failing_site("false") -M.time = FT +main_files.live.time = FT FT.t = 5000.0 _cap.clear() run(c.handle_action("auto_toggle")) # Stop: try 1 (forced) @@ -997,7 +998,7 @@ _cap.clear() run(c.handle_action("auto_toggle")) # Stop, fails again check("a NEW failure streak is logged again, once", len([1 for lv, m in _cap if lv >= logging.ERROR]) == 1) -M.time = _real_time +main_files.live.time = _real_time # shutdown with a failed release: the one 0 W still goes out inside the bound c, h, f = failing_site("hang") @@ -1098,7 +1099,7 @@ check("the two new Last-event hints exist and are plain", .endswith("trying again")) # --- 3j. the call sites ------------------------------------------------------- -src = (HERE / "app" / "main.py").read_text(encoding="utf-8") +src = main_files.source() ss = src.splitlines() @@ -1115,7 +1116,8 @@ check("main.py: the Stop button and shutdown() call command_site_release(); " "the two maintenance-abort paths keep command_site_zero() (a third call " "is the all-GoodWe branch inside command_site_release itself)", len(rel) == 2 and len(zer) == 3 - and "async def command_site_release" in "\n".join(ss[zer[1] - 30:zer[1]])) + and any("async def command_site_release" in "\n".join(ss[i - 30:i]) + for i in zer)) # ============================================================================= print() diff --git a/goodwe_controller/test_split_patches.py b/goodwe_controller/test_split_patches.py new file mode 100644 index 0000000..7bd26bb --- /dev/null +++ b/goodwe_controller/test_split_patches.py @@ -0,0 +1,181 @@ +"""MAINT-21 tripwire: a test must patch a Controller global where it is read. + +The Controller's code lives in app/main.py and in the files split from it +(app/ctl_*.py, app/rows.py). A function reads a module global from its own +file, so `app.main.NAME = fake` changes only the code that is still in +main.py. This file fails when a test or tool still does that: + + 1. it patches an `app.main` attribute that main.py's own functions no + longer read (a stale patch, silently inert), or + 2. it patches an `app.main` attribute that another file also reads (the + patch reaches only part of the code). + +The way to patch is `tools/main_files.py`: `main_files.live.NAME = fake` sets +NAME in every file that reads it and raises when none does. + +Part 3 runs the scan on spoilt sources and the patch helper on the real tree. +Read MUTATION.md for the habit this follows. `python3 test_split_patches.py` +""" + +import ast +import glob +import os +import sys + +HERE = os.path.dirname(os.path.abspath(__file__)) +sys.path.insert(0, HERE) +sys.path.insert(0, os.path.join(HERE, "tools")) +import main_files # noqa: E402 + +fails = [] +ALIASES = {"m", "M", "main", "app_main", "_main", "_main_mod", "main_mod"} + + +def check(name, cond): + print(f" {'ok ' if cond else 'FAIL'} {name}") + if not cond: + fails.append(name) + + +def main_aliases(tree): + """Names bound to the module app.main in one file.""" + al = set() + for n in ast.walk(tree): + if isinstance(n, ast.Import): + al.update(a.asname for a in n.names + if a.name == "app.main" and a.asname) + elif isinstance(n, ast.ImportFrom) and n.module == "app": + al.update(a.asname or a.name for a in n.names if a.name == "main") + for n in ast.walk(tree): + if (isinstance(n, ast.Assign) and isinstance(n.value, ast.Name) + and n.value.id in al): + al.update(t.id for t in n.targets if isinstance(t, ast.Name)) + # `for mod in (app_main, homeview): mod.datetime = fake` + if (isinstance(n, ast.For) and isinstance(n.target, ast.Name) + and isinstance(n.iter, (ast.Tuple, ast.List)) + and any(isinstance(e, ast.Name) and e.id in al + for e in n.iter.elts)): + al.add(n.target.id) + return al + + +def flat(targets): + """The assignment targets, tuples and lists taken apart.""" + for t in targets: + if isinstance(t, (ast.Tuple, ast.List)): + yield from flat(t.elts) + else: + yield t + + +def patches(src): + """[(line, name)]: every attribute of app.main a file assigns, or hands to + setattr / a patching helper as `(app.main alias, "name", value)`.""" + tree = ast.parse(src) + al = main_aliases(tree) + out = [] + for n in ast.walk(tree): + targets = [] + if isinstance(n, ast.Assign): + targets = n.targets + elif isinstance(n, (ast.AugAssign, ast.AnnAssign)): + targets = [n.target] + for t in flat(targets): + # `app_main.NAME = x`, or `rig.m.NAME = x` where rig did + # `import app.main as m` + if isinstance(t, ast.Attribute) and ( + (isinstance(t.value, ast.Name) and t.value.id in al) + or (isinstance(t.value, ast.Attribute) + and t.value.attr in ALIASES)): + out.append((n.lineno, t.attr)) + if (isinstance(n, ast.Call) and len(n.args) >= 3 + and isinstance(n.args[0], ast.Name) and n.args[0].id in al + and isinstance(n.args[1], ast.Constant) + and isinstance(n.args[1].value, str) + and ast.unparse(n.func) != "getattr"): + out.append((n.lineno, n.args[1].value)) + return out + + +def problems(src, where="", readers=main_files.reading): + """Messages for each patch in `src` that the rule above rejects.""" + out = [] + for line, name in patches(src): + who = readers(name) + if "main" not in who: + out.append(f"{where}:{line} patches main.{name}, which main.py " + f"does not read" + (f" (read by {who})" if who else "")) + elif who != ["main"]: + out.append(f"{where}:{line} patches main.{name}, which " + f"{[w for w in who if w != 'main']} also read: use " + f"main_files.live.{name}") + return out + + +# --------------------------------------------------------------------------- # +print("1. no test and no tool patches a main global the code reads elsewhere") +sites = bad = 0 +for path in sorted(glob.glob(os.path.join(HERE, "test_*.py")) + + glob.glob(os.path.join(HERE, "tools", "*.py"))): + if os.path.basename(path) == "test_split_patches.py": + continue + with open(path, encoding="utf-8") as fh: + src = fh.read() + found = problems(src, os.path.relpath(path, HERE)) + sites += len(patches(src)) + for msg in found: + print(" " + msg) + bad += len(found) +check(f"{sites} patches of an app.main attribute found, {bad} stale or partial", + sites > 0 and bad == 0) + +# --------------------------------------------------------------------------- # +print("\n2. the scan is not blind: spoilt sources are caught") +HEAD = "import app.main as m\n" +check("main. is stale", + len(problems(HEAD + "m.no_such_global_anywhere = 1\n")) == 1) +check("main.datetime is partial (the clock is read in more than one file)" + if len(main_files.reading("datetime")) > 1 else + "main.datetime (one reader here, so nothing to catch yet)", + len(problems(HEAD + "m.datetime = 1\n")) == + (1 if len(main_files.reading("datetime")) > 1 else 0)) +check("the same through setattr, a helper and an alias", + len(problems(HEAD + "k = m\nsetattr(k, 'no_such_global_anywhere', 1)\n" + "patched(m, 'no_such_global_anywhere', 1)(f)\n")) == 2) +check("a patch through main_files.live is not flagged", + problems(HEAD + "import main_files\n" + "main_files.live.datetime = 1\n") == []) +check("a name only main reads may still be patched on main", + problems(HEAD + "m.load_options = 1\n") == []) + +# --------------------------------------------------------------------------- # +print("\n3. main_files.live sets a global in every file that reads it") +import importlib # noqa: E402 + +live = main_files.live +for name in ("datetime", "compute", "_mono"): + readers = main_files.reading(name) + mods = [importlib.import_module("app." + r) for r in readers] + before = [getattr(m, name) for m in mods] + sentinel = object() + setattr(live, name, sentinel) + try: + hit = all(getattr(m, name) is sentinel for m in mods) + read_back = getattr(live, name) is sentinel + finally: + for m, old in zip(mods, before): + setattr(m, name, old) + check(f"{name}: set in all {len(mods)} reading file(s) {readers}, and " + f"read back", bool(mods) and hit and read_back) +try: + live.no_such_global_anywhere = 1 + raised = False +except AttributeError: + raised = True +check("a name no file reads raises instead of patching nothing", raised) + +print() +if fails: + print(f"FAILED: {len(fails)}") + sys.exit(1) +print("all ok") diff --git a/goodwe_controller/test_static_tariff.py b/goodwe_controller/test_static_tariff.py index 2537ac3..378a73d 100644 --- a/goodwe_controller/test_static_tariff.py +++ b/goodwe_controller/test_static_tariff.py @@ -81,6 +81,8 @@ from app.static_tariff import ( from app.validate import validate_startup_config HERE = Path(__file__).resolve().parent +sys.path.insert(0, str(HERE / "tools")) +import main_files # noqa: E402 UTC = timezone.utc # PRICE-02: `TariffPlan.arbitrage(now=...)` is required. This instant is before every @@ -893,7 +895,7 @@ check("the new module holds no option-defaults dict of its own, so this ticket " check("...and it reads the option through price.price_option(), the framework's " "single read path, rather than through opts.get(key, )", "price_option(opts" in _SRC and 'opts.get("static_profile"' not in _SRC) -_MAIN = (HERE / "app" / "main.py").read_text(encoding="utf-8") +_MAIN = main_files.source() check("...and main.py grew no `o.get(\"static_profile\", )` fallback " "either - it calls static_status(o, now), and the option is read once, " "inside the framework", diff --git a/goodwe_controller/test_tariff24.py b/goodwe_controller/test_tariff24.py index f5b74a4..abf6110 100644 --- a/goodwe_controller/test_tariff24.py +++ b/goodwe_controller/test_tariff24.py @@ -40,6 +40,7 @@ logging.disable(logging.WARNING) import opt11p3_replay as rp # noqa: E402 from named_absence import first, nth, present # noqa: E402 +import main_files # noqa: E402 import app.main as m # noqa: E402 from app import homeview, modetrade, packmode # noqa: E402 from app import price as _price, static_tariff as _st # noqa: E402 @@ -196,7 +197,7 @@ def drive(o, *, start=NIGHT, minutes=20, soc0=None, choice=CHOICE, for i in c.inverters: i.dev_min, i.dev_max = -5000.0, 5000.0 c.auto = True - real_dt, real_hv = m.datetime, homeview.datetime + real_dt, real_hv = main_files.live.datetime, homeview.datetime clock = [start] class _DT(real_dt): @@ -204,7 +205,7 @@ def drive(o, *, start=NIGHT, minutes=20, soc0=None, choice=CHOICE, def now(cls, tz=None): return clock[0] if tz is None else clock[0].astimezone(tz) - m.datetime = homeview.datetime = _DT + main_files.live.datetime = homeview.datetime = _DT _real_load = _price.load_prices, _st.load_prices _price.load_prices = _st.load_prices = _no_fetch started = task_started(o) @@ -246,7 +247,7 @@ def drive(o, *, start=NIGHT, minutes=20, soc0=None, choice=CHOICE, await task except asyncio.CancelledError: pass - m.datetime, homeview.datetime = real_dt, real_hv + main_files.live.datetime, homeview.datetime = real_dt, real_hv _price.load_prices, _st.load_prices = _real_load return c, started diff --git a/goodwe_controller/test_tariff24_weather.py b/goodwe_controller/test_tariff24_weather.py index 5d69662..10c6322 100644 --- a/goodwe_controller/test_tariff24_weather.py +++ b/goodwe_controller/test_tariff24_weather.py @@ -47,6 +47,7 @@ logging.disable(logging.WARNING) import opt11p3_replay as rp # noqa: E402 from named_absence import first, nth, present # noqa: E402 +import main_files # noqa: E402 import app.main as m # noqa: E402 from app import arbitrage, homeview, modetrade, solarfc # noqa: E402 from app.main import Controller # noqa: E402 @@ -175,7 +176,7 @@ def drive(o, *, fc="fresh", points=None, minutes=20, tick=5.0, # forecast IS lost, so it runs with a hold that never covers # (test_opt27.py tests the cover). c.fc_hold = _NoHold() - real_dt, real_hv = m.datetime, homeview.datetime + real_dt, real_hv = main_files.live.datetime, homeview.datetime clock = [t0] class _DT(real_dt): @@ -183,7 +184,7 @@ def drive(o, *, fc="fresh", points=None, minutes=20, tick=5.0, def now(cls, tz=None): return clock[0] if tz is None else clock[0].astimezone(tz) - m.datetime = homeview.datetime = _DT + main_files.live.datetime = homeview.datetime = _DT pts = None if points is None else points task = None if pts is None: @@ -248,7 +249,7 @@ def drive(o, *, fc="fresh", points=None, minutes=20, tick=5.0, await task except asyncio.CancelledError: pass - m.datetime, homeview.datetime = real_dt, real_hv + main_files.live.datetime, homeview.datetime = real_dt, real_hv return c return asyncio.run(go()), rows diff --git a/goodwe_controller/test_ux54_dst.py b/goodwe_controller/test_ux54_dst.py index 850873b..288ce97 100644 --- a/goodwe_controller/test_ux54_dst.py +++ b/goodwe_controller/test_ux54_dst.py @@ -36,6 +36,7 @@ logging.disable(logging.WARNING) import ux54_scenarios as S # noqa: E402 import app.main as M # noqa: E402 +import main_files # noqa: E402 from app import arbitrage, dayplan, dayview, homeview, solarfc # noqa: E402 from app import tariff # noqa: E402 from app.daycurve import SolarToday # noqa: E402 @@ -90,7 +91,8 @@ class FakeDT(datetime): return NOW[0].astimezone(tz) if tz else NOW[0].replace(tzinfo=None) -for _mod in (M, homeview, dayview): # what reads the wall clock +main_files.live.datetime = FakeDT # the Controller's clock +for _mod in (homeview, dayview): # the other readers of the clock _mod.datetime = FakeDT TZ_MODULES = (tariff, dayplan, homeview, solarfc) diff --git a/goodwe_controller/test_validate.py b/goodwe_controller/test_validate.py index ea9c5df..6cfff7c 100644 --- a/goodwe_controller/test_validate.py +++ b/goodwe_controller/test_validate.py @@ -1028,6 +1028,11 @@ check("...and the drain SET is not clamped either, so the twin key the card " _srcs = {name: open(os.path.join(os.path.dirname(os.path.abspath(__file__)), "app", name), encoding="utf-8").read() for name in ("main.py", "validate.py", "maintenance.py")} +# MAINT-21: main.py stands for itself and the files split from it. +sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), + "tools")) +import main_files # noqa: E402 +_srcs["main.py"] = main_files.source() _literals = {name: re.findall( r'"(maintenance_[a-z_]+)"\s*,\s*(-?\d+(?:\.\d+)?)\s*[,)]', src) for name, src in _srcs.items()} diff --git a/goodwe_controller/test_watchdog.py b/goodwe_controller/test_watchdog.py index 7389bf3..0d9e172 100644 --- a/goodwe_controller/test_watchdog.py +++ b/goodwe_controller/test_watchdog.py @@ -1161,9 +1161,12 @@ check("...and it does not raise the same card on every cycle - a per-PROCESS " # SAFETY-34: a Core-ONLY restart. The add-on process lives on (measured on # TEST-23), HA's memory is wiped, so the SAME process must re-assert the card. +import os # noqa: E402 +sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "tools")) # noqa: E402 +import main_files # noqa: E402 import app.main as _main_mod # noqa: E402 -_real_mono, _clock = _main_mod._mono, [_main_mod._mono()] -_main_mod._mono = lambda: _clock[0] +_real_mono, _clock = main_files.live._mono, [main_files.live._mono()] +main_files.live._mono = lambda: _clock[0] try: _h3 = _CircHass(a_w=0.0, b_w=0.0) _b.hass = _h3 @@ -1173,7 +1176,7 @@ try: asyncio.run(_b.check_circulating()) _late = [c for c in _h3.calls if c[0] == "persistent_notification"] finally: - _main_mod._mono = _real_mono + main_files.live._mono = _real_mono check("SAFETY-34: inside REANNOUNCE_S the same process does not re-raise - no " "storm on the event bus", len(_early) == 0) check("SAFETY-34: a Core-only restart wipes the card and the add-on process " diff --git a/goodwe_controller/tools/main_files.py b/goodwe_controller/tools/main_files.py new file mode 100644 index 0000000..4ef7056 --- /dev/null +++ b/goodwe_controller/tools/main_files.py @@ -0,0 +1,98 @@ +"""MAINT-21: the Controller lives in app/main.py and the files split from it. + +A test that reads `app/main.py` for a call, a comment or a def reads +`source()` instead; a test that replaces a global that `main` used to read +calls `patch_global()`, which sets it in each file whose code reads it. A name +no file reads is an error: a stale patch cannot pass unnoticed. +""" +import ast +import glob +import importlib +import os +import symtable + +APP = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "app") + + +def files(): + """main.py, rows.py and ctl_*.py, in that order, as bare file names.""" + split = ["rows.py"] + sorted(os.path.basename(p) + for p in glob.glob(os.path.join(APP, "ctl_*.py"))) + return ["main.py"] + [f for f in split + if os.path.exists(os.path.join(APP, f))] + + +def text(name): + with open(os.path.join(APP, name), encoding="utf-8") as fh: + return fh.read() + + +def source(): + """All the files' text, one after the other.""" + return "\n".join(text(f) for f in files()) + + +def tree(src=None): + """`ast.parse(source())` with every `*Mixin` class folded into + `Controller`, so `Controller` has all its methods. Positions refer to + `source()`.""" + src = source() if src is None else src + mod = ast.parse(src) + ctl = next(n for n in mod.body + if isinstance(n, ast.ClassDef) and n.name == "Controller") + keep = [] + for n in mod.body: + if isinstance(n, ast.ClassDef) and n.name.endswith("Mixin"): + ctl.body.extend(n.body) + else: + keep.append(n) + mod.body = keep + return mod + + +def _function_reads(table, acc): + for s in table.get_symbols(): + if (table.get_type() == "function" and s.is_global() + and s.is_referenced()): + acc.add(s.get_name()) + for child in table.get_children(): + _function_reads(child, acc) + + +def reading(name): + """The bare module names (`main`, `ctl_cycle` ...) whose functions read + `name` as a global.""" + out = [] + for f in files(): + acc = set() + _function_reads(symtable.symtable(text(f), f, "exec"), acc) + if name in acc: + out.append(f[:-3]) + return out + + +class _Live: + """The globals the Controller's code reads, wherever they are read. + + `live.NAME = value` sets NAME in every file whose functions read it; + `live.NAME` reads it. A name no file reads is an AttributeError, so a + patch that changes nothing cannot pass unnoticed. + """ + + def __getattr__(self, name): + mods = reading(name) + if not mods: + raise AttributeError(f"no file under app/ reads the global " + f"{name!r}") + return getattr(importlib.import_module("app." + mods[0]), name) + + def __setattr__(self, name, value): + mods = reading(name) + if not mods: + raise AttributeError(f"no file under app/ reads the global " + f"{name!r}: a patch of it changes nothing") + for stem in mods: + setattr(importlib.import_module("app." + stem), name, value) + + +live = _Live() diff --git a/goodwe_controller/tools/maint20_same_code.py b/goodwe_controller/tools/maint20_same_code.py index de3b5de..610b56c 100644 --- a/goodwe_controller/tools/maint20_same_code.py +++ b/goodwe_controller/tools/maint20_same_code.py @@ -5,12 +5,19 @@ For each FILE (default: every goodwe_controller/app/*.py that differs from BASE_REF, default release/1.0) the ast.dump() of the tree with docstrings -removed must be identical at BASE_REF and in the working tree. Also prints -code lines vs comment-only + docstring lines (whole lines, via tokenize) before -and after. Run from the repository root. Exit 1 on any code difference. +removed must be identical at BASE_REF and in the working tree, and so must +the `python -OO` compiled code (a wholly removed docstring leaves a no-op +there). An added or removed app/*.py file is a code difference. The diff +against BASE_REF may touch only goodwe_controller/app/*.py, +goodwe_controller/DECISIONS/*.md and this script. Also prints code lines vs +comment-only + docstring lines (whole lines, via tokenize) before and after, +and the docstrings removed entirely or added. Run from the repository root. +Exit 1 on any difference. """ import ast import io +import os +import re import subprocess import sys import tokenize @@ -53,29 +60,87 @@ def counts(src): return len(code), len(doc) + len(com - code - doc) +def qualnames(src): + out = {} + + def walk(node, prefix): + for n in ast.iter_child_nodes(node): + if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef, + ast.ClassDef)): + q = prefix + n.name + out[q] = docstring(n) is not None + walk(n, q + ".") + out[""] = docstring(ast.parse(src)) is not None + walk(ast.parse(src), "") + return out + + +def code_sig(co): + consts = tuple(code_sig(c) if hasattr(c, "co_code") else c + for c in co.co_consts) + return (co.co_name, co.co_code, consts, co.co_names, co.co_varnames, + co.co_freevars, co.co_cellvars, co.co_flags, co.co_argcount, + co.co_stacksize, co.co_exceptiontable) + + +def oo_same(old, new): + return (code_sig(compile(old, "f", "exec", optimize=2)) + == code_sig(compile(new, "f", "exec", optimize=2))) + + def git(*a): return subprocess.run(["git", *a], check=True, capture_output=True, text=True).stdout +def exists(base, f): + return subprocess.run(["git", "cat-file", "-e", f"{base}:{f}"], + capture_output=True).returncode == 0 + + +ALLOWED = re.compile(r"^goodwe_controller/(app/[^/]+\.py|DECISIONS/[^/]+\.md|" + r"tools/maint20_same_code\.py)$") + + +def ratio(m, c): + return f"{m / c:.2f}" if c else "n/a" + + def main(argv): base = argv[0] if argv else "release/1.0" - files = argv[1:] or [ - f for f in git("diff", "--name-only", base, "--", - "goodwe_controller/app").split() - if f.endswith(".py")] bad = 0 print(f"base {base} = {git('rev-parse', base).strip()}") + changed = git("diff", "--name-only", base).split() + for f in changed: + if not ALLOWED.match(f): + print(f"FAIL: diff touches {f}, outside app/*.py, DECISIONS/*.md " + "and this script") + bad += 1 + files = argv[1:] or [f for f in changed if re.match( + r"^goodwe_controller/app/[^/]+\.py$", f)] for f in files: + in_base, in_head = exists(base, f), os.path.exists(f) + if in_base != in_head: + print(f"CODE DIFFERS {f} " + f"{'removed' if in_base else 'added'} file") + bad += 1 + continue old = git("show", f"{base}:{f}") new = open(f, encoding="utf-8").read() same = dump(old) == dump(new) + oo = oo_same(old, new) (c0, m0), (c1, m1) = counts(old), counts(new) print(f"{'SAME CODE' if same else 'CODE DIFFERS'} {f} " f"code {c0}->{c1} comment+doc {m0}->{m1} " - f"ratio {m0 / c0:.2f}->{m1 / c1:.2f}") - bad += not same - print("OK: no code change" if not bad else f"FAIL: {bad} file(s) differ") + f"ratio {ratio(m0, c0)}->{ratio(m1, c1)} " + f"-OO {'same' if oo else 'DIFFERS'}") + bad += (not same) + (not oo) + qo, qn = qualnames(old), qualnames(new) + for q in sorted(q for q in qo if qo[q] and not qn.get(q, True)): + print(f" docstring REMOVED: {f}:{q}") + for q in sorted(q for q in qn if qn[q] and not qo.get(q, True)): + print(f" docstring ADDED: {f}:{q}") + print("OK: no code change" if not bad else f"FAIL: {bad} problem(s)") return 1 if bad else 0 diff --git a/goodwe_controller/tools/maint21_same_ast.py b/goodwe_controller/tools/maint21_same_ast.py new file mode 100644 index 0000000..7564a42 --- /dev/null +++ b/goodwe_controller/tools/maint21_same_ast.py @@ -0,0 +1,142 @@ +#!/usr/bin/env python3 +"""MAINT-21: prove that splitting app/main.py moved code and changed none. + + python3 goodwe_controller/tools/maint21_same_ast.py [BASE_REF] [--docstrings] + +Every module-level def, class and assignment of app/main.py at BASE_REF +(default release/1.0), and every method of its `Controller`, is looked up by +qualified name in the working tree: app/main.py, app/rows.py and the mixin +classes of app/ctl_*.py (a mixin's methods count as `Controller.`). +Each must be found exactly once with an identical `ast.dump()`, docstrings +removed unless --docstrings. Allowed extras: the `Controller` class header, +`_LOG = logging.getLogger("goodwe")` in a module that logs, and import lines. +Prints one line per file and `OK` or the differences. The diff against +BASE_REF may touch only goodwe_controller/app, DECISIONS, test_*.py and +tools. Run from the repository root on a clean checkout (untracked files are +read, but the diff check only sees tracked ones). Exit 1 on any difference. +""" +import ast +import collections +import glob +import os +import re +import subprocess +import sys + +APP = "goodwe_controller/app" +MIXIN = re.compile(r"^[A-Z][A-Za-z]*Mixin$") + + +def git(*a): + return subprocess.run(["git", *a], check=True, capture_output=True, + text=True).stdout + + +def bare(n, docstrings): + if not docstrings: + for x in ast.walk(n): + if isinstance(x, (ast.FunctionDef, ast.AsyncFunctionDef, + ast.ClassDef)) and x.body: + e = x.body[0] + if (isinstance(e, ast.Expr) and isinstance(e.value, ast.Constant) + and isinstance(e.value.value, str)): + x.body = x.body[1:] or [ast.Pass()] + return ast.dump(n) + + +def key_of(n): + if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)): + return n.name + if isinstance(n, ast.Assign): + return "=" + ",".join(ast.unparse(t) for t in n.targets) + if isinstance(n, ast.AnnAssign): + return "=" + ast.unparse(n.target) + return "?" + ast.unparse(n)[:60] + + +def units(src, docstrings, mixins): + """{qualified name: [dump, ...]} for one file's text.""" + out = collections.defaultdict(list) + tree = ast.parse(src) + for n in tree.body: + if isinstance(n, (ast.Import, ast.ImportFrom)): + continue + if (isinstance(n, ast.Expr) and isinstance(n.value, ast.Constant) + and isinstance(n.value.value, str)): + continue + if isinstance(n, ast.ClassDef) and ( + n.name == "Controller" or (mixins and MIXIN.match(n.name))): + for m in n.body: + out["Controller." + key_of(m)].append(bare(m, docstrings)) + continue + out[key_of(n)].append(bare(n, docstrings)) + return out + + +def main(argv): + docstrings = "--docstrings" in argv + argv = [a for a in argv if not a.startswith("--")] + base = argv[0] if argv else "release/1.0" + bad = 0 + print(f"base {base} = {git('rev-parse', base).strip()}") + for f in git("diff", "--name-only", base).split(): + if not re.match(r"^goodwe_controller/(app/[^/]+|DECISIONS/[^/]+|" + r"test_[^/]+\.py|tools/[^/]+)$", f): + print(f"FAIL: diff touches {f}") + bad += 1 + old = units(git("show", f"{base}:{APP}/main.py"), docstrings, False) + files = ["main.py", "rows.py"] + sorted( + os.path.basename(p) for p in glob.glob(f"{APP}/ctl_*.py")) + where = collections.defaultdict(list) # key -> [(file, dump)] + for fn in files: + p = f"{APP}/{fn}" + if not os.path.exists(p): + continue + for k, dumps in units(open(p, encoding="utf-8").read(), docstrings, + True).items(): + for d in dumps: + where[k].append((fn, d)) + found = collections.Counter() + problems = collections.defaultdict(list) + for k, dumps in old.items(): + if k == "Controller": + continue + got = where.get(k, []) + if k == "=_LOG": # one per module that logs, all the same + got = got[:1] * len(dumps) if all( + d == dumps[0] for _, d in got) else [] + if len(got) != len(dumps): + problems["?"].append(f"{k}: {len(dumps)} in base, " + f"{len(got)} in head") + continue + for (fn, d), want in zip(got, dumps): + if d != want: + problems[fn].append(f"{k}: AST differs") + else: + found[fn] += 1 + for k, got in where.items(): + if k not in old and k != "=_LOG": + for fn, _ in got: + problems[fn].append(f"{k}: not in base") + for fn in files: + if not os.path.exists(f"{APP}/{fn}"): + continue + if problems.get(fn): + print(f"DIFFERS {fn}") + for line in problems[fn]: + print(" ", line) + bad += len(problems[fn]) + else: + print(f"OK {fn} {found[fn]} units identical") + for line in problems.get("?", []): + print("DIFFERS ", line) + bad += 1 + total = sum(found.values()) + print(f"base units {sum(len(v) for k, v in old.items() if k != 'Controller')}" + f", identical in head {total}") + print("OK: code moved, none changed" if not bad else f"FAIL: {bad} problem(s)") + return 1 if bad else 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv[1:])) diff --git a/goodwe_controller/tools/opt11_identity.py b/goodwe_controller/tools/opt11_identity.py index f775816..4bf29be 100644 --- a/goodwe_controller/tools/opt11_identity.py +++ b/goodwe_controller/tools/opt11_identity.py @@ -26,6 +26,7 @@ from datetime import datetime, timedelta, timezone sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) +import main_files # noqa: E402 import app.main as m # noqa: E402 from app.main import Controller # noqa: E402 @@ -157,7 +158,7 @@ def run(n, *, extra=None, dur=2700.0, store=None, on_cycle=None, load=house, for i in c.inverters: i.dev_min, i.dev_max = -5000.0, 5000.0 c.auto = True - real_dt = m.datetime + real_dt = main_files.live.datetime clock = [0.0] class _DT(real_dt): @@ -165,7 +166,7 @@ def run(n, *, extra=None, dur=2700.0, store=None, on_cycle=None, load=house, def now(cls, tz=None): return BASE + timedelta(seconds=clock[0]) - m.datetime = _DT + main_files.live.datetime = _DT rows = [] try: t = 0.0 @@ -186,7 +187,7 @@ def run(n, *, extra=None, dur=2700.0, store=None, on_cycle=None, load=house, on_cycle(c, t) t += TICK finally: - m.datetime = real_dt + main_files.live.datetime = real_dt return rows, c return asyncio.run(go()) diff --git a/goodwe_controller/tools/opt11p3_replay.py b/goodwe_controller/tools/opt11p3_replay.py index a9eac56..589c22f 100644 --- a/goodwe_controller/tools/opt11p3_replay.py +++ b/goodwe_controller/tools/opt11p3_replay.py @@ -41,6 +41,7 @@ from datetime import datetime, timedelta, timezone HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) sys.path.insert(0, HERE) +import main_files # noqa: E402 import app.main as m # noqa: E402 from app.main import Controller # noqa: E402 from app.p1 import make_sample, split_signed # noqa: E402 @@ -348,7 +349,7 @@ def run(variant, house, pts, start, dur, *, check=None, stride=1, n=2, if patch is not None: patch(c) c.auto = True - real_dt = m.datetime + real_dt = main_files.live.datetime clock = [start] class _DT(real_dt): @@ -356,7 +357,7 @@ def run(variant, house, pts, start, dur, *, check=None, stride=1, n=2, def now(cls, tz=None): return clock[0] if tz is None else clock[0].astimezone(tz) - m.datetime = _DT + main_files.live.datetime = _DT plan_hour = None try: t = 0.0 @@ -416,7 +417,7 @@ def run(variant, house, pts, start, dur, *, check=None, stride=1, n=2, check(c, hass, now, pr) t += tick finally: - m.datetime = real_dt + main_files.live.datetime = real_dt return c c = asyncio.run(go()) return stats, c diff --git a/goodwe_controller/tools/safety103_plant.py b/goodwe_controller/tools/safety103_plant.py index 122f939..544b0df 100644 --- a/goodwe_controller/tools/safety103_plant.py +++ b/goodwe_controller/tools/safety103_plant.py @@ -22,6 +22,7 @@ sys.path.insert(0, HERE) sys.path.insert(0, os.path.join(HERE, "tools")) import opt11_identity as rig # noqa: E402 +import main_files # noqa: E402 from app import main as app_main, packmode # noqa: E402 from app.main import Controller # noqa: E402 from app.store import unit_key # noqa: E402 @@ -127,13 +128,13 @@ def run(n, house, *, before=off, dur=T + 90.0, tick=1.0, reg_s=10.0, for i in c.inverters: i.dev_min, i.dev_max = -5000.0, 5000.0 c.auto = True - real_dt, clock = app_main.datetime, [0.0] + real_dt, clock = main_files.live.datetime, [0.0] class _DT(real_dt): @classmethod def now(cls, tz=None): return rig.BASE + timedelta(seconds=clock[0]) - app_main.datetime = _DT + main_files.live.datetime = _DT rows = [] try: t = 0.0 @@ -161,7 +162,7 @@ def run(n, house, *, before=off, dur=T + 90.0, tick=1.0, reg_s=10.0, reason=c.loop_reason)) t += tick finally: - app_main.datetime = real_dt + main_files.live.datetime = real_dt return rows, c return asyncio.run(go()) diff --git a/goodwe_controller/tools/safety128_rig.py b/goodwe_controller/tools/safety128_rig.py index 3d97eec..1e8898d 100644 --- a/goodwe_controller/tools/safety128_rig.py +++ b/goodwe_controller/tools/safety128_rig.py @@ -33,6 +33,7 @@ from datetime import datetime, timedelta, timezone sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) +import main_files # noqa: E402 import app.main as m # noqa: E402 from app.main import Controller # noqa: E402 from app.p1 import make_sample, split_signed # noqa: E402 @@ -222,7 +223,7 @@ class Rig: i.dev_min, i.dev_max = -MAXW[i.name[-1]], MAXW[i.name[-1]] c.auto = True self.c = c - real_dt = m.datetime + real_dt = main_files.live.datetime clock = [self.start] class _DT(real_dt): @@ -230,7 +231,7 @@ class Rig: def now(cls, tz=None): return clock[0] if tz is None else clock[0].astimezone(tz) - m.datetime = _DT + main_files.live.datetime = _DT floor = float(self.o.get("cycle_floor_s", 15)) last_grid, last_cycle, last_n = object(), None, None try: @@ -260,7 +261,7 @@ class Rig: sample(self, c, t) t += 1.0 finally: - m.datetime = real_dt + main_files.live.datetime = real_dt return c return asyncio.run(go()) diff --git a/goodwe_controller/tools/safety78_identity.py b/goodwe_controller/tools/safety78_identity.py index 06af703..8815a2f 100644 --- a/goodwe_controller/tools/safety78_identity.py +++ b/goodwe_controller/tools/safety78_identity.py @@ -33,6 +33,7 @@ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) import opt11_identity as rig # noqa: E402 import opt11p3_identity as p3 # noqa: E402 import safety79_identity as s79 # noqa: E402 +import main_files # noqa: E402 import app.main as m # noqa: E402 from app import packmode # noqa: E402 from app.store import unit_key # noqa: E402 @@ -76,7 +77,7 @@ def run(n, *, modes=False, dur=DUR, load=load, extra=None): if modes: extra.update(p3.ARB, battery_modes_enabled=True) seen, extra_rows = [], [] - real_resolve = m.resolve + real_resolve = main_files.live.resolve def spy(claims, **kw): seen.append(tuple((c.source, c.priority, c.kind, c.value, c.lo, c.hi, @@ -96,7 +97,7 @@ def run(n, *, modes=False, dur=DUR, load=load, extra=None): db = os.path.join(tempfile.mkdtemp(prefix="s78-"), "tariff.db") real = rig.Controller rig.Controller = functools.partial(real, peak_db_path=db) - m.resolve = spy + main_files.live.resolve = spy try: rows, c = rig.run(n, extra=extra, dur=dur, load=load, soc=s79.soc, cut=lambda u, t: False, @@ -105,7 +106,7 @@ def run(n, *, modes=False, dur=DUR, load=load, extra=None): store=store_cheap(n) if modes else None) finally: rig.Controller = real - m.resolve = real_resolve + main_files.live.resolve = real_resolve return [r + (x,) for r, x in zip(rows, extra_rows)], c diff --git a/goodwe_controller/tools/safety81_sim.py b/goodwe_controller/tools/safety81_sim.py index a0accfc..c3dcc12 100644 --- a/goodwe_controller/tools/safety81_sim.py +++ b/goodwe_controller/tools/safety81_sim.py @@ -29,6 +29,7 @@ from datetime import timedelta sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) import opt11_identity as rig # noqa: E402 +import main_files # noqa: E402 import app.main as m # noqa: E402 from app import packmode # noqa: E402 from app.main import Controller # noqa: E402 @@ -140,13 +141,13 @@ def run(load, *, margin=50, dur=2700.0, rating=2000.0, cap=3500.0, for i in c.inverters: i.dev_min, i.dev_max = -5000.0, 5000.0 c.auto = True - real_dt, clock = m.datetime, [0.0] + real_dt, clock = main_files.live.datetime, [0.0] class _DT(real_dt): @classmethod def now(cls, tz=None): return rig.BASE + timedelta(seconds=clock[0]) - m.datetime = _DT + main_files.live.datetime = _DT rows, late = [], random.Random(8100) errors = [] @@ -173,7 +174,7 @@ def run(load, *, margin=50, dur=2700.0, rating=2000.0, cap=3500.0, rows.append((t, c.target, round(plant.hist[-1][1], 6))) t += TICK finally: - m.datetime = real_dt + main_files.live.datetime = real_dt logging.getLogger("goodwe").removeHandler(h) return plant, c, rows, errors plant, c, rows, errors = asyncio.run(go()) diff --git a/goodwe_controller/tools/safety84_identity.py b/goodwe_controller/tools/safety84_identity.py index 87730c0..ff1675c 100644 --- a/goodwe_controller/tools/safety84_identity.py +++ b/goodwe_controller/tools/safety84_identity.py @@ -23,6 +23,7 @@ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) import opt11_identity as rig # noqa: E402 import safety79_identity as s79 # noqa: E402 +import main_files # noqa: E402 import app.main as m # noqa: E402 from app import tariff # noqa: E402 @@ -71,7 +72,7 @@ def run(n, *, cheap=True, month_peak=None, dur=DUR, load=load, soc=None, """Rows (opt11_identity's fields plus every claim, the guard and the phases) and the controller. `month_peak` banks that peak this month.""" seen, extra_rows = [], [] - real_resolve = m.resolve + real_resolve = main_files.live.resolve def spy(claims, **kw): seen.append(tuple((c.source, c.priority, c.kind, c.value, c.lo, c.hi, @@ -93,7 +94,7 @@ def run(n, *, cheap=True, month_peak=None, dur=DUR, load=load, soc=None, "2026-09-02T10:00:00+00:00")).connection.commit() real = rig.Controller rig.Controller = functools.partial(real, peak_db_path=db) - m.resolve = spy + main_files.live.resolve = spy try: rows, c = rig.run(n, extra=dict(s79.P1, **OPT, **(extra or {})), dur=dur, load=load, soc=soc or s79.soc, @@ -102,7 +103,7 @@ def run(n, *, cheap=True, month_peak=None, dur=DUR, load=load, soc=None, store=store or s79.store_charging(n)) finally: rig.Controller = real - m.resolve = real_resolve + main_files.live.resolve = real_resolve return [r + (x,) for r, x in zip(rows, extra_rows)], c diff --git a/goodwe_controller/tools/safety94_rig.py b/goodwe_controller/tools/safety94_rig.py index f832c5e..9e4bc65 100644 --- a/goodwe_controller/tools/safety94_rig.py +++ b/goodwe_controller/tools/safety94_rig.py @@ -25,6 +25,7 @@ from datetime import datetime, timedelta, timezone sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) +import main_files # noqa: E402 import app.main as m # noqa: E402 from app.main import Controller # noqa: E402 @@ -169,7 +170,7 @@ def run(n, load, dur, *, tau=10.0, tick=1.0, soc=None, cut=None, for i in c.inverters: i.dev_min, i.dev_max = -5000.0, 5000.0 c.auto = True - real_dt = m.datetime + real_dt = main_files.live.datetime clock = [0.0] class _DT(real_dt): @@ -177,7 +178,7 @@ def run(n, load, dur, *, tau=10.0, tick=1.0, soc=None, cut=None, def now(cls, tz=None): return BASE + timedelta(seconds=clock[0]) - m.datetime = _DT + main_files.live.datetime = _DT out = {"stale": [], "refused": [], "rows": [], "c": c} was = {i.name: False for i in c.inverters} was_ref = {i.name: 0 for i in c.inverters} @@ -213,7 +214,7 @@ def run(n, load, dur, *, tau=10.0, tick=1.0, soc=None, cut=None, dict(plant.reg), [mm.phase for mm in c.maints])) t += 1.0 finally: - m.datetime = real_dt + main_files.live.datetime = real_dt return out return asyncio.run(go())