fix: model protocol 3 and 4 telemetry maps

Author: Maksym Shtembuliak

CHANGELOG.md

@@ -11,7 +11,8 @@ the GitHub release body should be rendered from the matching version section her
 
 - Added built-in detection and telemetry mapping for the Sandisolar SD 11KP48V
   WIFI fingerprint (`layout=4`, `model=0x8003`) from issue #13 evidence.
-  Compatible controls remain explicitly untested and Full-Control-only.
+  Its two hardware-confirmed Secondary Priority controls are available normally;
+  the other compatible controls remain explicitly untested and Full-Control-only.
 - Added a typed support-acquisition boundary so read-only cloud evidence can be
   collected for an identified collector before an inverter driver is known.
 - Added 118 opt-in, document-backed settings for the exact Kevolt
@@ -21,6 +22,11 @@ the GitHub release body should be rendered from the matching version section her
 
 ### Changed
 
+- Rebuilt the Anenji Protocol No. 3-10 telemetry layer as one documented shared
+  schema with separate Protocol 3 and Protocol 4 output projections. ANJ-11KW,
+  HHS-11kW and Sandisolar fingerprints now select registers by protocol identity,
+  never by a zero/non-zero value fallback, while ordinary SMG Protocol 1 devices
+  retain their existing map.
 - Moved device-support analysis and collector cloud-traffic capture under one
   **Expand device support** menu with separate readiness rules for read-only
   metadata, active learning, and proxy capture.
@@ -38,10 +44,10 @@ the GitHub release body should be rendered from the matching version section her
   challenge on the exact observed session, accepts only a correlated full-PN
   response, and never falls back to peer-IP routing. Unknown wire dialects are
   tried only on separate callback attempts and separate physical sockets.
-- Correct the Anenji HHS-11kW non-parallel Grid Power source for the exact
-  layout-3/model-29440 fingerprint: hardware-correlated cloud traffic reads
-  holding register 340, not the compatible-family register 204.
-
+- Corrected the canonical grid and inverter power projection for documented
+  Protocol 3/4 layouts. Grid Power now comes from holding register 340, with
+  protocol-specific output/load blocks; legacy total fields remain diagnostic
+  evidence rather than speculative runtime fallbacks.
 - Corrected the Kevolt PD0080G-TPM-EU rated-power scale from 80 kW to its
   hardware-confirmed 8 kW rating without changing the stable internal
   fingerprint key or its already-correct battery-value sign.

catalog/inverter_models/models/anenji_anj_11kw_48v_wifi_p.json

@@ -26,14 +26,14 @@
     "vendor_register_map": "documented",
     "notes": [
       "Device-specific runtime profile is user-confirmed.",
-      "Private Anenji Protocol No. 3-10 documentation backs a model-specific register map for this runtime family.",
+      "Communication Protocol No. 3-10 documentation defines the protocol-4 telemetry projection used by this model.",
       "Register 602 secondary-output priority is documented and hardware-read-correlated; local write behavior remains conditional pending a device retest."
     ]
   },
   "known_limitations": [
     "Secondary Output Priority writes are available only in Full Control until register 602 is write-tested on hardware."
   ],
-  "knowledge_summary": "Anenji 11kW unit with a model-specific profile and register schema, backed by donor captures, user-confirmed controls, and the Protocol No. 3-10 register documentation.",
+  "knowledge_summary": "Anenji 11kW unit with a model-specific control profile over the shared protocol-4 register projection, backed by donor captures, user-confirmed controls, and the Protocol No. 3-10 documentation.",
   "source_keys": [
     "corpus_anenji_anj_11kw",
     "private_message_anenji_anj_11kw_validation",

catalog/inverter_models/models/anenji_hhs_11kw_wifi_no_parallel.json

@@ -26,15 +26,15 @@
     "vendor_register_map": "documented",
     "notes": [
       "The exact layout/model fingerprint is captured from a beta.3 support archive.",
-      "The compatible protocol 3-10 telemetry schema is enabled read-only.",
-      "A later proxy capture and matching DESSMonitor export confirmed Grid Power at holding register 340 for this exact fingerprint.",
+      "The protocol-3 telemetry projection is enabled read-only.",
+      "A later proxy capture and matching DESSMonitor export confirmed the documented L1 Grid Power at holding register 340 for this exact fingerprint.",
       "No ANJ-11KW writable capability is inherited until this exact HHS model is write-validated."
     ]
   },
   "known_limitations": [
     "Local controls remain unavailable pending model-specific hardware validation."
   ],
