fix(enphase): settle the power buckets and derive load from the balance

[springfall2008]

Fixes two sensor bugs spotted in a deployed system: a saw-toothing pv_power, and a load_power that tracked PV instead of house usage. Independent of #4429.

1. Saw-tooth on the power sensors

interval_power read the 15-minute bucket that had just closed, assuming it was complete. It isn't — the cloud keeps back-filling a bucket for several minutes after it ends, so the first read returns roughly a third of the eventual value and later corrects upward:

09:56  idx=38  674 Wh → 2696 W
10:01  idx=39  243 Wh →  972 W   ← new bucket, still filling
10:07  idx=39  759 Wh → 3036 W   ← same bucket, settled (3.1x)
10:18  idx=40  276 Wh → 1104 W   ← next bucket, drops again

In a 13-hour log, 23 buckets were re-read with a changed value — every one an increase. This affected pv_power, grid_power and battery_power equally, since all three come from the same call; PV was just the most visible.

Fixed by stepping back to a bucket that has stopped changing. Observed revisions only ever touched the just-closed bucket, so one extra step suffices. Cost is up to one extra bucket of lag.

2. load_power was PV

It was published from /app-api/<site>/get_latest_power, which returns production, not consumption. The night-time data is conclusive — it reads 0-1 W from midnight to 04:00, and tracks the PV ramp by day:

Time	get_latest_power	PV bucket	Actual house load
08:51	1759 W	1736 W	232 W
09:29	2363 W	2092 W	252 W
10:07	3105 W	3036 W	260 W

automatic_config wires this to Predbat's load_power arg, which gap-fills load_today — so PV-shaped data was being fed into house-load history.

Load is now the energy-balance residual of the other three channels, from the same settled bucket, so the four sensors agree and a power-flow card balances. That is exactly how the cloud derives its own consumption channel — verified equal to within 1 Wh on 80 of 96 buckets — so reading that channel instead would gain nothing.

Known limitation, deliberately accepted

Being the residual, load absorbs all the timing and rounding skew between the micros, the CT clamps and the battery telemetry. On a site cycling 30 kWh/day through the battery to serve a 5 kWh house load, those terms dwarf the house term and the residual goes unphysical while the battery works hard — around 21% of buckets. It is clamped at zero so it can never render a negative house load, and it is accurate when the battery is calm (1 bad bucket in 8 with the battery idle; a steady 220-260 W through the morning).

Alternatives were measured and rejected:

• Aggregating — needs a 2-4 hour window before it is reliably plausible, by which point it is no longer house load in any useful sense.
• Deltaing the daily totals — worse, not better: 99/141 implausible versus 9/43, because the channels restate on independent schedules (a 2995 Wh export increment appeared in one 5-minute poll). Not a precision limit; at ~470 W a 5-minute interval accrues ~39 Wh, so ±1 Wh quantisation is only ±12 W.
• Enphase's own consumption channel — identical numbers, as above.

load_today is unaffected and remains accurate (buckets sum exactly to the daily total). Documented in docs/components.md, including the 15-30 minute lag now carried by all four power sensors.

The real fix is the Enlighten live MQTT feed (MeterSummaryData over AWS IoT), which carries measured pv/storage/grid/load channels directly. That is being investigated separately; this change is the best available from the /today endpoint in the meantime.

Testing

Five new tests written test-first, covering the settled-bucket selection, the start-of-day clamp, the derived load, the negative-residual clamp, and the consistency invariant (load == pv + grid + battery). One existing test updated — it asserted the old get_latest_power value for load.

./run_pre_commit passes: all hooks green, full quick suite green.

Version bumped v8.47.4 → v8.47.6.

Note: get_latest_power is still fetched and cached but no longer published. It is retained deliberately as the only genuinely live PV figure available — it will be needed to validate the MQTT feed's agg_p_mw scaling.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR fixes two EnphaseCloud monitoring issues in Predbat by (1) deriving instantaneous power from a settled intra-day /today energy bucket to avoid saw-toothing, and (2) publishing load_power as the energy-balance residual of PV/grid/battery so it reflects house usage and keeps the power-flow model consistent.

Changes:

• Adjust power derivation to step back from the just-closed (still back-filled) bucket and use a settled bucket instead.
• Replace load_power publishing from get_latest_power with a derived residual (pv + grid + battery) clamped at zero.
• Update docs and extend Enphase API tests to cover settled-bucket selection, start-of-day clamping, derived load, and negative residual clamping.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
docs/components.md	Documents the added 15–30 minute lag for power sensors and the residual-based load_power limitations.
apps/predbat/tests/test_enphase_api.py	Adds/updates tests for settled-bucket power selection and derived/clamped load behavior.
apps/predbat/predbat.py	Bumps Predbat version to v8.47.6.
apps/predbat/enphase.py	Implements settled-bucket selection and derives/publishes load_power from the bucket-based balance.