docs(alphaess): state that the Open API cannot control export - #4744
Open
springfall2008 wants to merge 2 commits into
Open
docs(alphaess): state that the Open API cannot control export#4744springfall2008 wants to merge 2 commits into
springfall2008 wants to merge 2 commits into
Conversation
The AlphaESS Open API has no forced-export, working-mode or dispatch endpoint, and AlphaESS document ctrDis as a discharge permission window - self-consumption inside it, charge-only outside it - so a programmed export window exports nothing beyond genuine solar surplus. Freeze Export is equally undeliverable: it needs the battery stopped from charging off solar, and gridCharge gates only timed grid charging, so the payload built for Freeze Export is identical to the Demand mode one. Document that, recommend predbat_mode "Control charge" on these systems, and note that forced export is reachable on the same hardware over local Modbus. Also corrects two existing claims: that a zero rate signals Freeze Export (it only holds the battery out of discharging), and the inverter_freeze_export_discharge_rate note, which cannot apply to the cloud component. Design-spec field-verification item 3 is marked answered. No behaviour change - the payload builders are correct for what the API accepts and are left intact. Refs #4701, #4723 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
A few newly added lines have minor but user-facing documentation wording issues (grammar/consistency) that could mislead readers about AlphaESS freeze/hold behavior.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR updates Predbat’s documentation (and the AlphaESS module docstring) to clearly state that the AlphaESS Open API cannot force export and therefore Predbat’s Force Export / Freeze Export features are not deliverable via the AlphaESS Cloud integration, recommending select.predbat_mode = Control charge for these systems.
Changes:
- Document AlphaESS Open API limitations: discharge windows are permission/self-consumption windows (not forced export) and the API cannot stop solar charging (so Freeze Export cannot work).
- Update AlphaESS-related setup/component docs to highlight the limitation and recommended configuration.
- Mark the relevant AlphaESS cloud integration design-spec field-verification item as answered based on #4701 and align the AlphaESS module docstring with the docs.
File summaries
| File | Description |
|---|---|
| docs/superpowers/specs/2026-08-22-alphaess-cloud-integration-design.md | Updates field-verification notes to reflect observed Open API export limitation. |
| docs/inverter-setup.md | Adds explicit installer-facing warning that AlphaESS Cloud can’t control export; points to apps-yaml detail and recommended mode. |
| docs/components.md | Updates component description/notes to state AlphaESS Cloud is charge-control only and export control isn’t possible. |
| docs/apps-yaml.md | Adds a dedicated section explaining why Force/Freeze Export can’t work via AlphaESS Open API; clarifies “zero rate” semantics and scope. |
| apps/predbat/alphaess.py | Updates module docstring to document the Open API export limitation and recommended configuration. |
Review details
Suppressed comments (2)
docs/components.md:1088
- Grammar: “AlphaESS document …” should be “AlphaESS documents …” (subject/verb agreement).
- A write reaching the cloud does not mean the inverter has applied it: the dongle collects new settings on its next poll, typically one to five minutes later. Predbat tolerates a few cycles of divergence before warning
docs/components.md:1089
- This bullet says a zero rate “signals a freeze”, but elsewhere in this PR the docs clarify that a zero rate only holds the battery out of discharging (it cannot stop solar charging), and Freeze Export is not deliverable on AlphaESS Cloud. Tweaking this wording to “hold” avoids implying Freeze Export works here.
- Files reviewed: 5/5 changed files
- Comments generated: 2
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+825
to
+826
| freeze CHARGE and the iBoost/car holds depend on. Update (GH#4701): supported by | ||
| AlphaESS's own manual - "outside the set time period, the batteries are only allowed |
Comment on lines
+17
to
+25
| EXPORT CANNOT BE CONTROLLED (GH#4701). The Open API has no forced-export, working-mode | ||
| or dispatch endpoint, and AlphaESS document ctrDis as a discharge PERMISSION window: | ||
| inside it the system runs in self-consumption, outside it the battery may only charge. | ||
| So a programmed export window exports nothing beyond genuine solar surplus. Freeze | ||
| Export is equally undeliverable - it needs the battery stopped from charging off solar, | ||
| and gridCharge only gates timed GRID charging, so the payload built for Freeze Export is | ||
| identical to the Demand mode one. Users should run predbat_mode 'Control charge'. The | ||
| builders below are left intact deliberately: they are correct for what the API accepts, | ||
| and forced export is available on the same hardware over local Modbus. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation-only. Related to #4701 and #4723 — deliberately not auto-closing either, since a follow-up code change is still on the table (see Follow-ups).
Summary
The AlphaESS Open API has no forced-export, working-mode or dispatch endpoint, and AlphaESS's own documentation describes
ctrDisas a discharge permission window — self-consumption inside it, charge-only outside it — rather than a forced export. So:gridChargegates only timed grid charging — so the payload built for Freeze Export comes out identical to the Demand mode one.execute.pypre-arms the discharge window up toplan_interval_minutesahead of each planned export slot, which on the permission-window semantics bars the battery from covering house load until that window opens. That is the side effect reported independently in ALPHAESS: Set discharge timeslot when exiting Axle VPP status. #4723.The docs now say so plainly and recommend
select.predbat_mode=Control chargeon AlphaESS, which stops export windows being planned or written at all. Forced export is available on the same hardware over local Modbus (dispatch registers), just not over the cloud API — noted as the route for anyone who needs it.Two existing claims are corrected as part of this:
apps-yaml.mdsaid a zero rate is how Predbat signals "freeze charge or freeze export". The zero rate only holds the battery out of discharging; it cannot stop it charging.inverter_freeze_export_discharge_ratenote cites an AlphaESS observation. That cannot have come from the cloud component, which cannot disable charging at all, so the note now says it does not apply here.Design-spec field-verification item 3 ("whether surplus above house load reaches the grid during a discharge window") is marked ANSWERED, No; item 2 gains the manual's supporting wording, and its incorrect claim that freeze export depends on it is corrected to freeze charge and the iBoost/car holds.
Files:
docs/apps-yaml.md,docs/inverter-setup.md,docs/components.md, thealphaess.pymodule docstring, and the design spec.Testing
No behaviour change — the payload builders are correct for what the API accepts and are left intact, so there is no new code to test.
cd coverage && ./run_pre_commit— all hooks pass (markdownlint, cspell, ruff, black), and the quick suite passes with 4 slow tests skipped.tools/triage_test.sh alphaess_control— PASSED. All sixalphaess_*test modules also pass unchanged.Follow-ups (not in this PR)
Control charge & dischargestill gets a plan built on exports that never happen, plus the pre-arm write from ALPHAESS: Set discharge timeslot when exiting Axle VPP status. #4723.automatic_configcould set this for AlphaESS systems, with a log line.batHighCapis the one untested lever: if it is a global charge ceiling rather than only the in-window target, writing it at the current SoC would stop solar charging and give real Freeze Export behaviour. Worth a field test before anything is built on it.