Polish SolisCloud integration stage 7

Author: fboundy

README.md

@@ -42,6 +42,18 @@ Whilst the solis inverters do provide total sensors for today, yesterday, month
 **Connection Type**:
 - **TCP (WiFi Dongle)**: Use for Data Logging Sticks (DLS) or WiFi dongles. Requires IP and Port (Default 502).
 - **Serial (RS485)**: Use for direct USB-RS485 connection. Requires Serial Port path.
+- **SolisCloud API**: Uses SolisCloud API key credentials. Polling is slower than local Modbus, but works when local Modbus is unavailable.
+- **Modbus + SolisCloud**: Creates one shared device/entity set with either automatic failover or a manual active-protocol selector.
+
+### Protocol Support
+| Mode | Sensor polling | Control writes | Notes |
+| --- | --- | --- | --- |
+| TCP/Serial Modbus | Full local register set | Full mapped register writes | Fastest and preferred where local access is reliable. |
+| SolisCloud API | Mapped cloud detail fields and verified control CIDs | Verified CIDs only: storage mode, backup SOC, over-discharge SOC, force-charge SOC, feed-in limit | Cloud data updates every few minutes and unmapped cloud-only sensors are marked unavailable. |
+| Modbus + SolisCloud failover | One protocol polls at a time; automatic switch on health loss | Active protocol first, then healthy backup where possible | Primary can be Modbus or cloud. |
+| Modbus + SolisCloud manual | One protocol polls at a time, selected by the Active Protocol entity | Active protocol first, then healthy backup where possible | Useful when maintenance or network conditions make one transport preferable. |
+
+Cloud setup derives the closest supported inverter model from SolisCloud metadata where possible. If SolisCloud identifies the model, that value is used to avoid choosing a sensor map that does not match the inverter.
 
 **Inverter Serial**: (Required)
 - Enter your inverter's serial number. This is now **mandatory** for generating unique entity IDs and ensuring configuration stability.

custom_components/solisconnect/cloud/api_client.py

