Improve docs around sync clients and reconnection

doc/source/client.rst

@@ -118,19 +118,32 @@ that a device have received the packet.
 Client usage
 ------------
 Using pymodbus client to set/get information from a device (server)
-is done in a few simple steps, like the following synchronous example::
+is done in a few simple steps.
+
+Synchronous example
+^^^^^^^^^^^^^^^^^^^
+
+::
 
     from pymodbus.client import ModbusTcpClient
 
     client = ModbusTcpClient('MyDevice.lan')   # Create client object
-    client.connect()                           # connect to device, reconnect automatically
+    client.connect()                           # connect to device
     client.write_coil(1, True, slave=1)        # set information in device
     result = client.read_coils(2, 3, slave=1)  # get information from device
     print(result.bits[0])                      # use information
     client.close()                             # Disconnect device
 
+The line :mod:`client.connect()` connects to the device (or comm port). If this cannot connect successfully within
+the timeout it throws an exception. After this initial connection, further
+calls to the same client (here, :mod:`client.write_coil(...)` and
+:mod:`client.read_coils(...)` ) will check whether the client is still
+connected, and automatically reconnect if not.
 
-and a asynchronous example::
+Asynchronous example
+^^^^^^^^^^^^^^^^^^^^
+
+::
 
     from pymodbus.client import AsyncModbusTcpClient
 
@@ -141,7 +154,7 @@ and a asynchronous example::
     print(result.bits[0])                            # use information
     client.close()                                   # Disconnect device
 
-The line :mod:`client = AsyncModbusTcpClient('MyDevice.lan')` only creates the object it does not activate
+The line :mod:`client = AsyncModbusTcpClient('MyDevice.lan')` only creates the object; it does not activate
 anything.
 
 The line :mod:`await client.connect()` connects to the device (or comm port), if this cannot connect successfully within
@@ -153,6 +166,9 @@ The line :mod:`result = await client.read_coils(2, 3, slave=1)` is an example of
 
 The last line :mod:`client.close()` closes the connection and render the object inactive.
 
+Usage notes
+^^^^^^^^^^^
+
 Large parts of the implementation are shared between the different classes,
 to ensure high stability and efficient maintenance.
 

pymodbus/client/serial.py

@@ -123,15 +123,15 @@ class ModbusSerialClient(ModbusBaseSyncClient):
     :param stopbits: Number of stop bits 0-2.
     :param handle_local_echo: Discard local echo from dongle.
     :param name: Set communication name, used in logging
-    :param reconnect_delay: Minimum delay in seconds.milliseconds before reconnecting.
-    :param reconnect_delay_max: Maximum delay in seconds.milliseconds before reconnecting.
+    :param reconnect_delay: Not used in the sync client
+    :param reconnect_delay_max: Not used in the sync client
     :param timeout: Timeout for a connection request, in seconds.
     :param retries: Max number of retries per request.
 
-    .. tip::
-        **reconnect_delay** doubles automatically with each unsuccessful connect, from
-        **reconnect_delay** to **reconnect_delay_max**.
-        Set `reconnect_delay=0` to avoid automatic reconnection.
+    Note that unlike the async client, the sync client does not perform
+    retries. If the connection has closed, the client will attempt to reconnect
+    once before executing each read/write request, and will raise a
+    ConnectionException if this fails.
 
     Example::
 
@@ -145,8 +145,6 @@ def run():
             client.close()
 
     Please refer to :ref:`Pymodbus internals` for advanced usage.
-
-    Remark: There are no automatic reconnect as with AsyncModbusSerialClient
     """
 
     state = ModbusTransactionState.IDLE

pymodbus/client/tcp.py

@@ -103,15 +103,15 @@ class ModbusTcpClient(ModbusBaseSyncClient):
     :param port: Port used for communication
     :param name: Set communication name, used in logging
     :param source_address: source address of client
-    :param reconnect_delay: Minimum delay in seconds.milliseconds before reconnecting.
-    :param reconnect_delay_max: Maximum delay in seconds.milliseconds before reconnecting.
+    :param reconnect_delay: Not used in the sync client
+    :param reconnect_delay_max: Not used in the sync client
     :param timeout: Timeout for a connection request, in seconds.
     :param retries: Max number of retries per request.
 
-    .. tip::
-        **reconnect_delay** doubles automatically with each unsuccessful connect, from
-        **reconnect_delay** to **reconnect_delay_max**.
-        Set `reconnect_delay=0` to avoid automatic reconnection.
+    Note that unlike the async client, the sync client does not perform
+    retries. If the connection has closed, the client will attempt to reconnect
+    once before executing each read/write request, and will raise a
+    ConnectionException if this fails.
 
     Example::
 
@@ -125,8 +125,6 @@ async def run():
             client.close()
 
     Please refer to :ref:`Pymodbus internals` for advanced usage.
-
-    Remark: There are no automatic reconnect as with AsyncModbusTcpClient
     """
 
     socket: socket.socket | None

pymodbus/client/tls.py

@@ -120,15 +120,15 @@ class ModbusTlsClient(ModbusTcpClient):
     :param port: Port used for communication
     :param name: Set communication name, used in logging
     :param source_address: Source address of client
-    :param reconnect_delay: Minimum delay in seconds.milliseconds before reconnecting.
-    :param reconnect_delay_max: Maximum delay in seconds.milliseconds before reconnecting.
+    :param reconnect_delay: Not used in the sync client
+    :param reconnect_delay_max: Not used in the sync client
     :param timeout: Timeout for a connection request, in seconds.
     :param retries: Max number of retries per request.
 
-    .. tip::
-        **reconnect_delay** doubles automatically with each unsuccessful connect, from
-        **reconnect_delay** to **reconnect_delay_max**.
-        Set `reconnect_delay=0` to avoid automatic reconnection.
+    Note that unlike the async client, the sync client does not perform
+    retries. If the connection has closed, the client will attempt to reconnect
+    once before executing each read/write request, and will raise a
+    ConnectionException if this fails.
 
     Example::
 
@@ -142,8 +142,6 @@ async def run():
             client.close()
 
     Please refer to :ref:`Pymodbus internals` for advanced usage.
-
-    Remark: There are no automatic reconnect as with AsyncModbusTlsClient
     """
 
     def __init__(  # pylint: disable=too-many-arguments

pymodbus/client/udp.py

@@ -103,15 +103,15 @@ class ModbusUdpClient(ModbusBaseSyncClient):
     :param port: Port used for communication.
     :param name: Set communication name, used in logging
     :param source_address: source address of client,
-    :param reconnect_delay: Minimum delay in seconds.milliseconds before reconnecting.
-    :param reconnect_delay_max: Maximum delay in seconds.milliseconds before reconnecting.
+    :param reconnect_delay: Not used in the sync client
+    :param reconnect_delay_max: Not used in the sync client
     :param timeout: Timeout for a connection request, in seconds.
     :param retries: Max number of retries per request.
 
-    .. tip::
-        **reconnect_delay** doubles automatically with each unsuccessful connect, from
-        **reconnect_delay** to **reconnect_delay_max**.
-        Set `reconnect_delay=0` to avoid automatic reconnection.
+    Note that unlike the async client, the sync client does not perform
+    retries. If the connection has closed, the client will attempt to reconnect
+    once before executing each read/write request, and will raise a
+    ConnectionException if this fails.
 
     Example::
 
@@ -125,8 +125,6 @@ async def run():
             client.close()
 
     Please refer to :ref:`Pymodbus internals` for advanced usage.
-
-    Remark: There are no automatic reconnect as with AsyncModbusUdpClient
     """
 
     socket: socket.socket | None