Merge pull request #30 from fboundy/patch

Make inverter serial optional for hybrid Modbus setup

Author: fboundy

.github/FUNDING.yml

@@ -1,15 +1,15 @@
 # These are supported funding model platforms
 
-github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
-patreon: # Replace with a single Patreon username
-open_collective: # Replace with a single Open Collective username
-ko_fi: https://ko-fi.com/fboundy#
-tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
-community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
-liberapay: # Replace with a single Liberapay username
-issuehunt: # Replace with a single IssueHunt username
-lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
-polar: # Replace with a single Polar username
-buy_me_a_coffee: pho3nix90 # Replace with a single Buy Me a Coffee username
-thanks_dev: # Replace with a single thanks.dev username
-custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']
+# github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+# patreon: # Replace with a single Patreon username
+# open_collective: # Replace with a single Open Collective username
+ko_fi: fboundy
+# tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+# community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+# liberapay: # Replace with a single Liberapay username
+# issuehunt: # Replace with a single IssueHunt username
+# lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+# polar: # Replace with a single Polar username
+# buy_me_a_coffee: pho3nix90 # Replace with a single Buy Me a Coffee username
+# thanks_dev: # Replace with a single thanks.dev username
+# custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

.gitignore

@@ -73,3 +73,7 @@ scripts/soliscloud_detail_dump.json
 
 # Working handoff notes (contain internal server details and real inverter serial; repo is public)
 WORKING_NOTES.md
+
+# Source docs
+docs/api/
+

README.md

@@ -117,10 +117,11 @@ Home Assistant only allows one `iot_class` value in the manifest. SolisConnect i
 - The SolisCloud API is rate-limited by the integration. Avoid running another cloud integration against the same key if you are seeing slow or failed cloud updates.
 - If older debug logs captured SolisCloud credentials before redaction was added, rotate the SolisCloud key secret and clear old logs.
 
-**Inverter Serial**: (Required)
+**Inverter Serial**: (Optional on hybrid Modbus models and SolisCloud; required otherwise)
 
