Merge release/1.0 (OPT-11 P4, #156) into safety-83-peak-over-drain

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

goodwe_controller/app/dayplan.py

@@ -0,0 +1,262 @@
+"""OPT-11 P4: the day plan. Will the sun fill each battery before the
+expensive hours? If not, how much should it take from the grid?
+
+Pure: the forecast (`solarfc`), the house profile, the price runs and the
+batteries in; a level per battery (`Plan.targets`) out. `modetrade.charge_to()`
+turns the level into permission to charge from the grid; main.py rebuilds the
+plan with the price runs (at most every 15 minutes) and keeps a level unless
+it moves by `HYST_KWH` or `HYST_FRAC` (`hold()`).
+
+The sums (OPT-11-design section 1, "Excess solar", with the owner's answers):
+* `sun`: trust x the solar the house will not use, between now and the
+  expensive run the cheap run is for, x the charge efficiency:
+  `trust x sum_h max(0, forecast_h - house_h) x EFF`.
+* Solar first batteries take it first, up to the ceiling. What is left is
+  shared by the Leftover solar batteries by their room.
+* Cheap hours only ignores the plan and fills to the ceiling, as in P3 and
+  the design (section 1). Skipping the sun's share cost money in the replay
+  (PR #156 review: 29.72 against 29.41 EUR on real 2026 prices).
+* A Leftover solar battery charges only up to what the house will draw from
+  it in the expensive runs before the next cheap run, less its share:
+  `min(ceiling, floor + house use / EFF) - share`. So it buys only the
+  shortfall, not up to the ceiling.
+* Solar first never charges from the grid (owner, 2026-09-29).
+
+The house profile is the add-on's own measurement, grid + battery power, per
+local hour, over the last `PROFILE_DAYS` days; the estimate for an hour is the
+median of that hour. It is net of the solar the house used itself, so for
+the solar sum it is never taken below the night-time median (`base()`).
+The site's own solar readings are not used: TEL-11 keeps them out of every
+control decision.
+"""
+
+import statistics
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+
+from .packmode import LEFTOVER_SOLAR, SOLAR_FIRST
+from .tariff import BILLING_TZ
+
+EFF = 0.95                  # charge (and discharge) efficiency
+HYST_KWH = 1.0              # a kept level moves only by this much...
+HYST_FRAC = 0.10            # ...or this share of the battery's shortfall
+PROFILE_DAYS = 7
+MIN_HOURS = 20              # hours of a day recorded before it counts
+NIGHT_HOURS = (0, 1, 2, 3, 4, 5, 22, 23)
+DEFAULT_TRUST_PCT = 70
+
+# Site verdicts (the page's forecast line).
+SUNNY, PARTLY, DARK = "sunny", "partly", "dark"
+
+
+# --------------------------------------------------------------------------- #
+# The house profile
+# --------------------------------------------------------------------------- #
+def _local(t: datetime):
+    return t.astimezone(BILLING_TZ)
+
+
+class HouseProfile:
+    """Hourly means of the house's net use (grid + battery power), kept per
+    local day and hour: `{"YYYY-MM-DD": {hour: [mean_w, samples]}}`. The
+    store holds `dump()`; `load()` takes it back and drops what is bad."""
+
+    def __init__(self, data=None):
+        self.days = {}
+        self._cur = None            # (day, hour, sum, n)
+        if isinstance(data, dict):
+            self.load(data)
+
+    def load(self, data):
+        for day, hours in data.items():
+            try:
+                datetime.strptime(str(day), "%Y-%m-%d")
+            except ValueError:
+                continue
+            if not isinstance(hours, dict):
+                continue
+            row = {}
+            for h, v in hours.items():
+                try:
+                    hi, w = int(h), float(v)
+                except (TypeError, ValueError):
+                    continue
+                if 0 <= hi < 24 and abs(w) < 1e6:
+                    row[hi] = w
+            if row:
+                self.days[str(day)] = row
+
+    def dump(self) -> dict:
+        return {d: {str(h): round(w, 1) for h, w in sorted(r.items())}
+                for d, r in sorted(self.days.items())}
+
+    def add(self, now: datetime, house_w) -> bool:
+        """One reading. Returns True when an hour closed (then store it)."""
+        lt = _local(now)
+        key = (lt.strftime("%Y-%m-%d"), lt.hour)
+        closed = False
+        if self._cur is not None and self._cur[:2] != key:
+            day, hour, s, n = self._cur
+            if n >= 60:                 # about 5 minutes of readings
+                self.days.setdefault(day, {})[hour] = s / n
+                closed = True
+            self._cur = None
+            self._prune(lt)
+        if house_w is None:
+            return closed
+        if self._cur is None:
+            self._cur = (key[0], key[1], 0.0, 0)
+        d, h, s, n = self._cur
+        self._cur = (d, h, s + float(house_w), n + 1)
+        return closed
+
+    def _prune(self, lt):
+        """Keep the last `PROFILE_DAYS` days; a day after today (the clock
+        was wrong once) would never age out, so it goes too."""
+        keep = (lt.date() - timedelta(days=PROFILE_DAYS)).isoformat()
+        today = lt.date().isoformat()
+        for d in [d for d in self.days if d < keep or d > today]:
+            del self.days[d]
+
+    def ready(self) -> bool:
+        """At least one day with `MIN_HOURS` hours recorded."""
+        return any(len(r) >= MIN_HOURS for r in self.days.values())
+
+    def hour_w(self, hour: int):
+        vals = [r[hour] for r in self.days.values() if hour in r]
+        return statistics.median(vals) if vals else None
+
+    def base(self):
+        vals = [w for h in NIGHT_HOURS if (w := self.hour_w(h)) is not None]
+        return statistics.median(vals) if vals else None
+
+    def estimator(self):
+        """`f(hour) -> W`, or None when not ready. Fixed at call time."""
+        if not self.ready():
+            return None
+        base = self.base() or 0.0
+        table = {}
+        for h in range(24):
+            w = self.hour_w(h)
+            table[h] = base if w is None else w
+        return lambda h: table[h], max(0.0, base)
+
+
+# --------------------------------------------------------------------------- #
+# The plan
+# --------------------------------------------------------------------------- #
+@dataclass(frozen=True)
+class Plan:
+    verdict: str                # SUNNY / PARTLY / DARK
+    sun_kwh: float              # solar the batteries can count on
+    fc_kwh: float               # the forecast over the same span
+    until: datetime             # the expensive run the plan is for
+    targets: dict               # name -> level % (Leftover solar only)
+    need_kwh: dict              # name -> kWh from the grid (0: none)
+    share_kwh: dict             # name -> kWh of solar counted for it
+
+
+def _hour_slices(t0, t1):
+    """Local-hour slices of [t0, t1): (start, end, local hour)."""
+    out, t = [], t0
+    while t < t1:
+        lt = _local(t)
+        nxt = (lt.replace(minute=0, second=0, microsecond=0)
+               + timedelta(hours=1)).astimezone(timezone.utc)
+        e = min(nxt, t1)
+        out.append((t, e, lt.hour))
+        t = e
+    return out
+
+
+def _room(p, to_pct):
+    if p.capacity_kwh is None or p.soc is None:
+        return 0.0
+    return max(0.0, float(to_pct) - float(p.soc)) / 100.0 * float(
+        p.capacity_kwh)
+
+
+def plan(forecast, house, runs, now, packs, *, trust_pct, floor_pct,
+         ceiling_pct):
+    """The day plan, or None when there is none to make: no forecast, no
+    house profile yet, no price plan, or no expensive run after the cheap
+    run. `house` is `HouseProfile.estimator()`'s answer. `packs` are
+    `modetrade.Pack`s."""
+    if forecast is None or house is None or runs is None or not runs.on \
+            or runs.cheap is None:
+        return None
+    house_w, base_w = house
+    until = next((g for g in runs.give if g.start >= runs.cheap.end), None)
+    if until is None:
+        return None
+    trust = max(0.0, min(1.0, float(trust_pct) / 100.0))
+    sun = fc_sum = 0.0
+    for s, e, h in _hour_slices(now, until.start):
+        pv = forecast.between(s, e)
+        if pv is None:
+            return None             # the span reaches a day with no forecast
+        hrs = (e - s).total_seconds() / 3600.0
+        use = max(house_w(h), base_w) * hrs / 1000.0
+        sun += max(0.0, pv - use)
+        fc_sum += pv
+    sun *= trust * EFF
+
+    usable = [p for p in packs if p.use and p.live and p.idle
+              and p.soc is not None and p.capacity_kwh]
+    sf = [p for p in usable if p.mode == SOLAR_FIRST]
+    price = [p for p in usable if p.mode == LEFTOVER_SOLAR]
+    sf_room = sum(_room(p, ceiling_pct) for p in sf)
+    excess = max(0.0, sun - sf_room)
+    rooms = {p.name: _room(p, ceiling_pct) for p in price}
+    total_room = sum(rooms.values())
+
+    # What the house draws in the expensive runs from the one this plan is
+    # for until the next cheap run (or a day), from the profile.
+    horizon = until.start + timedelta(hours=24)
+    use_kwh = 0.0
+    for g in runs.give:
+        if g.start < until.start or g.start >= horizon:
+            continue
+        for s, e, h in _hour_slices(g.start, g.end):
+            use_kwh += max(0.0, house_w(h)) * (
+                e - s).total_seconds() / 3600.0 / 1000.0
+    caps = {p.name: float(p.capacity_kwh) for p in price}
+    cap_sum = sum(caps.values()) or 1.0
+
+    targets, need, share = {}, {}, {}
+    for p in price:
+        sh = excess * rooms[p.name] / total_room if total_room > 0 else 0.0
+        sh_pct = sh / caps[p.name] * 100.0
+        want = use_kwh * caps[p.name] / cap_sum / EFF
+        top = min(float(ceiling_pct),
+                  float(floor_pct) + want / caps[p.name] * 100.0)
+        level = max(0.0, top - sh_pct)
+        targets[p.name] = round(level, 2)
+        need[p.name] = round(_room(p, level), 3)
+        share[p.name] = round(sh, 3)
+    if sun < sf_room:
+        verdict = DARK
+    elif any(v > 0.05 for v in need.values()):
+        verdict = PARTLY
+    else:
+        verdict = SUNNY
+    return Plan(verdict, round(sun, 3), round(fc_sum, 3), until.start,
+                targets, need, share)
+
+
+def hold(old: dict | None, new: dict, capacity: dict) -> dict:
+    """Hysteresis: a battery keeps its old level unless the new one differs
+    by at least `HYST_KWH`, or by `HYST_FRAC` of the larger level's energy
+    (whichever is less). A battery new to the plan takes its level at once;
+    one that left the plan is dropped at once."""
+    out = {}
+    for name, level in new.items():
+        was = (old or {}).get(name)
+        cap = float(capacity.get(name) or 0.0)
+        if was is None or cap <= 0:
+            out[name] = level
+            continue
+        moved = abs(level - was) / 100.0 * cap
+        step = min(HYST_KWH, HYST_FRAC * max(was, level) / 100.0 * cap)
+        out[name] = level if moved >= step else was
+    return out

goodwe_controller/app/homeview.py

@@ -345,7 +345,10 @@ def mode_runs(c, day0, day1, now, shadow):
                                    else (soc - floor)) / 100.0 * cap)
             return kwh
         blocks = []
