fix: support explicit routed collector discovery

Add bounded known-IP scan targets and preserve advertised NAT callback settings during identity checks. Correct issue #6 device attribution, document setup paths, and cover UDP payloads and native HA flows.

Author: Maksym Shtembuliak

CHANGELOG.md

@@ -9,6 +9,11 @@ the GitHub release body should be rendered from the matching version section her
 
 ### Added
 
+- Advanced setup can include up to eight known collector IPs in the ordinary
+  scan, alongside local discovery. Routed/VPN collectors no longer require a
+  hardcoded scan target. The list is setup-flow scoped; identity and recovery
+  checks remain mandatory.
+
 - Added a separate read-only **EyeBond 09C1 family** profile, qualified against
   the manufacturer's map and ZL Power GSIII captures (#50). It reports input
   and output voltage/frequency separately, battery voltage, load percentage,
@@ -52,6 +57,13 @@ the GitHub release body should be rendered from the matching version section her
 
 ### Fixed
 
+- Manual callback identity checks now honor the configured advertised callback
+  IP and port, separately from Home Assistant's local listener. NAT overrides
+  no longer apply only to later recovery/runtime requests.
+- Corrected the issue #6 catalog attribution: PI30 captures from Sumry devices
+  do not confirm Yingfa YF6.2K-2K-LEL-IF support. That model is now unresolved;
+  generic PI30 support and the independently evidenced issue #27 model remain.
+
 - Keep the configured callback IP when local-interface enumeration fails (#52).
   The default-route address is no longer treated as a complete interface list;
   existing BusyBox and collector-subnet discovery remain unchanged.

README.md

@@ -191,6 +191,9 @@ combines broadcast replies, already connected collectors, and a local `/24`
 unicast fallback when broadcast discovery is not enough. On a larger network,
 use the correct subnet broadcast or enter a known collector address through
 advanced setup instead of expecting every address in a `/16` to be probed.
+For a routed subnet, **Add known collector IPs to scan** supplements local
+discovery with explicitly entered addresses. Use manual setup when the collector
+needs a different callback address or port behind NAT.
 
 <p align="center"><img src="docs/images/setup-02-scanning.png" alt="Scanning the local network" width="480"></p>
 

catalog/inverter_models/models/yingfa_yf6_2k_2k_lel_if.json

@@ -4,44 +4,36 @@
   "manufacturer": "Yingfa",
   "model": "YF6.2K-2K-LEL-IF",
   "aliases": [
-    "YF6.2K",
-    "PI30 6200"
+    "YF6.2K"
   ],
-  "lifecycle": "supported",
+  "lifecycle": "research",
   "variants": [
     {
-      "variant_key": "pi30_max_qpiri",
-      "label": "PI30 MAX 6200W raw-ASCII runtime over SmartESS DTU AT collector",
-      "device_descriptor_keys": [
-        "pi30_max_qpiri"
-      ],
-      "known_firmware": [
-        "VERFW:00074.11",
-        "VERFW2:00000.00"
-      ]
+      "variant_key": "unidentified",
+      "label": "Protocol and runtime mapping not yet confirmed",
+      "device_descriptor_keys": []
     }
   ],
   "validation": {
-    "hardware": "captured",
-    "telemetry": "confirmed",
-    "controls": "partial"
+    "hardware": "reported",
+    "telemetry": "unknown",
+    "controls": "none"
   },
   "coverage": {
-    "runtime_control_surface": "available",
-    "smartess_control_surface": "cloud_catalog",
+    "runtime_control_surface": "none",
+    "smartess_control_surface": "unknown",
     "vendor_register_map": "unknown",
     "notes": [
-      "The proxy capture proves PI30 ASCII telemetry and cloud-visible PI30 controls, but Home Assistant write behavior is not yet independently user-confirmed.",
-      "This collector family uses raw PI30 ASCII payloads directly over the SmartESS DTU AT callback stream rather than the legacy EyeBond binary FC=4 forwarding tunnel."
+      "The earlier PI30 capture was attributed to this model in error. The owner clarified that the captured devices were Sumry inverters, not this Yingfa."
     ]
   },
   "known_limitations": [
-    "The commercial model name is known from the user report, not from a local inverter identity command in the captured traffic.",
-    "QMN/model-number evidence was not present in the cloud proxy capture, so runtime resolution is currently by PI30 protocol plus QPIRI 28-field MAX-family shape."
+    "No confirmed inverter protocol or runtime mapping is available for this particular model.",
+    "Working collector discovery or a UDP callback acknowledgement does not establish inverter compatibility."
   ],
-  "knowledge_summary": "Yingfa YF6.2K-2K-LEL-IF support is based on issue #6 and a private proxy capture. The inverter speaks PI30 ASCII through a SmartESS DTU AT collector; QPI reports PI30, QPIRI reports a 28-field 6200W/48V MAX-style rating, and QPIGS returns live telemetry. The integration should use the PI30 MAX runtime surface over raw AT-text payload transport for this collector family.",
+  "knowledge_summary": "The issue #6 owner reports a Yingfa YF6.2K-2K-LEL-IF, but its inverter protocol remains unresolved. Previously linked PI30 evidence belongs to Sumry devices and is not proof of support for this Yingfa. This correction does not remove generic PI30 support or evidence for other independently reported Yingfa models.",
   "source_keys": [
     "github_issue_6",
-    "support_archive_issue_6_20260622_proxy_capture"
+    "issue_6_device_attribution_correction"
   ]
 }

