feat: add document-backed SMG write profiles

Author: Maksym Shtembuliak

CHANGELOG.md

@@ -9,6 +9,11 @@ the GitHub release body should be rendered from the matching version section her
 
 ### Added
 
+- Added version-specific, document-backed write profiles for Anenji
+  Communication Protocol No. 3-10 variants 3, 4, 5, and 6. The exact HHS-11kW
+  Protocol 3 fingerprint can now opt into its documented controls through Full
+  Control; all new controls remain untested, and destructive reset/counter-clear
+  operations stay blocked.
 - Added built-in detection and telemetry mapping for the Sandisolar SD 11KP48V
   WIFI fingerprint (`layout=4`, `model=0x8003`) from issue #13 evidence.
   Its two hardware-confirmed Secondary Priority controls are available normally;
@@ -22,6 +27,12 @@ the GitHub release body should be rendered from the matching version section her
 
 ### Changed
 
+- Replaced the ambiguous writable `modbus_smg/base.json` profile with one
+  explicit, document-backed classic SMG RS232 V1 map shared by compatible
+  layout 1/2/11 model profiles. Exact hardware overlays retain their existing
+  tested controls and model-only registers, while unknown SMG fingerprints
+  remain read-only. The V1 document version is no longer presented as proof
+  that register 184 must contain protocol number 1.
 - 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,

catalog/inverter_models/models/anenji_4200_protocol_1.json

@@ -28,9 +28,9 @@
   "coverage": {
     "runtime_control_surface": "device_scoped_overlay",
     "smartess_control_surface": "device_scoped_overlay",
-    "vendor_register_map": "unknown",
+    "vendor_register_map": "documented",
     "notes": [
-      "Base runtime profile exposes the standard ANJ-4200/SMG Protocol 1 surface.",
+      "The common runtime surface comes from the documented classic SMG RS232 V1 map; the observed register-184 value 1 is separate runtime identity evidence.",
       "Full cloud shadow-learning correlated 77 cloud write attempts and activated eight device-scoped learned controls; writes were captured but intentionally not applied."
     ]
   },
@@ -40,6 +40,7 @@
   ],
   "knowledge_summary": "Anenji 4200 Protocol 1 variant has user support captures from an ANJ-4000W-24V device. Runtime detection resolves exactly to the SMG Protocol 1 surface, read telemetry is confirmed, and a full shadow-learning run mapped the SmartESS 0925 write surface without leaking writes to the real inverter. Treat controls as partial until specific Home Assistant writes are user-validated.",
   "source_keys": [
+    "documentation_classic_smg_rs232_v1",
     "note_anenji_4200_rule_migration",
     "github_issue_9",
     "support_archive_issue_9_20260619",

catalog/inverter_models/models/anenji_6200_single_output.json

@@ -25,16 +25,17 @@
   "coverage": {
     "runtime_control_surface": "available",
     "smartess_control_surface": "unknown",
-    "vendor_register_map": "unknown",
+    "vendor_register_map": "documented",
     "notes": [
-      "Runtime write surface is inherited from the shared SMG base profile; not every write is independently validated on this commercial unit."
+      "Runtime writes inherit the documented classic SMG RS232 V1 surface; not every write is independently validated on this commercial unit."
     ]
   },
   "known_limitations": [
     "Controls inherit the SMG 6200 control set; not every writable setting is independently confirmed on this unit."
   ],
   "knowledge_summary": "Anenji single-output 6200 (layout 1) bound to the shared SMG base surface; same control set as the verified SMG 6200.",
   "source_keys": [
+    "documentation_classic_smg_rs232_v1",
     "corpus_anenji_6200_single"
   ]
 }

catalog/inverter_models/models/anenji_anj_6200_48pl.json