-        if rp.charge_useful() and pm.mode in GRID_CHARGE_MODES:
+        # P4: with a day plan, the grid block is the planned shortfall.
+        need = plan_need(c, inv.name)
+        if rp.charge_useful() and (need > 0.0 if need is not None
+                                   else pm.mode in GRID_CHARGE_MODES):
             blocks.append(("grid", rp.cheap))
         sell = rp.sell if pm.sell and pm.can_sell else None
         for g in rp.give:
@@ -358,6 +361,8 @@ def mode_runs(c, day0, day1, now, shadow):
                 continue
             hrs = (run.end - run.start).total_seconds() / 3600.0
             kwh = room(kind, hrs)
+            if kind == "grid" and need is not None:
+                kwh = min(kwh, need)
             if kwh < MIN_KWH:
                 continue
             price = run.mean_eur_kwh
@@ -382,6 +387,56 @@ def mode_runs(c, day0, day1, now, shadow):
     return out, None
 
 
+def plan_need(c, name):
+    """P4: kWh this battery buys from the grid by the day plan, or None when
+    there is no plan for it (then P3 option A applies)."""
+    targets = c.plan_targets() if hasattr(c, "plan_targets") else None
+    if not targets or name not in targets:
+        return None
+    inv = next((i for i in c.inverters if i.name == name), None)
+    if inv is None or inv.soc is None or not inv.capacity_kwh:
+        return None
+    return max(0.0, targets[name] - float(inv.soc)) / 100.0 * float(
+        inv.capacity_kwh)
+
+
+def plan_state(c):
+    """P4: `"plan"` (a day plan is made), `"learning"` (no house profile
+    yet), `"no_forecast"` (set but missing or stale), or None (not set, or
+    battery modes off)."""
+    if not getattr(c, "modes_on", False) or \
+            getattr(c, "fc_entity", None) is None:
+        return None
+    if getattr(c, "solar_fc", None) is None:
+        return "no_forecast"
+    hp = getattr(c, "house_profile", None)
+    if hp is not None and not hp.ready():
+        return "learning"
+    return "plan" if getattr(c, "day_plan", None) is not None else None
+
+
+def solar_block(c, now):
+    """P4: the solar forecast line for the Batteries screen and the Simple
+    settings view: `{state, fc_kwh, count_kwh, updated, line}`."""
+    st = plan_state(c)
+    out = {"state": st, "fc_kwh": None, "count_kwh": None, "updated": None,
+           "line": ""}
+    if st is None and getattr(c, "solar_fc", None) is None:
+        return out
+    fc = getattr(c, "solar_fc", None)
+    if fc is not None:
+        trust = float(getattr(c, "solar_trust_pct", 70)) / 100.0
+        out.update(fc_kwh=round(fc.today.kwh, 1),
+                   count_kwh=round(fc.today.kwh * trust, 1),
+                   updated=hhmm(fc.at))
+    if st in ("no_forecast", "learning"):
+        out["line"] = _t("solar." + st)
+    elif fc is not None:
+        out["line"] = line_solar(fc.today.kwh, out["count_kwh"],
+                                 out["updated"])
+    return out
+
+
 def maintenance_runs(c, day0, day1, now, shadow):
     """The monthly battery cycle: under way now, or starting later today.
     The cycle starts in the hour `maintenance_start_hour` names, read as the
@@ -664,7 +719,9 @@ def battery_rows(c, shadow, running, held=False):
             refused=refusing(c, inv), peak=peak,
             giving=flow(inv.batt) == "giving", other_refuses=other,
             sf_ahead=sf_ahead, role=role, plan=plan, has_at=bool(at),
-            other_cycle=cycling)
+            other_cycle=cycling,
+            day=None if pm is None or pm.mode not in PRICE_MODES
+            else day_key(c, inv.name))
         rows.append({
             "name": inv.name,
             "level_pct": None if inv.soc is None else float(inv.soc),
@@ -699,10 +756,25 @@ def battery_rows(c, shadow, running, held=False):
     return rows
 
 
+def day_key(c, name):
+    """P4: the day plan's word for one Leftover solar or Cheap hours
+    battery: `sun_fills`, `tops_up`, `no_forecast`, or None."""
+    st = plan_state(c)
+    if st == "no_forecast":
+        mode = c.pack_mode(next(i for i in c.inverters if i.name == name))
+        return "no_forecast" if mode.mode == LEFTOVER_SOLAR else None
+    if st != "plan":
+        return None
+    need = plan_need(c, name)
+    if need is None:
+        return None
+    return "tops_up" if need >= MIN_KWH else "sun_fills"
+
+
 def battery_why(*, modes_on, mode, off, reading, phase, shadow, running,
                 held, refused, peak, sf_ahead, giving=False,
                 other_refuses=None, role=None, plan=None,
-                has_at=False, other_cycle=None) -> str:
+                has_at=False, other_cycle=None, day=None) -> str:
     """The key of one battery's "why" line (`home_words.why`), most urgent
     first. Pure, so every branch is tested without a controller."""
     if not reading:
@@ -729,6 +801,8 @@ def battery_why(*, modes_on, mode, off, reading, phase, shadow, running,
     if not modes_on:
         return "modes_off"
     # OPT-11 P3: the battery's role in the price runs this cycle.
+    if role == "hold" and day is not None:
+        return day              # P4: what the day plan decided
     if role in ROLE_WHY:
         if role == "hold" and not has_at:
             return "saves_later"
@@ -876,6 +950,7 @@ def _build(c, *, level, checks, now):
                  modes_on=bool(getattr(c, "modes_on", False)),
                  running=running, held=held, shadow=shadow)
     return {
+        "solar": solar_block(c, now),
         "state": {"kind": kind, "pill": pill(kind),
                   "ran": ctl.get("text", "") if ctl else "",
                   "sub": banner_sub(kind)},
@@ -1172,6 +1247,10 @@ def run_house_amount() -> str:
     return _t("run.house_amount")
 
 
+def line_solar(fc_kwh, count_kwh, at) -> str:
+    return _t("solar.line", kwh=_kwh(fc_kwh), count=_kwh(count_kwh), at=at)
+
+
 def line_no_trade(key) -> str:
     return "" if key == "off" else _t("no_trade." + key)
 
@@ -1314,6 +1393,8 @@ def _samples() -> list:
                                                 off=off, peak=peak)))
     out += [("plan", why_words(k, name="Battery A")) for k in words["why"]]
     out += [("plan", today_words(k)) for k in words["today"]]
+    out += [("plan", line_solar(9.2, 6.4, "10:15")),
+            ("plan", _t("solar.no_forecast")), ("plan", _t("solar.learning"))]
     out += [("plan", line_no_trade(k)) for k in
             ("not_covered", "no_prices", "peak", "not_firm", "not_worth",
              "no_level")]

goodwe_controller/app/main.py

@@ -42,9 +42,11 @@ from .arbiter import (
     P_SAFETY, SET, Claim, Resolution, actuator_for, pre_resolve, resolve,
 )
 from . import allocator
+from . import dayplan
 from . import modetrade
 from . import packmode
 from . import priceruns
+from . import solarfc
 from . import control as _ctl
 from .control import Tuning, compute, maintenance_charge_floor, peak_at_risk
 from .delivery import (
@@ -235,6 +237,11 @@ def load_options() -> dict:
 # valued at (`priceruns.plan(ref_eur_kwh=)`): the rest of that day.
 REF_CHEAP_KEEP = timedelta(hours=12)
 
+# OPT-11 P4: the store key of the house profile (dayplan.HouseProfile), and
+# how often the forecast sensors are read (they change hourly at most).
+HOUSE_PROFILE_KEY = "house_profile"
+FORECAST_READ_S = 60.0
+
 
 def why_raised(resolution, claims) -> bool:
     """F2 (OPT-11 P1 test): did the limit that bound the site target push it
