Add configuration visibility & control, robust multi-inverter energy, resilience, and a CLI (5.3.0)

[bbarabe]

Add configuration visibility & control, robust multi-inverter energy, resilience, and a CLI (5.3.0)

This is the resubmission promised when I closed #5 ("found an issue with battery energy — will fix before resubmitting"). It has since been through several months of daily use on a live two-inverter (master/slave) plant, plus a full review pass to integrate everything you shipped in 5.0.1/5.0.2.

The branch merges your main (5.0.2) as an ancestor, so the diff below is exactly what's new — nothing of yours is deleted or rewritten away. Where I diverge from a 5.0.2 behavior it's deliberate, called out below, and backed by measurements.

24 files changed, ~3,800 insertions / ~990 deletions across 74 commits. I kept the commits small and focused rather than squashing, so the history documents why each change exists — several of them record measurements that are worth preserving. Happy to squash on merge if you prefer.

---

Highlights

1. Inverter configuration: read-only sensors + a gated write action

• The System Work Mode programming is exposed as diagnostic sensors: Work Mode, Energy Pattern, Solar Sell, Time-of-Use enable + day-of-week flags, all six TOU slots (time / power / SOC / mode), Max Solar Power, Max Sell Power, Zero Export Power.
• A solark.configure_inverter action writes those settings — but only when the "Allow write access" config option (default off) is enabled. With it off, the integration is strictly read-only, same as today.
• Writes always target the master inverter (equipMode == 1, resolved once and cached). After a write, settings polling briefly accelerates (~15 s for up to a minute) because the cloud's /read endpoint lags its own /set — the read-back is eventually consistent.
• ⚠️ Reviewer note — this looks like a bug but isn't: the portal's "Max Sell Power" writes pvMaxLimit, and "Max Solar Power" writes solarMaxSellPower. The cloud field names are misleading. We verified empirically: setting Max Sell Power to a distinctive 17990 W on the portal (confirmed on the inverter LCD) changed pvMaxLimit; solarMaxSellPower held its old value. There are comments at both mapping sites so nobody "fixes" it back to the literal reading — including me; I tried once and the live test reverted me.

2. Energy correctness on multi-inverter plants

