fix(gateway): write entities for the bound control target, not just primary units (#4360)

On a multi-AIO site automatic_config picks the Gateway/EMS as the control target
and binds every PredBat arg to its serial suffix. _inject_entities only ever
wrote entities for units flagged primary — and firmware never flags a Gateway or
EMS primary — so none of the bound entities were written. They held whatever
value they had and silently froze.

Observed in production: a site froze for 69 minutes with byte-identical SoC,
battery power, grid power, load power and PV power, while PredBat continued to
plan and issue control against a stale 76% SoC. The only escaping symptom was the
clock-skew warning, because inverter_time is the one bound value whose staleness
is self-evident against wall clock — which sends users to fix an inverter clock
that is not broken.

Inject a unit when it is primary OR when automatic_config bound args to it
(tracked in _suffix_to_serial), and write inverter_time under the bound suffix
rather than the primary's. Non-primary units that are not the control target stay
skipped, preserving the existing guard against double-counted power readings.

Adds TestBoundEntitiesAreWritten, which asserts the invariant directly: every
entity automatic_config binds must actually be written by _inject_entities.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: mgazza

apps/predbat/gateway.py

@@ -59,6 +59,21 @@
 _GATEWAY_OPTIONS_TIME = [(_GATEWAY_BASE_TIME + datetime.timedelta(seconds=m * 60)).strftime("%H:%M:%S") for m in range(0, 24 * 60, 5)]
 
 
+def _serial_suffix(serial):
+    """Return the entity-name suffix for an inverter serial.
+
+    Entity IDs use the last six characters of the serial, lower-cased; serials of
+    six characters or fewer are used whole.
+
+    Args:
+        serial: Inverter serial string.
+
+    Returns:
+        str: The lower-cased suffix used in gateway entity IDs.
+    """
+    return serial[-6:].lower() if len(serial) > 6 else serial.lower()
+
+
 PLAN_MODE_AUTO = 0
 PLAN_MODE_CHARGE = 1
 PLAN_MODE_DISCHARGE = 2
@@ -719,6 +734,22 @@ def _process_telemetry(self, data):
         if self._needs_reconfigure(status):
             self.automatic_config()
 
+    def _is_bound_target(self, inv):
+        """Whether automatic_config bound PredBat's args to this inverter's suffix.
+
+        ``_suffix_to_serial`` is populated by ``automatic_config`` with exactly the
+        control-target suffixes, so it is the authoritative record of which entities
+        PredBat reads. Empty before the first auto-config, in which case no unit is
+        bound yet and the primary-only path applies.
+
+        Args:
+            inv: A ``predbat_InverterEntry`` from the gateway status.
+
+        Returns:
+            bool: True if this unit's entities are read by PredBat.
+        """
+        return _serial_suffix(inv.serial) in self._suffix_to_serial
+
     def _inject_entities(self, status):
         """Inject inverter entities into PredBat state cache.
 
@@ -735,10 +766,14 @@ def _inject_entities(self, status):
             app="gateway",
         )
 
-        # Inverter time from gateway timestamp — use first primary inverter's serial
+        # Inverter time from gateway timestamp — write it under the suffix PredBat
+        # actually reads (the control target), not the primary's, or the bound
+        # inverter_time arg is never updated and silently freezes.
         if status.timestamp > 0 and len(status.inverters) > 0:
-            primary_inv = next((inv for inv in status.inverters if inv.primary), status.inverters[0])
-            ts_suffix = primary_inv.serial[-6:].lower() if len(primary_inv.serial) > 6 else primary_inv.serial.lower()
+            ts_inv = next((inv for inv in status.inverters if self._is_bound_target(inv)), None)
+            if ts_inv is None:
+                ts_inv = next((inv for inv in status.inverters if inv.primary), status.inverters[0])
+            ts_suffix = _serial_suffix(ts_inv.serial)
             dt = datetime.datetime.fromtimestamp(status.timestamp, tz=self.local_tz)
             self.dashboard_item(
                 f"sensor.{self.prefix}_gateway_{ts_suffix}_inverter_time",
@@ -748,12 +783,15 @@ def _inject_entities(self, status):
             )
 
         for inv in status.inverters:
-            # Skip non-primary inverters — EMS/gateway units report overlapping
-            # power readings that would cause doubled values on the dashboard.
-            if not inv.primary:
+            # Inject primary (battery-bearing) units, plus whichever unit automatic_config
+            # bound PredBat's args to. On a multi-AIO site the control target is the
+            # Gateway/EMS, which firmware never flags primary — skipping it left every
+            # bound arg unwritten and frozen at its last value. Non-primary units that are
+            # NOT the control target stay skipped: they report overlapping power readings
+            # that would double up on the dashboard.
+            if not inv.primary and not self._is_bound_target(inv):
                 continue
-            suffix = inv.serial[-6:].lower() if len(inv.serial) > 6 else inv.serial.lower()
-            self._inject_inverter_entities(inv, suffix)
+            self._inject_inverter_entities(inv, _serial_suffix(inv.serial))
 
         # EV charger entities (device-level, present only when a charge point is connected)
         self._inject_ev_entities(status)

apps/predbat/tests/test_gateway.py

@@ -1,6 +1,7 @@
 """
 Tests for GatewayMQTT component.
 """
+
 import sys
 import os
 import math
@@ -291,6 +292,7 @@ def _make_gateway(self):
         gw._last_status = None
         gw.args = {}
         gw.local_tz = pytz.timezone("Europe/London")
+        gw._suffix_to_serial = {}  # set by automatic_config; empty = nothing bound yet
         gw._dashboard_calls = {}  # entity_id → (state, attributes)
 
         def capture_dashboard(entity_id, state=None, attributes=None, app=None):
@@ -673,6 +675,97 @@ def test_inverter_rate_max_uses_6000_when_both_zero(self):
         assert state == 6000
 
 
+class TestBoundEntitiesAreWritten:
+    """Every entity automatic_config() binds must actually be written by _inject_entities().
+
+    A bound-but-never-written entity holds whatever value it last had and silently
+    freezes — surfacing only as PredBat's clock-skew warning once the stale
+    inverter_time drifts past the threshold.
+    """
+
+    def _make_gateway(self):
+        from gateway import GatewayMQTT
+        from unittest.mock import MagicMock
+
+        gw = GatewayMQTT.__new__(GatewayMQTT)
+        gw.base = MagicMock()
+        gw.log = MagicMock()
+        gw.prefix = "predbat"
+        gw._last_status = None
+        gw._auto_configured = False
+        gw._suffix_to_serial = {}
+        gw.args = {}
+        gw._args = {}
+        gw.local_tz = pytz.timezone("Europe/London")
+        gw.gateway_inverter_serial = []
+        gw.gateway_evc_automatic = False
+        gw.gateway_evc_control = False
+        gw._dashboard_calls = {}
+
+        def capture_set_arg(key, value):
+            gw._args[key] = value
+
+        def capture_dashboard(entity_id, state=None, attributes=None, app=None):
+            gw._dashboard_calls[entity_id] = (state, attributes)
+
+        gw.set_arg = capture_set_arg
+        gw.dashboard_item = capture_dashboard
+        return gw
+
+    def _add_inverter(self, status, serial, primary, inv_type=None):
+        inv = status.inverters.add()
+        inv.type = inv_type if inv_type is not None else pb.INVERTER_TYPE_GIVENERGY
+        inv.serial = serial
+        inv.primary = primary
+        inv.connected = True
+        inv.active = True
+        inv.battery.soc_percent = 50
+        inv.battery.capacity_wh = 9500
+        inv.battery.rate_max_w = 5000
+        return inv
+
+    def _gateway_plus_two_aios(self):
+        """Reproduces the field topology: a Gateway coordinating two primary AIOs.
+
+        Per GivTCP rules automatic_config picks the Gateway as the control target,
+        so every arg binds to the Gateway's serial suffix. The Gateway is not
+        flagged primary — firmware only sets primary on battery inverters.
+        """
+        status = pb.GatewayStatus()
+        status.device_id = "pbgw_test"
+        status.firmware = "0.27.0"
+        status.timestamp = 1741789200
+        status.schema_version = 1
+        self._add_inverter(status, "GW2315G357", primary=False, inv_type=pb.INVERTER_TYPE_GIVENERGY_GATEWAY)
+        self._add_inverter(status, "CH2335G421", primary=True)
+        self._add_inverter(status, "CH2432G070", primary=True)
+        return status
+
+    def test_bound_inverter_time_entity_is_written(self):
+        """The inverter_time entity bound by automatic_config must be written."""
+        gw = self._make_gateway()
+        gw._last_status = self._gateway_plus_two_aios()
+        gw.automatic_config()
+
+        bound = gw._args["inverter_time"][0]
+
+        gw._inject_entities(gw._last_status)
+
+        assert bound in gw._dashboard_calls, "automatic_config bound inverter_time to {} but _inject_entities never wrote it; " "written entities were: {}".format(bound, sorted(gw._dashboard_calls))
+
+    def test_bound_soc_entity_is_written(self):
+        """The soc_percent entity bound by automatic_config must be written."""
+        gw = self._make_gateway()
+        gw._last_status = self._gateway_plus_two_aios()
+        gw.automatic_config()
+
+        bound = gw._args["soc_percent"][0]
+
+        gw._inject_entities(gw._last_status)
+
+        assert bound in gw._dashboard_calls, "automatic_config bound soc_percent to {} but _inject_entities never wrote it; " "written entities were: {}".format(bound, sorted(gw._dashboard_calls))
+
+
 class TestDebugLogging:
     """Tests for the gateway_debug verbose telemetry/plan dump helper."""
 
@@ -4259,6 +4352,7 @@ def run_gateway_tests(my_predbat=None):
         TestInjectEntities,
         TestDebugLogging,
         TestAutomaticConfig,
+        TestBoundEntitiesAreWritten,
         TestEvTelemetry,
         TestEvAutoConfig,
         TestEvInitialize,