@@ -948,6 +955,25 @@ class Controller:
         self._mode_trade_was = False
         self._charge_blocked_q = None
         self._ref_cheap = None
+        # OPT-11 P4: the solar forecast and the day plan. Only with battery
+        # modes on AND `pv_forecast_entity` set; otherwise none of this runs
+        # and every mode acts as in P3 option A.
+        self.fc_entity = (opts.get("pv_forecast_entity") or None) \
+            if self.modes_on else None
+        self.fc_tomorrow_entity = opts.get("pv_forecast_tomorrow_entity") \
+            or None
+        self.solar_trust_pct = opts.get("solar_trust_pct",
+                                        dayplan.DEFAULT_TRUST_PCT)
+        self.solar_fc = None
+        self.solar_fc_why = (solarfc.NOT_SET if self.fc_entity is None
+                             else solarfc.MISSING)
+        self._fc_read_mono = None
+        self.day_plan = None
+        self._plan_targets = None
+        self.house_profile = None
+        if self.fc_entity is not None:
+            self.house_profile = dayplan.HouseProfile(
+                (getattr(store, "data", None) or {}).get(HOUSE_PROFILE_KEY))
         # OPT-11 P2: (topic, reason) of MQTT commands refused and logged once.
         self._mqtt_refused = set()
         self._mqtt_refused_more = 0
@@ -2082,10 +2108,14 @@ class Controller:
         plan = self.fresh_tariff_plan(now)
         if plan is None or not plan.has_prices:
             self.mode_runs, self._runs_key = None, None
+            self.day_plan = None
             return None
         slot = int(now.timestamp() // 900)
         key = (id(plan), slot, tuple((p.name, p.use, p.mode, p.sell)
                                      for p in packs))
+        if self.fc_entity is not None:
+            # P4: a forecast arriving or going rebuilds the plan at once.
+            key += (self.solar_fc is None,)
         if key != self._runs_key:
             done_c = self._run_done.get("charge", (None, set()))[1]
             done_s = self._run_done.get("sell", (None, set()))[1]
@@ -2103,6 +2133,9 @@ class Controller:
                 charge_kwh=e[0], charge_kw=e[1], sell_kwh=e[2],
                 sell_kw=e[3],
                 ref_eur_kwh=None if ref is None else ref.mean_eur_kwh)
+            if self.fc_entity is not None:
+                new = self._day_plan(now, packs, floor_pct, ceiling_pct,
+                                     new, plan, required, ref, done_c, e)
             self.mode_runs = priceruns.keep_started(self.mode_runs, new, now)
             self._runs_key = key
         runs = self.mode_runs
@@ -2117,6 +2150,42 @@ class Controller:
             self._ref_cheap = runs.cheap
         return runs
 
