Rectify sync/async client parameters AND make new client documentation.

doc/source/library/pymodbus.client.rst

@@ -1,82 +1,55 @@
-pymodbus\.client package
-========================
+pymodbus\.client
+================
 
-Pymodbus offers a :mod:`synchronous client <pymodbus.client>`, and async clients based on :mod:`asyncio <pymodbus.client.asynchronous>`.
+Pymodbus offers a :mod:`synchronous client <pymodbus.client>` and a :mod:`client based on asyncio <pymodbus.client.asynchronous>`.
 
-Each client shares a :mod:`client mixin <pymodbus.client.helper_sync>` which offers simple methods for reading and writing.
+In general each transports (Serial, TCP, TLS and UDP) have its own class.
+However the actual implementation is highly shared.
 
-Submodules
-----------
+AsyncModbusSerialClient class
+-----------------------------
 
-pymodbus\.client\.helper_sync module
-------------------------------------
-
-.. automodule:: pymodbus.client.helper_sync
+.. automodule:: pymodbus.client.async_serial
     :members:
-    :undoc-members:
-    :show-inheritance:
 
-pymodbus\.client\.ModbusSerialClient module
--------------------------------------------
+ModbusSerialClient class
+------------------------
 
 .. automodule:: pymodbus.client.sync_serial
     :members:
-    :undoc-members:
-    :show-inheritance:
-
-pymodbus\.client\.ModbusTCPClient module
-----------------------------------------
-
-.. automodule:: pymodbus.client.sync_tcp
-    :members:
-    :undoc-members:
-    :show-inheritance:
 
-pymodbus\.client\.ModbusTLSClient module
-----------------------------------------
+AsyncModbusTcpClient class
+--------------------------
 
-.. automodule:: pymodbus.client.sync_tls
+.. automodule:: pymodbus.client.async_tcp
     :members:
-    :undoc-members:
-    :show-inheritance:
 
-pymodbus\.client\.ModbusUDPClient module
-----------------------------------------
+ModbusTcpClient class
+---------------------
 
-.. automodule:: pymodbus.client.sync_udp
+.. automodule:: pymodbus.client.sync_tcp
     :members:
-    :undoc-members:
-    :show-inheritance:
 
-pymodbus\.client\.AsyncModbusUDPClient module
----------------------------------------------
+AsyncModbusTlsClient class
+--------------------------
 
-.. automodule:: pymodbus.client.async_udp
+.. automodule:: pymodbus.client.async_tls
     :members:
-    :undoc-members:
-    :show-inheritance:
 
-pymodbus\.client\.AsyncModbusTLSClient module
----------------------------------------------
+ModbusTlsClient class
+---------------------
 
-.. automodule:: pymodbus.client.async_tls
+.. automodule:: pymodbus.client.sync_tls
     :members:
-    :undoc-members:
-    :show-inheritance:
 
-pymodbus\.client\.AsyncModbusSerialClient module
-------------------------------------------------
+AsyncModbusUdpClient class
+--------------------------
 
-.. automodule:: pymodbus.client.async_serial
+.. automodule:: pymodbus.client.async_udp
     :members:
-    :undoc-members:
-    :show-inheritance:
-
 
-pymodbus\.client\.AsyncModbusTCPClient module
----------------------------------------------
+ModbusUdpClient class
+---------------------
 
-.. automodule:: pymodbus.client.async_tcp
+.. automodule:: pymodbus.client.sync_udp
     :members:
-    :undoc-members:
-    :show-inheritance:

examples/client_async.py