• energy_today / energy_total now sum across every inverter in the plant instead of reporting whichever inverter the API lists first. On this two-inverter system the old behavior under-reported daily production by roughly half.
• Deliberate divergence from 5.0.2: plant /realtime is a fallback, not the preferred source, for etoday/etotal. Its etoday agrees with the per-inverter sum exactly, but its etotal runs ~26% high on this (account-migrated) system, tracking the sum with a large fixed offset that appears in no other endpoint — the inverter list, /api/v1/plants, and the plant's own year-by-year PV history all agree within ~1%. We settled which side is right with an independent physical meter: module-level Tigo monitoring on the same array agrees with the per-inverter sum, not with etotal (the small remaining gap is DC-vs-AC conversion loss, as expected). Preferring /realtime would mirror a known-bad number and inject a one-time step into a TOTAL_INCREASING sensor, corrupting recorder statistics behind the Energy dashboard. The full reasoning lives in the _get_realtime_data docstring. (Note: the portal's overview card displays the bad etotal, so "matches the portal" is unfortunately not the same as "correct".)
• Spurious mid-day zeros from API glitches are filtered with a bounded (30-min) retention window; after it expires, a reported zero for energy_today is accepted as the genuine daily reset, and energy_total goes unknown rather than serving stale data through a long outage.
• New native energy sensors, all restore their totals across restarts: grid import/export energy, battery charge/discharge energy, home consumption energy (trapezoidal integration of the corresponding power sensors, owned by this integration — no dependency on the integration helper's internals).

3. Resilience

• Total cloud outage → entities go unavailable (as in your versions), instead of anything defaulting to 0. Partial failure degrades per-sensor: if only the flow endpoint fails, power/SOC report unknown while energy and status values fetched from other endpoints stay fresh; brief gaps retain last-known status values (30-min bound).
• A Repair issue is raised after an hour of continuous fetch failure (per sub-fetch, per entry) and clears itself on recovery.
• Setup survives cloud hiccups during HA startup (retry-with-backoff via ConfigEntryNotReady instead of a dead "Failed to set up"), and accounts that can read telemetry but not settings (installer/limited logins, or plants with no master) keep all their normal sensors — only the config sensors stay unavailable.
• Logins are serialized behind a lock so the two coordinators can't fire duplicate credential requests on simultaneous token expiry.

4. New sensors beyond energy

• AC Relay Status — on/off-grid detection straight from the inverter's relay register (workdata /194), much more reliable than inferring from power flows. Matched by register number so the p2 cluster's column-name change (AcRelayStatus/194 vs the old AcRelayStatus(NA)/194) can't break it again.
• Grid Status, Generator Status, Battery Charge/Discharge Power.

5. Architecture: HA-independent client + CLI

• The api.py monolith is split: solark_client.py (API client, HA-independent), solark_auth.py (OAuth + legacy login), solark_logging.py (your redaction from d336443, ported verbatim), solark_errors.py. api.py remains as a compatibility shim re-exporting the same public names (SolArkCloudAPI, SolArkCloudAPIError, _redact_secrets, _redact_secret_text) with compatible signatures.
• Because the client no longer needs HA, there's a CLI (python -m solark_cli) for poking the cloud API directly — plant data, raw endpoint dumps, settings read, gateway list, TOU slot writes. See CLI.md. Credentials come from a gitignored solark_secrets.json (template included). This is how most of the endpoint behavior above was measured.
• Everything you shipped in 5.0.1/5.0.2 is carried: URL auto-discovery (discovery.py is byte-identical to yours), retired-host normalization, PV minPower handling, the MPPT placeholder-ramp guard, the SOC curCap guard, battery sign flags, and the log redaction — applied at every log site in the split modules.

6. Upgrade safety (please scrutinize — this was a priority)

• No entity duplication: all nine of your sensor keys and the {entry_id}_{key} unique_id format are unchanged.
• No entity renames, ever: the integration never rewrites registry entity_ids. Fresh installs get predictable ids via suggested_object_id; existing installs keep whatever ids (and customizations) they have, so no automation or dashboard breaks on upgrade.
• Config entry migration v1 → v4, idempotent, verified against a pristine v1 entry: v2 seeds the write-access option (off), v3 is registry cleanup that's a no-op for your users, v4 rewrites retired hosts (mysolark.com, ecsprod-api*) to current defaults — the old api_url still serves reads but rejects writes since the p2 account migration, so entries stuck on it look healthy until the first write fails.
• Minimum HA is now 2024.3 (hacs.json): the migration uses async_update_entry(..., version=...), which doesn't exist earlier — on older cores the old floor of 2023.5 would have bricked the entry mid-migration.
• Timezone-sensitive API date queries use the HA-configured timezone instead of UTC (fixes wrong-day workdata/flow results in evening hours for western timezones; the cloud resets at midnight UTC).

7. Docs

• README/QUICKSTART updated for solarkcloud.com and auto-discovery, sensor/action tables expanded, CLI.md added, Energy-dashboard guide updated for the built-in energy sensors, QUICKSTART's UTF-8 mojibake repaired, and CHANGELOG rewritten so 5.3.0 reads as one release on top of your 5.0.2.

---

Testing

• Months of continuous operation on a live two-inverter Sol-Ark plant (p2 cluster account), including the Energy dashboard, TOU writes via the action, and both login paths.
• Migration exercised from a real 5.0.0-era entry through v4.
• Outage behavior exercised against real cloud incidents (that's where the repair issue, retention windows, and unavailable-not-zero rules come from).
• Register mapping, /realtime behavior, and endpoint cross-checks measured with the included CLI; the decisive numbers are recorded in the relevant commit messages and docstrings.

Notes for review

• The commit history is intentionally granular; git log --reverse reads as a narrative. The commits touching solark_client.py parsing carry the endpoint measurements inline.
• Two behaviors intentionally differ from 5.0.2 and are flagged inline in code: /realtime as fallback (§2) and meter-first grid import/export (explicit meter fields are trusted before direction flags when existsMeter is set).
• I'm happy to split anything out, squash, or adjust naming/conventions to your preference.