fix: preserve learned Modbus write commands

Author: Maksym Shtembuliak

CHANGELOG.md

@@ -81,6 +81,13 @@ the GitHub release body should be rendered from the matching version section her
 
 ### Fixed
 
+- Newly learned Modbus controls retain the captured FC06 or FC16 write command
+  through profile generation and runtime dispatch. Incomplete, conflicting or
+  unrepresentable write shapes remain support evidence instead of guessed
+  controls. The SMG driver also honors explicit FC06 declarations in existing
+  profiles; FC16 remains the default when no override is declared. Older learned
+  profiles need a new learning run to regenerate their command metadata.
+
 - Collector connection settings remain reachable before the inverter is
   identified (#49). Unknown collector capabilities no longer imply a local-only
   ESP collector or hide callback diagnostics. Endpoint changes still require

custom_components/eybond_local/drivers/smg.py

@@ -680,6 +680,9 @@ async def async_write_capability(
                 encoded_word=int(raw_words[0]),
             )
             await session.write_holding(capability.register, [merged])
+        elif capability.write_function == 6:
+            for offset, word in enumerate(raw_words):
+                await session.write_single_holding(capability.register + offset, int(word))
         else:
             await session.write_holding(capability.register, raw_words)
 

custom_components/eybond_local/support/shadow_learning/overlay_generator.py

@@ -205,6 +205,7 @@ def generate_shadow_learning_overlay_drafts(
         "read_enum_bindings": read_enum_bindings,
         "learned_capabilities": list(learned_summary["generated"]),
         "skipped_duplicates": list(learned_summary["skipped"]),
+        "skipped_controls": list(learned_summary["rejected"]),
         # Read sensors materialized from unique value/enum correlations.
         "learned_read_sensors": list(learned_read["generated"]),
         "skipped_read_sensors": list(learned_read["skipped"]),
@@ -930,6 +931,7 @@ def _build_learned_capabilities(
     generated: list[dict[str, Any]] = []
     generated_summary: list[dict[str, Any]] = []
     skipped_summary: list[dict[str, Any]] = []
+    rejected_summary: list[dict[str, Any]] = []
 
     next_order = 9000
     for group in grouped:
@@ -976,6 +978,37 @@ def _build_learned_capabilities(
             )
             continue
 
+        write_contract = _observed_modbus_write_contract(group) if register >= 0 else None
+        if register >= 0 and write_contract is None:
+            rejected_summary.append(
+                {
+                    "field_id": field_id,
+                    "field_name": field_name,
+                    "register": register,
+                    "reason": "unproven_modbus_write_contract",
+                }
+            )
+            continue
+
+        classification = _classify_learned_control(group)
+        if write_contract is not None and (
+            write_contract[1] != 1
+            or classification["word_count"] != write_contract[1]
+        ):
+            # A multi-register cloud command must never become a truncated
+            # single-register switch/action merely because its labels look familiar.
+            # Numeric multiword captures also need a proven encoding before
+            # they can be represented by the runtime capability codec.
+            rejected_summary.append(
+                {
+                    "field_id": field_id,
+                    "field_name": field_name,
+                    "register": register,
+                    "reason": "unsupported_modbus_write_shape",
+                }
+            )
+            continue
+
         base_key = (
             _capability_key(field_id=field_id, field_name=field_name, register=register)
             if register >= 0
@@ -985,7 +1018,6 @@ def _build_learned_capabilities(
         existing_keys.add(capability_key)
 
         read_key = _g_ascii_read_key_for_group(group)
-        classification = _classify_learned_control(group)
         classification, command_map = _normalize_g_ascii_feature_flag_capability(
             group=group,
             classification=classification,
@@ -1024,6 +1056,8 @@ def _build_learned_capabilities(
             "order": next_order,
             "learned_provenance": provenance,
         }
+        if write_contract is not None:
+            capability["write_function"] = write_contract[0]
         next_order += 1
 
         minimum = classification.get("minimum")
@@ -1058,6 +1092,7 @@ def _build_learned_capabilities(
                 "field_id": field_id,
                 "field_name": field_name,
                 "register": register,
+                "write_function": capability.get("write_function"),
                 "command": command,
                 "command_map": capability.get("command_map", {}),
                 "read_key": read_key,
@@ -1068,7 +1103,40 @@ def _build_learned_capabilities(
             }
         )
 
-    return generated, {"generated": generated_summary, "skipped": skipped_summary}
+    return generated, {
+        "generated": generated_summary,
+        "skipped": skipped_summary,
+        "rejected": rejected_summary,
+    }
+
+
+def _observed_modbus_write_contract(group: dict[str, Any]) -> tuple[int, int] | None:
+    """Require one observed, representable function/width; never guess FC16.
+
+    Cloud metadata describes a setting, not the wire operation. Every correlated
+    sample must agree before the generated control is allowed to replay it.
+    Older/incomplete or conflicting evidence stays in the support artifacts.
+    """
+
+    contract: tuple[int, int] | None = None
+    for sample in group.get("samples") or []:
+        observation = sample["observation"]
+        function = observation.get("function_code")
+        values = observation.get("values")
+        if (
+            type(function) is not int
+            or function not in (6, 16)
+            or type(values) is not list
+            or len(values) not in (1, 2)
+            or any(type(value) is not int or not 0 <= value <= 0xFFFF for value in values)
+            or (function == 6 and len(values) != 1)
+        ):
+            return None
+        observed = (function, len(values))
+        if contract is not None and observed != contract:
+            return None
+        contract = observed
+    return contract
 
 
 def _group_matched_records(correlation: dict[str, Any]) -> list[dict[str, Any]]:
@@ -1114,12 +1182,10 @@ def _group_matched_records(correlation: dict[str, Any]) -> list[dict[str, Any]]:
                 "requested_at": str(item.get("requested_at") or "").strip(),
                 "observation": {
                     "register": register,
-                    "function_code": _to_int(observation.get("function_code")) or 16,
-                    "values": [
-                        int(value)
-                        for value in list(observation.get("values") or [])
-                        if _to_int(value) is not None
-                    ],
+                    # Preserve malformed/missing fields for fail-closed contract
+                    # validation rather than defaulting or dropping bad words.
+                    "function_code": observation.get("function_code"),
+                    "values": observation.get("values"),
                     "devcode": _to_int(observation.get("devcode")),
                     "devaddr": _to_int(observation.get("devaddr")),
                     "unit": _to_int(observation.get("unit")),

docs/user/DEVICE_LEARNING.md

@@ -228,6 +228,33 @@ If you are helping add support for a model:
 
 The Support Archive includes the relevant learning evidence.
 
+### Learning controls from SmartValue / ValueCloud
+
+For a supported Modbus inverter such as MUST PV3300, choose **Verify additional
+local controls** and **ValueCloud API**, using the account you use in SmartValue.
+The same endpoint-change and interception precautions above apply. The result
+can include controls missing from the built-in profile; it does not duplicate
+settings already provided by that profile or guarantee that every cloud control
+can be added.
+
+Select and apply the controls you want to try. Selected learned controls are
+available in Auto or Full Control; Read Only still blocks all writes. Learning
+identifies the local commands but blocks the test writes, so it does **not** prove
+that the real inverter accepted them. Tell the maintainer which controls you
+actually tested and share a fresh Support Archive afterward. You can also share
+the archive without applying any controls.
+
+An **Ongrid Switch** label does not by itself mean a complete inverter power
+switch. Check its actual effect separately, only when an interruption is safe
+and manual recovery is available. Do not assume that remote turn-on will remain
+possible after turning it off.
+
+New learned Modbus controls preserve the captured write-command type rather
+than substituting another one. Incomplete or conflicting captures stay support
+evidence instead of becoming writable controls. Previously generated local
+profiles are not rewritten by an update; rerun learning if you need to regenerate
+an older learned control with the corrected command type.
+
 ## If learning fails
 
 Common causes: