Merge pull request #55 from txau/feat/sumry-ges-7530-identity

feat: bind Anenji GES48120 to Sumry/GES 0x7530 via identity anchors

Author: groove-max

CHANGELOG.md

@@ -9,10 +9,10 @@ the GitHub release body should be rendered from the matching version section her
 
 ### Added
 
-- Recorded Anenji GES48120M250-500P / Sumry-style register evidence and an
-  offline-tested read-only subset (#49). This is a research catalog entry,
-  not automatic device support: model/class identification still needs a
-  confirmed response. No additional live probes or controls are enabled.
+- Anenji GES48120M250-500P auto-binds through exact Sumry/GES identity anchors
+  (model 45, product class 10, protocol raw 220) and exposes the existing
+  nine-field read-only 0x7530 subset (#49, #55). Broader telemetry, derived
+  power totals and controls remain out of scope.
 
 - Victor NM-PRO-6.2KW in the supported model catalog, backed by the owner's
   PI30 archive and specifically reported working controls. It reuses the

catalog/inverter_models/models/anenji_ges48120m250_500p.json

@@ -4,36 +4,40 @@
   "manufacturer": "Anenji",
   "model": "GES48120M250-500P",
   "aliases": ["Anenji white 12kW split-phase"],
-  "lifecycle": "research",
+  "lifecycle": "experimental",
   "variants": [
     {
-      "variant_key": "sumry_ges_7530_unqualified_identity",
-      "label": "0x7530 telemetry observed; automatic identity not qualified",
-      "device_descriptor_keys": [],
-      "known_firmware": []
+      "variant_key": "sumry_ges_7530",
+      "label": "Sumry/GES 0x7530 map, model 45 / class 10 / protocol 220",
+      "device_descriptor_keys": ["anenji_ges48120m250_500p"],
+      "known_firmware": ["protocol raw 220 (0x00DC at 0xC768)"]
     }
   ],
-  "validation": {"hardware": "captured", "telemetry": "partial", "controls": "none"},
+  "validation": {
+    "hardware": "captured",
+    "telemetry": "partial",
+    "controls": "none"
+  },
   "coverage": {
     "runtime_control_surface": "none",
     "smartess_control_surface": "unknown",
     "vendor_register_map": "partial",
     "notes": [
-      "CRC-valid owner FC03 replies corroborate battery and phase-A output/mains voltage, current and frequency locations in the community-hosted V2.6.3 PDF.",
-      "A small read-only schema is retained for offline replay only; no runtime descriptor, detection action or model-selection bypass enables it.",
-      "The owner's fork reports screen agreement, but voltage/SOC plausibility is not family identity. Model/class registers 0xC738/0xC739 have not been captured."
+      "Runtime binding requires three exact FC03 identity anchors on holding registers 0xC738-0xC739 and 0xC768: model code 45, product class 10, protocol version raw 220.",
+      "The bound read-only surface exposes nine phase-A and battery measurements from 0x7530, 0x7548 and 0x756A only; no derived power totals or write profile.",
+      "CRC-valid owner captures corroborate battery and phase-A output/mains voltage, current and frequency in the community-hosted V2.6.3 PDF."
     ]
   },
   "known_limitations": [
-    "Automatic detection remains unsupported pending a qualified model/class fingerprint; the PDF gives no GES-specific model-code value.",
-    "Split-phase second-leg, active-power direction, CT and temperature-location semantics are not qualified by the available raw evidence.",
-    "No derived power totals, inferred watts from AC voltage/current, controls or write profiles are exposed.",
-    "The protocol PDF is community-hosted, not independently authenticated supplier documentation."
+    "Split-phase second leg, PV, CT-only grid semantics, temperatures and active-power registers are not part of this read-only subset.",
+    "Product class 10 is required for this entry; other PDF enum values must not select this descriptor.",
+    "The protocol PDF is community-hosted, not independently authenticated supplier documentation.",
+    "No controls or write profiles are exposed."
   ],
-  "knowledge_summary": "Issue #49 establishes an Anenji GES48120M250-500P answering the Sumry/GES-style 0x7530 holding-register map, not the low-address SMG map. Battery and phase-A telemetry have a source-backed offline decoder. The public fork is useful corroboration, not a safe automatic binding: immutable model/class values and split-phase semantics remain unresolved. This research record does not claim runtime support.",
+  "knowledge_summary": "Anenji GES48120M250-500P answers the Sumry/GES-style high-address holding map at 0x7530, not the low-address SMG map. Owner FC03 captures establish model 45, product class 10 and protocol 220 together with corroborated battery and phase-A telemetry. The integration exposes a small read-only runtime surface gated on all three identity anchors.",
   "source_keys": [
     "issue_49_ges_7530_read_evidence",
-    "community_ges_modbus_v263",
-    "issue_49_txau_fork_a4125af"
+    "issue_49_ges_identity_capture",
+    "community_ges_modbus_v263"
   ]
 }

catalog/inverter_models/sources/issue_49_ges_7530_read_evidence.json

@@ -6,6 +6,6 @@
   "reference": "project-issue:49; project-comment:5881202245; project-comment:5881411950",
   "captured_at": "2026-10-02",
   "visibility": "public",
-  "summary": "Owner identifies the white 12kW split-phase unit as GES48120M250-500P. Raw slave-1 FC03 replies at 0x7530, 0x7548 and 0x756A pass CRC and length checks. Battery voltage 51.5 V, SOC 65%, phase-A output 122.9 V and mains 122.7 V agree with the community protocol. No 0xC738/0xC739 model/class response is supplied; successful telemetry alone does not qualify automatic binding.",
+  "summary": "Owner identifies the white 12kW split-phase unit as GES48120M250-500P. Raw slave-1 FC03 replies at 0x7530, 0x7548 and 0x756A pass CRC and length checks. Battery voltage 51.5 V, SOC 65%, phase-A output 122.9 V and mains 122.7 V agree with the community protocol. Identity registers 0xC738/0xC739 and 0xC768 are captured separately in issue_49_ges_identity_capture.",
   "assertions": ["commercial_identity", "register_map", "telemetry_validation"]
 }

catalog/inverter_models/sources/issue_49_ges_identity_capture.json

@@ -0,0 +1,11 @@
+{
+  "schema_version": 1,
+  "source_key": "issue_49_ges_identity_capture",
+  "kind": "github_comment",
+  "title": "Issue #49 GES48120M250-500P FC03 identity registers",
+  "reference": "project-issue:49; project-comment:5953299167",
+  "captured_at": "2026-10-02",
+  "visibility": "public",
+  "summary": "Owner slave-1 FC03 reads at 0xC738 (2 words) and 0xC768 (1 word) pass CRC checks. Model code 45 (0x002D), product class 10 (0x000A), protocol version raw 220 (0x00DC). Together with the existing 0x7530 telemetry captures these anchors qualify automatic read-only binding for this unit.",
+  "assertions": ["register_map", "fingerprint", "telemetry_validation"]
+}

custom_components/eybond_local/protocol_catalogs/inverter_catalog.json

@@ -930,6 +930,46 @@
       {"key": "identity.hopewind_switch", "source_key": "hopewind_switch", "register": 40546},
       {"key": "identity.hopewind_state", "source_key": "hopewind_state", "register": 40547}
      ]
+    },
+    {
+     "key": "modbus_catalog.sumry_ges_identity_model_class",
+     "kind": "modbus_read",
+     "register": 51000,
+     "count": 2,
+     "function": 3,
+     "cost": 1,
+     "optional": true,
+     "evidence_fields": [
+      {
+       "key": "identity.sumry_ges_model_code",
+       "source_key": "sumry_ges_model_code",
+       "register": 51000,
+       "words": 1
+      },
+      {
+       "key": "identity.sumry_ges_product_class",
+       "source_key": "sumry_ges_product_class",
+       "register": 51001,
+       "words": 1
+      }
+     ]
+    },
+    {
+     "key": "modbus_catalog.sumry_ges_identity_protocol",
+     "kind": "modbus_read",
+     "register": 51048,
+     "count": 1,
+     "function": 3,
+     "cost": 1,
+     "optional": true,
+     "evidence_fields": [
+      {
+       "key": "identity.sumry_ges_protocol_version",
+       "source_key": "sumry_ges_protocol_version",
+       "register": 51048,
+       "words": 1
+      }
+     ]
     }
    ],
    "layouts": [],
@@ -1206,6 +1246,33 @@
     "Support capture uses protocol_catalogs/command_schemas/eybond_g_ascii/base.json as the schema-driven read-only command probe plan. Captured unknown fields are maintainer evidence only until the schema/driver decoder is explicitly updated."
    ]
   },
+  "sumry_ges_7530": {
+   "ranges": [
+    [
+     30000,
+     3
+    ],
+    [
+     30024,
+     3
+    ],
+    [
+     30058,
+     3
+    ],
+    [
+     51000,
+     2
+    ],
+    [
+     51048,
+     1
+    ]
+   ],
+   "notes": [
+    "Anenji GES48120M250-500P Sumry/GES map: read-only FC03 telemetry at 0x7530/0x7548/0x756A plus identity holding registers 0xC738-0xC739 (model/class) and 0xC768 (protocol version raw 220). Modbus RTU 9600 8N1, slave 1."
+   ]
+  },
   "aohai_fsa": {
    "ranges": [
     [
@@ -1813,6 +1880,17 @@
    "default_for_driver": true,
    "support_capture_policy": "aohai_fsa"
   },
+  {
+   "key": "sumry_ges_7530_read_only",
+   "protocol_key": "modbus_catalog",
+   "driver_key": "modbus_catalog",
+   "variant_key": "sumry_ges_7530",
+   "profile_name": "",
+   "register_schema_name": "sumry_ges_7530/base.json",
+   "tier": "partial",
+   "read_only": true,
+   "support_capture_policy": "sumry_ges_7530"
+  },
   {
    "key": "growatt_spf_untested",
    "protocol_key": "modbus_catalog",
@@ -3123,6 +3201,39 @@
     "confidence": "documented-read-only"
    }
   },
+  {
+   "entry_key": "anenji_ges48120m250_500p",
+   "surface_key": "sumry_ges_7530_read_only",
+   "model_name": "Anenji GES48120M250-500P (Sumry/GES 0x7530)",
+   "aliases": [
+    "Anenji white 12kW split-phase"
+   ],
+   "priority": 115,
+   "anchors": [
+    {
+     "key": "identity.sumry_ges_model_code",
+     "equals": 45,
+     "cost": 1
+    },
+    {
+     "key": "identity.sumry_ges_product_class",
+     "equals": 10,
+     "cost": 1
+    },
+    {
+     "key": "identity.sumry_ges_protocol_version",
+     "equals": 220,
+     "cost": 1
+    }
+   ],
+   "provenance": {
+    "sources": [
+     "GitHub issue #49 owner capture: FC03 0xC738/0xC739 model 45 product class 10, 0xC768 protocol 220, and CRC-valid 0x7530 telemetry",
+     "community Sumry/GES inverter Modbus protocol V2.6.3 (quky PDF)"
+    ],
+    "confidence": "capture-confirmed-read-only"
+   }
+  },
   {
    "entry_key": "hopewind_0237_family",
    "surface_key": "hopewind_0237_untested_controls",

custom_components/eybond_local/protocol_catalogs/register_schemas/sumry_ges_7530/base.json

@@ -1,6 +1,6 @@
 {
   "schema_key": "sumry_ges_7530_evidence_subset",
-  "title": "Sumry/GES 0x7530 evidence subset (not enabled for detection)",
+  "title": "Sumry/GES 0x7530 read-only telemetry subset",
   "driver_key": "modbus_catalog",
   "protocol_family": "sumry_ges_7530",
   "blocks": [

docs/README.md

@@ -39,7 +39,7 @@ If you are extending or maintaining the project, use [../CONTRIBUTING.md](../CON
 ## Architecture and design references
 
 - [SMG Protocol Maps](architecture/SMG_PROTOCOL_MAPS.md) — evidence, independent protocol branches, generic controls, and model-specific overrides.
-- [Sumry/GES 0x7530 Qualification](architecture/SUMRY_GES_7530.md) — offline read-only evidence subset, blocked automatic identity, and the specific missing diagnostic reads.
+- [Sumry/GES 0x7530 Qualification](architecture/SUMRY_GES_7530.md) — exact-match read-only binding for Anenji GES48120, nine-field subset, and remaining telemetry/control limits.
 - [Collector Connection Architecture](architecture/CONNECTION_ARCHITECTURE.md) — maintainer reference for the connection axes, session/PN ownership, `callback_on_demand`, endpoint ownership rules, and what must not be reintroduced.
 - [Cloud Learning Architecture](architecture/CLOUD_LEARNING_ARCHITECTURE.md) — provider-neutral learning methods, typed API sources, trust boundaries, and read-only metadata evidence.
 - [Typed Telemetry Migration](architecture/TYPED_TELEMETRY.md) — staged replacement of the broad runtime value mapping with a strict measurement contract.