github nicois/foxess-control v1.0.22-beta.7

pre-releaseone hour ago

Fixed

  • AC-coupled installs no longer report grid import while they are exporting. With solar coming through a separate inverter (not wired into the FoxESS PV strings) and the battery full, the integration showed Grid Consumption Energy climbing and Grid Feed-in Energy stuck at zero, while the native FoxESS app showed the site exporting 1.52 kW — reported on an H3 5kW Gen 2 with WebSocket enabled (issue #18). The AC-coupled generation is the meterPower2 variable over REST, but the real-time WebSocket carries it as a node named aux, which the integration never read. So during any smart session the grid-direction inference (C-006) ran believing the site was generating nothing while it was in fact producing 3.32 kW: from a house load of 1.80 kW it predicted an import of 1.80 kW, the actual grid reading was 1.52 kW, and because those two magnitudes agree within the 3x reliability window the gridStatus field — which correctly said export — was never consulted. The sign came out backwards, and every kWh the site exported was booked as consumption. The existing "additional solar power variable" option could not save it: that value was added to pvPower after the direction had already been decided, so the balance never saw it however fresh it was. The WebSocket path now reads aux and folds it in before the balance runs, preferring the live value and falling back to the last REST-polled one when a frame does not carry it (dropping the term would put the balance straight back into the same failure mode). Units are handled per C-004 — watts as strings unless the field's own unit says kW. This is opt-in and changes nothing for anyone else: the term is only applied if you have set Additional solar power variable (usually meterPower2), because on a DC-coupled system the meaning of aux is not established. The derived direction logic is deliberately kept — it exists because gridStatus is not always reliable (D-010) — since the defect here was the input it was fed, not the arithmetic. If you have AC-coupled solar and have not yet set that option, set it: it is what enables both this fix and the correct total-generation figure the pacing algorithm works from. Refs C-004, C-006, D-010.
  • The control card now tells you when it has stopped receiving updates, and stops offering you buttons that cannot work. A user on 1.0.22-beta.5 clicked Cancel on a smart charge session, confirmed it, and watched the card go on showing a live charging session "even after a long time" — so they reported cancel as broken. It was not: their recorder history and system log show the session going idle at 12:20:01 and again at 12:21:22 and staying idle for 45 minutes, until one of their own automations re-armed it. The integration did exactly what it was asked; their browser had stopped receiving state updates, and the card gave them nothing whatsoever to see that with. This was a gap in 1.0.22-beta.5: that release added a staleness banner and dimming to the overview card and left the control card — the one that owns Cancel, Charge and Discharge — with nothing, which is the worse half of the pair. A stale overview shows misleading numbers; a stale control card invites you to act on them, and _handleAction called callService regardless of how old the view was, so on a dead WebSocket the click went nowhere and the user was left believing they had acted. The control card now carries the same treatment as the overview card, from the same code (a new shared foxess-stale.js imported by both, rather than a second copy of a threshold table that would drift): a warning banner at full strength above readings that are dimmed and desaturated, with the two causes worded differently because they need opposite responses from you — no connection to Home Assistant ("your readings are frozen; check your browser or network") versus inverter data stale ("check the inverter or the cloud API"). Only hass.connected distinguishes them, because the age a card displays is computed in your browser against its own clock, so a disconnected page shows an age that grows without bound while every number on it is frozen. While disconnected, Charge, Discharge and Cancel are all disabled, and the banner says why: the service call provably cannot be delivered, so an enabled button is a lie, and it is the specific lie that produced this report. When the connection is fine but the data is old the controls stay fully usable, deliberately — you may be cancelling precisely because you can see something is wrong, the call still reaches Home Assistant, and Home Assistant acts on its own state rather than on your browser's snapshot. Two smaller fixes ride along. The card's data-source badge used a flat 30-second staleness threshold against a 300-second poll interval, so a perfectly healthy REST install rendered the "stale" badge about 90% of the time — the same cry-wolf bug the overview card was fixed for, and the reason "API · 45m" did not stand out from the "API · 2m" the card showed the rest of the day; it now uses the per-source thresholds (WebSocket 60 s, REST and Modbus 900 s = three missed polls). And the staleness treatment is applied on the partial re-render path too, which is what runs while the Charge/Discharge form is open — the moment you are about to act is the worst possible moment to hide that the view is frozen. Refs C-020, C-029.
  • Cancel now acknowledges itself immediately, instead of appearing to do nothing. The confirming click used to fire clear_overrides and re-render from unchanged state, so nothing at all changed on screen until Home Assistant pushed new state — which is a large part of why the user above could not tell "my click didn't register" from "it worked and the session is ending". The button now switches to Cancelling… and goes un-clickable the instant you confirm, so a second click cannot fire a second request. It clears as soon as Home Assistant sends any news about the session (it ends, or its phase changes), and it is bounded: if the request never settles and no state ever arrives, the card gives up after 15 seconds and says so rather than sitting on "Cancelling…" forever — a permanently spinning card would be a new bug, not a fix for the old one. If the request is rejected outright, that is surfaced in words under the buttons with Cancel re-enabled so you can retry, rather than the failure being swallowed and the card left looking untouched — and that message retires when the session it was about ends, so you are never left reading "tap Cancel to retry" on an idle card that no longer has a Cancel button. It does survive ordinary polling, though, so there is time to read it. Refs C-020.

Changed

  • Test infrastructure: an E2E failure capture can finally describe a card failure. No user-visible change — this is entirely test-harness diagnostics. CI run 33380962649 lost a TestFormInputPersistence failure to two blind spots. The .html artefact was written from page.content(), which is document.documentElement.outerHTML, and outerHTML does not serialise shadow roots — so for a dashboard whose cards sit four shadow hops inside Home Assistant, the dump stopped at <home-assistant> and contained nothing that was on screen. Grepping the real artefact for ha-textfield, form-start or No active operations returned nothing at all, even though the accompanying screenshot showed all three, which left the one question the failing test had asked — did the form ever open? — unanswerable from the evidence. The capture now walks every open shadow root and emits its content inline, each block wrapped in a self-describing #shadow-root (open) of TAG comment pair so a reader can tell shadow content from light DOM at a glance; subtrees containing no shadow host are still handed to outerHTML verbatim, so fidelity and cost are the browser's own. Depth and size are capped, and the cap announces itself in place rather than silently truncating, because a shortened dump that reads as a complete one produces a confidently wrong conclusion. A deliberately deep tree is not a hypothetical: with the depth cap removed the same walk raises RangeError: Maximum call stack size exceeded, and because the write is wrapped in contextlib.suppress, that failure would have deleted the artefact rather than reported anything — so the walk also falls back to the old shallow dump instead of losing the file. Second, the browser-diagnostics .log is now written on every capture, unconditionally. It was previously written only when the recorder buffer was non-empty, so for this failure — where the recorder was attached and the browser genuinely had nothing to say — no file appeared, and an absent file cannot be told apart from a harness bug that forgot to attach a recorder. Those are opposite conclusions: one is a defect in the test infrastructure, the other is evidence, positively ruling out a console error, an uncaught exception and a lost asset as the cause. The log now states which of the two it is describing, in words. Finally, the Playwright-native waits re-raise their own exception, whose entire text is Page.wait_for_function: Timeout 10000ms exceeded.; the capture summary that wait_for_condition puts in its message was being discarded, which is why this reached a human as an unexplained timeout with no hint that artefacts existed. Those sites now re-raise the same exception type carrying the summary. Regression class tests/test_e2e_failure_capture_shadow_dom.py, which drives a real Chromium DOM built to Home Assistant's actual nesting and asserts on the bytes written to the artefact rather than on the serialiser's source text, verified against eight deliberately wrong implementations before the real one was kept: the status quo (caught by five tests), a blind "concatenate every element's outerHTML and every shadow root's innerHTML" dump (three — and notably not caught by the straightforward "is the marker present" assertion, which is exactly why the negative controls exist), a correct walk that failed to delimit shadow content (one), the walk with its depth cap removed (one), the walk with no fallback, so an evaluate failure deleted the artefact (one), a log that did not distinguish a missing recorder from a silent browser (one), an unconditional log that dropped the recorded entries (two, one of them the pre-existing Lovelace panel-load test), and the original capture-then-discard-the-summary re-raise (one). The capture also now records navigations, because the improved capture immediately earned its keep and then ran out of things to say. Replaying the failing body ~1200 times under deliberate CPU load reproduced the failure once, and the new artefact localised it exactly: the timeout is the first wait, so the form never opened, and the serialised card shows a perfectly healthy idle card ten seconds later — SoC 50%, "No active operations", both action buttons present, no form overlay anywhere. The only unexplained content left was two aborted asset loads, net::ERR_ABORTED on a translations JSON and a frontend_latest chunk, which hints the document was replaced mid-load without saying so — and the difference decides the diagnosis, because a navigation landing between the click and the wait yields a fresh card with no form state and raises no "Execution context was destroyed", so every retry path stays dormant while the wait polls a healthy card until its budget expires. _set_form_value already carries a recovery branch for exactly that mode, so it is one this harness has met before. Navigations are now recorded with the main frame marked separately, since only a main-frame navigation replaces the card, and a negative control pins that a page which never navigated must not report one — an unconditionally emitted line would assert the very thing the next diagnosis needs to rule out. Nothing was changed in the test or the card, deliberately: 1600 instrumented replays showed the click always landing and always rendering the form synchronously, so no branch has been shown to need changing, and raising the wait's budget would be tuning a trigger away rather than fixing a cause (C-031). Refs C-031, C-029, C-020.
  • Test infrastructure: Flaky Test Detection's job timeout raised from 30 to 50 minutes. On v1.0.22-beta.6 ten of the twenty matrix jobs were cancelled at exactly 30 minutes while every job that finished passed — a time limit surfacing as a red workflow with no test actually failing. The previous fix (per-test rather than per-file selection, v1.0.22-beta.5) removed the variance in job size, where a third of the matrix drew 166 of 174 tests; it did not make the jobs fast, and the judgement at the time that they "were not legitimately slow" was wrong. A flat 87-test half runs 16-30 minutes on a GitHub runner, and the E2E suite has since gained a cold-browser-context test class for the Lovelace panel-load recovery work. 50 minutes clears the observed ceiling while still failing a genuine hang.

Added

  • An inverter that cannot release Mode Scheduler control now says so, instead of doing nothing forever (issue #17). Reported on an H3-12.0-E running 1.0.22-beta.6: Could not turn the Mode Scheduler master switch on via /op/v0/device/scheduler/set on inverter H3-12.0-E; writing the schedule anyway. requests.exceptions.HTTPError: 404 Client Error: Not Found. That endpoint is the only API call that can turn the master switch off, so scheduler handback can never work on that hardware — and until now a user could switch the option on, watch nothing happen at the end of every session for the rest of the install's life, and find the explanation only by downloading a diagnostics file and reading last_handback. Which is exactly the failure C-020 exists to prevent. Three things changed. A Repair issue now appears (Settings → System → Repairs) naming the model and the endpoint, so it reads as the continuation of the warning already in the user's log; it is the shape Repairs are for — you asked for something your hardware cannot do, it will never start working by itself, and there is one useful action, which is turning the option back off. It is raised only when the option is on, because nobody who never asked for handback should be told their inverter cannot do it, and it is withdrawn when the option goes off, when the endpoint later answers, or on a restart that has not yet seen a 404 — a firmware fix retires it without anyone doing anything. The disable_scheduler action now refuses, with the reason, rather than reporting a success it did not achieve. And the missing endpoint is remembered rather than rediscovered at every session boundary: the master-switch write is already attempted before every schedule write, so by the time a teardown asks, the answer is known at no extra cost, and the handback declines with something to say instead of failing a step it was never going to win. How much is inferred from one response is bounded deliberately, because over-inferring would permanently disable a working feature: only a 404 counts — a 500, a timeout, or the errno 40257 a device without a scheduler answers with are all left alone, since none of them says the endpoint is absent — nothing is persisted, so a reload re-tests from scratch, and any later successful write erases the memory immediately. Modelled as a separate fact, not as "this device has no Mode Scheduler": that device's own flag endpoint says it does have one, and its schedule writes enable the switch implicitly, so calling it unsupported would be a confident falsehood about the owner's hardware — the same mistake get_scheduler_flag was changed to stop making — and would send them hunting for a firmware limitation they do not have. Smart charging and discharging are entirely unaffected on these inverters, and always were; nothing about sessions changes, and the session's own override group still comes off at teardown whether or not the handback can do anything (C-025 outranks this whole feature). Also covered end to end in a real Home Assistant for the first time (C-029): the disable_scheduler action over the real service registry including its mid-session refusal, and the 404 case from the wire all the way to a Repair issue listed by the repairs/list_issues websocket command. Writing that end-to-end coverage turned up something worth knowing if you drive this action from a script: a refusal is fully legible over the websocket API — which is what the frontend, Developer Tools, scripts and automations all use, message and translation key included — but Home Assistant's REST POST /api/services/foxess_control/disable_scheduler maps only two specific exception types to a 400 and lets everything else escape, so a refusal there arrives as a bare 500 Server got itself in trouble with the reason discarded. That is Home Assistant's behaviour for every integration rather than anything this one can change, but it is the difference between "the action explained itself" and "the action broke", so prefer a script step or a websocket call over raw REST if you need to know why. Regression coverage in tests/test_handback_policy.py::TestSchedulerSetUnavailable, tests/test_handback_foxess.py::TestTheMasterSwitchWriteEndpointIsRemembered and tests/test_handback_teardown.py::TestTheMasterSwitchWriteEndpointIsMissing, verified against four deliberately wrong implementations before the real one was kept: one folding the 404 into "no Mode Scheduler support" (caught by six tests), one recording any failed master-switch write so a single transient 500 disabled the feature until the next restart (three), one that never withdrew the Repair issue, so the notice outlived both the option being turned off and the endpoint starting to answer (two), and one raising the Repair issue regardless of the option, which would have notified every install that never opted in (one). The warning itself already fired once per inverter and then dropped to debug — that shipped in 1.0.22-beta.6 and needed no change; a test now also pins the demotion, so a future "fix" cannot silence the repeat outright and leave nothing to correlate against.
  • New action foxess_control.disable_scheduler — "Release the inverter now" (issue #16 asked for it by name). Turns the Mode Scheduler master switch off and returns the inverter to its own settings: work mode Self Use, plus your own Min SoC on grid if the integration recorded it. Local Modbus control works again, and a Min SoC below the scheduler's 10% floor becomes possible (issue #4). It deliberately does not consult the "Release the inverter when idle" option, because calling the action is the request — the option governs the automatic handback after every session, and requiring both would leave the person who wants their inverter released once, without signing up for it forever, with no action at all. That is not a licence to invent a floor: the value put back is still only the one the integration read before it ever touched that register, and if it never captured one, nothing is written (P-002). Every guard the automatic path applies applies here, by being the same code rather than a second copy of it: it refuses during a smart charge or discharge session (C-025 — disabling the scheduler mid-session strands the live override, so the group stops driving the inverter while the integration still believes it is discharging), refuses when the schedule contains work modes this integration does not manage and names the mode so "remove it in the FoxESS app" is actionable advice (C-018), refuses on a device that reports no Mode Scheduler, distinguishes "could not find out" from "your hardware does not have one", and makes no API call whatsoever in entity mode. Unlike the automatic path, a refusal is raised into the service call and shown in the UI immediately: a service that silently does nothing is worse than no service, because the user concludes their inverter was released (C-020). A device that refuses a write, by contrast, does not raise — by then the three independent steps have each been attempted and some may have taken effect, so an exception would misreport a partial handback as a total one; those go to the recent-errors buffer and the last-outcome record instead (C-026, D-059). It is not a second clear_overrides: no schedule group is added or removed, so a user asking for local control back does not silently lose a group they built, and calling it twice is not an error. Named, described and translated in all ten shipped locales, refusal message included — Home Assistant serves action labels from translations/<lang>.json rather than strings.json, so a missing locale renders the bare key. Regression class tests/test_handback_teardown.py::TestDisableSchedulerAction (plus a locale-parity class), verified against four deliberately wrong implementations before the real one was kept: one that bypassed the policy and wrote the master switch directly (caught by five tests), one that substituted the configured Min SoC default when nothing had been captured (two, one of them the automatic path's), one that made the action honour the opt-in option (nine), and one that logged refusals instead of raising them (seven). The tests themselves needed a second pass for the same reason: ServiceNotFound is a subclass of ServiceValidationError, so the one refusal test that checked only the exception type passed while the action did not exist at all.
  • The diagnostics download now explains the handback. Settings → Devices & Services → FoxESS Control → ⋮ → Download diagnostics gains a handback section carrying whether the option is on, the Min SoC on grid that was captured as yours, and the outcome of the most recent handback attempt — including the ones that declined, with the reason. That last part is the point: the handback is off by default, so on almost every install every outcome is a decline, and "why is my inverter still scheduler-controlled?" has to be answerable from a download taken on a system where, by design, nothing happened (C-020, C-026). "Never captured" and "captured 0%" are reported as different things, because a 0 % floor is exactly what issue #4 is about and a download that rendered the two identically could not say whether a handback will restore anything at all. The last known state of the Mode Scheduler master switch is included too, and it follows the write that turns the switch off as well as reads of it — otherwise a report from a released inverter would claim the switch was still on and contradict the device it was describing. The section is read entirely from memory: generating diagnostics makes no API call. That is asserted against recorded HTTP traffic rather than inferred from the code, because a download is requested precisely when the cloud is already misbehaving, and a report that hangs or trips the rate limiter is the one report that would have explained the problem. When the switch has never been observed the field is null rather than false, since "we never looked" and "we looked and it was off" send troubleshooting to opposite places. Nothing in the section is a credential, and that is proved by test rather than argued — non-vacuously, since the check first asserts the section is populated. Regression class tests/test_diagnostics.py::TestHandbackSection / ::TestHandbackSectionMakesNoRequest (15 tests), verified against three deliberately wrong implementations before the real one was kept: one testing the captured floor for truthiness so a real 0 % floor read as "nothing captured" (three tests), one fetching the scheduler flag live on the diagnostics path (four tests, one of them counting requests), and one whose cached flag tracked reads but not writes, so the download reported the master switch as still on for an inverter the integration had just released (one test).
  • The "Release the inverter when idle" option now does something. With it switched on, the end of every smart session hands the inverter back to its own settings: the Mode Scheduler master switch is turned off, the device's own work mode is set to Self Use, and your own Min SoC on grid is put back — exactly the value the integration read before it ever touched that register, including 0%, which the Mode Scheduler itself refuses to accept (issues #16, #4). With Mode Scheduler off the inverter obeys local Modbus control again, and the integration turns it straight back on for the next session, so sessions are unaffected. Off by default: an install that has not opted in makes no new API call of any kind at any session boundary — not merely no writes — so upgrading changes nothing until you ask it to. The order is fixed and is the safety argument for the whole feature: the session's schedule group comes off first, and only then does the master switch go off, because a failure the other way round would leave the inverter force-discharging behind a scheduler the integration could no longer steer (P-001). For the same reason a handback failure can never hold up the override removal (C-025) or be mistaken for one; failures are recorded individually in the diagnostics download's recent-errors buffer, collapsed by cause so one repeatedly failing teardown cannot evict the other 29 entries, and a last-outcome record keeps the reason even when the answer is "nothing happened" — a handback that fails silently is worse than one that never runs, because the toggle being on invites you to assume your inverter was released. Handback never acts while a session is running, and because that check is a snapshot it is re-taken immediately before the switch goes off and immediately after: a session that starts in that window has the switch turned straight back on. clear_overrides hands back too, since a user asking for their inverter back is the clearest case there is. Regression class tests/test_handback_teardown.py (29 tests) plus two end-to-end tests in a real Home Assistant, verified against eleven deliberately wrong implementations before the real one was kept — including one that handed back before removing the group (caught by five tests, one of them asserting request order, since the end state is identical either way and only the intermediate state is dangerous), one that ignored the opt-in option (four tests), one that swallowed step failures silently (two), one that trusted the session snapshot (two), one that omitted the error-buffer de-duplication (one), one that substituted the configured Min SoC default when nothing had been captured (one), and one with no exception guard at all, whose handback failure escaped into the listener and faked a failed override removal (three). Five of the 29 exist because a bug in the handback code itself must not become a session-boundary violation: every inverter interaction already absorbs its own failure, so nothing in normal operation reached the module's outermost guard, leaving its "never raises" promise load-bearing and untested — the sort of promise that quietly stops being true at the first refactor. Those tests also pin the honesty of the record: a crash must not leave the diagnostics download still reporting the previous session's success, and must never leave a half-written record describing a handback that never happened in that shape.
  • A "Release the inverter when idle" option in the integration's options (Settings → Devices & Services → FoxESS Control → Configure), which is the switch the scheduler handback of issues #16 and #4 will hang off. Off by default, and it does nothing yet — the teardown wiring lands separately, so this release only makes the option settable and readable. Nothing on the control path reads it, no byte on the wire differs, and no existing install changes behaviour. The default is the part worth being careful about rather than the feature: Home Assistant replaces the whole options dict with whatever an options flow returns, and the value it returns for a field the user never touched is the schema default — so a default of "on" would have enabled the handback, and with it writes to the user's own persistent Min SoC register, for anyone who merely opened the dialog and pressed Submit. Both directions are pinned by test, including an entry saved before this version existed reading as off all the way through to IntegrationConfig. For the same reason the tests also assert that adding the field did not make the dialog destructive: every other option the step owns (polling interval, Min SoC on grid, battery capacity, export limit, smart headroom, BMS interval, WebSocket mode, the additional-PV variable) is given a deliberately non-default value, and a save that only means to flip the new toggle must return all of them unchanged — compared as whole IntegrationConfig objects, not merely as present keys, since an options flow that silently reset someone's configuration would be far worse than this feature is worth.
  • The captured Min SoC is shown beside that toggle, read-only, as Home Assistant helper text (C-020). It has to be visible, because the captured value is authoritative and never re-read: a handback user who changes their floor in the FoxESS app has it put back. The remedy already exists — turning the option off and on re-captures — but a remedy for a value nobody can see is not a remedy. A dash is shown when nothing has been captured, deliberately not a number, since a number there would be a claim about the user's inverter that the integration has not actually read; the surrounding text explains the dash, so what the user reads stays localised in all ten languages. 0% renders as 0% rather than as "nothing captured", because a 0 % floor is exactly what issue #4 is about and a truthiness test there would hide the feature's own use case. The dialog still opens when the integration failed to set up, since "we do not know" is a perfectly good thing for it to say. Label and description are translated into all ten shipped locales, with a new locale-parity regression class — tests/test_card_translations.py covers only the Lovelace card's JavaScript tables, so the options flow had no such guard, and Home Assistant serves these labels from translations/<lang>.json rather than strings.json, meaning a locale missing the key renders the raw option name on a toggle that rewrites the user's Min SoC. Regression class tests/test_handback_options.py (48 tests), verified against four deliberately wrong implementations before the real one was kept: one defaulting the option to on (caught by three tests), one replacing the options schema instead of extending it so the save dropped every other option (three tests), one whose default ignored the saved value so every options save silently disabled the feature (one test), and one testing the captured floor for truthiness so a real 0 % floor read as "nothing captured" (one test).

Don't miss a new foxess-control release

NewReleases is sending notifications on new releases.