@@ -244,12 +244,41 @@ async def async_at_read_batch(self, inverter_sn: str, cids: list[int]) -> dict[i
             _LOGGER.warning("SolisCloud atReadBatch returned no parseable records; raw payload: %s", data)
         return results
 
+    @staticmethod
+    def _control_failure(payload) -> str | None:
+        """Return an embedded control failure message from a successful HTTP/API payload."""
+        if isinstance(payload, list):
+            for item in payload:
+                failure = SolisCloudApiClient._control_failure(item)
+                if failure:
+                    return failure
+            return None
+        if not isinstance(payload, dict):
+            return None
+
+        code = payload.get("code") or payload.get("resultCode") or payload.get("errorCode")
+        if code not in (None, "", "0", 0):
+            return str(payload.get("msg") or payload.get("message") or f"code={code}")
+
+        for key in ("success", "result", "isSuccess"):
+            if payload.get(key) is False:
+                return str(payload.get("msg") or payload.get("message") or f"{key}=false")
+
+        for key in ("data", "result", "response", "responses", "records", "list"):
+            if key in payload:
+                failure = SolisCloudApiClient._control_failure(payload[key])
+                if failure:
+                    return failure
+        return None
+
     async def async_control(self, inverter_sn: str, cid: int, value: str, old_value: str | None = None) -> bool:
         """Write a control register (CID) value; returns True on success."""
         await self.async_ensure_token()
         params = {"inverterSn": str(inverter_sn), "cid": str(cid), "value": str(value)}
         if old_value is not None:
             params["yuanzhi"] = str(old_value)
-        # _post raises on any non-zero response code, so reaching here means success.
-        await self._post(RESOURCE_CONTROL, params, with_token=True)
+        data = await self._post(RESOURCE_CONTROL, params, with_token=True)
+        failure = self._control_failure(data)
+        if failure:
+            raise SolisCloudApiError(f"SolisCloud control for cid {cid} failed: {failure}")
         return True

custom_components/solisconnect/cloud/model_detection.py

@@ -0,0 +1,58 @@
+"""Helpers for deriving a SolisConnect model from SolisCloud metadata."""
+
+from __future__ import annotations
+
+import re
+
+from custom_components.solisconnect.data.solis_config import SOLIS_INVERTERS
+
+MODEL_NAMES = tuple(sorted((inverter.model for inverter in SOLIS_INVERTERS), key=len, reverse=True))
+
+# Verified live: SolisCloud product code 3102 reports an S5-EH1P inverter.
+PRODUCT_CODE_TO_MODEL = {
+    "3102": "S5-EH1P",
+}
+
+MODEL_FIELDS = (
+    "model",
+    "productModel",
+    "product_model",
+    "inverterType",
+    "inverter_type",
+    "machine",
+    "productName",
+    "product_name",
+    "typeName",
+    "type_name",
+)
+
+
+def cloud_model_metadata(record: dict | None) -> dict[str, str]:
+    """Return useful cloud model-identifying fields as strings."""
+    if not isinstance(record, dict):
+        return {}
+    metadata = {}
+    for key in MODEL_FIELDS:
+        value = record.get(key)
+        if value not in (None, ""):
+            metadata[key] = str(value)
+    return metadata
+
+
+def infer_model_from_cloud_record(record: dict | None) -> str | None:
+    """Infer the closest configured model from SolisCloud inverter metadata."""
+    metadata = cloud_model_metadata(record)
+    if not metadata:
+        return None
+
+    haystack = " ".join(metadata.values()).upper()
+    for model in MODEL_NAMES:
+        if model.upper() in haystack:
+            return model
+
+    for value in metadata.values():
+        normalized = re.sub(r"\D", "", value)
+        if normalized in PRODUCT_CODE_TO_MODEL:
+            return PRODUCT_CODE_TO_MODEL[normalized]
+
+    return None

custom_components/solisconnect/config_flow.py

@@ -10,12 +10,14 @@
 from .const import (
     CONF_BAUDRATE,
     CONF_BYTESIZE,
+    CONF_CLOUD_DETECTED_MODEL,
     CONF_CLOUD_INVERTER_ID,
     CONF_CLOUD_KEY_ID,
     CONF_CLOUD_KEY_SECRET,
     CONF_CLOUD_PASSWORD,
     CONF_CLOUD_PLANT_ID,
     CONF_CLOUD_POLL_INTERVAL,
+    CONF_CLOUD_PRODUCT_MODEL,
     CONF_CLOUD_USERNAME,
     CONF_CONNECTION_TYPE,
     CONF_FAILOVER_PRIMARY,
@@ -185,6 +187,8 @@ def __init__(self):
         self._cloud_data = None
         self._resolved_serial = None
         self._resolved_cloud_id = None
+        self._cloud_product_model = None
+        self._cloud_detected_model = None
 
     async def async_step_user(self, user_input=None):
         """Handle initial step - ask for connection type."""
@@ -266,21 +270,41 @@ async def async_step_cloud(self, user_input=None):
             if self._both_mode:
                 # The dual entry is keyed by the Modbus serial; the cloud plant must contain it
                 user_input = {**user_input, CONF_INVERTER_SERIAL: self._modbus_data[CONF_INVERTER_SERIAL]}
-            serial, inverter_id, error = await self._validate_cloud_config(user_input)
+            serial, inverter_id, detected_model, product_model, error = await self._validate_cloud_config(user_input)
             if error:
                 errors["base"] = error
             elif self._both_mode:
+                if detected_model and self._modbus_data.get("model") != detected_model:
+                    _LOGGER.info(
+                        "SolisCloud model metadata identifies %s; overriding selected model %s for serial %s",
+                        detected_model,
+                        self._modbus_data.get("model"),
+                        serial,
+                    )
+                    self._modbus_data["model"] = detected_model
                 self._cloud_data = user_input
                 self._resolved_serial = serial
                 self._resolved_cloud_id = inverter_id
+                self._cloud_product_model = product_model
+                self._cloud_detected_model = detected_model
                 return await self.async_step_dual_mode()
             else:
                 await self.async_set_unique_id(serial)
                 self._abort_if_unique_id_configured()
+                if detected_model and user_input.get("model") != detected_model:
+                    _LOGGER.info(
+                        "SolisCloud model metadata identifies %s; overriding selected model %s for serial %s",
+                        detected_model,
+                        user_input.get("model"),
+                        serial,
+                    )
                 data = {
                     **user_input,
+                    "model": detected_model or user_input.get("model"),
                     CONF_INVERTER_SERIAL: serial,
                     CONF_CLOUD_INVERTER_ID: inverter_id,
+                    CONF_CLOUD_PRODUCT_MODEL: product_model,
+                    CONF_CLOUD_DETECTED_MODEL: detected_model,
                     CONF_CONNECTION_TYPE: CONN_TYPE_CLOUD,
                     CONF_PROTOCOL_MODE: PROTO_CLOUD_ONLY,
                 }
@@ -325,6 +349,8 @@ async def async_step_dual_mode(self, user_input=None):
                 **self._cloud_data,
                 CONF_INVERTER_SERIAL: serial,
                 CONF_CLOUD_INVERTER_ID: self._resolved_cloud_id,
+                CONF_CLOUD_PRODUCT_MODEL: self._cloud_product_model,
+                CONF_CLOUD_DETECTED_MODEL: self._cloud_detected_model,
                 CONF_PROTOCOL_MODE: protocol_mode,
                 CONF_FAILOVER_PRIMARY: primary,
             }
@@ -335,15 +361,16 @@ async def async_step_dual_mode(self, user_input=None):
             data_schema=vol.Schema({vol.Required("dual_mode", default="failover_modbus"): vol.In(DUAL_MODE_OPTIONS)}),
         )
 
