OPT-11 P2: HA entities for battery modes

Each battery gets an MQTT-discovered Mode select and Use switch, only while
battery_modes_enabled is true. Commands go through handle_action(), the
/action path; refusals are logged once. Retained commands are never applied.
Turning modes off removes exactly the configs announced (kept in the store).
With modes off the announcement is byte-identical to ed739d4.

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

goodwe_controller/app/main.py

@@ -72,7 +72,9 @@ from .maintenance import (
     IDLE, POWER_MOVING, MaintConfig, Maintenance, MaintResult,
     arbitrate as maint_arbitrate,
 )
-from .mqtt import (MqttPublisher, announced_units, optional_keys, unit_slugs,
+from .mqtt import (MODE_CONFIGS_KEY, MODE_LABELS, USE_OFF, USE_ON,
+                   MqttPublisher, announced_units, mode_payloads,
+                   mode_retractions, optional_keys, parse_command, unit_slugs,
                    unit_state_key)
 from . import peakguard
 from . import packshare
@@ -901,9 +903,11 @@ class Controller:
         # turned them on behaves exactly as before (SAFETY-10 section 1). Each
         # battery's mode and on/off switch live in the store, not in options,
         # so a change applies at once (`pack_use`, `pack_mode` actions).
-        self.modes_on = opts.get("battery_modes_enabled") is True
+        self.modes_on = packmode.enabled(opts)
         # The units whose mode fault is logged already (edge-logged).
         self._mode_faults = set()
+        # OPT-11 P2: (topic, reason) of MQTT commands refused and logged once.
+        self._mqtt_refused = set()
         # [(pack name, why)] for packs that are due and waiting their turn.
         # Empty at a roster of one, where nothing can defer anything.
         self._maint_deferred = []
@@ -2053,6 +2057,56 @@ class Controller:
         pm = self.pack_mode(inv)
         return {"unit": inv.name, "use": pm.use, "mode": pm.mode}
 
+    def mode_values(self) -> dict:
+        """OPT-11 P2: each battery's mode and switch, for their HA state
+        topics. Read from the store, so they are right after a restart. Empty
+        while battery modes are off."""
+        if not self.modes_on:
+            return {}
+        out = {}
+        names = [inv.name for inv in self.inverters]
+        for inv, slug in zip(self.inverters, unit_slugs(names)):
+            pm = self.pack_mode(inv)
+            out[unit_state_key(slug, "mode")] = MODE_LABELS.get(pm.mode,
+                                                               pm.mode)
+            out[unit_state_key(slug, "use")] = USE_ON if pm.use else USE_OFF
+        return out
+
+    async def mqtt_command(self, topic, payload, retained) -> None:
+        """OPT-11 P2: one command from a battery's HA switch or mode list.
+
+        It goes through handle_action(), the page's /action path, so the
+        checks and the store write are the same. A retained command (one the
+        broker replays on subscribe, e.g. after a restart) is never applied:
+        the store already holds the last choice. A refusal is logged once per
+        topic and reason. Never raises: MQTT must not reach control.
+        """
+        try:
+            slug, action, value, why = parse_command(
+                topic, payload, retained, packmode.MODES)
+            if why is None:
+                names = [inv.name for inv in self.inverters]
+                unit = dict(zip(unit_slugs(names), names)).get(slug)
+                result = await self.handle_action(action, unit=unit,
+                                                  value=value)
+                if not (isinstance(result, dict) and "error" in result):
+                    self.mqtt.publish(self.mode_values())
+                    return
+                why = result["error"]
+            else:
+                why = messages.pack_refused(why)
+            topic_s = str(topic)[:128]
+            _LOG.debug("Home Assistant command %s %s refused: %s", topic_s,
+                       repr(payload)[:48], why)
+            if (topic_s, why) in self._mqtt_refused \
+                    or len(self._mqtt_refused) >= 32:
+                return
+            self._mqtt_refused.add((topic_s, why))
+            _LOG.warning("Home Assistant command on %s ignored: %s", topic_s,
+                         why)
+        except Exception:                               # noqa: BLE001
+            _LOG.exception("Home Assistant command could not be handled")
+
     def _maint_stop_off(self, machine, now) -> None:
         """OPT-11: stop this battery's maintenance cycle because it is off."""
         if machine.phase == IDLE:
@@ -5144,6 +5198,8 @@ class Controller:
             values[unit_state_key(slug, "soc")] = inv.soc
             values[unit_state_key(slug, "sign_latch")] = (
                 "tripped" if inv.sign_wd.tripped else "clear")
+        # OPT-11 P2: each battery's mode and switch; nothing while modes are off.
+        values.update(self.mode_values())
         self.mqtt.publish(values)
 
     async def shutdown(self) -> None:
@@ -6189,6 +6245,16 @@ async def amain() -> None:
         # took the control loop down with it.
         broker = None
         try:
+            # OPT-11 P2: each battery's switch and mode list, only while
+            # battery modes are on. The config topics are kept in the store,
+            # so turning modes off removes exactly the ones announced.
+            _modes = packmode.MODES if packmode.enabled(opts) else ()
+            _mode_cfgs = [t for t, _ in mode_payloads(roster_names(opts),
+                                                      _modes)]
+            _retract = mode_retractions(store.data.get(MODE_CONFIGS_KEY),
+                                        _mode_cfgs)
+            if _modes:
+                store.set(MODE_CONFIGS_KEY, _mode_cfgs)
             broker = await hass.mqtt_service()
             pub = MqttPublisher(
                 broker.get("host") if broker else None,
@@ -6208,6 +6274,8 @@ async def amain() -> None:
                 # is what `build_roster()` itself reads. At a roster of one this
                 # announces nothing new - see `announced_units()`.
                 units=roster_names(opts),
+                modes=_modes,
+                retract=_retract,
             )
         except Exception as err:  # noqa: BLE001
             _LOG.warning("MQTT unavailable (%s) - continuing without status entities", err)
@@ -6221,6 +6289,8 @@ async def amain() -> None:
 
         stop = asyncio.Event()
         controller = Controller(opts, hass, store, pub, stop=stop)
+        if callable(getattr(pub, "bind", None)):
+            pub.bind(asyncio.get_running_loop(), controller.mqtt_command)
         runner = await web.start(controller, port=INGRESS_PORT)
 
         loop = asyncio.get_running_loop()