+    def _day_plan(self, now, packs, floor_pct, ceiling_pct, runs, plan,
+                  required, ref, done_c, e):
+        """OPT-11 P4: the day plan (`dayplan.plan()`) on the runs just made,
+        its levels held by the hysteresis (`dayplan.hold()`), then the runs
+        made again with each battery's shortfall as the charge, so the cheap
+        run is only as long as the shortfall needs. With no plan (no or stale
+        forecast, no house profile yet) the levels are dropped: P3 option A.
+        Returns the runs to keep."""
+        dp = dayplan.plan(
+            self.solar_fc,
+            None if self.house_profile is None
+            else self.house_profile.estimator(),
+            priceruns.keep_started(self.mode_runs, runs, now), now, packs,
+            trust_pct=self.solar_trust_pct, floor_pct=floor_pct,
+            ceiling_pct=ceiling_pct)
+        self.day_plan = dp
+        if dp is None:
+            self._plan_targets = None
+            return runs
+        self._plan_targets = dayplan.hold(
+            self._plan_targets, dp.targets,
+            {p.name: p.capacity_kwh for p in packs})
+        e2 = modetrade.energy(packs, floor_pct, ceiling_pct, done_c, (),
+                              targets=self._plan_targets)
+        return priceruns.plan(
+            plan.read.points, now, required_eur_kwh=required,
+            charge_kwh=e2[0], charge_kw=e2[1], sell_kwh=e[2], sell_kw=e[3],
+            ref_eur_kwh=None if ref is None else ref.mean_eur_kwh)
+
+    def plan_targets(self):
+        """P4: each battery's planned level, or None (no day plan). Dropped
+        at once when the forecast goes (stale or missing)."""
+        if self.solar_fc is None:
+            return None
+        return self._plan_targets
+
     def _mode_roles(self, now, maint_results):
         """OPT-11 P3: each battery's role and range this tick. Grid charging
         and selling need a fresh plan that `TariffPlan.arbitrage()` allows
@@ -2155,9 +2224,22 @@ class Controller:
                 price_now = None
         house = (None if self.grid is None or self.site_batt_w is None
                  else float(self.grid) + float(self.site_batt_w))
-        done_c = self._run_mark("charge", runs and runs.cheap, packs,
-                                lambda p: p.soc is not None
-                                and p.soc >= ceiling_pct)
+        if self.house_profile is not None and \
+                self.house_profile.add(now, house):
+            self.store.set(HOUSE_PROFILE_KEY, self.house_profile.dump())
+        targets = self.plan_targets()
+        if targets is None:
+            done_c = self._run_mark("charge", runs and runs.cheap, packs,
+                                    lambda p: p.soc is not None
+                                    and p.soc >= ceiling_pct)
+        else:
+            # P4: out of the run at its planned level. A level the
+            # hysteresis moved opens the run to it again (a new mark key).
+            def full(p):
+                to = modetrade.charge_to(p, ceiling_pct, targets)
+                return p.soc is not None and (to is None or p.soc >= to)
+            done_c = self._run_mark("charge", runs and runs.cheap, packs,
+                                    full, tuple(sorted(targets.items())))
         done_s = self._run_mark("sell", runs and runs.sell, packs,
                                 lambda p: p.soc is not None
                                 and p.soc <= floor_pct)
@@ -2170,7 +2252,7 @@ class Controller:
             headroom_w=self.arb_headroom_w, floor_pct=floor_pct,
             ceiling_pct=ceiling_pct, house_w=house, charging_now=was,
             blocked=self._charge_blocked_q == quarter,
-            done_charge=done_c, done_sell=done_s,
+            done_charge=done_c, done_sell=done_s, targets=targets,
             draining=any(r.phase == DRAIN for r in maint_results or ()))
         # A charge the guard or the headroom stopped stays off this period.
         if was and self.mode_tick.action != modetrade.CHARGE and \
@@ -2178,10 +2260,13 @@ class Controller:
             self._charge_blocked_q = quarter
         return self.mode_tick
 
-    def _run_mark(self, kind, run, packs, out) -> set:
+    def _run_mark(self, kind, run, packs, out, extra=None) -> set:
         """The batteries that left run `run` (full, or at the floor); they
-        stay out until it ends, so a level edge does not re-arm them."""
+        stay out until it ends, so a level edge does not re-arm them.
+        `extra` (P4: the planned levels) is part of the run's key."""
         key = None if not run else (run.start, run.end)
+        if key is not None and extra is not None:
+            key += (extra,)
         was_key, done = self._run_done.get(kind, (None, set()))
         if key != was_key:
             done = set()
@@ -2552,6 +2637,22 @@ class Controller:
         self.pv_w, self.pv_why, self.pv_parts = pv_read.total(
             list(zip(roster, states)), pv_read.inverted(self.o))
 