-  "knowledge_summary": "An Anenji HHS 11kW non-parallel inverter with an exact captured protocol-3 fingerprint. The integration exposes its compatible telemetry schema read-only, including hardware-correlated Grid Power, and deliberately withholds ANJ write controls.",
+  "knowledge_summary": "An Anenji HHS 11kW non-parallel inverter with an exact captured protocol-3 fingerprint. The integration exposes the shared protocol-3 telemetry projection read-only, including hardware-correlated Grid Power, and deliberately withholds ANJ write controls.",
   "source_keys": [
     "github_issue_13_hhs_11kw_beta3",
     "github_issue_13_hhs_grid_power_20260827"

catalog/inverter_models/models/sandisolar_sd_11kp48v_wifi.json

@@ -18,24 +18,29 @@
   "validation": {
     "hardware": "captured",
     "telemetry": "partial",
-    "controls": "none"
+    "controls": "partial"
   },
   "coverage": {
     "runtime_control_surface": "available",
     "smartess_control_surface": "unknown",
     "vendor_register_map": "documented",
     "notes": [
       "The exact layout/model fingerprint is captured from the issue #13 beta.4 support archive.",
-      "Telemetry uses the documented Anenji protocol-4 register schema; this prevents generic SMG interpretation of register 227 as temperature.",
-      "The compatible ANJ write surface is inherited only as untested Full-Control candidates. Automatic control mode exposes none of these writes."
+      "Telemetry uses the documented protocol-4 projection; this prevents generic SMG interpretation of register 227 as temperature.",
+      "Canonical Grid and inverter power values use the protocol-4 L1 points. Legacy total fields remain available in support captures instead of acting as value-based fallbacks.",
+      "Secondary Charging Priority and Secondary Output Priority are hardware-confirmed on this exact fingerprint.",
+      "The remaining compatible ANJ write surface is inherited only as untested Full-Control candidates."
     ]
   },
   "known_limitations": [
-    "No local write has been validated on this exact Sandisolar fingerprint; every inherited control remains Full-Control-only until hardware retesting."
+    "Only Secondary Charging Priority and Secondary Output Priority have been hardware-validated; every other inherited control remains Full-Control-only until hardware retesting."
   ],
-  "knowledge_summary": "Sandisolar SD 11KP48V WIFI with exact layout-4/model-0x8003 identity. Captured telemetry follows the documented ANJ protocol-4 map, while compatible write candidates remain explicitly untested.",
+  "knowledge_summary": "Sandisolar SD 11KP48V WIFI with exact layout-4/model-0x8003 identity. Captured telemetry and protocol documentation select the shared protocol-4 projection, while compatible write candidates remain explicitly untested.",
   "source_keys": [
     "github_issue_13_sandisolar_sd_11kp48v_beta4",
-    "documentation_anenji_protocol_3_10"
+    "github_issue_13_sandisolar_grid_power_20260829",
+    "github_issue_13_sandisolar_secondary_controls_20260827",
+    "documentation_anenji_protocol_3_10",
+    "third_party_easun_smg_ii_11kw_register_map"
   ]
 }

catalog/inverter_models/sources/documentation_anenji_protocol_3_10.json

@@ -7,7 +7,7 @@
   "captured_at": "2026-06-19",
   "visibility": "private",
   "summary_publishable": true,
-  "summary": "Private local copy of Communication.Protocol.No.3-10.pdf, a 20-page Modbus RTU register document covering protocol numbers 3, 4, 5, and 6 for the ANJ-11KW runtime family.",
+  "summary": "Private local copy of Communication.Protocol.No.3-10.pdf, a Modbus RTU register document that distinguishes shared, total, and per-output points across protocol numbers 3, 4, 5, and 6 for the ANJ-11KW-compatible runtime family.",
   "assertions": [
     "register_map",
     "runtime_compatibility"

catalog/inverter_models/sources/github_issue_13_sandisolar_grid_power_20260829.json

@@ -0,0 +1,14 @@
+{
+  "schema_version": 1,
+  "source_key": "github_issue_13_sandisolar_grid_power_20260829",
+  "kind": "github_issue",
+  "title": "Sandisolar SD 11KP48V WIFI Grid Power correlation",
+  "reference": "project-issue:13",
+  "captured_at": "2026-08-29",
+  "visibility": "public",
+  "summary": "For the exact layout-4/model-0x8003 Sandisolar fingerprint, manufacturer-cloud screenshots and the inverter display showed non-zero Grid Power while the inherited register-204 projection remained zero in Home Assistant. This is supporting evidence that register 204 is not a usable canonical Grid Power source for this layout; the primary register-340 mapping comes from the protocol-4 documentation rather than from a same-instant raw correlation.",
+  "assertions": [
+    "telemetry_validation",
+    "register_map"
+  ]
+}

catalog/inverter_models/sources/github_issue_13_sandisolar_secondary_controls_20260827.json

@@ -0,0 +1,15 @@
+{
+  "schema_version": 1,
+  "source_key": "github_issue_13_sandisolar_secondary_controls_20260827",
+  "kind": "github_issue",
+  "title": "Sandisolar SD 11KP48V WIFI secondary-priority control validation",
+  "reference": "project-issue:13#sandisolar-secondary-priority-validation",
+  "captured_at": "2026-08-27",
+  "visibility": "public",
+  "summary": "The owner of the exact Sandisolar SD 11KP48V WIFI layout-4/model-0x8003 fingerprint confirmed that local writes and subsequent readback for Secondary Charging Priority and Secondary Output Priority both worked correctly. No other inherited write capability was validated by this report.",
+  "assertions": [
+    "hardware_test",
+    "write_validation",
+    "control_behavior"
+  ]
+}

catalog/inverter_models/sources/third_party_easun_smg_ii_11kw_register_map.json

@@ -0,0 +1,13 @@
+{
+  "schema_version": 1,
+  "source_key": "third_party_easun_smg_ii_11kw_register_map",
+  "kind": "third_party_impl",
+  "title": "Easun SMG II 11kW register map implementation",
+  "reference": "https://github.com/alcestide/easun-smg-ii-11kw",
+  "captured_at": "2026-08-29",
+  "visibility": "public",
+  "summary": "An independent compatible implementation maps holding register 340 to signed L1 Grid Active Power and marks it applicable to protocol layouts 3, 4, 5, and 6. Its register 204 Total Grid Active Power entry is not marked applicable to those layouts.",
+  "assertions": [
+    "register_map"
+  ]
+}

custom_components/eybond_local/drivers/smg.py

@@ -499,14 +499,6 @@ async def async_read_values(
         config_block = await session.read_holding(config_block_start, config_block_count)
         values.update(_decode_block(config_block_start, config_block, config_fields))
         values.update(await _read_optional_specs(session, aux_config_fields))
-        # Exact model overlays may correct a value inherited from a compatible
-        # family schema.  Remove the inherited projection before the optional
-        # read so a failed model-specific read is reported as unavailable,
-        # never as a plausible value from the wrong register.
-        value_overrides = schema.spec_sets.get("value_overrides", ())
-        for spec in value_overrides:
-            values.pop(spec.key, None)
-        values.update(await _read_optional_specs(session, value_overrides))
         missing_probe_details = await _read_missing_optional_probe_details(session, inverter)
         if missing_probe_details:
             inverter.details.update(missing_probe_details)

custom_components/eybond_local/metadata/register_schema_loader.py

@@ -462,6 +462,15 @@ def _merge_raw_schema(
         **base.get("scalar_registers", {}),
         **overlay.get("scalar_registers", {}),
     }
+    merged["spec_sets"] = _remove_spec_set_items(
+        merged["spec_sets"],
+        overlay.get("spec_set_removals", {}),
+    )
+    merged["measurement_descriptions"] = _remove_keyed_items(
+        merged["measurement_descriptions"],
+        overlay.get("measurement_description_removals", []),
+        key_field="key",
+    )
 
     for key, value in overlay.items():
         if key in {
@@ -472,6 +481,8 @@ def _merge_raw_schema(
             "enum_tables",
             "bit_labels",
             "scalar_registers",
+            "spec_set_removals",
+            "measurement_description_removals",
         }:
             continue
         merged[key] = value
@@ -502,6 +513,45 @@ def _merge_nested_maps(
     return merged
 
 
+def _remove_spec_set_items(
+    spec_sets: Mapping[str, list[dict[str, Any]]],
+    removals: Any,
+) -> dict[str, list[dict[str, Any]]]:
+    """Remove inherited specs explicitly named by a declarative overlay."""
+
+    merged = {key: [dict(item) for item in value] for key, value in spec_sets.items()}
+    if not isinstance(removals, Mapping):
+        raise ValueError("register_schema:spec_set_removals_must_be_mapping")
+    for set_key, removed_keys in removals.items():
+        if not isinstance(removed_keys, list) or any(
+            type(item) is not str or not item or item != item.strip()
+            for item in removed_keys
+        ):
+            raise ValueError(f"register_schema:invalid_spec_set_removals:{set_key}")
+        removed = set(removed_keys)
+        merged[str(set_key)] = [
+            item for item in merged.get(str(set_key), []) if item.get("key") not in removed
+        ]
+    return merged
+
+
+def _remove_keyed_items(
+    items: list[Mapping[str, Any]],
+    removed_keys: Any,
+    *,
+    key_field: str,
+) -> list[dict[str, Any]]:
+    """Remove inherited keyed records explicitly named by an overlay."""
+
+    if not isinstance(removed_keys, list) or any(
+        type(item) is not str or not item or item != item.strip()
+        for item in removed_keys
+    ):
+        raise ValueError(f"register_schema:invalid_{key_field}_removals")
+    removed = set(removed_keys)
+    return [dict(item) for item in items if item.get(key_field) not in removed]
+
+
 def _merge_keyed_list(
     base: list[Mapping[str, Any]],
     overlay: list[Mapping[str, Any]],