fix: qualify MUST controls and capture optional BMS evidence

Author: Maksym Shtembuliak

CHANGELOG.md

@@ -9,6 +9,10 @@ the GitHub release body should be rendered from the matching version section her
 
 ### Added
 
+- MUST PV3300 Support Archives can collect the optional documented BMS/SOC
+  block with one bounded read. This is diagnostic evidence only; normal polling
+  and sensor exposure are unchanged until firmware support is confirmed.
+
 - 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
@@ -57,6 +61,11 @@ the GitHub release body should be rendered from the matching version section her
 
 ### Fixed
 
+- MUST PV/PH18 controls no longer claim local write verification based only on
+  cloud-catalog presence. All 27 document-backed controls require Full Control;
+  the 20 previously shown in Auto are now correctly untested. No inverter
+  settings are changed automatically; review automations using those controls.
+
 - 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.

catalog/inverter_models/models/must_pv18_3024.json

@@ -30,7 +30,7 @@
     "vendor_register_map": "partial",
     "notes": [
       "Runtime support uses the MUST PH RS485 map (v1.4.3 and v1.4.15 xlsx, cross-checked against the third-party implementation), with per-control read-back over gap-free register blocks.",
-      "The control surface is cross-referenced from the SmartESS cloud device_settings field catalog and the vendor 1.4.15 register map: the 20 fields the cloud exposes ship tested (visible in the default control mode); datasheet-only settings absent from the cloud catalog (grid charging and the battery-equalization block) ship untested (full-control only).",
+      "All 27 controls are document-backed but locally unverified, available only in Full Control. Presence in the SmartESS cloud settings catalog is not a local hardware write test; the former tested flags for 20 cloud-visible fields were withdrawn.",
       "The register map is documentary; hardware write confirmation is still pending a tester report. The inverter validates its own writes, so a register that is absent or locked self-disables via the write-failure block."
     ]
   },

catalog/inverter_models/models/must_pv3300.json

@@ -28,11 +28,12 @@
     "smartess_control_surface": "cloud_catalog",
     "vendor_register_map": "partial",
     "notes": [
-      "Inherits the existing MUST control profile unchanged.",
+      "Inherits all 27 document-backed MUST controls as untested, available only in Full Control; cloud visibility does not prove local writes on this firmware.",
       "Whole-percent load and battery/grid direction normalization are qualified by the PV3300 local marker, not by the retail label or live power magnitude."
     ]
   },
   "known_limitations": [
+    "SOC is not yet exposed. Support Archives can check the vendor-documented optional BMS register block, but its availability on this firmware is unconfirmed.",
     "Learned maps tied to the older generic MUST schema are not automatically rebased; existing compatibility checks remain in force.",
     "Output Current and Inverter Load Current can remain zero on the reported unit; their meaning is still under investigation.",
     "Other PV/PH/EP models retain the common register interpretation because published MUST documents disagree on load-percentage units.",

custom_components/eybond_local/drivers/must.py

@@ -1,4 +1,4 @@
-"""MUST PV/PH18 Modbus RTU read-only driver."""
+"""MUST PV/PH18 telemetry and document-backed, unverified local controls."""
 
 from __future__ import annotations
 
@@ -31,6 +31,7 @@
 
 
 _MODEL_PREFIXES = ("PV", "PH", "EP")
+_BMS_DIAGNOSTIC_TIMEOUT_SECONDS = 3.0
 
 
 class MustPvPh18Driver(ModbusWriteErrorMixin, InverterDriver):
@@ -254,6 +255,21 @@ async def async_capture_support_evidence(
                     source="PH/PV Modbus 1.4.3 and protocol 1916 current registers",
                     purpose="support_only_zero_bulk_current_single_read_comparison",
                 )
+            # The vendor's 6422/1916 map describes a separate optional BMS
+            # window (voltage/current/temperature/reserved/SOC). Its presence
+            # on this firmware is not yet confirmed. Archive-only, one bounded
+            # read, no runtime schema/identity/fixture promotion or SOC guess.
+            current_status = evidence.get("current_read_diagnostics", {}).get("status", "completed")
+            if current_status == "completed":
+                evidence["bms_read_diagnostics"] = await capture_support_reads(
+                    session,
+                    ((109, 5, "bms_soc_candidate"),),
+                    timeout_seconds=_BMS_DIAGNOSTIC_TIMEOUT_SECONDS,
+                    source="Manufacturer protocol 6422 (1916), FC03 BMS registers 109-113",
+                    purpose="support_only_optional_bms_soc_availability",
+                )
+            else:
+                evidence["bms_read_diagnostics"] = {"status": "skipped_after_current_read_failure"}
         return evidence
 
     def local_register_read_plans(

custom_components/eybond_local/protocol_catalogs/profiles/must_pv_ph18/base.json

@@ -46,7 +46,7 @@
       "provenance": "doc_backed",
       "support_notes": "From PH PV RS485 Modbus RTU 1.4.3 xlsx; the SmartESS cloud exposes this control in its device settings for this model, awaiting on-hardware write confirmation.",
       "enabled_default": true,
-      "tested": true
+      "tested": false
     },
     {
       "key": "power_save_mode",
@@ -60,7 +60,7 @@
       "provenance": "doc_backed",
       "support_notes": "From PH PV RS485 Modbus RTU 1.4.3 xlsx; the SmartESS cloud exposes this control in its device settings for this model, awaiting on-hardware write confirmation.",
       "enabled_default": true,
-      "tested": true
+      "tested": false
     },
     {
       "key": "grid_charge_enable",
@@ -107,7 +107,7 @@
         }
       ],
       "enabled_default": true,
-      "tested": true
+      "tested": false
     },
     {
       "key": "grid_max_charge_current",
@@ -126,7 +126,7 @@
       "provenance": "doc_backed",
       "support_notes": "From PH PV RS485 Modbus RTU 1.4.3 xlsx; the SmartESS cloud exposes this control in its device settings for this model, awaiting on-hardware write confirmation.",
       "enabled_default": true,
-      "tested": true
+      "tested": false
     },
     {
       "key": "max_combined_charge_current",
@@ -145,7 +145,7 @@
       "provenance": "doc_backed",
       "support_notes": "From PH PV RS485 Modbus RTU 1.4.3 xlsx; the SmartESS cloud exposes this control in its device settings for this model, awaiting on-hardware write confirmation.",
       "enabled_default": true,
-      "tested": true
+      "tested": false
     },
     {
       "key": "inverter_output_voltage",
@@ -164,7 +164,7 @@
       "provenance": "doc_backed",
       "support_notes": "From PH1800/PV1800/EP1800/PV3500/EP3500 RS485 Modbus RTU 1.4.15 xlsx; the SmartESS cloud exposes this control in its device settings for this model, awaiting on-hardware write confirmation.",
       "enabled_default": true,
-      "tested": true
+      "tested": false
     },
     {
       "key": "inverter_output_frequency",
@@ -192,7 +192,7 @@
         }
       ],
       "enabled_default": true,
-      "tested": true
+      "tested": false
     },
     {
       "key": "pv_max_charge_current",
@@ -211,7 +211,7 @@
       "provenance": "doc_backed",
       "support_notes": "From PH1800/PV1800/EP1800/PV3500/EP3500 RS485 Modbus RTU 1.4.15 xlsx; the SmartESS cloud exposes this control in its device settings for this model, awaiting on-hardware write confirmation.",
       "enabled_default": true,
-      "tested": true
+      "tested": false
     },
     {
       "key": "float_voltage",
@@ -230,7 +230,7 @@
       "provenance": "doc_backed",
       "support_notes": "From PH1800/PV1800/EP1800/PV3500/EP3500 RS485 Modbus RTU 1.4.15 xlsx; the SmartESS cloud exposes this control in its device settings for this model, awaiting on-hardware write confirmation.",
       "enabled_default": true,
-      "tested": true
+      "tested": false
     },
     {
       "key": "absorption_voltage",
@@ -249,7 +249,7 @@
       "provenance": "doc_backed",
       "support_notes": "From PH1800/PV1800/EP1800/PV3500/EP3500 RS485 Modbus RTU 1.4.15 xlsx; the SmartESS cloud exposes this control in its device settings for this model, awaiting on-hardware write confirmation.",
       "enabled_default": true,
-      "tested": true
+      "tested": false
     },
     {
       "key": "battery_type",
@@ -307,7 +307,7 @@
         }
       ],
       "enabled_default": true,
