feat(discovery): inverter records carry entities, capabilities and Predbat-named ratings (observe-only, piece 1)

.cspell/custom-dictionary-workspace.txt

@@ -719,6 +719,7 @@ WEXITSTATUS
 WIFEXITED
 WNOHANG
 workmode
+worktree
 writeonly
 wrongsha
 wwxxabcdefyyzz

apps/predbat/alphaess.py

@@ -95,6 +95,20 @@
 
 _HOLD_NOT_EVALUATED = object()
 
+# The behaviour an AlphaESSCloud inverter has, stated for the discovery record's capabilities. A
+# literal, never read back from INVERTER_DEF: the record has to rebuild the row on its own, or the
+# completeness test proves nothing. support_feedin_first is False because the row leaves it out and
+# inverter.py defaults it to False; there is no feed-in-first mode in the Open API.
+ALPHAESS_CAPABILITIES = {
+    "support_charge_freeze": True,
+    "support_discharge_freeze": True,
+    "support_feedin_first": False,
+    "can_span_midnight": False,
+    "charge_discharge_with_rate": False,
+    "charge_control_immediate": False,
+    "target_soc_used_for_discharge": True,
+}
+
 
 class AlphaESSAPI(ComponentBase):
     """AlphaESS Open API cloud component."""
@@ -866,28 +880,79 @@ async def automatic_config(self):
 
         await self.apply_hybrid_verdict()
 
+    def _discovery_entities(self, sn):
+        """The settings automatic_config() binds for one system, as discovery entity descriptors.
+
+        Each entity id is formed with the same _sensor_name()/_control_name() call automatic_config()
+        makes, so the two cannot drift apart. The record describes this system alone (spec D10): a
+        setting automatic_config() binds only when a figure is known - an energy counter, the
+        capacity, poinv - is described whenever this system reports it, although automatic_config()
+        binds it only once every system does. pv_power and pv_today are described even under
+        automatic_ignore_pv, which is the user's opt-out rather than a fact about the device (D11).
+        The three *_power_invert settings are always False, which is the descriptor's default, so no
+        descriptor carries invert. car_charging_* belong to the chargers and cars sections, and
+        export_limit and battery_min_soc are never bound (see automatic_config()).
+        """
+        entities = {
+            "soc_percent": {"entity_id": self._sensor_name(sn, "soc"), "access": "r", "unit": "%"},
+            "battery_power": {"entity_id": self._sensor_name(sn, "battery_power"), "access": "r", "unit": "W"},
+            "grid_power": {"entity_id": self._sensor_name(sn, "grid_power"), "access": "r", "unit": "W"},
+            "load_power": {"entity_id": self._sensor_name(sn, "load_power"), "access": "r", "unit": "W"},
+            "pv_power": {"entity_id": self._sensor_name(sn, "pv_power"), "access": "r", "unit": "W"},
+        }
+        energy = self.device_energy.get(sn, {})
+        for leaf in ("load_today", "import_today", "export_today", "pv_today"):
+            if leaf in energy:
+                entities[leaf] = {"entity_id": self._sensor_name(sn, leaf), "access": "r", "unit": "kWh"}
+        if self.battery_capacity(sn) > 0:
+            entities["soc_max"] = {"entity_id": self._sensor_name(sn, "battery_capacity"), "access": "r", "unit": "kWh"}
+        if self.inverter_limit(sn) > 0:
+            entities["inverter_limit"] = {"entity_id": self._sensor_name(sn, "inverter_limit"), "access": "r", "unit": "W"}
+        if self.battery_rate_max(sn) > 0:
+            entities["battery_rate_max"] = {"entity_id": self._sensor_name(sn, "battery_rate_max"), "access": "r", "unit": "W"}
+
+        entities["reserve"] = {"entity_id": self._control_name("number", sn, "battery_schedule_reserve"), "access": "rw", "unit": "%"}
+        for direction, prefix in (("charge", "charge"), ("export", "discharge")):
+            entities["{}_start_time".format(prefix)] = {"entity_id": self._control_name("select", sn, "battery_schedule_{}_start_time".format(direction)), "access": "rw", "domain": "select", "format": "HH:MM:SS"}
+            entities["{}_end_time".format(prefix)] = {"entity_id": self._control_name("select", sn, "battery_schedule_{}_end_time".format(direction)), "access": "rw", "domain": "select", "format": "HH:MM:SS"}
+            entities["scheduled_{}_enable".format(prefix)] = {"entity_id": self._control_name("switch", sn, "battery_schedule_{}_enable".format(direction)), "access": "rw", "domain": "switch"}
+        entities["charge_limit"] = {"entity_id": self._control_name("number", sn, "battery_schedule_charge_soc"), "access": "rw", "unit": "%"}
+        entities["charge_rate"] = {"entity_id": self._control_name("number", sn, "battery_schedule_charge_power"), "access": "rw", "unit": "W", "step": 100}
+        entities["discharge_target_soc"] = {"entity_id": self._control_name("number", sn, "battery_schedule_export_soc"), "access": "rw", "unit": "%"}
+        entities["discharge_rate"] = {"entity_id": self._control_name("number", sn, "battery_schedule_export_power"), "access": "rw", "unit": "W", "step": 100}
+        entities["schedule_write_button"] = {"entity_id": self._control_name("switch", sn, "battery_schedule_charge_write"), "access": "rw", "domain": "switch"}
+        return entities
+
     def build_discovery(self):
         """
         Describe the discovered AlphaESS systems for the discovery catalogue.
 
         Reads only what get_device_list() already holds - self.device_list and self.device_detail -
-        plus the EV-charger verdict _apply_live_payload() records, so this adds no API calls and
-        cannot change what AlphaESS does. Reporting is independent of self.automatic: the catalogue
-        records the hardware, and the report's own "automatic" flag says whether Predbat wired
-        apps.yaml to it.
+        plus the EV-charger verdict _apply_live_payload() records and the energy counters already
+        read, so this adds no API calls and cannot change what AlphaESS does. Reporting is
+        independent of self.automatic: the catalogue records the hardware, and the report's own
+        "automatic" flag says whether Predbat wired apps.yaml to it.
 
         self.device_list holds serial strings (sysSn), and only systems that passed has_battery()
         at discovery: a battery-less system (the VT1000 family, cobat 0 or missing) is dropped in
         get_device_list() and never reaches device_detail. automatic_config() applies no further
         test - it registers every serial in device_list as "AlphaESSCloud" - so inverter_type is set
         on every record, mirroring automatic_config() as the source of truth.
 
-        Ratings are getEssList's own figures: poinv (kW) as inverter_w via inverter_limit(), popv
-        (kW) as pv_w, cobat (kWh) as battery_kwh via battery_capacity(). cobat is one scalar per
-        system, so there is no list of entries to mis-sum. A system reports "solar" only when popv
-        says PV is attached.
+        capabilities is the ALPHAESS_CAPABILITIES constant and entities is _discovery_entities(sn):
+        together they rebuild the AlphaESSCloud INVERTER_DEF row, and entities holds every setting
+        automatic_config() binds for the system.
+
+        Ratings are getEssList's own figures under their Predbat setting names: poinv (kW) as
+        inverter_limit (W) via inverter_limit(), cobat (kWh) as soc_max via battery_capacity(), and
+        popv (kW) as the descriptive pv_w. cobat is one scalar per system, so there is no list of
+        entries to mis-sum. A system reports "solar" only when popv says PV is attached.
 
         Deliberately not reported:
+        - export_limit: AlphaESS reports no export power limit, and poinv is the inverter rating,
+          not the grid connection's cap (automatic_config() warns about this).
+        - battery_rate_max as a rating: the API reports no battery power limit; battery_rate_max()
+          is poinv or the user's override, so only its entity binding is described.
         - emsStatus: a status that changes. refresh_discovery() compares whole reports, so a
           changing value would re-file the report every time it moved.
         - usCapacity and surplusCobat: they fit "current SoC" and "configured usable depth" equally
@@ -926,12 +991,12 @@ def build_discovery(self):
             ratings = {}
             inverter_w = self.inverter_limit(sn)
             if inverter_w > 0:
-                ratings["inverter_w"] = inverter_w
+                ratings["inverter_limit"] = inverter_w
             if pv_kw > 0:
                 ratings["pv_w"] = pv_kw * 1000.0
             battery_kwh = self.battery_capacity(sn)
             if battery_kwh > 0:
-                ratings["battery_kwh"] = battery_kwh
+                ratings["soc_max"] = battery_kwh
 
             flags = ["ev_charger"] if self._ev_present.get(sn) is True else []
 
@@ -941,11 +1006,12 @@ def build_discovery(self):
                     inverter_type="AlphaESSCloud",
                     composition="direct",
                     functions=functions,
-                    capabilities=["schedule", "target_soc", "discharge_target", "charge_rate_power"],
+                    capabilities=dict(ALPHAESS_CAPABILITIES),
                     flags=flags,
                     hardware_ids={"serial": sn},
                     info=info,
                     ratings=ratings,
+                    entities=self._discovery_entities(sn),
                 )
             )
 

apps/predbat/component_base.py

@@ -58,6 +58,11 @@ class ComponentBase(ABC):
             the registry (the standalone CLI harnesses), so report_discovery() always has a name.
     """
 
+    # Seconds inverter.py waits between writing a setting and reading it back. The component owns the
+    # entities, so it owns this timing; INVERTER_DEF's write_and_poll_sleep is 2 for every cloud type and
+    # 10 for the GivEnergy types (GivTCP and GE Cloud override it). See coordinator.inverter_definition().
+    WRITE_AND_POLL_SLEEP = 2
+
     # Declared on the class, not only assigned in __init__, so they exist even on a component built
     # without it - the test harnesses construct components with Cls.__new__(Cls) to exercise one
     # method in isolation. refresh_discovery() must not be able to raise on such an instance: an

apps/predbat/config.py

@@ -1852,7 +1852,7 @@
         "has_timed_pause": True,
         "charge_time_format": "HH:MM:SS",
         "charge_time_entity_is_option": True,
-        "soc_units": "kWh",
+        "soc_units": "%",
         "num_load_entities": 1,
         "has_ge_inverter_mode": False,
         "has_ge_eco_toggle": True,
@@ -1880,7 +1880,7 @@
         "has_timed_pause": False,
         "charge_time_format": "HH:MM:SS",
         "charge_time_entity_is_option": True,
-        "soc_units": "kWh",
+        "soc_units": "%",
         "num_load_entities": 1,
         "has_ge_inverter_mode": False,
         "has_ge_eco_toggle": False,