-    async def _validate_cloud_config(self, user_input) -> tuple[str | None, str | None, str | None]:
+    async def _validate_cloud_config(self, user_input) -> tuple[str | None, str | None, str | None, str | None, str | None]:
         """Check credentials against the SolisCloud API and resolve the inverter serial + cloud id.
 
-        Returns (serial, inverter_id, None) on success or (None, None, error_message) on failure.
+        Returns (serial, inverter_id, detected_model, product_model, None) on success.
         The cloud id is required alongside the serial for inverterDetail reads.
         """
         from homeassistant.helpers.aiohttp_client import async_get_clientsession
 
         from .cloud.api_client import SolisCloudApiClient, SolisCloudApiError
+        from .cloud.model_detection import cloud_model_metadata, infer_model_from_cloud_record
 
         client = SolisCloudApiClient(
             session=async_get_clientsession(self.hass),
@@ -357,21 +384,26 @@ async def _validate_cloud_config(self, user_input) -> tuple[str | None, str | No
             records = await client.async_inverter_list(user_input[CONF_CLOUD_PLANT_ID].strip())
         except SolisCloudApiError as error:
             _LOGGER.warning("SolisCloud validation failed: %s", error)
-            return None, None, "Cannot reach the SolisCloud API with these credentials. Check the key id/secret and plant id."
+            return None, None, None, None, "Cannot reach the SolisCloud API with these credentials. Check the key id/secret and plant id."
 
-        by_serial = {str(rec["sn"]).upper(): str(rec.get("id") or "") for rec in records if rec.get("sn")}
+        by_serial = {str(rec["sn"]).upper(): rec for rec in records if rec.get("sn")}
         if not by_serial:
-            return None, None, "No inverters found for this plant id."
+            return None, None, None, None, "No inverters found for this plant id."
 
         wanted = (user_input.get(CONF_INVERTER_SERIAL) or "").strip().upper()
         if wanted:
             if wanted not in by_serial:
-                return None, None, f"Inverter serial {wanted} not found in this plant (found: {', '.join(by_serial)})."
-            return wanted, by_serial[wanted] or None, None
+                return None, None, None, None, f"Inverter serial {wanted} not found in this plant (found: {', '.join(by_serial)})."
+            record = by_serial[wanted]
+            metadata = cloud_model_metadata(record)
+            product_model = metadata.get("productModel") or metadata.get("model")
+            return wanted, str(record.get("id") or "") or None, infer_model_from_cloud_record(record), product_model, None
         if len(by_serial) == 1:
-            serial, inverter_id = next(iter(by_serial.items()))
-            return serial, inverter_id or None, None
-        return None, None, f"This plant has multiple inverters ({', '.join(by_serial)}); please enter the serial of the one to add."
+            serial, record = next(iter(by_serial.items()))
+            metadata = cloud_model_metadata(record)
+            product_model = metadata.get("productModel") or metadata.get("model")
+            return serial, str(record.get("id") or "") or None, infer_model_from_cloud_record(record), product_model, None
+        return None, None, None, None, f"This plant has multiple inverters ({', '.join(by_serial)}); please enter the serial of the one to add."
 
     async def async_step_reconfigure(self, user_input=None):
         """Handle reconfiguration."""
@@ -419,17 +451,27 @@ async def async_step_reconfigure_cloud(self, user_input=None):
         entry = self.hass.config_entries.async_get_entry(self.context["entry_id"])
 
         if user_input is not None:
-            serial, inverter_id, error = await self._validate_cloud_config(user_input)
+            serial, inverter_id, detected_model, product_model, error = await self._validate_cloud_config(user_input)
             if error:
                 errors["base"] = error
             elif serial != entry.unique_id:
                 errors["base"] = f"Serial {serial} does not match this entry ({entry.unique_id}). Add a new entry for a different inverter."
             else:
+                if detected_model and user_input.get("model") != detected_model:
+                    _LOGGER.info(
+                        "SolisCloud model metadata identifies %s; overriding selected model %s for serial %s",
+                        detected_model,
+                        user_input.get("model"),
+                        serial,
+                    )
                 data = {
                     **entry.data,
                     **user_input,
+                    "model": detected_model or user_input.get("model"),
                     CONF_INVERTER_SERIAL: serial,
                     CONF_CLOUD_INVERTER_ID: inverter_id,
+                    CONF_CLOUD_PRODUCT_MODEL: product_model,
+                    CONF_CLOUD_DETECTED_MODEL: detected_model,
                 }
                 return self.async_update_reload_and_abort(entry, data=data)
 

custom_components/solisconnect/const.py

@@ -39,6 +39,8 @@
 CONF_CLOUD_KEY_SECRET = "cloud_key_secret"
 CONF_CLOUD_PLANT_ID = "cloud_plant_id"
 CONF_CLOUD_INVERTER_ID = "cloud_inverter_id"
+CONF_CLOUD_PRODUCT_MODEL = "cloud_product_model"
+CONF_CLOUD_DETECTED_MODEL = "cloud_detected_model"
 CONF_CLOUD_POLL_INTERVAL = "cloud_poll_interval"
 DEFAULT_CLOUD_POLL_INTERVAL = 300
 MIN_CLOUD_POLL_INTERVAL = 60

custom_components/solisconnect/diagnostics.py

@@ -0,0 +1,81 @@
+"""Diagnostics support for SolisConnect."""
+
+from __future__ import annotations
+
+from homeassistant.config_entries import ConfigEntry
+from homeassistant.core import HomeAssistant
+
+from custom_components.solisconnect.const import CONTROLLER, DOMAIN
+from custom_components.solisconnect.helpers import redact_config
+from custom_components.solisconnect.sensor_data.cloud_mapping import CLOUD_CID_MAP, CLOUD_INPUT_MAP, registers_covered
+
+
+def _controller_diagnostics(controller) -> dict:
+    data = {
+        "model": getattr(controller, "model", None),
+        "serial_number": getattr(controller, "serial_number", None) or getattr(controller, "device_serial_number", None),
+        "cache_scope": getattr(controller, "cache_scope", None),
+        "connected": controller.connected() if hasattr(controller, "connected") else None,
+    }
+
+    active_protocol = getattr(controller, "active_protocol", None)
+    if isinstance(active_protocol, str):
+        data.update(
+            {
+                "mode": getattr(controller, "mode", None),
+                "active_protocol": active_protocol,
+                "failover_primary": getattr(controller, "failover_primary", None),
+                "has_modbus": getattr(controller, "modbus", None) is not None,
+                "has_cloud": getattr(controller, "cloud", None) is not None,
+            }
+        )
+        if getattr(controller, "cloud", None) is not None:
+            data["cloud"] = _controller_diagnostics(controller.cloud)
+        if getattr(controller, "modbus", None) is not None:
+            data["modbus"] = _controller_diagnostics(controller.modbus)
+        return data
+
+    poll_interval = getattr(controller, "poll_interval", None)
+    if isinstance(poll_interval, int):
+        data.update(
+            {
+                "plant_id": getattr(controller, "plant_id", None),
+                "inverter_id_present": bool(getattr(controller, "inverter_id", None)),
+                "last_cloud_success": str(getattr(controller, "last_cloud_success", None)),
+                "poll_interval": poll_interval,
+            }
+        )
+    else:
+        data.update(
+            {
+                "host": getattr(controller, "host", None),
+                "connection_type": getattr(controller, "connection_type", None),
+                "connection_id": getattr(controller, "connection_id", None),
+                "last_modbus_success": str(getattr(controller, "last_modbus_success", None)),
+            }
+        )
+    return data
+
+
+async def async_get_config_entry_diagnostics(hass: HomeAssistant, entry: ConfigEntry) -> dict:
+    """Return diagnostics for a config entry."""
+    controller = hass.data.get(DOMAIN, {}).get(CONTROLLER, {}).get(entry.entry_id)
+    covered = registers_covered()
+
+    return {
+        "entry": {
+            "entry_id": entry.entry_id,
+            "version": entry.version,
+            "domain": entry.domain,
+            "title": entry.title,
+            "unique_id_present": bool(entry.unique_id),
+            "data": redact_config(dict(entry.data)),
+            "options": redact_config(dict(entry.options)),
+        },
+        "controller": _controller_diagnostics(controller) if controller is not None else None,
+        "cloud_mapping": {
+            "detail_fields": len(CLOUD_INPUT_MAP),
+            "control_cids": len(CLOUD_CID_MAP),
+            "covered_registers": len(covered),
+        },
+    }