-      "tested": true
+      "tested": false
     },
     {
       "key": "battery_stop_charge_voltage",
@@ -326,7 +326,7 @@
       "provenance": "doc_backed",
       "support_notes": "From PH1800/PV1800/EP1800/PV3500/EP3500 RS485 Modbus RTU 1.4.15 xlsx; the SmartESS cloud exposes this control in its device settings for this model, awaiting on-hardware write confirmation.",
       "enabled_default": true,
-      "tested": true
+      "tested": false
     },
     {
       "key": "battery_stop_discharge_voltage",
@@ -345,7 +345,7 @@
       "provenance": "doc_backed",
       "support_notes": "From PH1800/PV1800/EP1800/PV3500/EP3500 RS485 Modbus RTU 1.4.15 xlsx; the SmartESS cloud exposes this control in its device settings for this model, awaiting on-hardware write confirmation.",
       "enabled_default": true,
-      "tested": true
+      "tested": false
     },
     {
       "key": "battery_low_voltage",
@@ -364,7 +364,7 @@
       "provenance": "doc_backed",
       "support_notes": "From PH1800/PV1800/EP1800/PV3500/EP3500 RS485 Modbus RTU 1.4.15 xlsx; the SmartESS cloud exposes this control in its device settings for this model, awaiting on-hardware write confirmation.",
       "enabled_default": true,
-      "tested": true
+      "tested": false
     },
     {
       "key": "battery_high_voltage",
@@ -383,7 +383,7 @@
       "provenance": "doc_backed",
       "support_notes": "From PH1800/PV1800/EP1800/PV3500/EP3500 RS485 Modbus RTU 1.4.15 xlsx; the SmartESS cloud exposes this control in its device settings for this model, awaiting on-hardware write confirmation.",
       "enabled_default": true,
-      "tested": true
+      "tested": false
     },
     {
       "key": "max_discharge_current",
@@ -402,7 +402,7 @@
       "provenance": "doc_backed",
       "support_notes": "From PH1800/PV1800/EP1800/PV3500/EP3500 RS485 Modbus RTU 1.4.15 xlsx; the SmartESS cloud exposes this control in its device settings for this model, awaiting on-hardware write confirmation.",
       "enabled_default": true,
-      "tested": true
+      "tested": false
     },
     {
       "key": "energy_use_mode",
@@ -442,7 +442,7 @@
         }
       ],
       "enabled_default": true,
-      "tested": true
+      "tested": false
     },
     {
       "key": "grid_protect_standard",
@@ -482,7 +482,7 @@
         }
       ],
       "enabled_default": true,
-      "tested": true
+      "tested": false
     },
     {
       "key": "solar_use_aim",
@@ -510,7 +510,7 @@
         }
       ],
       "enabled_default": true,