-- Enter your inverter's serial number. This is now **mandatory** for generating unique entity IDs and ensuring configuration stability.
-- On Modbus hybrid inverters, once connectivity is confirmed the integration reads the serial directly from the device and silently corrects a mistyped value (grid/string models don't expose this register, so the typed value is used as-is). On SolisCloud, the serial is optional and auto-resolved when your plant has exactly one inverter.
+- Used to generate unique entity IDs and ensure configuration stability — every entry needs one, but you don't always have to type it.
+- On Modbus **hybrid** inverters, you can leave this blank: once connectivity is confirmed, the integration reads the serial directly from the device and uses it (silently correcting a mistyped value too, if you did type one). **Grid/string** models don't expose this register, so you still need to type it there — if you leave it blank on a grid/string model, the form will ask again.
+- On SolisCloud, the serial is optional and auto-resolved when your plant has exactly one inverter; you only need to type it to disambiguate a plant with multiple inverters.
 
 **Poll Interval**:
 

custom_components/solisconnect/config_flow.py

@@ -75,7 +75,11 @@
 # Base schema with common fields (for both TCP and Serial)
 BASE_CONFIG_SCHEMA = {
     vol.Required(CONF_CONNECTION_TYPE, default=CONN_TYPE_TCP): vol.In(CONNECTION_TYPES),
-    vol.Required(CONF_INVERTER_SERIAL): str,
+    # Optional: hybrid inverters have their serial read from the device (registers
+    # 33004-33019) once connectivity is confirmed, so it doesn't need to be typed. Grid/
+    # string models don't expose that register range, so _create_entry_from_input (and the
+    # dual-mode Modbus step) re-check after validation and ask again if it's still blank.
+    vol.Optional(CONF_INVERTER_SERIAL, default=""): str,
     vol.Required("slave", default=1): int,
     vol.Optional("poll_interval_fast", default=10): vol.All(int, vol.Range(min=10)),
     vol.Optional("poll_interval_normal", default=15): vol.All(int, vol.Range(min=15)),
@@ -538,6 +542,17 @@ async def _create_entry_from_input(self, data):
 
             return self.async_show_form(step_id="config", data_schema=vol.Schema(schema_dict), errors=errors)
 
+        # 2b. The serial field is optional because hybrid models auto-detect it during
+        # validation above; grid/string models don't expose that register range, so if it's
+        # still blank at this point there's no way to identify the device — ask for it.
+        if not (data.get(CONF_INVERTER_SERIAL) or "").strip():
+            errors["base"] = "Could not detect the inverter serial automatically; please enter it manually."
+            if data.get(CONF_CONNECTION_TYPE) == CONN_TYPE_TCP:
+                schema_dict = TCP_CONFIG_SCHEMA
+            else:
+                schema_dict = SERIAL_CONFIG_SCHEMA
+            return self.async_show_form(step_id="config", data_schema=self.add_suggested_values_to_schema(vol.Schema(schema_dict), data), errors=errors)
+
         # 3. Check for Duplicates
         if CONF_INVERTER_SERIAL in data:
             await self.async_set_unique_id(data[CONF_INVERTER_SERIAL])

tests/test_config_flow.py

@@ -253,6 +253,90 @@ async def fake_read_input_register(register, count):
         assert 33002 in registers_read  # HMI-version detection is not gated by inverter type
 
 
+@pytest.mark.asyncio
+async def test_flow_user_blank_serial_auto_detected_from_device(hass: HomeAssistant):
+    """The serial field is optional: a hybrid model can be set up without typing it at all."""
+    device_serial_registers = _encode_serial_registers("1234567890123456")
+
+    async def fake_read_input_register(register, count):
+        if register == 33004:
+            return device_serial_registers
+        return [1]
+
+    with (
+        patch("custom_components.solisconnect.modbus_controller.ModbusController.connect", return_value=True),
+        patch(
+            "custom_components.solisconnect.modbus_controller.ModbusController.async_read_input_register",
+            side_effect=fake_read_input_register,
+        ),
+        patch("custom_components.solisconnect.async_setup_entry", return_value=True),
+    ):
+        result = await hass.config_entries.flow.async_init(DOMAIN, context={"source": config_entries.SOURCE_USER})
+        result = await hass.config_entries.flow.async_configure(result["flow_id"], user_input={"connection_type": CONN_TYPE_TCP})
+
+        config_input = {
+            "host": "1.2.3.4",
+            "port": 502,
+            "slave": 1,
+            "model": "S6-EH1P",
+            "connection": "S2_WL_ST",
+            "has_v2": True,
+            "has_pv": True,
+            "has_ac_coupling": False,
+            "has_parallel": False,
+            "has_battery": True,
+            "has_hv_battery": False,
+            "has_generator": False,
+            # inverter_serial omitted entirely
+        }
+        result = await hass.config_entries.flow.async_configure(result["flow_id"], user_input=config_input)
+
+        assert result["type"] == data_entry_flow.FlowResultType.CREATE_ENTRY
+        assert result["data"]["inverter_serial"] == "1234567890123456"
+
+
+@pytest.mark.asyncio
+async def test_flow_user_blank_serial_without_detection_shows_error(hass: HomeAssistant):
+    """A grid model with no typed serial has no way to auto-detect one; the form must ask again."""
+
+    async def fake_read_input_register(register, count):
+        if register == 33004:
+            return None  # grid models don't expose this range anyway; belt-and-braces
+        return [1]
+
+    with (
+        patch("custom_components.solisconnect.modbus_controller.ModbusController.connect", return_value=True),
+        patch(
+            "custom_components.solisconnect.modbus_controller.ModbusController.async_read_input_register",
+            side_effect=fake_read_input_register,
+        ),
+        patch("custom_components.solisconnect.async_setup_entry", return_value=True),
+    ):
+        result = await hass.config_entries.flow.async_init(DOMAIN, context={"source": config_entries.SOURCE_USER})
+        result = await hass.config_entries.flow.async_configure(result["flow_id"], user_input={"connection_type": CONN_TYPE_TCP})
+
+        config_input = {
+            "host": "1.2.3.4",
+            "port": 502,
+            "slave": 1,
+            "model": "S6-GR1P",
+            "connection": "S2_WL_ST",
+            "has_v2": True,
+            "has_pv": True,
+            "has_ac_coupling": False,
+            "has_parallel": False,
+            "has_battery": True,
+            "has_hv_battery": False,
+            "has_generator": False,
+            # inverter_serial omitted; grid model can't auto-detect it
+        }
+        result = await hass.config_entries.flow.async_configure(result["flow_id"], user_input=config_input)
+
+        assert result["type"] == data_entry_flow.FlowResultType.FORM
+        assert result["step_id"] == "config"
+        assert "manually" in result["errors"]["base"]
+
+
 @pytest.mark.asyncio
 async def test_flow_user_connection_error(hass: HomeAssistant):
     """Test user initialized flow with connection error."""