+    async def _read_forecast(self) -> None:
+        """OPT-11 P4: the solar forecast sensors (`solarfc.read()`). A
+        failed or stale read is no forecast, never a zero."""
+        today = await self.hass.state(self.fc_entity)
+        tomorrow = (await self.hass.state(self.fc_tomorrow_entity)
+                    if self.fc_tomorrow_entity else None)
+        now = datetime.now(timezone.utc)
+        fc, why = solarfc.read(today, tomorrow, now)
+        if (fc is None) != (self.solar_fc is None) or why != self.solar_fc_why:
+            self.log_event(
+                "solar forecast: " + ("read" if fc is not None else
+                                      f"none ({why})"),
+                hint=messages.hint("forecast_read" if fc is not None
+                                   else "forecast_none"))
+        self.solar_fc, self.solar_fc_why = fc, why
+
     async def read_inputs(self, now_mono: float | None = None) -> None:
         """Every input this cycle needs, and SAFETY-37's freshness verdict.
 
@@ -2603,6 +2704,14 @@ class Controller:
         _reads = [self._read_unit(inv, now_mono) for inv in self.inverters]
         if self.pv_roster:
             _reads.append(self._read_pv())
+        # OPT-11 P4: the solar forecast, in the same gather (a slow sensor
+        # must not delay control), at most once per FORECAST_READ_S.
+        if self.fc_entity is not None and (
+                self._fc_read_mono is None
+                or now_mono - self._fc_read_mono >= FORECAST_READ_S
+                or now_mono < self._fc_read_mono):
+            self._fc_read_mono = now_mono
+            _reads.append(self._read_forecast())
         await asyncio.gather(*_reads)
         if o.get("peak_forecast_entity"):
             raw = await self.hass.number(o["peak_forecast_entity"])

goodwe_controller/app/messages.py

@@ -906,6 +906,8 @@ HINTS = {
     "trade_charge": "Trading: charging while the price is low",
     "trade_give": "Trading: giving power while the price is high",
     "trade_off": "Trading: waiting for a better price",
+    "forecast_read": "Solar forecast read, the day plan uses it",
+    "forecast_none": "No solar forecast, so Leftover solar takes solar only",
     "split": "The power split between inverters changed",
     "clash": "Two limits clash, inverters set to 0 W",
     "no_setpoint": "An inverter has no “Setpoint entity”, inverters stay at 0 W",
@@ -1173,6 +1175,9 @@ LABELS = {
     "batt_entity": "Battery power entity",
     "pv_entity": "Solar production entity",
     "pv_entities": "Solar production entities, per inverter",
+    "pv_forecast_entity": "Solar forecast, today",
+    "pv_forecast_tomorrow_entity": "Solar forecast, tomorrow",
+    "solar_trust_pct": "Trust in the forecast",
     "p1_phase_import_entities": "Import entities per phase",
     "p1_phase_export_entities": "Export entities per phase",
 }

goodwe_controller/app/modetrade.py

@@ -23,7 +23,11 @@ Roles (the page's Why line names them):
 
 Rules that keep this safe (tests: test_modes_p3.py):
   * every range holds 0 W (a mode may forbid a direction, never force one);
-  * a Solar first battery never charges from the grid (no forecast yet, P4);
+  * a Solar first battery never charges from the grid;
+  * P4: with a day plan (`targets`), a Leftover solar battery charges from
+    the grid only up to its planned level, never above the ceiling; with
+    none it takes solar only (P3 option A). Cheap hours only fills to the
+    ceiling either way (`charge_to()`);
   * grid charging needs a measured peak guard that is clear and a measured
     headroom (SAFETY-45); the trade is sized to that headroom, whose aim is
     `peak_cap_w - peak_margin_w` (SAFETY-79). It starts only at START_W or
@@ -47,7 +51,7 @@ Rules that keep this safe (tests: test_modes_p3.py):
 from dataclasses import dataclass
 
 from .packmode import (CHEAP_HOURS, GRID_CHARGE_MODES, LEFTOVER_SOLAR,
-                       SOLAR_FIRST)
+                       PLAN_CHARGE_MODES, SOLAR_FIRST)
 
 OFF, HOUSE, HOLD, GIVE, SELL, CHARGE, REST = (
     "off", "house", "hold", "give", "sell", "charge", "rest")
@@ -90,13 +94,35 @@ def _room_kwh(p: Pack, pct: float) -> float:
     return max(0.0, abs(pct - p.soc)) / 100.0 * float(p.capacity_kwh)
 
 
-def chargers(packs, ceiling_pct, done=()) -> list:
-    """Batteries that may charge from the grid in a cheap run: the modes in
-    `packmode.GRID_CHARGE_MODES` (Cheap hours only until P4's forecast)."""
-    return [p for p in packs
-            if p.use and p.idle and p.live and p.mode in GRID_CHARGE_MODES
-            and p.soc is not None and p.soc < ceiling_pct
-            and p.refused >= 0 and p.name not in done]
+def charge_to(p: Pack, ceiling_pct, targets=None):
+    """The level this battery may charge to from the grid, or None.
+
+    `targets` is the day plan (`dayplan.plan()`: name -> level), or None
+    when there is none (no forecast, stale, or not configured). With no plan
+    this is P3 option A exactly: Cheap hours to the ceiling, the others never.
+    With a plan, a Leftover solar battery charges only to its planned level
+    (the sun fills the rest); a battery the plan leaves out, Cheap hours only
+    included, gets the no-plan answer. Solar first never charges."""
+    if p.mode in GRID_CHARGE_MODES:
+        return float(ceiling_pct)
+    if targets is None or p.name not in targets \
+            or p.mode not in PLAN_CHARGE_MODES:
+        return None
+    t = targets[p.name]
+    return None if t is None else min(float(ceiling_pct), float(t))
+
+
+def chargers(packs, ceiling_pct, done=(), targets=None) -> list:
+    """Batteries that may charge from the grid in a cheap run: below the
+    level `charge_to()` allows them (P4: the day plan's)."""
+    out = []
+    for p in packs:
+        to = charge_to(p, ceiling_pct, targets)
+        if (to is not None and p.use and p.idle and p.live
+                and p.soc is not None and p.soc < to
+                and p.refused >= 0 and p.name not in done):
+            out.append(p)
+    return out
 
 
 def sellers(packs, floor_pct, done=()) -> list:
@@ -108,11 +134,15 @@ def sellers(packs, floor_pct, done=()) -> list:
             and p.refused <= 0 and p.name not in done]
 
 
-def energy(packs, floor_pct, ceiling_pct, done_charge=(), done_sell=()):
-    """`(charge_kwh, charge_kw, sell_kwh, sell_kw)` for `priceruns.plan()`."""
-    ch = chargers(packs, ceiling_pct, done_charge)
+def energy(packs, floor_pct, ceiling_pct, done_charge=(), done_sell=(),
+           targets=None):
+    """`(charge_kwh, charge_kw, sell_kwh, sell_kw)` for `priceruns.plan()`.
+    With a day plan the charge is each battery's shortfall, so the cheap run
+    is only as long as the shortfall needs."""
+    ch = chargers(packs, ceiling_pct, done_charge, targets)
     se = sellers(packs, floor_pct, done_sell)
-    return (sum(_room_kwh(p, ceiling_pct) for p in ch),
+    return (sum(_room_kwh(p, charge_to(p, ceiling_pct, targets))
+                for p in ch),
             sum(abs(p.rating_w) for p in ch) / 1000.0,
             sum(_room_kwh(p, floor_pct) for p in se),
             sum(abs(p.rating_w) for p in se) / 1000.0)
@@ -121,7 +151,7 @@ def energy(packs, floor_pct, ceiling_pct, done_charge=(), done_sell=()):
 def decide(runs, now, packs, *, charge_ok, sell_ok, trade_why, price_now,
            headroom_w, floor_pct, ceiling_pct, house_w, charging_now=False,
            blocked=False, done_charge=(), done_sell=(),
-           draining=False) -> Tick:
+           targets=None, draining=False) -> Tick:
     """This tick's ranges, roles and site ask.
 
     `runs` is the kept `priceruns.RunPlan` or None (no fresh prices).
@@ -132,8 +162,9 @@ def decide(runs, now, packs, *, charge_ok, sell_ok, trade_why, price_now,
     `house_w` is the measured house (grid + batteries), or None.
     `charging_now` says last tick charged (then any headroom above 0 keeps
     it going); `blocked` that the guard or the headroom stopped a charge in
-    this 15-minute period. `draining` says a battery drains for its
-    monthly cycle, so none may charge from the grid (why "cycle").
+    this 15-minute period. `targets` is the day plan (`charge_to()`).
+    `draining` says a battery drains for its monthly cycle, so none may
+    charge from the grid (why "cycle").
     """
     plan_on = runs is not None and runs.on
     in_cheap = plan_on and runs.cheap.holds(now) and runs.charge_useful()
@@ -141,7 +172,8 @@ def decide(runs, now, packs, *, charge_ok, sell_ok, trade_why, price_now,
     in_sell = plan_on and runs.sell is not None and runs.sell.holds(now)
 
     why = None
-    ch = chargers(packs, ceiling_pct, done_charge) if in_cheap else []
+    ch = chargers(packs, ceiling_pct, done_charge, targets) if in_cheap \
+        else []
     if ch and draining:
         ch, why = [], "cycle"
     charging = False

goodwe_controller/app/packmode.py

@@ -46,10 +46,13 @@ SELL_KEY = "pack_sell"              # OPT-11 P3: sell in the sell run
 # refused; the sell code in modetrade/priceruns stays, unreachable.
 SELLING_ENABLED = False
 
-# The modes that may charge from the grid in a cheap run. Leftover solar joins
-# when the solar forecast exists (P4); until then it takes solar only (owner
-# decision 2026-09-29, option A).
+# The modes that may charge from the grid in a cheap run with no day plan.
+# Leftover solar takes solar only then (owner decision 2026-09-29, option A).
 GRID_CHARGE_MODES = (CHEAP_HOURS,)
+# OPT-11 P4: with a fresh solar forecast, the day plan (dayplan.py) lets
+# Leftover solar charge from the grid, by the shortfall only. Cheap hours only
+# ignores the plan (fills to the ceiling); Solar first never grid-charges.
+PLAN_CHARGE_MODES = (LEFTOVER_SOLAR,)
 
 
 def enabled(opts) -> bool:

goodwe_controller/app/solarfc.py

@@ -0,0 +1,254 @@
+"""OPT-11 P4: the solar forecast, read from a Home Assistant sensor.
+
+Pure: HA state dicts and the time in, a `Forecast` (or None and why) out.
+main.py reads the entities; dayplan.py uses the answer. FCST-01 replaces
+this later with the add-on's own forecast (owner answer, 2026-09-27).
+
+Two options name the sensors: `pv_forecast_entity`, the solar energy still
+to come TODAY, and `pv_forecast_tomorrow_entity`, TOMORROW's (optional; it
+is only needed for a cheap run before midnight). Supported, by the entities
+they create (DOCS.md lists them):
+
+* Forecast.Solar (HA core): `sensor.energy_production_today_remaining` and
+  `sensor.energy_production_tomorrow`. The state only; no hourly split.
+* Solcast PV Forecast (HACS `solcast_solar`):
+  `sensor.solcast_pv_forecast_forecast_remaining_today` and
+  `..._forecast_tomorrow`, with `detailedForecast` (or `detailedHourly`):
+  `[{period_start, pv_estimate}]`, kW per period.
+* Open-Meteo Solar Forecast (HACS `open_meteo_solar_forecast`):
+  `sensor.energy_production_today_remaining` / `..._tomorrow`, with
+  `wh_period`: `{period start: Wh}`.
+
+Any other sensor whose state is energy in Wh, kWh or MWh works too, as a
+state only. The unit is read, never guessed (the rule `pv.watts()` has).
+Without an hourly split, the day's energy is spread over a fixed bell from
+06:00 to 20:00 local time (`BELL_FROM_H`, `BELL_TO_H`).
+
+A reading older than `FRESH_S`, or from before local midnight, is stale,
+and a stale or missing forecast is no forecast: the day plan is off and
+every mode acts as in P3 option A.
+"""
+
+import math
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+
+from .hass import BAD_STATES
+from .tariff import BILLING_TZ
+
+KWH_PER = {"Wh": 0.001, "kWh": 1.0, "MWh": 1000.0}
+
+# Stale after 3 h. The integrations above refresh at least hourly, so a
+# 2 h limit would flag a site whose hourly poll was missed once.
+FRESH_S = 3 * 3600.0
+
+# The bell a state-only forecast is spread over, in local hours.
+BELL_FROM_H, BELL_TO_H = 6.0, 20.0
+
+# Why there is no forecast (the page words are in ui_text `home_words`).
+NOT_SET, MISSING, UNIT, STALE, BAD = (
+    "not_set", "missing", "unit", "stale", "bad")
+
+
+@dataclass(frozen=True)
+class Day:
+    """One day's forecast: `kwh` still to come (today) or in all (tomorrow),
+    and the hourly split if the sensor has one: `((start, end, kwh), ...)`."""
+    day0: datetime              # local midnight, as UTC
+    kwh: float
+    periods: tuple = ()
+
+
+@dataclass(frozen=True)
+class Forecast:
+    today: Day
+    tomorrow: Day | None
+    at: datetime                # when the sensor last reported
+
+    def between(self, t0: datetime, t1: datetime) -> float | None:
+        """kWh the sun should give between `t0` (now or later) and `t1`.
+        None when the span reaches the sunny hours of a day with no
+        forecast (tomorrow, when its sensor is not set)."""
+        if t1 <= t0:
+            return 0.0
+        last = self.tomorrow or self.today
+        if t1 > last.day0 + timedelta(days=1, hours=BELL_FROM_H):
+            return None
+        total = 0.0
+        for day in (self.today, self.tomorrow):
+            if day is None:
+                continue
+            a = max(t0, day.day0)
+            b = min(t1, day.day0 + timedelta(days=1))
+            if b > a:
+                total += _day_between(day, a, b, t0)
+        return total
+
+
+def _local_hour(t: datetime) -> float:
+    lt = t.astimezone(BILLING_TZ)
+    return lt.hour + lt.minute / 60.0 + lt.second / 3600.0
+
+
+def _bell(h: float) -> float:
+    """Cumulative share of a day's sun by local hour `h` (0..1)."""
+    if h <= BELL_FROM_H:
+        return 0.0
+    if h >= BELL_TO_H:
+        return 1.0
+    x = (h - BELL_FROM_H) / (BELL_TO_H - BELL_FROM_H)
+    return (1.0 - math.cos(math.pi * x)) / 2.0
+
+
+def _hours_since(day0, t):
+    return (t - day0).total_seconds() / 3600.0
+
+
+def _day_between(day: Day, a: datetime, b: datetime, now: datetime) -> float:
+    if day.periods:
+        out = 0.0
+        for s, e, kwh in day.periods:
+            lo, hi = max(a, s), min(b, e)
+            if hi > lo:
+                out += kwh * (hi - lo).total_seconds() / (e - s).total_seconds()
+        return out
+    # State only: `kwh` is what is left from `max(now, day0)` to the day's
+    # end, spread over the bell.
+    h_from = _hours_since(day.day0, max(now, day.day0))
+    left = 1.0 - _bell(h_from)
+    if left <= 1e-9:
+        return 0.0
+    share = (_bell(_hours_since(day.day0, b))
+             - _bell(_hours_since(day.day0, a))) / left
+    return day.kwh * max(0.0, share)
+
+
+def _parse_time(v):
+    try:
+        t = datetime.fromisoformat(str(v).replace("Z", "+00:00"))
+    except (TypeError, ValueError):
+        return None
+    return t if t.tzinfo else t.replace(tzinfo=timezone.utc)
+
+
+def _periods(attrs: dict, day0: datetime) -> tuple:
+    """The hourly split, if the sensor has one, for the day at `day0`."""
+    d1 = day0 + timedelta(days=1)
+    out = []
+    for key in ("detailedForecast", "detailedHourly"):
+        rows = attrs.get(key)
+        if isinstance(rows, list) and rows:
+            starts = []
+            for r in rows:
+                if not isinstance(r, dict):
+                    continue
+                t = _parse_time(r.get("period_start"))
+                try:
+                    kw = float(r.get("pv_estimate"))
+                except (TypeError, ValueError):
+                    continue
+                if t is not None and math.isfinite(kw) and kw >= 0:
+                    starts.append((t, kw))
+            starts.sort()
+            for i, (t, kw) in enumerate(starts):
+                step = (starts[i + 1][0] - t if i + 1 < len(starts)
+                        else timedelta(minutes=30 if key ==
+                                       "detailedForecast" else 60))
+                if step <= timedelta(0) or step > timedelta(hours=1):
+                    step = timedelta(minutes=30 if key == "detailedForecast"
+                                     else 60)
+                if day0 <= t < d1:
+                    out.append((t, t + step,
+                                kw * step.total_seconds() / 3600.0))
+            if out:
+                return tuple(out)
+    wh = attrs.get("wh_period")
+    if isinstance(wh, dict) and wh:
+        rows = []
+        for k, v in wh.items():
+            t = _parse_time(k)
+            try:
+                e = float(v)
+            except (TypeError, ValueError):
+                continue
+            if t is not None and math.isfinite(e) and e >= 0:
+                rows.append((t, e / 1000.0))
+        rows.sort()
+        for i, (t, kwh) in enumerate(rows):
+            nxt = rows[i + 1][0] if i + 1 < len(rows) else t + timedelta(
+                hours=1)
+            if nxt - t > timedelta(hours=1) or nxt <= t:
+                nxt = t + timedelta(hours=1)
+            if day0 <= t < d1:
+                out.append((t, nxt, kwh))
+    return tuple(out)
+
+
+def _day(state, day0, now, *, today):
+    """`(Day, None)` or `(None, why)` from one sensor's state dict."""
+    if state is None:
+        return None, MISSING
+    raw = str(state.get("state", "")).strip()
+    if raw.lower() in BAD_STATES:
+        return None, MISSING
+    try:
+        v = float(raw)
+    except ValueError:
+        return None, BAD
+    attrs = state.get("attributes") or {}
+    unit = str(attrs.get("unit_of_measurement") or "").strip()
+    if unit not in KWH_PER:
+        return None, UNIT
+    kwh = v * KWH_PER[unit]
+    if not math.isfinite(kwh) or kwh < 0:
+        return None, BAD
+    periods = _periods(attrs, day0)
+    if periods and today:
+        # The split is the whole day; keep what is still to come, scaled so
+        # it adds up to the state (the state is what the integration says
+        # is left).
+        left = sum(k * max(0.0, min(1.0, (e - max(s, now)).total_seconds()
+                                    / (e - s).total_seconds()))
+                   for s, e, k in periods)
+        if left > 1e-6:
+            f = kwh / left
+            periods = tuple((s, e, k * f) for s, e, k in periods)
+    return Day(day0, kwh, periods), None
+
+
+def _reported(state):
+    ts = [_parse_time(state.get(k)) for k in
+          ("last_reported", "last_updated", "last_changed")]
+    ts = [t for t in ts if t is not None]
+    return max(ts) if ts else None
+
+
+def read(today_state, tomorrow_state, now: datetime, *,
+         configured=True):
+    """`(Forecast, None)` or `(None, why)`. `tomorrow_state` may be None
+    (the option is not set, or the sensor is missing): the forecast then
+    covers today only."""
+    if not configured:
+        return None, NOT_SET
+    here = now.astimezone(BILLING_TZ)
+    d0 = datetime(here.year, here.month, here.day, tzinfo=BILLING_TZ)
+    nd = d0.date() + timedelta(days=1)
+    d1 = datetime(nd.year, nd.month, nd.day, tzinfo=BILLING_TZ)
+    day0, day1 = d0.astimezone(timezone.utc), d1.astimezone(timezone.utc)
+    today, why = _day(today_state, day0, now, today=True)
+    if today is None:
+        return None, why
+    at = _reported(today_state)
+    # A reading from before local midnight is yesterday's "left today" (0
+    # after sunset) until the integration refreshes: stale, not a dark day.
+    if at is None or at < day0 or (now - at).total_seconds() > FRESH_S \
+            or (at - now).total_seconds() > 300:
+        return None, STALE
+    tomorrow = None
+    if tomorrow_state is not None:
+        t, _w = _day(tomorrow_state, day1, now, today=False)
+        t_at = _reported(tomorrow_state)
+        if t is not None and t_at is not None and t_at >= day0 \
+                and (now - t_at).total_seconds() <= FRESH_S:
+            tomorrow = t
+    return Forecast(today, tomorrow, at), None

goodwe_controller/app/static/app.js

@@ -403,6 +403,9 @@
     else $("#batt-banner").replaceChildren();
     keepFocus(() => {
       $("#bcards").replaceChildren(...S.batteries.map(batteryCard));
+      // OPT-11 P4: the solar forecast line under the cards.
+      const sl = $("#batt-solar"), line = modes && S.solar ? S.solar.line : "";
+      if (sl) { sl.textContent = line || ""; sl.hidden = !line; }
       if (simpleHost && simpleHost.isConnected) {
         simpleHost.replaceChildren(...(modes ? S.batteries.map(simpleRow)
           : [h("p", { class: "small muted", style: "margin:4px 0" }, t("batteries.modes_off.name") + ". " + t("batteries.description"))]));

goodwe_controller/app/static/index.html

@@ -101,6 +101,7 @@
     <a class="btn" href="#settings" data-t="batteries.settings"></a>
   </div>
   <div id="bcards"></div>
+  <p class="small muted" id="batt-solar" hidden></p>
   <details class="grp" id="batt-how" hidden>
     <summary><span class="grow"><strong data-t="batteries.how.name"></strong><span class="small muted gdesc" data-t="batteries.how.description"></span></span><span class="chev" aria-hidden="true">&#8250;</span></summary>
     <div class="body small">

goodwe_controller/app/static/settings.js

@@ -446,7 +446,17 @@
       e.textContent = ok ? e.dataset.kwNote.replace("{kw}", window.UX13.kw(mp.peak_w) + " kW") : "";
     });
   }
+  // OPT-11 P4: the solar forecast card shows the add-on's forecast line.
+  function fillSolar() {
+    const st = window.UX13.status();
+    const line = st && st.solar ? st.solar.line : "";
+    document.querySelectorAll("#simple [data-solar-note]").forEach((e) => {
+      e.textContent = line || "";
+      e.hidden = !line;
+    });
+  }
   document.addEventListener("ux13:status", fillNotes);
+  document.addEventListener("ux13:status", fillSolar);
   function simpleField(f) {
     const row = fieldRow(f, null, "simple");
     row.querySelector(".head").append(chip(f.applies));
@@ -458,6 +468,7 @@
       const help = row.querySelector(".help");
       if (help) help.textContent = n.description;
     }
+    if (f.note === "forecast") row.append(h("div", { class: "small muted", "data-solar-note": "", hidden: true }));
     return h("div", { class: "card" }, row);
   }
   function renderSimple() {

goodwe_controller/app/ui_text/en.json

@@ -119,7 +119,7 @@
     "description": "Every setting, grouped by task.",
     "view": {"name": "Settings view", "simple": "Simple", "installer": "Installer"},
     "simple": {"description": "The choices a home owner makes.",
-      "note": {"month_peak": {"description": "This month's peak so far: {kw}."}, "shadow": {"description": "Use Always on while you test a new installation."}},
+      "note": {"month_peak": {"description": "This month's peak so far: {kw}."}, "shadow": {"description": "Use Always on while you test a new installation."}, "forecast": {"description": "With a forecast, a battery buys only what the sun will not give."}},
       "batteries": {"name": "Batteries"},
       "more": {"description": "Looking for the meter, inverters or prices?"},
       "installer": "Open the installer view"},
@@ -335,8 +335,12 @@
       "saves": "Saves its power for {at}.",
       "saves_later": "Saves its power for higher prices.",
       "no_prices": "No prices, so it follows the house.",
-      "no_spread": "Prices differ too little, so it follows the house."
+      "no_spread": "Prices differ too little, so it follows the house.",
+      "sun_fills": "Enough sun is forecast, so it does not charge from the grid.",
+      "tops_up": "Too little sun is forecast, so it charges some from the grid.",
+      "no_forecast": "No solar forecast, so it charges from solar only."
     },
