fix: release the serial port between polls (#384)

v1.7.0 gave serial entries a shared connection and, with it, a connection held
open for the lifetime of the entry. That is right for TCP and wrong for serial: a
serial port is exclusive, so holding it denies it to everything else on the
machine.

A reporter with two SPF inverters went from working on v1.6.6 to one inverter
permanently offline, with pyserial reporting 'Could not exclusively lock port
/dev/ttyUSB3' on every poll. Before v1.7.0 the port was opened and closed per
poll, so two entries naming the same adapter differently alternated and mostly
worked; holding it turned that into a hard lockout for whichever lost the race.

end_poll() gives the port back after each poll for serial and leaves TCP alone.
Reopening costs ~2 ms against a poll that reads 98 registers. Entries that do
share a hub are still serialized by the lock.

Also: a failed serial open now explains itself instead of surfacing as a bare
'Failed to connect', and the docs cover choosing a stable path - CH340 adapters
(vendor 1a86) have no serial number, so by-id cannot distinguish two of them and
ttyUSBn numbering swaps on reboot, which is how two entries end up on one
adapter without anyone noticing.

Verified red without the fix.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: 0xAHA

RELEASENOTES.md

@@ -4,6 +4,31 @@
 
 ---
 
+## v1.7.3 (pre-release)
+
+Issues: #384
+
+> **Pre-release for testing.** v1.6.2 remains the stable release.
+>
+> **Fixes a serial regression introduced in v1.7.0.** If you are on v1.7.0-v1.7.2 with a
+> USB-RS485 adapter, update.
+
+- **Serial ports are released between polls again.** v1.7.0 held the port open for the
+  lifetime of the entry. A serial port is exclusive, so on some setups the second config
+  entry could never open it and reported `Could not exclusively lock port` on every poll,
+  taking that inverter permanently offline. Reopening costs about 2 ms. Reported by
+  @dinkalin-ux. (#384)
+- **A serial port that cannot be opened now says why.** Previously this surfaced only as
+  `Failed to connect`, with the real reason buried in a pymodbus line above it. The warning
+  now names the likely cause and the command that confirms it.
+- **Documentation: choosing a stable serial path.** CH340 adapters — the most common cheap
+  USB-RS485 type — have no serial number, so `/dev/serial/by-id/` cannot tell two of them
+  apart and `/dev/ttyUSBn` numbering swaps between reboots. `by-path` is the right choice
+  for those. This makes it easy to configure two entries that unknowingly point at the same
+  adapter.
+
+---
+
 ## v1.7.2 (pre-release)
 
 Issues: #384

custom_components/growatt_modbus/growatt_modbus.py

@@ -512,6 +512,28 @@ def begin_poll(self) -> None:
         """Reset the per-poll recovery budget. Call once per poll, before any reads."""
         self._recoveries_this_poll = 0
 
+    def end_poll(self) -> None:
+        """Give an exclusive serial port back between polls.
+
+        A TCP socket is cheap to hold and reconnecting costs a round trip, so TCP keeps its
+        connection open across polls. A serial port is different: it is **exclusive**, and
+        holding it denies it to every other process on the machine — including a second
+        config entry that names the same adapter by a different path.
+
+        Before v1.7.0 the port was opened and closed per poll, so two such entries alternated
+        and mostly worked, with occasional collisions. Holding it open turned that into a
+        permanent lockout for whichever entry lost the race, with pyserial reporting
+        "Could not exclusively lock port" on every poll thereafter (#384).
+
+        Reopening a serial port costs about 2 ms, which is nothing next to a poll that reads
+        98 registers. The lock still serializes entries that do share a hub.
+        """
+        if not self.is_serial:
+            return
+        with self._lock:
+            self.disconnect()
+            self._client = None
+
     def _begin_recovery(self) -> bool:
         """True if a reset+retry is still within this poll's recovery budget."""
         if self._recoveries_this_poll >= self._max_recoveries_per_poll:
@@ -567,6 +589,25 @@ def ensure_connected(self) -> bool:
         if result:
             self._connected = True
             self._flush_receive_buffer()
+        elif self.is_serial:
+            # pyserial logs "[Errno 11] Could not exclusively lock port ..." and pymodbus
+            # turns it into a bare "Failed to connect", which tells the user nothing about
+            # the one cause that actually matters: somebody else already has this port.
+            #
+            # The usual somebody else is a second config entry naming the same adapter by a
+            # different path. That is easy to do by accident with cheap CH340 adapters
+            # (USB vendor 1a86), which ship without a serial number — so two of them produce
+            # by-id names that do not distinguish them, and the /dev/ttyUSBn numbering swaps
+            # on reboot. by-path is stable per physical socket and is the right choice there.
+            logger.warning(
+                "[SharedConn %s] Could not open the serial port. If the log above shows "
+                "'Could not exclusively lock port', another process or another Growatt "
+                "config entry already has it open. Check whether two entries point at the "
+                "same adapter under different names (/dev/ttyUSBn vs /dev/serial/by-id/... "
+                "vs /dev/serial/by-path/...) — run: ls -l /dev/serial/by-id/ "
+                "/dev/serial/by-path/",
+                self.connection_id,
+            )
         return result
 
     def disconnect(self) -> None:
@@ -1098,7 +1139,9 @@ def _flush_receive_buffer(self) -> None:
     def disconnect(self):
         """Close connection and release resources (critical for preventing file descriptor leaks)"""
         if self._shared_conn is not None:
-            # Connection lifetime is managed by the hub.
+            # Connection lifetime is managed by the hub — except for serial, where the hub
+            # gives the port back between polls. See SharedModbusConnection.end_poll().
+            self._shared_conn.end_poll()
             return
         if self.client:
             try:

custom_components/growatt_modbus/manifest.json

@@ -14,5 +14,5 @@
     "pymodbus>=3.0.0",
     "pyserial>=3.4"
   ],
-  "version": "1.7.2"
+  "version": "1.7.3"
 }