catalog/inverter_models/schemas/model.schema.json

@@ -42,9 +42,9 @@
           "label": {"type": "string", "minLength": 1},
           "device_descriptor_keys": {
             "type": "array",
-            "minItems": 1,
+            "minItems": 0,
             "items": {"type": "string"},
-            "description": "Keys of devices[] entries in the runtime inverter catalog."
+            "description": "Keys of devices[] entries in the runtime inverter catalog. Empty only for an unresolved research variant; the catalog validator enforces this lifecycle boundary."
           },
           "validation": {
             "type": "object",

catalog/inverter_models/sources/github_issue_6.json

@@ -6,9 +6,8 @@
   "reference": "project-issue:6",
   "captured_at": "2026-06-22",
   "visibility": "public",
-  "summary": "Device owner reported a Yingfa YF6.2K-2K-LEL-IF inverter behind an EyeBond logger. The local network topology initially masked the callback source address, but routing/NAT diagnostics later confirmed that the collector could call Home Assistant back with its real remote address.",
+  "summary": "Device owner reported an unresolved Yingfa YF6.2K-2K-LEL-IF behind an EyeBond logger across routed networks. Collector connectivity observations are not evidence of a specific inverter protocol. The later device-attribution correction separates Sumry captures from this Yingfa report.",
   "assertions": [
-    "commercial_identity",
-    "runtime_compatibility"
+    "commercial_identity"
   ]
 }

catalog/inverter_models/sources/issue_6_device_attribution_correction.json

@@ -0,0 +1,12 @@
+{
+  "schema_version": 1,
+  "source_key": "issue_6_device_attribution_correction",
+  "kind": "private_message",
+  "title": "Issue #6 device attribution correction",
+  "reference": "private:issue-6-device-attribution-correction-20260930",
+  "captured_at": "2026-09-30",
+  "visibility": "private",
+  "summary_publishable": true,
+  "summary": "The owner clarified that the PI30 evidence in this case concerns Sumry inverters, reporting 6.2 kW and 4.2 kW units, while the Yingfa device remains unresolved. Exact Sumry commercial model names and per-device capture attribution still require confirmation; successful operation of both units, model-specific mappings and write validation are not inferred from the power ratings.",
+  "assertions": ["commercial_identity"]
+}

catalog/inverter_models/sources/support_archive_issue_6_20260622_proxy_capture.json

@@ -2,12 +2,12 @@
   "schema_version": 1,
   "source_key": "support_archive_issue_6_20260622_proxy_capture",
   "kind": "support_archive",