@@ -29,10 +29,10 @@
 # import the various client implementations
 # --------------------------------------------------------------------------- #
 from pymodbus.client import (
-    AsyncModbusUDPClient,
-    AsyncModbusTLSClient,
     AsyncModbusSerialClient,
-    AsyncModbusTCPClient,
+    AsyncModbusTcpClient,
+    AsyncModbusTlsClient,
+    AsyncModbusUdpClient,
 )
 from pymodbus.transaction import (
     ModbusAsciiFramer,
@@ -49,54 +49,75 @@ async def setup_async_client():
     _logger.info("### Create client object")
 
     if args.comm == "tcp":
-        client = AsyncModbusTCPClient(
-            "127.0.0.1",  # define tcp address where to connect to.
+        client = AsyncModbusTcpClient(
+            "127.0.0.1",
             port=args.port,  # on which port
-            framer=ModbusSocketFramer,  # how to interpret the messages
-            timeout=1,  # waiting time for request to complete
-            retries=3,  # retries per transaction
-            retry_on_empty=False,  # Is an empty response a retry
-            source_address=("localhost", 0),  # bind socket to address
-            strict=True,  # use strict timing, t1.5 for Modbus RTU
+            # Common optional paramers:
+            #    protocol_class=ModbusClientProtocol,
+            #    modbus_decoder=ClientDecoder,
+            framer=args.framer,
+            #    timeout=10,
+            #    retries=3,
+            #    retry_on_empty=False,
+            #    close_comm_on_error=False,
+            #    strict=True,
+            # TCP setup parameters
+            #    source_address=("localhost", 0),
         )
     elif args.comm == "udp":
-        client = AsyncModbusUDPClient(
-            "localhost",  # define tcp address where to connect to.
-            port=args.port,  # on which port
-            framer=args.framer,  # how to interpret the messages
-            timeout=1,  # waiting time for request to complete
-            retries=3,  # retries per transaction
-            retry_on_empty=False,  # Is an empty response a retry
-            source_address=("localhost", 0),  # bind socket to address
-            strict=True,  # use strict timing, t1.5 for Modbus RTU
+        client = AsyncModbusUdpClient(
+            "localhost",
+            #    port=502,
+            # Common optional paramers:
+            #    protocol_class=ModbusClientProtocol,
+            #    modbus_decoder=ClientDecoder,
+            framer=args.framer,
+            #    timeout=10,
+            #    retries=3,
+            #    retry_on_empty=False,
+            #    close_comm_on_error=False,
+            #    strict=True,
+            # UDP setup parameters
+            #    source_address=None,
         )
     elif args.comm == "serial":
         client = AsyncModbusSerialClient(
-            args.port,  # serial port
-            framer=args.framer,  # how to interpret the messages
-            stopbits=1,  # The number of stop bits to use
-            bytesize=7,  # The bytesize of the serial messages
-            parity="even",  # Which kind of parity to use
-            baudrate=9600,  # The baud rate to use for the serial device
-            handle_local_echo=False,  # Handle local echo of the USB-to-RS485 adaptor
-            timeout=1,  # waiting time for request to complete
-            strict=True,  # use strict timing, t1.5 for Modbus RTU
+            args.port,
+            # Common optional paramers:
+            #    protocol_class=ModbusClientProtocol,
+            #    modbus_decoder=ClientDecoder,
+            #    framer=ModbusRtuFramer,
+            #    timeout=10,
+            #    retries=3,
+            #    retry_on_empty=False,
+            #    close_comm_on_error=False,
+            #    strict=True,
+            # Serial setup parameters
+            #    baudrate=9600,
+            #    bytesize=8,
+            #    parity="N",
+            #    stopbits=1,
+            #    handle_local_echo=False,
         )
     elif args.comm == "tls":
-        client = AsyncModbusTLSClient(
-            host="localhost",  # define tcp address where to connect to.
-            port=args.port,  # on which port
-            sslctx=None,  # ssl control
-            certfile=None,  # certificate file
-            keyfile=None,  # key file
-            password=None,  # pass phrase
-            framer=args.framer,  # how to interpret the messages
-            timeout=1,  # waiting time for request to complete
-            retries=3,  # retries per transaction
-            retry_on_empty=False,  # Is an empty response a retry
-            source_address=("localhost", 0),  # bind socket to address
-            server_hostname="localhost",  # used for cert verification
-            strict=True,  # use strict timing, t1.5 for Modbus RTU
+        client = AsyncModbusTlsClient(
+            "localhost",
+            port=args.port,
+            # Common optional paramers:
+            #    protocol_class=None,
+            #    modbus_decoder=ClientDecoder,
+            framer=args.framer,
+            #    timeout=10,
+            #    retries=3,
+            #    retry_on_empty=False,
+            #    close_comm_on_error=False,
+            #    strict=True,
+            # TLS setup parameters
+            #    sslctx=None,
+            #    certfile=None,
+            #    keyfile=None,
+            #    password=None,
+            #    server_hostname="localhost",
         )
     await client.start()
     return client

examples/client_sync.py

@@ -48,52 +48,74 @@ def setup_sync_client():
     _logger.info("### Create client object")
     if args.comm == "tcp":
         client = ModbusTcpClient(
-            host="127.0.0.1",  # define tcp address where to connect to.
-            port=args.port,  # on which port
-            framer=args.framer,  # how to interpret the messages
-            timeout=1,  # waiting time for request to complete
-            retries=3,  # retries per transaction
-            retry_on_empty=False,  # Is an empty response a retry
-            source_address=("localhost", 0),  # bind socket to address
-            strict=True,  # use strict timing, t1.5 for Modbus RTU
+            "127.0.0.1",
+            port=args.port,
+            # Common optional paramers:
+            #    protocol_class=None,
+            #    modbus_decoder=ClientDecoder,
+            framer=args.framer,
+            #    timeout=10,
+            #    retries=3,
+            #    retry_on_empty=False,y
+            #    close_comm_on_error=False,
+            #    strict=True,
+            # TCP setup parameters
+            #    source_address=("localhost", 0),
         )
     elif args.comm == "udp":
         client = ModbusUdpClient(
-            host="localhost",  # define tcp address where to connect to.
-            port=args.port,  # on which port
-            framer=args.framer,  # how to interpret the messages
-            timeout=1,  # waiting time for request to complete
-            retries=3,  # retries per transaction
-            retry_on_empty=False,  # Is an empty response a retry
-            source_address=("localhost", 0),  # bind socket to address
-            strict=True,  # use strict timing, t1.5 for Modbus RTU
+            "localhost",
+            #    port=502,
+            # Common optional paramers:
+            #    protocol_class=ModbusClientProtocol,
+            #    modbus_decoder=ClientDecoder,
+            framer=args.framer,
+            #    timeout=10,
+            #    retries=3,
+            #    retry_on_empty=False,
+            #    close_comm_on_error=False,
+            #    strict=True,
+            # UDP setup parameters
+            #    source_address=None,
         )
     elif args.comm == "serial":
         client = ModbusSerialClient(
             port=args.port,  # serial port
-            framer=args.framer,  # how to interpret the messages
-            stopbits=1,  # The number of stop bits to use
-            bytesize=7,  # The bytesize of the serial messages
-            parity="E",  # Which kind of parity to use
-            baudrate=9600,  # The baud rate to use for the serial device
-            handle_local_echo=False,  # Handle local echo of the USB-to-RS485 adaptor
-            timeout=1,  # waiting time for request to complete
-            strict=True,  # use strict timing, t1.5 for Modbus RTU
+            # Common optional paramers:
+            #    protocol_class=ModbusClientProtocol,
+            #    modbus_decoder=ClientDecoder,
+            #    framer=ModbusRtuFramer,
+            #    timeout=10,
+            #    retries=3,
+            #    retry_on_empty=False,
+            #    close_comm_on_error=False,.
+            #    strict=True,
+            # Serial setup parameters
+            #    baudrate=9600,
+            #    bytesize=8,
+            #    parity="N",
+            #    stopbits=1,
+            #    handle_local_echo=False,
         )
     elif args.comm == "tls":
         client = ModbusTlsClient(
-            host="localhost",  # define tcp address where to connect to.
-            port=args.port,  # on which port
-            sslctx=None,  # ssl control
-            certfile=None,  # certificate file
-            keyfile=None,  # key file
-            password=None,  # pass phrase
-            framer=args.framer,  # how to interpret the messages
-            timeout=1,  # waiting time for request to complete
-            retries=3,  # retries per transaction
-            retry_on_empty=False,  # Is an empty response a retry
-            source_address=("localhost", 0),  # bind socket to address
-            strict=True,  # use strict timing, t1.5 for Modbus RTU
+            "localhost",
+            port=args.port,
+            # Common optional paramers:
+            #    protocol_class=None,
+            #    modbus_decoder=ClientDecoder,
+            framer=args.framer,
+            #    timeout=10,
+            #    retries=3,
+            #    retry_on_empty=False,
+            #    close_comm_on_error=False,
+            #    strict=True,
+            # TLS setup parameters
+            #    sslctx=None,
+            #    certfile=None,
+            #    keyfile=None,
+            #    password=None,
+            #    server_hostname="localhost",
         )
     return client, args.comm != "udp"
 

examples/contrib/asynchronous_asyncio_modbus_tls_client.py

@@ -11,7 +11,7 @@
 import ssl
 import asyncio
 
-from pymodbus.client import AsyncModbusTLSClient
+from pymodbus.client import AsyncModbusTlsClient
 
 # -------------------------------------------------------------------------- #
 # the TLS detail security can be set in SSLContext which is the context here
@@ -38,7 +38,7 @@ async def start_async_test(client):
     # ----------------------------------------------------------------------- #
     # pass SSLContext which is the context here to ModbusTcpClient()
     # ----------------------------------------------------------------------- #
-    new_client = AsyncModbusTLSClient(  # pylint: disable=unpacking-non-sequence
+    new_client = AsyncModbusTlsClient(  # pylint: disable=unpacking-non-sequence
         "test.host.com",
         8020,
         sslctx=sslctx,

pymodbus/client/__init__.py

@@ -2,10 +2,10 @@
 
 import external classes, to make them easier to use:
 """
-from pymodbus.client.async_udp import AsyncModbusUDPClient
-from pymodbus.client.async_tls import AsyncModbusTLSClient
 from pymodbus.client.async_serial import AsyncModbusSerialClient
-from pymodbus.client.async_tcp import AsyncModbusTCPClient
+from pymodbus.client.async_tcp import AsyncModbusTcpClient
+from pymodbus.client.async_tls import AsyncModbusTlsClient
+from pymodbus.client.async_udp import AsyncModbusUdpClient
 from pymodbus.client.sync_serial import ModbusSerialClient
 from pymodbus.client.sync_tcp import ModbusTcpClient
 from pymodbus.client.sync_tls import ModbusTlsClient
@@ -15,10 +15,10 @@
 #  Exported symbols
 # ---------------------------------------------------------------------------#
 __all__ = [
-    "AsyncModbusUDPClient",
-    "AsyncModbusTLSClient",
     "AsyncModbusSerialClient",
-    "AsyncModbusTCPClient",
+    "AsyncModbusTcpClient",
+    "AsyncModbusTlsClient",
+    "AsyncModbusUdpClient",
     "ModbusSerialClient",
     "ModbusTcpClient",
     "ModbusTlsClient",