+    "solar": {"line": "Solar still to come today: {kwh}, we count on {count}. Updated {at}.", "no_forecast": "No solar forecast now, so Leftover solar charges from solar only.", "learning": "The add-on is learning your house's use. The plan starts after one full day."},
     "today": {
       "not_planned": "Not planned yet.",
       "no_runs": "No cheap or expensive hours left today.",

goodwe_controller/app/ui_text/nl.json

@@ -114,7 +114,7 @@
     "description": "Elke instelling, per taak.",
     "view": {"name": "Weergave van de instellingen", "simple": "Eenvoudig", "installer": "Installateur"},
     "simple": {"description": "De keuzes die een eigenaar maakt.",
-      "note": {"month_peak": {"description": "De piek van deze maand tot nu: {kw}."}, "shadow": {"description": "Kies Altijd aan terwijl u een nieuwe installatie test."}},
+      "note": {"month_peak": {"description": "De piek van deze maand tot nu: {kw}."}, "shadow": {"description": "Kies Altijd aan terwijl u een nieuwe installatie test."}, "forecast": {"description": "Met een prognose koopt een batterij alleen wat de zon niet geeft."}},
       "batteries": {"name": "Batterijen"},
       "more": {"description": "Zoekt u de meter, de omvormers of de prijzen?"},
       "installer": "De installateursweergave openen"},
@@ -277,8 +277,12 @@
       "saves": "Spaart haar stroom voor {at}.",
       "saves_later": "Spaart haar stroom voor hogere prijzen.",
       "no_prices": "Geen prijzen, dus ze volgt het huis.",
-      "no_spread": "De prijzen verschillen te weinig, dus ze volgt het huis."
+      "no_spread": "De prijzen verschillen te weinig, dus ze volgt het huis.",
+      "sun_fills": "Er is genoeg zon voorspeld, dus ze laadt niet van het net.",
+      "tops_up": "Te weinig zon voorspeld, dus ze laadt wat van het net.",
+      "no_forecast": "Geen zonneprognose, dus ze laadt alleen met zonne-energie."
     },