-  "title": "Yingfa YF6.2K-2K-LEL-IF proxy capture",
+  "title": "Issue #6 PI30 proxy capture — commercial attribution corrected",
   "reference": "private:support-archive-issue-6-20260622-proxy-capture",
   "captured_at": "2026-06-22",
   "visibility": "private",
   "summary_publishable": true,
-  "summary": "Private proxy capture 01KVRFV6VETJ4B7MQ54DB5RDFF_20260622T211305079147Z.zip shows a SmartESS DTU AT collector using endpoint dtu_ess.eybond.com,18899,TCP and UART 2400,8,1,NONE. The cloud sends raw PI30 ASCII commands directly on the AT callback stream: QPI, QID, QSID, QVFW, QVFW2, QPIRI, QFLAG, QPIGS, QPIGS2, QMODI, QPIWS, QDI, QMCHGCR, QMUCHGCR, and QOPM. QPI returns PI30; QPIRI returns a 28-field 6200W/48V rating; QPIGS returns a 21-field live telemetry frame.",
+  "summary": "Private capture shows raw PI30 ASCII over a SmartESS DTU AT collector: QPI returns PI30, QPIRI returns a 28-field 6200 W / 48 V rating, and QPIGS returns a 21-field live telemetry frame. These wire facts remain valid, but the earlier attribution to Yingfa YF6.2K-2K-LEL-IF is withdrawn following the owner's Sumry clarification. The capture does not establish an exact Sumry commercial model or validate a separate 4.2 kW unit.",
   "assertions": [
     "runtime_compatibility",
     "telemetry_validation",

custom_components/eybond_local/connection/callback_identity.py

@@ -289,6 +289,10 @@ class CallbackIdentityRequest:
     # explicit bootstrap protocol selection (see OnboardingWireProbeIntent).
     # ``None`` keeps today's passive-evidence-only behavior.
     bootstrap_probe: OnboardingWireProbeIntent | ObservedSessionWireProbeIntent | None = None
+    # Callback payload destination may differ from the local listener behind
+    # NAT. These are validated user settings, never inferred from the TCP peer.
+    advertised_server_ip: str = ""
+    advertised_tcp_port: int = 0
 
 
 @dataclass(frozen=True, slots=True)
@@ -370,8 +374,8 @@ async def async_send(self, request: CallbackIdentityRequest) -> None:
 
         await async_send_callback_trigger(
             bind_ip=request.server_ip,
-            advertised_server_ip=request.server_ip,
-            advertised_server_port=int(request.tcp_port),
+            advertised_server_ip=request.advertised_server_ip or request.server_ip,
+            advertised_server_port=int(request.advertised_tcp_port or request.tcp_port),
             target_ip=request.target_ip,
             udp_port=int(request.udp_port),
             timeout=DEFAULT_ONBOARDING_TIMEOUT_POLICY.discovery_timeout,

custom_components/eybond_local/flows/config/base.py

@@ -74,6 +74,9 @@ def __init__(self) -> None:
         self._default_broadcast = DEFAULT_DISCOVERY_TARGET
         self._interface_options: list[dict[str, str]] = []
         self._auto_config: dict[str, Any] = {}
+        # Explicit scan intent only; never inferred from TCP peers or stored as
+        # a second runtime route. Each selected collector still needs admission.
+        self._scan_known_collector_ips: tuple[str, ...] = ()
         self._manual_defaults: dict[str, Any] = {}
         self._manual_config: dict[str, Any] = {}
         self._manual_result: OnboardingResult | None = None

custom_components/eybond_local/flows/config/manual.py

@@ -200,6 +200,8 @@ async def _async_run_manual_callback_attempt(
                 old_session_id=identity_context.old_session_id,
                 owner_prefix="callback_verification",
                 bootstrap_probe=bootstrap_probe,
+                advertised_server_ip=str(settings.get(CONF_ADVERTISED_SERVER_IP) or "").strip(),
+                advertised_tcp_port=int(settings.get(CONF_ADVERTISED_TCP_PORT) or 0),
             ),
         )
         if not outcome.identity_certified: