python-intelbras-solar-local 0.1.0__tar.gz → 0.1.1__tar.gz

{python_intelbras_solar_local-0.1.0 → python_intelbras_solar_local-0.1.1}/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project are documented here.
 
+## [0.1.1] - 2026-10-24
+
+### Fixed
+- Malformed or mismatched Modbus replies now raise `IntelbrasSolarProtocolError`
+  and reopen the connection. Before, a bare `IndexError`/`ValueError` escaped.
+  The WiNet-S produced such frames when two clients polled at the same time
+  (observed on the real IONS-5K M5): bad MBAP length, wrong function code,
+  wrong byte count.
+- The Modbus transaction id now starts at a random value, so two concurrent
+  clients no longer accept each other's replies.
+
 ## [0.1.0] - 2026-10-24
 
 ### Added

{python_intelbras_solar_local-0.1.0 → python_intelbras_solar_local-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-intelbras-solar-local
-Version: 0.1.0
+Version: 0.1.1
 Summary: Async Python client for Intelbras solar inverters (Sungrow WiNet-S) over Modbus TCP and the datalogger WebSocket
 Project-URL: Homepage, https://github.com/hudsonbrendon/python-intelbras-solar-local
 Project-URL: Documentation, https://hudsonbrendon.github.io/python-intelbras-solar-local/

{python_intelbras_solar_local-0.1.0 → python_intelbras_solar_local-0.1.1}/docs/usage.md

@@ -31,6 +31,12 @@ asyncio.run(main())
 To share an `aiohttp.ClientSession`, as Home Assistant does, pass `session=`. The client then leaves the session open
 when it closes.
 
+## One client at a time
+
+The WiNet-S datalogger serves Modbus TCP poorly to concurrent clients: requests time out, and replies can arrive
+malformed. The client raises `IntelbrasSolarProtocolError` for malformed replies and reopens the connection, so a bad
+reply never turns into wrong data. Even so, keep one Modbus client per datalogger.
+
 ## Controls
 
 !!! warning

{python_intelbras_solar_local-0.1.0 → python_intelbras_solar_local-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-intelbras-solar-local"
-version = "0.1.0"
+version = "0.1.1"
 description = "Async Python client for Intelbras solar inverters (Sungrow WiNet-S) over Modbus TCP and the datalogger WebSocket"
 readme = "README.md"
 requires-python = ">=3.11"

{python_intelbras_solar_local-0.1.0 → python_intelbras_solar_local-0.1.1}/src/intelbras_solar_local/__init__.py

@@ -40,4 +40,4 @@ __all__ = [
     "DEVICE_MODELS",
     "WORK_STATES",
 ]
-__version__ = "0.1.0"
+__version__ = "0.1.1"

{python_intelbras_solar_local-0.1.0 → python_intelbras_solar_local-0.1.1}/src/intelbras_solar_local/modbus.py

@@ -6,6 +6,7 @@ clashes with the ``pymodbus`` version pinned by Home Assistant.
 from __future__ import annotations
 
 import asyncio
+import random
 import struct
 
 from .const import (
@@ -19,6 +20,10 @@ from .exceptions import IntelbrasSolarConnectionError, IntelbrasSolarProtocolErr
 _MBAP = struct.Struct(">HHHB")
 
 
+class _FramingError(Exception):
+    """Malformed frame; the connection must be reopened to resync."""
+
+
 class ModbusTcpClient:
     """One persistent Modbus TCP connection, reopened on demand after errors."""
 
@@ -35,7 +40,9 @@ class ModbusTcpClient:
         self.timeout = timeout
         self._reader: asyncio.StreamReader | None = None
         self._writer: asyncio.StreamWriter | None = None
-        self._tid = 0
+        # Random start: the WiNet-S can leak replies across concurrent clients,
+        # and two clients both counting from 1 would accept each other's frames.
+        self._tid = random.randrange(0x10000)
         # The WiNet-S serves one request at a time; serialize every call.
         self._lock = asyncio.Lock()
 
@@ -59,8 +66,13 @@ class ModbusTcpClient:
             Mapping of register address to its unsigned 16-bit value.
         """
         body = await self._request(struct.pack(">BHH", function, address, count))
-        size = body[1]
-        values = struct.unpack(f">{size // 2}H", body[2 : 2 + size])
+        if body[0] != function or len(body) != 2 + count * 2 or body[1] != count * 2:
+            # A reply to some other request: the stream is out of sync.
+            await self.async_close()
+            raise IntelbrasSolarProtocolError(
+                f"Modbus reply does not match function {function} x {count} registers"
+            )
+        values = struct.unpack(f">{count}H", body[2:])
         return {address + i: v for i, v in enumerate(values)}
 
     async def async_write(self, address: int, value: int) -> None:
@@ -76,6 +88,11 @@ class ModbusTcpClient:
                 raise IntelbrasSolarConnectionError(
                     f"Modbus {self.host}:{self.port}: {err!r}"
                 ) from err
+            except _FramingError as err:
+                await self.async_close()
+                raise IntelbrasSolarProtocolError(
+                    f"Modbus {self.host}:{self.port}: {err}"
+                ) from err
         if body[0] & 0x80:
             raise IntelbrasSolarProtocolError(
                 f"Modbus exception {body[1]} on function {body[0] & 0x7F}"
@@ -93,6 +110,8 @@ class ModbusTcpClient:
         await self._writer.drain()
         while True:
             tid, _, length, _ = _MBAP.unpack(await self._reader.readexactly(7))
+            if length < 3:
+                raise _FramingError(f"bad MBAP length {length}")
             body = await self._reader.readexactly(length - 1)
             # Drop late replies to a request that already timed out.
             if tid == self._tid:

{python_intelbras_solar_local-0.1.0 → python_intelbras_solar_local-0.1.1}/tests/conftest.py

@@ -44,6 +44,8 @@ class FakeInverter:
         self.input = dict(INPUT)
         self.holding = dict(HOLDING)
         self.writes: list[tuple[int, int, int]] = []
+        # Next replies to corrupt: "short_mbap" or "wrong_count".
+        self.garbage: list[str] = []
         self.port = 0
         self._server: asyncio.base_events.Server | None = None
 
@@ -76,6 +78,14 @@ class FakeInverter:
                 body = pdu
             else:
                 body = bytes([fc | 0x80, 1])
+            if self.garbage:
+                mode = self.garbage.pop(0)
+                if mode == "short_mbap":
+                    writer.write(struct.pack(">HHHB", tid, 0, 0, unit))
+                    await writer.drain()
+                    continue
+                if mode == "wrong_count":
+                    body = bytes([fc, 2, 0, 1])
             writer.write(struct.pack(">HHHB", tid, 0, len(body) + 1, unit) + body)
             await writer.drain()
         writer.close()

{python_intelbras_solar_local-0.1.0 → python_intelbras_solar_local-0.1.1}/tests/test_client.py

@@ -41,4 +41,4 @@ async def test_controls_write_expected_registers(inverter):
 
 
 def test_version():
-    assert __version__ == "0.1.0"
+    assert __version__ == "0.1.1"

{python_intelbras_solar_local-0.1.0 → python_intelbras_solar_local-0.1.1}/tests/test_modbus.py

@@ -34,3 +34,19 @@ async def test_unreachable_raises_connection_error(inverter):
     client = ModbusTcpClient("127.0.0.1", port, timeout=1)
     with pytest.raises(IntelbrasSolarConnectionError):
         await client.async_read(4, 5000, 1)
+
+
+async def test_garbage_frames_raise_protocol_error_and_resync(inverter):
+    client = ModbusTcpClient("127.0.0.1", inverter.port)
+    inverter.garbage = ["short_mbap", "wrong_count"]
+    with pytest.raises(IntelbrasSolarProtocolError, match="MBAP length"):
+        await client.async_read(4, 5000, 3)
+    with pytest.raises(IntelbrasSolarProtocolError, match="does not match"):
+        await client.async_read(4, 5000, 3)
+    assert await client.async_read(4, 5000, 1) == {5000: 50}
+    await client.async_close()
+
+
+def test_transaction_ids_start_randomly():
+    starts = {ModbusTcpClient("127.0.0.1")._tid for _ in range(20)}
+    assert len(starts) > 1