+    "solar": {"line": "Nog verwachte zon vandaag: {kwh}, we rekenen op {count}. Bijgewerkt om {at}.", "no_forecast": "Nu geen zonneprognose, dus Overschot zonne-energie laadt alleen met zon.", "learning": "De add-on leert eerst het verbruik van uw huis. Het plan start na één volle dag."},
     "today": {
       "not_planned": "Nog niet gepland.",
       "no_runs": "Vandaag geen goedkope of dure uren meer.",

goodwe_controller/app/uilayout.py

@@ -129,7 +129,14 @@ GROUPS = (
                              wizard=3),)),
         # OPT-11: the switch that turns battery modes on. Each battery's mode
         # and on/off switch are runtime state on the Batteries screen.
-        Part("modes", (Field("battery_modes_enabled", TOGGLE),)),
+        Part("modes", (
+            Field("battery_modes_enabled", TOGGLE),
+            # OPT-11 P4: the solar forecast; today's also on Settings, Simple.
+            Field("pv_forecast_entity", ENTITY, kind="energy", simple=True,
+                  note="forecast"),
+            Field("pv_forecast_tomorrow_entity", ENTITY, kind="energy"),
+            Field("solar_trust_pct", SLIDER, "%", step=5),
+        )),
     )),
     Group("tariff", (
         Part("", (

goodwe_controller/app/validate.py

@@ -246,6 +246,10 @@ NOT READY banner already names the problem, (b) does not apply.
  12. `peak_margin_w` outside 0-500 W, not whole, or not below `peak_cap_w`.
      SAFETY-79; the Supervisor checks the range too, but not for sim/inject.py.
 
+ 13. OPT-11 P4: `solar_trust_pct` outside 30-100 or not whole, or a solar
+     forecast entity that is not a `sensor.` id. A trust of 0 or 500 % would
+     make the day plan buy everything or nothing, which no one means.
+
 WHAT IS DELIBERATELY *NOT* REFUSED, because it is untidy rather than unsafe:
 
   - `integrator_max_w` above `max_w`. DOCS.md is right that the only thing the
@@ -324,9 +328,10 @@ WHAT IS DELIBERATELY *NOT* REFUSED, because it is untidy rather than unsafe:
 """
 
 import logging
+import re
 from typing import NamedTuple
 
-from . import messages, pv
+from . import dayplan, messages, pv, solarfc
 from .arbitrage import enabled as arbitrage_on
 from .control import SLEW_RAIL_FRAC, LOOP_TICK_S, PLANT_SETTLE_S
 from .custom_formula import (
@@ -1199,6 +1204,7 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None,
 
     # --- 12. SAFETY-79: the margin the peak guard keeps under the limit -----
     problems += _margin_problems(opts)
+    problems += _forecast_problems(opts)
 
     # --- warnings: real, but not worth refusing over -------------------------
     integ = opts.get("integrator_max_w")
@@ -1751,6 +1757,8 @@ def _entities_read(opts: dict) -> list[tuple[str, str, str]]:
     add("pv_entities" if solar else "pv_entity", list(pv.entities(opts)))
     for key in ("peak_forecast_entity", "price_now_entity", "price_avg_entity"):
         add(key, opts.get(key))
+    for key in FORECAST_KEYS:
+        add(key, opts.get(key))
     return out
 
 
@@ -1790,6 +1798,19 @@ def _entity_notes(notes, opts: dict, entities: dict, bad=()) -> None:
             _advise(notes, "warn", (key,),
                     f"{entity} reads in {unit}, but {S(key, where)} is "
                     "taken as watts, so pick a sensor in W.")
+        if key in FORECAST_KEYS and unit not in solarfc.KWH_PER:
+            _advise(notes, "warn", (key,),
+                    f"{entity} does not read in kWh, so pick a solar "
+                    "forecast sensor in kWh.")
+    if any(opts.get(k) for k in FORECAST_KEYS) and \
+            opts.get("battery_modes_enabled") is not True:
+        _advise(notes, "info", ("pv_forecast_entity",),
+                "The solar forecast is used only with battery modes on.")
+    if opts.get("pv_forecast_tomorrow_entity") and \
+            not opts.get("pv_forecast_entity"):
+        _advise(notes, "warn", ("pv_forecast_tomorrow_entity",),
+                "Tomorrow's forecast is used only with today's, so set "
+                f"{S('pv_forecast_entity')} too.")
 
 
 # --------------------------------------------------------------------------- #
@@ -2045,6 +2066,33 @@ def _margin_problems(opts: dict) -> list[str]:
     return []
 
 
+TRUST_RANGE_PCT = (30, 100)
+# A Home Assistant sensor id; it goes into the /api/states/<id> path.
+_SENSOR_ID = re.compile(r"sensor\.[a-z0-9_]+")
+FORECAST_KEYS = ("pv_forecast_entity", "pv_forecast_tomorrow_entity")
+
+
+def _forecast_problems(opts: dict) -> list[str]:
+    """Rule 13 (OPT-11 P4): the trust is a whole percentage in range, and
+    each forecast entity set is a sensor."""
+    out = []
+    raw = opts.get("solar_trust_pct")
+    trust = _number(opts, "solar_trust_pct", dayplan.DEFAULT_TRUST_PCT)
+    lo, hi = TRUST_RANGE_PCT
+    if trust is None or trust != int(trust) or not lo <= trust <= hi:
+        out.append(f"{S('solar_trust_pct')} must be a whole number from {lo} "
+                   f"to {hi} %. It is {messages.shown(raw)}.")
+    for key in FORECAST_KEYS:
+        e = opts.get(key)
+        if e is None or e == "":
+            continue
+        if not isinstance(e, str) or not _SENSOR_ID.fullmatch(e):
+            out.append(f"{S(key)} must be a sensor, like "
+                       f"sensor.energy_production_today_remaining. It is "
+                       f"{messages.shown(e)}.")
+    return out
+
+
 def _number(opts: dict, key, default):
     raw = opts.get(key, default)
     if raw is None or raw == "":