feat: shared Modbus connection mode for multi-slave RS485 gateways (v1.0.8)

Fixes RS485 cross-talk on gateways like USR-DR164 when two integration
entries share the same host:port with different slave IDs. Previously, two
independent TCP sockets caused transaction ID mismatches and corrupted
readings as the gateway delivered each slave's response to the wrong session.

All TCP entries on the same host:port now share one ModbusTcpClient and a
threading.Lock (SharedModbusConnection hub). Reads/writes are serialized:
one slave's complete request/response cycle completes before the next begins.
A 50ms inter-slave pause (configurable) lets the RS485 bus settle. Lock
acquisition times out after 30s to prevent starvation. The hub reconnects
and flushes stale buffer bytes on socket drop, preserving the existing
issue-#317 protection.

Detection is automatic — no config options needed.

Closes #351

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 0xAHA

README.md

@@ -3,7 +3,7 @@
 # Growatt Modbus Integration for Home Assistant ☀️
 
 ![HACS Badge](https://img.shields.io/badge/HACS-Custom-orange.svg)
-![Version](https://img.shields.io/badge/Version-1.0.7-blue.svg)
+![Version](https://img.shields.io/badge/Version-1.0.8-blue.svg)
 [![GitHub Issues](https://img.shields.io/github/issues/0xAHA/Growatt_ModbusTCP.svg)](https://github.com/0xAHA/Growatt_ModbusTCP/issues)
 [![GitHub Stars](https://img.shields.io/github/stars/0xAHA/Growatt_ModbusTCP.svg?style=social)](https://github.com/0xAHA/Growatt_ModbusTCP)
 

RELEASENOTES.md

@@ -4,6 +4,35 @@
 
 ---
 
+## v1.0.8
+
+Issues: #351
+
+- **New: Shared Modbus connection mode for multi-inverter RS485-to-TCP gateways (Issue #351):**
+  When two integration entries point at the same RS485-to-TCP gateway (identical host:port, different
+  slave IDs), the integration now automatically shares a single `ModbusTcpClient` TCP socket between
+  them instead of opening two independent connections.
+
+  **Why this matters:** Consumer gateways like the USR-DR164 accept both TCP connections but cannot
+  correctly demultiplex RS485 responses back to the right session under simultaneous load. The result
+  is transaction ID mismatches ("request ask for id=2 but got id=3") and corrupted readings as each
+  slave's response is delivered to the wrong TCP session.
+
+  **How it works:** Detection is automatic — no configuration required. At setup, if a second entry
+  shares the same host:port as an existing one, both coordinators use the same `SharedModbusConnection`
+  hub. All reads and writes are serialized through a `threading.Lock`, ensuring one slave's complete
+  request/response cycle finishes before the next begins. A 50ms inter-slave pause is added after
+  each poll to let the RS485 bus settle (configurable via `inter_slave_delay` option).
+
+  Recovery: if the connection drops mid-read, the lock is always released (via `finally` block) and
+  the hub reconnects + flushes stale buffer bytes on the next poll. Lock acquisitions time out after
+  30s to prevent a hung coordinator from blocking others indefinitely.
+
+  Serial connections are not affected (each serial device opens its own file handle; same-device
+  multi-slave serial setups are unusual and typically handled by the OS serial stack).
+
+---
+
 ## v1.0.7
 
 - **New: Backup Box support (Growatt ARK transfer switch, TL-XH/MIN TL-XH):**

custom_components/growatt_modbus/__init__.py

@@ -16,12 +16,14 @@
     CONF_DEVICE_STRUCTURE_VERSION,
     CONF_INVERTER_SERIES,
     CONF_REGISTER_MAP,
+    CONF_CONNECTION_TYPE,
     CURRENT_DEVICE_STRUCTURE_VERSION,
     WRITABLE_REGISTERS,
     DEVICE_TYPE_INVERTER,
 )
 from .coordinator import GrowattModbusCoordinator
 from .diagnostic import async_setup_services
+from .growatt_modbus import SharedModbusConnection
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -33,10 +35,11 @@
 async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
     """Set up the Growatt Modbus integration."""
     hass.data.setdefault(DOMAIN, {})
-    
+    hass.data[DOMAIN].setdefault("_connections", {})
+
     # Set up diagnostic service
     await async_setup_services(hass)
-    
+
     return True
 
 
@@ -218,7 +221,31 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
         _LOGGER.info("Removing stale number entity %s (WIT export_limit_w reg 203 not writable)", _stale_export_eid)
         entity_registry.async_remove(_stale_export_eid)
 
-    coordinator = GrowattModbusCoordinator(hass, entry)
+    # Shared connection hub: all TCP entries on the same host:port share one ModbusTcpClient
+    # and a threading.Lock to serialize reads/writes and prevent RS485 cross-talk on the gateway.
+    # This is transparent for single-entry setups (hub refcount=1, no actual sharing).
+    hub: SharedModbusConnection | None = None
+    connection_type = entry.data.get(CONF_CONNECTION_TYPE, "tcp")
+    if connection_type == "tcp":
+        from homeassistant.const import CONF_HOST, CONF_PORT
+        host = entry.data.get(CONF_HOST, "")
+        port = entry.data.get(CONF_PORT, 502)
+        timeout = entry.options.get("timeout", 10)
+        hub_key = f"{host}:{port}"
+        connections = hass.data[DOMAIN].setdefault("_connections", {})
+        if hub_key not in connections:
+            connections[hub_key] = SharedModbusConnection(host=host, port=port, timeout=timeout)
+            _LOGGER.debug("Created shared Modbus connection hub for %s", hub_key)
+        hub = connections[hub_key]
+        hub.acquire_ref()
+        if hub._refcount > 1:
+            _LOGGER.info(
+                "Shared Modbus connection mode: entry %s joined hub for %s (refcount=%d) — "
+                "RS485 gateway cross-talk prevention active",
+                entry.entry_id, hub_key, hub._refcount,
+            )
+
+    coordinator = GrowattModbusCoordinator(hass, entry, hub=hub)
 
     await coordinator.async_config_entry_first_refresh()
 
@@ -278,7 +305,18 @@ async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     """Unload a config entry."""
     if unload_ok := await hass.config_entries.async_unload_platforms(entry, PLATFORMS):
         coordinator = hass.data[DOMAIN].pop(entry.entry_id)
-        await hass.async_add_executor_job(coordinator.modbus_client.disconnect)
+        hub = getattr(coordinator, '_hub', None)
+        if hub is not None:
+            # Release the hub reference; hub disconnects when refcount reaches 0
+            connections = hass.data[DOMAIN].get("_connections", {})
+            hub.release_ref()
+            if hub._refcount <= 0:
+                # Remove from registry — hub already disconnected in release_ref()
+                hub_key = f"{hub.host}:{hub.port}"
+                connections.pop(hub_key, None)
+                _LOGGER.debug("Shared Modbus connection hub for %s removed (no more users)", hub_key)
+        else:
+            await hass.async_add_executor_job(coordinator.modbus_client.disconnect)
 
     return unload_ok
 

custom_components/growatt_modbus/const.py

@@ -60,6 +60,14 @@
 #            Controls are within their respective devices (inverter or battery)
 CURRENT_DEVICE_STRUCTURE_VERSION = 2
 
+# ============================================================================
+# SHARED CONNECTION MODE
+# When two TCP entries share the same host:port, a single ModbusTcpClient is
+# reused with a threading.Lock to serialize reads and prevent RS485 cross-talk.
+# ============================================================================
+SHARED_LOCK_TIMEOUT = 30       # seconds to wait for shared bus lock before giving up
+DEFAULT_INTER_SLAVE_DELAY_MS = 50  # ms pause after each slave poll to let RS485 bus settle
+
 # ============================================================================
 # SENSOR TYPE CLASSIFICATIONS FOR OFFLINE BEHAVIOR
 # ============================================================================

custom_components/growatt_modbus/coordinator.py

@@ -30,11 +30,13 @@
     DEVICE_TYPE_LOAD,
     DEVICE_TYPE_BATTERY,
     DEVICE_TYPE_BACKUPBOX,
+    SHARED_LOCK_TIMEOUT,
+    DEFAULT_INTER_SLAVE_DELAY_MS,
 )
 
 from .const import REGISTER_MAPS
 
-from .growatt_modbus import GrowattModbus, GrowattData
+from .growatt_modbus import GrowattModbus, GrowattData, SharedModbusConnection
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -97,11 +99,13 @@ def test_connection(config: dict) -> dict:
 class GrowattModbusCoordinator(DataUpdateCoordinator[GrowattData]):
     """Growatt Modbus data update coordinator."""
 
-    def __init__(self, hass: HomeAssistant, entry: ConfigEntry) -> None:
+    def __init__(self, hass: HomeAssistant, entry: ConfigEntry,
+                 hub: 'SharedModbusConnection | None' = None) -> None:
         """Initialize the coordinator."""
         self.entry = entry
         self.config = entry.data
         self.hass = hass
+        self._hub = hub  # Shared connection hub (TCP multi-entry same host:port)
 
         self._slave_id = entry.data[CONF_SLAVE_ID]
 
@@ -351,10 +355,17 @@ def _initialize_client(self):
                     slave_id=self.config[CONF_SLAVE_ID],
                     register_map=register_map,
                     timeout=timeout,
-                    invert_battery_power=invert_battery_power
+                    invert_battery_power=invert_battery_power,
+                    shared_conn=self._hub,
                 )
-                _LOGGER.debug("Initialized TCP Growatt client at %s:%s (invert_battery_power=%s)",
-                             self.config[CONF_HOST], self.config[CONF_PORT], invert_battery_power)
+                if self._hub:
+                    _LOGGER.debug(
+                        "Initialized TCP Growatt client at %s:%s (shared connection mode, invert_battery_power=%s)",
+                        self.config[CONF_HOST], self.config[CONF_PORT], invert_battery_power,
+                    )
+                else:
+                    _LOGGER.debug("Initialized TCP Growatt client at %s:%s (invert_battery_power=%s)",
+                                 self.config[CONF_HOST], self.config[CONF_PORT], invert_battery_power)
             else:  # serial
                 self._client = GrowattModbus(
                     connection_type="serial",
@@ -896,8 +907,60 @@ async def _async_update_data(self) -> GrowattData:
             self.data = GrowattData()
             return self.data
 
+    def _fetch_data_shared(self) -> GrowattData | None:
+        """Fetch data using the shared connection hub (holds hub lock for the full poll)."""
+        hub = self._hub
+        inter_slave_delay = self.config_entry.options.get(
+            "inter_slave_delay", DEFAULT_INTER_SLAVE_DELAY_MS
+        ) / 1000.0
+
+        acquired = hub._lock.acquire(timeout=SHARED_LOCK_TIMEOUT)
+        if not acquired:
+            _LOGGER.warning(
+                "Shared Modbus connection busy (lock timeout %ds) for %s:%s slave %s — skipping this poll",
+                SHARED_LOCK_TIMEOUT,
+                self.config.get(CONF_HOST),
+                self.config.get(CONF_PORT),
+                self.config.get(CONF_SLAVE_ID),
+            )
+            return None
+
+        try:
+            if not hub.ensure_connected():
+                _LOGGER.warning(
+                    "Shared Modbus connection could not connect to %s:%s",
+                    self.config.get(CONF_HOST), self.config.get(CONF_PORT),
+                )
+                return None
+
+            self._client._battery_voltage_range = self.config_entry.options.get(
+                "battery_voltage_range", "Auto-detect"
+            )
+            delay_s = self.config_entry.options.get("modbus_delay", 250) / 1000.0
+            self._client._default_min_read_interval = delay_s
+            if not self._client._backed_off:
+                self._client.min_read_interval = delay_s
+
+            data = self._client.read_all_data()
+            if data is not None and not self._serial_number:
+                self._read_device_identification()
+
+            time.sleep(inter_slave_delay)
+            return data
+
+        except Exception as err:
+            _LOGGER.warning("Error during shared data fetch for slave %s: %s",
+                            self.config.get(CONF_SLAVE_ID), err)
+            return None
+
+        finally:
+            hub._lock.release()
+
     def _fetch_data(self) -> GrowattData | None:
         """Fetch data from the inverter (runs in executor)."""
+        if self._hub is not None:
+            return self._fetch_data_shared()
+
         max_retries = 3
         retry_delay = 3  # seconds - increased from 2