Device reason 'battery would not last' names when it would be empty (v3.1.21)

User 11.10.: the battery line said 6.8 h left, PV start in 5.2 h, yet the
miner stayed off. The reason now says when the battery would hit its reserve
with the device (same load as the rule: learned night base + devices) and
until when it must last (solar start + 1 h).

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

Author: xchillxx

custom_components/surplus_pilot/coordinator.py

@@ -930,6 +930,11 @@ def explain(self) -> list[str]:
             if not dec.on and fp.get("start") is not None and fp.get("need_h", 0) > 0:
                 extra += (f" — Mindestlaufzeit: fehlen {fp['need_h']:.1f} h, Pflichtlauf ab "
                           f"{dt_util.as_local(fp['start']).strftime('%H:%M')}").replace(".", ",")
+            if dec.battery_empty is not None:
+                need = dt_util.as_local(dt_util.parse_datetime(d["solar_start"])) + timedelta(
+                    hours=P.BATTERY_PATH_BUFFER_H)
+                extra += (f" (damit leer ~{dt_util.as_local(dec.battery_empty).strftime('%H:%M')}, "
+                          f"nötig bis {need.strftime('%H:%M')})")
             lines.append(f"{names.get(did, did)}: {'an' if dec.on else 'aus'} — "
                          f"{REASON_TEXT.get(dec.reason, dec.reason)}{extra}")
         return lines

custom_components/surplus_pilot/manifest.json

@@ -9,5 +9,5 @@
   "iot_class": "local_polling",
   "issue_tracker": "https://github.com/xchillxx/surplus-pilot/issues",
   "requirements": [],
-  "version": "3.1.20"
+  "version": "3.1.21"
 }

custom_components/surplus_pilot/planner.py

@@ -157,6 +157,7 @@ class DeviceDecision:
     on: bool
     reason: str
     path: str = ""   # "ueberschuss" | "akku" | "pflicht" | ""
+    battery_empty: datetime | None = None   # akku_reicht_nicht: home battery at its reserve with this device
 
 
 @dataclass
@@ -336,6 +337,25 @@ def battery_lasts(inp: Inputs, planned_on: dict[str, bool], extra: DeviceInput |
     return avail >= load
 
 
+def battery_empty_at(inp: Inputs, planned_on: dict[str, bool], extra: DeviceInput) -> datetime | None:
+    """When the home battery would reach its reserve with the same load as
+    battery_lasts (night base load + planned devices + this one, each until
+    its window end) - the reason's "why" in one time."""
+    if inp.battery_soc is None:
+        return None
+    left = max(0.0, (inp.battery_soc - inp.battery_min_soc) / 100.0 * inp.battery_capacity_kwh)
+    devs = [d for d in inp.devices if planned_on.get(d.id) or d.id == extra.id]
+    t, step = inp.now, timedelta(minutes=5)
+    for _ in range(24 * 12):
+        kw = inp.night_base_kw + sum(d.decision_kw for d in devs if d.window_end is None or d.window_end > t)
+        use = kw * step.total_seconds() / 3600.0
+        if use >= left:
+            return t + step * (left / use)
+        left -= use
+        t += step
+    return None
+
+
 def _hours(inp: Inputs, t: datetime) -> float:
     return (t - inp.now).total_seconds() / 3600.0
 
@@ -874,7 +894,8 @@ def _devices(inp: Inputs, remaining: float,
             reason = "kein_ueberschuss"
         else:
             reason = "akku_reicht_nicht"
-        out[d.id] = DeviceDecision(False, reason)
+        empty = battery_empty_at(inp, planned, d) if reason == "akku_reicht_nicht" else None
+        out[d.id] = DeviceDecision(False, reason, battery_empty=empty)
     return out
 
 

custom_components/surplus_pilot/sensor.py

@@ -224,6 +224,7 @@ def extra_state_attributes(self):
             "mindestlauf_ab": co.forced_run_start(did),
             "leistung_kw": co._decision_kw(self._dev),
             "name": self._dev.get(CONF_DEV_NAME),
+            "akku_leer_um": dec.battery_empty.isoformat() if dec and dec.battery_empty else None,
         }
 
 

dashboards/surplus-pilot.yaml

@@ -138,7 +138,7 @@ views:
             content: |
               | Device | | Reason | Runtime today | Power |
               |---|---|---|---|---|
-              {% for e in integration_entities('surplus_pilot') | sort if e.startswith('sensor.') and state_attr(e, 'laufzeit_heute_h') is not none %}{% set a = states[e].attributes %}| **{{ a.name }}** | {{ '🟢 on' if a.an else '⚪ off' }}{% if a.schaltet_in_s %} → {{ 'on' if a.soll_an else 'off' }} in {{ (a.schaltet_in_s / 60) | round(0) | int }} min{% endif %} | {{ state_translated(e) }} | {{ a.laufzeit_heute_h | round(1) }} h | {{ a.leistung_kw | round(2) }} kW |
+              {% for e in integration_entities('surplus_pilot') | sort if e.startswith('sensor.') and state_attr(e, 'laufzeit_heute_h') is not none %}{% set a = states[e].attributes %}| **{{ a.name }}** | {{ '🟢 on' if a.an else '⚪ off' }}{% if a.schaltet_in_s %} → {{ 'on' if a.soll_an else 'off' }} in {{ (a.schaltet_in_s / 60) | round(0) | int }} min{% endif %} | {{ state_translated(e) }}{% if a.akku_leer_um %} · empty ~{{ (as_datetime(a.akku_leer_um) | as_local).strftime('%H:%M') }}{% endif %} | {{ a.laufzeit_heute_h | round(1) }} h | {{ a.leistung_kw | round(2) }} kW |
               {% endfor %}
           # one tile per device: Off = Surplus Pilot leaves the device alone
           - type: tile

tests/test_planner.py

@@ -517,3 +517,16 @@ def test_charge_windows_show_the_planned_grid_charging_ahead():
     # target already reached -> nothing planned
     car.soc = 55.0
     assert P.charge_windows(base_inputs(now, car=car, departures=[dep], prices=prices)) == []
+
+
+def test_battery_reason_names_when_the_battery_would_be_empty():
+    """11.10. live 03:56: battery 31 %, 13.8 kWh, night base 0.39 kW, miner
+    0.142 kW -> 2.2 kWh / 0.53 kW: empty ~08:06, needed until 10:09."""
+    now = datetime(2026, 10, 11, 3, 56, tzinfo=TZ)
+    m = miner()
+    m.decision_kw = 0.142
+    plan = P.make_plan(base_inputs(now, battery_soc=31.0, battery_capacity_kwh=13.8, night_base_kw=0.39,
+                                   devices=[m]))
+    dec = plan.devices["miner"]
+    assert dec.reason == "akku_reicht_nicht"
+    assert abs((dec.battery_empty - now.replace(hour=8, minute=5)).total_seconds()) < 5 * 60