@@ -23,16 +23,17 @@
   "coverage": {
     "runtime_control_surface": "available",
     "smartess_control_surface": "unknown",
-    "vendor_register_map": "unknown",
+    "vendor_register_map": "documented",
     "notes": [
-      "Runtime write surface is shared with SMG 6200; write behavior is not independently confirmed on this commercial unit."
+      "Runtime writes use the documented classic SMG RS232 V1 surface plus the SMG 6200 model overlay; write behavior is not independently confirmed on this commercial unit."
     ]
   },
   "known_limitations": [
     "Shares the SMG 6200 runtime surface; writes are not independently hardware-confirmed on this unit."
   ],
   "knowledge_summary": "SMG layout 2 model that reuses the SMG 6200 runtime surface; reported via a GitHub issue and a support capture.",
   "source_keys": [
+    "documentation_classic_smg_rs232_v1",
     "github_issue_8",
     "support_archive_anj6200_48pl"
   ]

catalog/inverter_models/models/anenji_hhs_11kw_wifi_no_parallel.json

@@ -18,25 +18,27 @@
   "validation": {
     "hardware": "captured",
     "telemetry": "partial",
-    "controls": "none"
+    "controls": "partial"
   },
   "coverage": {
-    "runtime_control_surface": "read_only",
+    "runtime_control_surface": "available",
     "smartess_control_surface": "unknown",
     "vendor_register_map": "documented",
     "notes": [
       "The exact layout/model fingerprint is captured from a beta.3 support archive.",
-      "The protocol-3 telemetry projection is enabled read-only.",
+      "The exact fingerprint uses the documented Protocol 3 telemetry and write matrices.",
       "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."
+      "Documented Protocol 3 controls are available only after the user explicitly selects Full Control; none is marked hardware-tested on this model.",
+      "Registers whose protocol-number column is empty, and Protocol 4/6-only OP2 controls, are not inherited."
     ]
   },
   "known_limitations": [
-    "Local controls remain unavailable pending model-specific hardware validation."
+    "No local write has been hardware-validated on this exact model; Auto mode remains read-only and the documented controls are experimental Full-Control candidates."
   ],
-  "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.",
+  "knowledge_summary": "An Anenji HHS 11kW non-parallel inverter with an exact captured Protocol 3 fingerprint. The integration exposes the shared telemetry projection, including hardware-correlated Grid Power, and offers only the controls explicitly valid for Protocol 3 as untested Full-Control candidates.",
   "source_keys": [
     "github_issue_13_hhs_11kw_beta3",
-    "github_issue_13_hhs_grid_power_20260827"
+    "github_issue_13_hhs_grid_power_20260827",
+    "documentation_anenji_protocol_3_10"
   ]
 }

catalog/inverter_models/models/aninerel_6200_dual_output.json

@@ -44,6 +44,7 @@
   ],
   "knowledge_summary": "Aninerel dual-output 6200 / Aninerel 6.2KW resolves to the OP2 6200 runtime surface (layout 11, model code 30979, rated 6200, firmware 7903_A6260126v1). The aninerel.zip donor capture and the issue #7 support package are treated as the same shared OP2 model family unless a future stable runtime anchor proves otherwise. Owner ESPHome YAML and shadow-learning evidence extend the known Modbus register map for this family.",
   "source_keys": [
+    "documentation_classic_smg_rs232_v1",
     "github_issue_7",
     "corpus_aninerel_op2_6200",
     "private_message_op2_registers",

catalog/inverter_models/models/aninerel_anl_4200t_24l_w_pro.json

@@ -23,9 +23,9 @@
   "coverage": {
     "runtime_control_surface": "available",
     "smartess_control_surface": "cloud_catalog",
-    "vendor_register_map": "unknown",
+    "vendor_register_map": "documented",
     "notes": [
-      "Binds a model-specific full-control surface (no longer the read-only family fallback). The family-proven SMG control set ships tested (visible in the default control mode); the family's unverified extras stay untested (full-control only).",
+      "Binds a model-specific full-control surface over the documented classic SMG RS232 V1 map (no longer the read-only family fallback). Hardware-tested controls are visible in the default control mode; unverified controls stay full-control only.",
       "A tester confirmed writes on hardware (2026-07-05); battery-voltage setpoint windows are left wide because this is a 24 V unit and the family templates carry 48 V-class windows, so the inverter's own write validation is the authority."
     ]
   },
@@ -35,6 +35,7 @@
   ],
   "knowledge_summary": "Aninerel ANL-4200T-24L-W-PRO reported via GitHub issue #3 and donor captures. It resolves exactly (SMG layout code 11) and binds a model-specific full-control surface: the family-proven SMG settings (output/charge source priority, battery voltage windows, charge-current limits, buzzer/LCD/input mode, boot mode) ship tested and a tester confirmed writes on hardware; the family's unverified extras (exit-fault action, output-rating/mode, power-saving, overload-bypass, remote turn-on/shutdown) stay untested and appear only in full control.",
   "source_keys": [
+    "documentation_classic_smg_rs232_v1",
     "github_issue_3",
     "corpus_aninerel_anl_4200t"
   ]

