Fix cloud-tool preparation races and partial telemetry reads

Serialize proxy and active learning startup with polling and unload cleanup. Restore SRNE battery/PV reads and valid catalog proof, correct MUST current labels, and add bounded read-only support diagnostics for MUST and Hopewind.

Add lifecycle and telemetry regressions, document behavior, and clarify manual main installation. Refs #23, #43, #44, #46, #13.

Author: Maksym Shtembuliak

CHANGELOG.md

@@ -9,6 +9,11 @@ the GitHub release body should be rendered from the matching version section her
 
 ### Added
 
+- Support archives include bounded, read-only checks of documented Hopewind
+  0237 control addresses (#23), and individual MUST PV3300 current registers
+  when the combined block reports all three as zero (#46). Results stay separate
+  from normal telemetry. These checks do not write settings or enable controls.
+
 - Added a read-only **Hopewind String (Protocol 0237)** profile, based on the
   manufacturer's map and successful local reads from a Bluesun BSM15K-B (#23).
   It exposes PV and AC generation, electrical readings, energy counters and
@@ -40,6 +45,23 @@ the GitHub release body should be rendered from the matching version section her
 
 ### Fixed
 
+- Proxy capture and active device learning now wait for an in-flight poll
+  before preparing the collector connection. New polls cannot interrupt the
+  preparation or its rollback; unloading waits for startup cleanup before
+  closing the link (#43). This fixes a reproduced overlap, not a confirmed
+  cause of every reported collector disconnect.
+
+- SRNE polling can recover battery and PV readings through five documented
+  short register groups after an explicit illegal-address rejection of the
+  combined DC block (#44). Timeouts and malformed responses do not trigger
+  this fallback. Missing groups remain unavailable instead of becoming zero.
+  The detected read-only family also retains the catalog proof required to
+  recreate its sensors after a Home Assistant reload.
+
+- MUST current labels now match the documented nodes: **Inverter Current**,
+  **Grid Current**, and **Load Current** (#46). Existing entity IDs and values
+  are unchanged; current is not estimated from power and voltage.
+
 - MUST PV3300 reports whole load percent and normalizes battery/grid directions
   for HA energy flows (#46): positive battery power/current means charging;
   positive grid power means importing. These corrections are model-scoped;

README.md

@@ -131,7 +131,10 @@ It is a small ESP8266/ESP32-based bridge that connects directly to the inverter
 ### Manual installation
 
 1. Download the archive from the [latest EyeBond Local release](https://github.com/groove-max/ha-eybond-local/releases/latest).
-2. Copy `custom_components/eybond_local/` into `config/custom_components/`.
+2. Extract the archive and copy only its `custom_components/eybond_local/`
+   folder into `config/custom_components/`. The final path must be
+   `config/custom_components/eybond_local/manifest.json`, without another
+   repository or `custom_components` folder nested inside it.
 3. Restart Home Assistant.
 4. Add **EyeBond Local** from **Settings → Devices & Services**.
 
@@ -148,9 +151,12 @@ yet. It does not update through HACS and may change before the next release.
 
 1. Back up your Home Assistant configuration.
 2. Download the current [`main` branch archive](https://github.com/groove-max/ha-eybond-local/archive/refs/heads/main.zip).
-3. Remove the existing `config/custom_components/eybond_local/` directory, then
-   copy the complete directory from the archive into `config/custom_components/`.
-   Do not mix files from two builds.
+3. Extract the archive. Inside `ha-eybond-local-main`, open `custom_components`.
+   Replace the existing `config/custom_components/eybond_local/` directory with
+   the complete **`eybond_local`** folder from there. Do not copy the outer
+   `ha-eybond-local-main` folder or mix files from two builds. Check that
+   `manifest.json` is directly inside `config/custom_components/eybond_local/`.
+   You do not need to remove the integration or its devices from Home Assistant.
 4. Restart Home Assistant and check the EyeBond Local entries.
 5. When reporting a result, include the Git commit shown on the repository page
    and attach a new Support Archive.

custom_components/eybond_local/drivers/modbus_catalog.py

@@ -51,6 +51,7 @@
     merge_capability_register_word,
 )
 from .catalog_probe import async_walk_detection_dag
+from .support_diagnostics import capture_support_reads
 
 logger = logging.getLogger(__name__)
 
@@ -356,13 +357,13 @@ async def async_capture_support_evidence(
                     "words": list(values),
                 }
             )
-        return {
+        evidence = {
             "capture_kind": "modbus_catalog_register_dump",
             "driver_key": self.key,
             "model_name": inverter.model_name,
             "serial_number": inverter.serial_number,
             "capture_notes": [
-                "Support capture only reads catalog blocks; it never invokes"
+                "Support capture only reads catalog blocks and optional support reads; it never invokes"
                 " the driver's optional write capabilities. Blocks list their"
                 " function codes (3 = holding, 4 = input).",
             ],
@@ -382,6 +383,16 @@ async def async_capture_support_evidence(
                 for item in captured_ranges
             ],
         }
+        plan = schema.support_read_plan
+        if plan is not None:
+            evidence["support_read_diagnostics"] = await capture_support_reads(
+                session,
+                tuple((block.start, block.count, block.key) for block in plan.blocks),
+                timeout_seconds=plan.timeout_seconds,
+                source=plan.source,
+                purpose=plan.purpose,
+            )
+        return evidence
 
     def local_register_read_plans(
         self, inverter: DetectedInverter

custom_components/eybond_local/drivers/must.py

@@ -15,6 +15,7 @@
 from ..payload.modbus import ModbusError, ModbusSession
 from ..payload.register_decode import decode_ascii_word, read_spec_set_values
 from .base import InverterDriver
+from .support_diagnostics import capture_support_reads
 from .local_register_evidence import (
     LocalRegisterReadPlan,
     LocalRegisterSnapshot,
@@ -217,7 +218,7 @@ async def async_capture_support_evidence(
                     "words": list(values),
                 }
             )
-        return {
+        evidence = {
             "capture_kind": "must_pv_ph18_modbus_register_dump",
             "driver_key": self.key,
             "model_name": inverter.model_name,
@@ -238,6 +239,22 @@ async def async_capture_support_evidence(
                 for item in captured_ranges
             ],
         }
+        if inverter.register_schema_name == "must_pv_ph18/pv3300.json":
+            raw = {
+                block["start"] + offset: word
+                for block in captured_ranges
+                for offset, word in enumerate(block["words"])
+            }
+            if all(raw.get(address) == 0 for address in (25210, 25211, 25212)):
+                evidence["current_read_diagnostics"] = await capture_support_reads(
+                    session,
+                    ((25210, 1, "inverter_current"), (25211, 1, "grid_current"),
+                     (25212, 1, "load_current")),
+                    timeout_seconds=6.0,
+                    source="PH/PV Modbus 1.4.3 and protocol 1916 current registers",
+                    purpose="support_only_zero_bulk_current_single_read_comparison",
+                )
+        return evidence
 
     def local_register_read_plans(
         self, inverter: DetectedInverter

custom_components/eybond_local/drivers/srne.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import asyncio
 from typing import Any
 
 from ..metadata.compiled_detection_catalog import load_compiled_detection_catalog
@@ -18,10 +17,11 @@
     async_capture_modbus_snapshot,
 )
 from .read_result import DriverReadMode, DriverReadResult
+from .support_diagnostics import capture_support_reads
 
 
 # SRNE Modbus V2.07, P01 DC Data Area (addresses in that table are hexadecimal).
-# Support-only diagnosis of a rejected 0x0100/18 read; never a runtime read plan.
+# Documented short reads after an explicit rejection of the 0x0100/18 block.
 # In particular, do not cross the optional/new fields or reserved 0x010D again.
 _DC_DIAGNOSTIC_RANGES = (
     (0x0100, 3, "battery"),
@@ -87,17 +87,28 @@ async def async_probe(self, transport, target: ProbeTarget) -> DetectedInverter
         if not _looks_like_srne_product_info(product_info):
             return None
 
-        surface = load_compiled_detection_catalog().surfaces["srne_modbus_read_only"]
+        catalog = load_compiled_detection_catalog()
+        evidence = {
+            "identity.product_info": product_info,
+            "protocol.protocol_id": "SRNE_MODBUS",
+        }
+        resolution = catalog.resolve_family(protocol_key=self.key, evidence=evidence)
+        if not resolution.surface_key:
+            return None
+        surface = catalog.surfaces[resolution.surface_key]
         details = {
             "product_info": product_info,
             "protocol_id": "SRNE_MODBUS",
             "catalog_detection": {
-                "resolution": "exact",
+                "resolution": resolution.resolution,
                 "surface_key": surface.key,
-                "evidence": {
-                    "identity.product_info": product_info,
-                    "protocol.protocol_id": "SRNE_MODBUS",
-                },
+                "confidence": resolution.confidence,
+                "candidate_keys": list(resolution.candidate_keys),
+                "catalog_version": resolution.catalog_version,
+                "descriptor_revisions": list(resolution.descriptor_revisions),
+                "evidence_fingerprint": resolution.evidence_fingerprint,
+                "evidence": evidence,
+                "decision_path": list(resolution.decision_path),
             },
         }
         return DetectedInverter(
@@ -125,7 +136,14 @@ async def async_read_values(
             inverter.register_schema_name or self.register_schema_name
         )
         session = self._session(transport, inverter.probe_target)
-        values = await read_spec_set_values(session, schema, ascii_style="printable")
+        values = await read_spec_set_values(
+            session,
+            schema,
+            ascii_style="printable",
+            illegal_address_fallbacks={
+                (3, 0x0100, 18): tuple((start, count) for start, count, _ in _DC_DIAGNOSTIC_RANGES)
+            },
+        )
         return DriverReadResult(values=values, mode=DriverReadMode.FULL)
 
     async def async_write_capability(
@@ -216,15 +234,23 @@ def local_register_read_plans(
         schema = load_register_schema(
             inverter.register_schema_name or self.register_schema_name
         )
-        return tuple(
-            LocalRegisterReadPlan.for_target(
-                inverter.probe_target,
-                function=3,
-                start=block.start,
-                count=block.count,
+        # Bounded background evidence uses the same documented DC groups, not
+        # the unsupported parent or zero-filled holes. Ordinary polling still
+        # prefers the compact parent when the device accepts it.
+        plans = []
+        for block in schema.blocks:
+            ranges = (
+                tuple((start, count) for start, count, _ in _DC_DIAGNOSTIC_RANGES)
+                if (block.start, block.count) == (0x0100, 18)
+                else ((block.start, block.count),)
             )
-            for block in schema.blocks
-        )
+            plans.extend(
+                LocalRegisterReadPlan.for_target(
+                    inverter.probe_target, function=3, start=start, count=count
+                )
+                for start, count in ranges
+            )
+        return tuple(plans)
 
     async def async_capture_local_register_snapshot(
         self, transport, inverter: DetectedInverter, *, collector_pn: str
@@ -257,45 +283,14 @@ async def _capture_dc_subranges(session: ModbusSession) -> dict[str, Any]:
     phase probing, capability writes or mutation of the runtime schema occurs.
     """
 
-    result: dict[str, Any] = {
-        "source": "SRNE Modbus V2.07, P01 DC Data Area",
-        "purpose": "support_only_rejected_dc_block",
-        "trigger_range": {"start": 0x0100, "count": 18},
-        "time_budget_seconds": _DC_DIAGNOSTIC_TIMEOUT,
-        "planned_ranges": [
-            {"start": start, "count": count, "group": group}
-            for start, count, group in _DC_DIAGNOSTIC_RANGES
-        ],
-        "status": "completed",
-        "captured_ranges": [],
-        "range_failures": [],
-    }
-    loop = asyncio.get_running_loop()
-    deadline = loop.time() + _DC_DIAGNOSTIC_TIMEOUT
-    for start, count, _group in _DC_DIAGNOSTIC_RANGES:
-        if loop.time() >= deadline:
-            result["status"] = "budget_exhausted"
-            break
-        timeout = asyncio.timeout_at(deadline)
-        try:
-            async with timeout:
-                words = await session.read_holding(start, count)
-        except Exception as exc:
-            expired = timeout.expired()
-            result["range_failures"].append(
-                {
-                    "start": start,
-                    "count": count,
-                    "error": "diagnostic_budget_exhausted" if expired else str(exc),
-                }
-            )
-            if _is_address_rejection(exc):
-                continue
-            result["status"] = "budget_exhausted" if expired else "stopped_on_error"
-            break
-        result["captured_ranges"].append(
-            {"start": start, "count": count, "words": list(words)}
-        )
+    result = await capture_support_reads(
+        session,
+        _DC_DIAGNOSTIC_RANGES,
+        timeout_seconds=_DC_DIAGNOSTIC_TIMEOUT,
+        source="SRNE Modbus V2.07, P01 DC Data Area",
+        purpose="support_only_rejected_dc_block",
+    )
+    result["trigger_range"] = {"start": 0x0100, "count": 18}
     return result
 
 

custom_components/eybond_local/drivers/support_diagnostics.py

@@ -0,0 +1,54 @@
+"""Bounded read-only evidence; never changes runtime maps or enables writes."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from ..payload.modbus import ModbusError, ModbusSession
+
+
+async def capture_support_reads(
+    session: ModbusSession,
+    ranges: tuple[tuple[int, int, str], ...],
+    *,
+    timeout_seconds: float,
+    source: str,
+    purpose: str,
+) -> dict[str, Any]:
+    """Read a fixed driver-owned list; only illegal addresses allow continuing."""
+
+    result: dict[str, Any] = {
+        "source": source,
+        "purpose": purpose,
+        "time_budget_seconds": timeout_seconds,
+        "planned_ranges": [
+            {"start": start, "count": count, "group": group}
+            for start, count, group in ranges
+        ],
+        "status": "completed",
+        "captured_ranges": [],
+        "range_failures": [],
+    }
+    loop = asyncio.get_running_loop()
+    deadline = loop.time() + timeout_seconds
+    for start, count, _group in ranges:
+        if loop.time() >= deadline:
+            result["status"] = "budget_exhausted"
+            break
+        timeout = asyncio.timeout_at(deadline)
+        try:
+            async with timeout:
+                words = await session.read_holding(start, count)
+        except Exception as exc:
+            expired = timeout.expired()
+            result["range_failures"].append({
+                "start": start, "count": count,
+                "error": "diagnostic_budget_exhausted" if expired else str(exc),
+            })
+            if isinstance(exc, ModbusError) and str(exc) == "exception_code:2":
+                continue
+            result["status"] = "budget_exhausted" if expired else "stopped_on_error"
+            break
+        result["captured_ranges"].append({"start": start, "count": count, "words": list(words)})
+    return result