goodwe-addon/goodwe_controller/DECISIONS/OPT-17-several-forecast-entities.md

OPT-17 - the solar forecast from several entities, summed

Status: for review. Tests: test_opt17.py. Two options added.

A site whose forecast comes as several Home Assistant sensors (one per inverter or roof side) had to build a template sensor to sum them. Now each day can list them.

Options

• pv_forecast_entities and pv_forecast_tomorrow_entities: lists of sensors, default [], the same shape as pv_entities.
• pv_forecast_entity and pv_forecast_tomorrow_entity are unchanged. An install that uses them needs no edit.
• Why new keys, not "string or list" in the old ones. Measured on Supervisor 2026.08.0 by tools/supervisor_shape_probe.py §J, as TEL-12's §G did for pv_entity. Declared as a list, each forecast key refuses the string an install already stores (Invalid list for option 'pv_forecast_entity'), and a [] default does not rescue it. The one spelling that takes both, match(.*)?, also takes the integer 417 and shows a plain text box, so a second sensor cannot be added in the UI.
• §J also shows: a 0.17.0 blob validates unchanged with the lists at []; the lists render as repeatable fields; a downgrade drops them and keeps the single keys.
• [] in options: is load-bearing, as for pv_entities.

Rules

1. One key per day. Setting the single key and the list for the same day is refused at start, with one message: keep the list, clear the single one. The list can hold that entity too. (TEL-12 lets pv_entities replace pv_entity with a caution row. Here the brief asked for a refusal: a doubled or dropped forecast changes what a battery buys, and no install has both keys yet, so the refusal breaks nothing.)
2. Each member in its own unit. Every member is read as one forecast sensor is today (solarfc._day()): Wh, kWh or MWh, never guessed. Then the day's kWh are added up. A repeated id counts once.
3. One member not usable means the day is not usable. Missing, unavailable, unknown, stale, not an energy unit, or a bad number: that day's sum is not used, exactly as when the single sensor reads that way. No today means no forecast (P3 option A). No tomorrow means today only.
4. Hourly split. If every member has a split, the splits are joined (overlapping periods add up). If any member has none, the sum is spread over the bell, as for a state-only sensor.
5. Time. The forecast is as old as its oldest member.
6. One read. All members of both days are read in one gather, inside the gather that reads the inverters, so a slow sensor does not delay control.
7. Shown and logged once. With two or more members, each one not usable is named on the status page by its place in the list (STYLE.md: no entity ids on the page), as a caution row titled "Solar forecast" on Home. The action log names the entity id, once when the set of failing members changes.
8. One member is the single key. A one-member list reads, plans, shows and logs exactly as the single key with that entity.

Why

• A partial sum is a smaller number that looks real. Two of three inverters' forecasts read as a duller day, and Leftover solar would then buy grid energy the sun was going to give. TEL-12 took the same rule for the same reason. No forecast is a known state with a tested fallback.
• The bell for a mixed list: joining one member's hours with another's total has no honest shape, and the bell is the existing state-only rule.

Cost

• One flaky member costs the whole day's forecast. A site with three sensors loses the plan more often than one with a template sum that hides gaps.
• Two more options (85).

What this does not cover

• No weighting or calibration per member; FCST-01 is still the own forecast.
• Members on different integrations with different refresh times: each must be fresh (3 h) on its own; there is no wait for a lagging one.
• The day plan itself, the trust and the house profile are unchanged.
• The Batteries screen still says only "no solar forecast now". The member is named on the status page.