fix(solis): use a stable voltage for amp<->watt conversions

[springfall2008]

This is an automated draft PR generated from issue #5090 — a maintainer should review it before merging.

Fixes #5090

Summary

The inverter holds its charge/discharge limits as currents (CID 7224/7226 and the per-slot currents), but get_nominal_voltage() re-derived every watt value from the live measured batteryVoltage. A fixed 70A limit therefore republished as anything from 3352W to 3726W as the pack moved with state of charge, dragging battery_rate_max (auto-bound to the max_charge_power entity), the write tolerance computed from it, and the read-back of every rate setpoint along with it.

Implements the strategy from the maintainer's field-data comment (#5090 (comment)). get_nominal_voltage() now returns, in priority order:

1. solis_nominal_voltage from apps.yaml — which previously fed only get_capacity_voltage() and did nothing for the rate paths, so there was no workaround for this at all;
2. the live voltage when it exceeds 60V — an HV pack, where behaviour is unchanged from the [Solis Cloud] Hard-coded nominal_voltage of 48V breaks power/capacity calculations for HV batteries #4493 fix (no sampled LV system passed 57.5V);
3. otherwise an LV pack classified by the BMS-requested charge voltage: 51.2V nominal at or above 55V, 48V below it;
4. otherwise the existing 48V fallback.

Two new helpers support this: get_live_battery_voltage() (the measurement, retaining the last-known fallback so #4493's behaviour is preserved exactly) and get_bms_charge_voltage() (the first non-zero of top-level batteryAcvSet or any batteryList[].batteryChargingVoltage — identical on all 14 sampled systems). The live voltage is still published as its own sensor for display.

Why not the original suggestion

The issue description's first idea — infer a nominal from a live reading and snap it to a pack class — does not work, and the field data is what establishes that: the LV classes overlap (a full 15S reaches 53.5V, a low 16S drops to 47.1V), so any rule reading a single sample lands in the wrong class. batteryType cannot arbitrate either, since it names the BMS protocol and PYLON_LV was reported by both classes. The charge voltage is the only field that separates them, and being a setting rather than a measurement it also holds still — which is what the bug needs.

Testing

coverage/run_pre_commit — all 12 hooks pass with no auto-fixes, and the bundled run_all --quick passes (All tests passed (4 slow tests skipped, total time: 120.45s)). npx cspell run separately over the changed files (the local cspell hook does not actually check spelling): clean.

Two new tests in test_solis.py, both of which fail without the fix and pass with it. Verified by restoring apps/predbat/solis.py to origin/main while keeping the test file, and driving the two tests directly:

• test_nominal_voltage_sources_and_stability — red with Expected the 48V fallback when no charge voltage is reported, got 51.3
• test_rate_setpoints_do_not_drift_with_battery_voltage — red with max_charge_power moved from 3647W to 3352W at 47.89V with the current unchanged, which lands inside the 3352W–3726W range the reporter measured over three days

The second is the test shape the issue asked for: it writes a slot rate in watts, moves the live voltage between the write and the next publish, and asserts the published watts and the battery_rate_max source entity are unchanged and that the write round trip closes. The first covers both charge-voltage field names, the 53.2 / 54.9 / 55.0 / 56.5 / 58.4 boundary, stability across the full 47.1–53.5V live range, the HV path plus its last-known fallback, and the no-charge-voltage fallback.

One note on the red run: the pre-fix solis.py reads nominal_voltage_last_known, which this PR renames, so the red driver sets that attribute on the mock to keep the failure behavioural rather than an AttributeError.

Notes

• HV packs still drift. Step 2 keeps the live voltage above 60V as specified, so an HV user still sees the 10–14% swing; solis_nominal_voltage is the only fix there, which the docs now say. Worth a follow-up if there are HV systems to sample.
• Behaviour change a reviewer should look at: when solis_nominal_voltage is configured it now wins for power conversions too, not just capacity. Three assertions in test_publish_entities encoded the opposite — that a configured 512V nominal is ignored in favour of a live 52.3V — and I updated them rather than working around them, since that preference is the bug.
• soc_max auto-binding left disabled. The original "would wobble cycle to cycle" rationale is now gone, but without solis_nominal_voltage the capacity is still an inference, and set_arg_auto() defaults to overwrite=True, so enabling it would replace a correct hand-entered soc_max with an approximate one. That is a maintainer's judgement rather than part of this fix; the line stays commented and the comment now states the current reasoning.
• The pre-existing test_get_nominal_voltage_and_capacity_voltage uses 533V, which is above the 60V threshold, so it now passes via the HV branch. It reads like general coverage but exercises only HV — the LV path is covered by the new test.
• The GitNexus MCP tools were not available in this session, so the blast-radius check was done by search: get_nominal_voltage() has 17 call sites, all within solis.py, no external callers, and no signature change.
• The wording changes in docs/apps-yaml.md, docs/components.md and templates/solis_cloud.yaml are not incidental — all three told users that the max charge/discharge power sensors use the live voltage and that solis_nominal_voltage is only needed for capacity, which is no longer true.
• Not addressed here, from the same comment: batteryChargingCurrent / batteryDischargeLimiting hold the BMS current limits separately from the inverter's own CID 7224/7226 settings. That belongs in tools/debug-journal.md rather than in this fix.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Clarify the diagnostic distinction between a latched voltage reading and the 48V fallback.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

This PR stabilizes Solis amp-to-watt conversions using configured, latched, or fallback voltage.

Changes:

• Updated Solis voltage selection and conversion logic.
• Added regression tests for stability and rate setpoints.
• Revised Solis documentation and configuration templates.

File summaries

File	Summary
templates/solis_cloud.yaml	Updated sample configuration guidance.
docs/components.md	Documented revised Solis conversion behavior.
docs/apps-yaml.md	Updated nominal-voltage configuration documentation.
apps/predbat/tests/test_solis.py	Added voltage and setpoint stability tests.
apps/predbat/solis.py	Implemented stable voltage selection and conversions.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.