docs/troubleshooting/rs485-gateways.md

@@ -165,6 +165,29 @@ The integration handles this for you: every entry pointing at the same device pa
 
 **Serial setups need v1.7.0 or later for this.** Before that, only TCP entries were coordinated — each serial entry opened its own client on the same adapter and paced only itself, which produced random read failures on *all* the inverters sharing that bus. If you have two entries on one adapter and see unexplained dropouts, this is the first thing to rule out.
 
+### Two adapters: check they are actually two
+
+The most common cheap USB-RS485 adapters use the **CH340** chip (USB vendor `1a86`), and CH340s ship **without a serial number**. That has two consequences if you own two of them:
+
+- Their `/dev/serial/by-id/` names do not distinguish them — you may see one entry, or two that differ only by an index that can move.
+- Their `/dev/ttyUSBn` numbers are assigned in enumeration order and **swap between reboots**.
+
+So it is entirely possible to configure two entries that both point at the *same* adapter under different names, leaving the second adapter unused. The symptom is one entry working and the other failing with:
+
+```
+[Errno 11] Could not exclusively lock port /dev/ttyUSB3: Resource temporarily unavailable
+```
+
+A serial port can only be held by one owner. If you see that, run:
+
+```bash
+ls -l /dev/serial/by-id/ /dev/serial/by-path/
+```
+
+Both listings show what each name resolves to. If two entries land on the same `ttyUSBn`, that is the problem.
+
+**For adapters without a serial number, prefer `/dev/serial/by-path/`.** It identifies the physical USB socket rather than the device, so it stays stable across reboots *and* distinguishes two identical adapters — which `by-id` cannot. Use `by-id` when the adapter does have a serial number (FTDI adapters usually do); it survives being moved to a different socket.
+
 Two consequences worth knowing:
 
 - **Polls queue, they do not overlap.** With several inverters the effective cycle is the sum of their polls. If a single poll takes 8 s, three inverters need an interval comfortably above 24 s.

tests/test_serial_shared_connection.py

@@ -127,6 +127,34 @@ def test_the_serial_buffer_is_drained_with_pyserials_own_method(serial_hub):
     assert fake.reset_calls >= 1, "stale bytes were never drained on a serial connection"
 
 
+def test_a_serial_port_is_released_between_polls(serial_hub):
+    """A serial port is exclusive. Holding it open across polls denies it to every other
+    process, including a second config entry naming the same adapter by a different path —
+    which turned an intermittent collision into a permanent 'Could not exclusively lock
+    port' for one of them (#384)."""
+    serial_hub.ensure_connected()
+    assert serial_hub._client is not None
+
+    serial_hub.end_poll()
+    assert serial_hub._client is None, "the serial port is still held after the poll ended"
+
+    # ...and the next poll must be able to open it again.
+    assert serial_hub.ensure_connected() is True
+
+
+def test_a_tcp_socket_is_kept_open_between_polls():
+    """The opposite rule for TCP: a socket costs nothing to hold and reconnecting costs a
+    round trip, so end_poll() must leave it alone."""
+    hub = SharedModbusConnection(host="10.0.0.1", port=502)
+    hub._client = object()
+    hub.end_poll()
+    assert hub._client is not None, "TCP connections should persist across polls"
+
+
+def test_ending_a_poll_is_safe_before_anything_connected(serial_hub):
+    serial_hub.end_poll()  # must not raise
+
+
 def test_flushing_never_propagates_an_error(serial_hub):
     """A failed flush is non-critical and must not take down the poll."""
     serial_hub.ensure_connected()