-      "tested": true
+      "tested": false
     },
     {
       "key": "discharge_to_grid_enable",
@@ -524,7 +524,7 @@
       "provenance": "doc_backed",
       "support_notes": "From PH1800/PV1800/EP1800/PV3500/EP3500 RS485 Modbus RTU 1.4.15 xlsx; the SmartESS cloud exposes this control in its device settings for this model, awaiting on-hardware write confirmation.",
       "enabled_default": true,
-      "tested": true
+      "tested": false
     },
     {
       "key": "battery_equalization_enable",

docs/generated/INVERTER_MODEL_CATALOG.generated.md

@@ -381,7 +381,7 @@ Runtime descriptors with no specific commercial model record. These are generic
 - Coverage: runtime available, cloud cloud_catalog, vendor map partial
   - Coverage notes:
     - Runtime support uses the MUST PH RS485 map (v1.4.3 and v1.4.15 xlsx, cross-checked against the third-party implementation), with per-control read-back over gap-free register blocks.
-    - The control surface is cross-referenced from the SmartESS cloud device_settings field catalog and the vendor 1.4.15 register map: the 20 fields the cloud exposes ship tested (visible in the default control mode); datasheet-only settings absent from the cloud catalog (grid charging and the battery-equalization block) ship untested (full-control only).
+    - All 27 controls are document-backed but locally unverified, available only in Full Control. Presence in the SmartESS cloud settings catalog is not a local hardware write test; the former tested flags for 20 cloud-visible fields were withdrawn.
     - The register map is documentary; hardware write confirmation is still pending a tester report. The inverter validates its own writes, so a register that is absent or locked self-disables via the write-failure block.
 - Summary: MUST PV18-3024 support is based on issue #5 support archives and a MUST PV/PH18 Modbus register map (v1.4.3 and v1.4.15). The user archives showed Auto/PI30 probe timeouts, SmartESS protocol asset "02FF,0,0," and collector serial baudrate 19200-8-1-0. The runtime accepts both the PV18 marker and a numeric PV1800 marker at Modbus register 20001, and binds a full MUST PV/PH18 Modbus surface using slave address 4. It exposes a writable control surface cross-referenced from the SmartESS cloud device_settings catalog and the 1.4.15 register map (output voltage/frequency, energy use mode, grid protection standard, charge-source priority, battery type, charge/discharge current limits, and battery voltage windows) with per-control read-back; hardware write confirmation is pending.
 - Variants:
@@ -391,7 +391,7 @@ Runtime descriptors with no specific commercial model record. These are generic
     - `must_pv18_3024` → surface `must_pv_ph18_full` (driver must_pv_ph18, variant pv_ph18)
       - Protocol: must_pv_ph18 | Detection: anchors (protocol.protocol_id=MUST_PV_PH18; identity.model_number=['PV18', 'PV1800'])
       - Tier: full | Read-only: no | Profile: must_pv_ph18/base.json | Schema: must_pv_ph18/base.json
-      - Capabilities: 27 (tested 20, untested 7); support tiers: standard 27 | Telemetry: 37 measurements, 0 binary sensors
+      - Capabilities: 27 (untested 27); support tiers: standard 27 | Telemetry: 37 measurements, 0 binary sensors
 - Known limitations:
   - Requires collector serial settings compatible with Modbus RTU 19200 8N1 and inverter slave address 4.
   - Control writes are derived from the SmartESS cloud settings catalog and the vendor register map, not yet independently confirmed on hardware; setpoint windows are left wide because the documented ranges are battery-voltage-grade dependent and the inverter validates its own writes.
@@ -405,7 +405,7 @@ Runtime descriptors with no specific commercial model record. These are generic
 - Validation: hardware captured, telemetry partial, controls partial
 - Coverage: runtime available, cloud cloud_catalog, vendor map partial
   - Coverage notes:
-    - Inherits the existing MUST control profile unchanged.
+    - Inherits all 27 document-backed MUST controls as untested, available only in Full Control; cloud visibility does not prove local writes on this firmware.
     - Whole-percent load and battery/grid direction normalization are qualified by the PV3300 local marker, not by the retail label or live power magnitude.
 - Summary: PV3300 keeps the common MUST map and controls, with a scoped telemetry override: whole-percent load, charge-positive battery current/power and import-positive grid power. Native AC converter power retains its vendor sign.
 - Variants:
@@ -415,8 +415,9 @@ Runtime descriptors with no specific commercial model record. These are generic
     - `must_pv3300` → surface `must_pv3300_full` (driver must_pv_ph18, variant pv3300)
       - Protocol: must_pv_ph18 | Detection: anchors (protocol.protocol_id=MUST_PV_PH18; identity.model_number=PV3300)
       - Tier: full | Read-only: no | Profile: must_pv_ph18/base.json | Schema: must_pv_ph18/pv3300.json
-      - Capabilities: 27 (tested 20, untested 7); support tiers: standard 27 | Telemetry: 37 measurements, 0 binary sensors
+      - Capabilities: 27 (untested 27); support tiers: standard 27 | Telemetry: 37 measurements, 0 binary sensors
 - Known limitations:
+  - SOC is not yet exposed. Support Archives can check the vendor-documented optional BMS register block, but its availability on this firmware is unconfirmed.
   - Learned maps tied to the older generic MUST schema are not automatically rebased; existing compatibility checks remain in force.
   - Output Current and Inverter Load Current can remain zero on the reported unit; their meaning is still under investigation.
   - Other PV/PH/EP models retain the common register interpretation because published MUST documents disagree on load-percentage units.

docs/user/RUNTIME_AND_INVERTER.md

@@ -133,6 +133,32 @@ load, create a Support Archive: for PV3300 it compares the combined response
 with individual reads. The integration does not replace a reported zero with
 an estimated current.
 
+### MUST controls and battery percentage
+
+The MUST profile, including PV3300, contains 27 document-backed controls such as
+**Energy Use Mode**, **Charge Source Priority**, charging limits and **Off-Grid
+Output**. They are **untested** locally: a setting appearing in the cloud app is
+not proof that the local command works on every firmware.
+
+To opt in, open **Configure → Polling and inverter detection → Control mode → Full Control**.
+The controls belong to the inverter device's configuration section, not the
+collector. Selecting Full Control does not send a command or change inverter
+settings. **Off-Grid Output** is specifically the off-grid output enable; it is
+not a general inverter power switch or the separate cloud **Ongrid Switch**.
+
+**Upgrade note:** older builds incorrectly treated 20 cloud-listed controls as
+tested. They are no longer exposed in **Auto**. Use Full Control if you choose
+to test them; review automations that referenced the earlier controls. Telemetry
+and the selected control mode are not changed. No local hardware qualification
+is implied by the existing broad setpoint limits; use only settings appropriate
+to your exact model and battery.
+
+There is no verified PV3300 SOC sensor yet. Its manufacturer protocol describes
+an optional BMS block containing SOC. Creating a Support Archive now checks that
+block once, read-only, with a three-second limit. Unsupported registers or a
+timeout are recorded in the archive; they do not add a zero-percent sensor or
+change normal polling. Battery capacity in Ah is a setting, not remaining charge.
+
 ## SRNE partial battery / PV readings
 
 Some SRNE firmware rejects a combined battery/PV request while answering smaller
@@ -196,6 +222,18 @@ Rated values are diagnostics, disabled by default. **Rated Power** is not a
 measurement of actual output power. **AC Charger Enabled** describes the charger
 state, not a measured charging current or power.
 
+**Grid Fault Voltage** is a separate field named that way in the manufacturer's
+protocol, kept under diagnostics and disabled by default. Enabling it makes its
+reading available for dashboards too; the diagnostic category does not change
+the value. It is not automatically substituted for Grid Voltage based on one
+comparison with a meter.
+
+The current PV readings come from a single `PV?` reply. They are not verified as
+a sum of two MPPT inputs, and separate PV1/PV2 channels are not yet mapped. Raw
+replies to those commands can help establish a model-specific extension.
+Polling uses the normal adaptive scheduler; check **Current Poll Interval** on
+the collector for the current value rather than assuming a fixed refresh rate.
+
 If a PV, output-frequency or rated-values request fails, that group's old values
 become unavailable while basic readings can continue. If the main status request
 fails, normal connection recovery applies. No inverter serial, battery percentage,