catalog/inverter_models/models/sandisolar_sd_hym_4862hwp.json

@@ -33,6 +33,7 @@
   "known_limitations": [],
   "knowledge_summary": "Maintainer's Sandisolar SD-HYM-4862HWP resolves to runtime descriptor smg_6200 via local SMG identity anchors: register 171 device_type/model_code=0x1E00 (7680), register 184 protocol/layout=1, and register 643 rated_power=6200. The local SMG register set does not expose the commercial model name, so the Sandisolar mapping is hardware/source-backed rather than register-name-backed. Full telemetry, the original SMG control set, and five cloud shadow-learning controls (304, 322, 330, 338, 425) are validated on this hardware; destructive actions 460 and 461 remain excluded.",
   "source_keys": [
+    "documentation_classic_smg_rs232_v1",
     "maintainer_sandisolar_sd_hym_4862hwp_hardware",
     "support_archive_sandisolar_shadow_learning_20260618"
   ]

catalog/inverter_models/sources/documentation_classic_smg_rs232_v1.json

@@ -0,0 +1,15 @@
+{
+  "schema_version": 1,
+  "source_key": "documentation_classic_smg_rs232_v1",
+  "kind": "documentation",
+  "title": "Classic SMG Modbus RTU RS232 protocol V1.0",
+  "reference": "https://github.com/syssi/esphome-smg-ii/blob/main/docs/SMG-RS232%2BCommunication%2BProtocol%2BV1.0.1.pdf",
+  "captured_at": "2026-08-30",
+  "visibility": "public",
+  "summary_publishable": true,
+  "summary": "Public copy of the November 2021 classic SMG Modbus RTU RS232 register document. It defines the shared telemetry and writable configuration map used by the classic SMG runtime family. The document calls register 184 invalid data, so observed values 1, 2, and 11 remain runtime layout evidence rather than being inferred from the document version.",
+  "assertions": [
+    "register_map",
+    "runtime_compatibility"
+  ]
+}

custom_components/eybond_local/control_policy.py

@@ -107,6 +107,8 @@ def can_expose_capability(
 ) -> bool:
     """Return whether a capability should be exposed as a control entity."""
 
+    if capability.resolved_support_tier == "blocked":
+        return False
     if control_mode == CONTROL_MODE_FULL:
         return True
     if control_mode == CONTROL_MODE_READ_ONLY:
@@ -125,6 +127,10 @@ def can_expose_preset(
 ) -> bool:
     """Return whether a preset should be exposed as a control entity."""
 
+    for item in preset.items:
+        capability = capabilities_by_key.get(item.capability_key)
+        if capability is None or capability.resolved_support_tier == "blocked":
+            return False
     if control_mode == CONTROL_MODE_FULL:
         return True
     if control_mode == CONTROL_MODE_READ_ONLY: