Client

Pymodbus offers both a synchronous client and a asynchronous client. Both clients offer simple calls for each type of request, as well as a unified response, removing a lot of the complexities in the modbus protocol.

In addition to the “pure” client, pymodbus offers a set of utilities converting to/from registers to/from “normal” python values.

The client is NOT thread safe, meaning the application must ensure that calls are serialized. This is only a problem for synchronous applications that use multiple threads or for asynchronous applications that use multiple asyncio.create_task.

It is allowed to have multiple client objects that e.g. each communicate with a TCP based device.

Client performance

There are currently a big performance gap between the 2 clients (try it on your computer examples/client_performance.py). This is due to a rather old implementation of the synchronous client, we are currently working to update the client code. Our aim is to achieve a similar data rate with both clients and at least double the data rate while keeping the stability. Table below is a test with 1000 calls each reading 10 registers.

client	asynchronous	synchronous
total time	0,33 sec	114,10 sec
ms/call	0,33 ms	114,10 ms
ms/register	0,03 ms	11,41 ms
calls/sec	3.030	8
registers/sec	30.300	87

Client protocols/framers

Pymodbus offers clients with transport different protocols and different framers

protocol	ASCII	RTU	RTU_OVER_TCP	SOCKET	TLS
SERIAL (RS-485)	Yes	Yes	No	No	No
TCP	Yes	No	Yes	Yes	No
TLS	No	No	No	No	Yes
UDP	Yes	No	Yes	Yes	No

Serial (RS-485)

Pymodbus do not connect to the device (server) but connects to a comm port or usb port on the local computer.

RS-485 is a half duplex protocol, meaning the servers do nothing until the client sends a request then the server being addressed responds. The client controls the traffic and as a consequence one RS-485 line can only have 1 client but upto 254 servers (physical devices).

RS-485 is a simple 2 wire cabling with a pullup resistor. It is important to note that many USB converters do not have a builtin resistor, this must be added manually. When experiencing many faulty packets and retries this is often the problem.

TCP

Pymodbus connects directly to the device using a standard socket and have a one-to-one connection with the device. In case of multiple TCP devices the application must instantiate multiple client objects one for each connection.

Tip

a TCP device often represent multiple physical devices (e.g Ethernet-RS485 converter), each of these devices can be addressed normally

TLS

A variant of TCP that uses encryption and certificates. TLS is mostly used when the devices are connected to the internet.

UDP

A broadcast variant of TCP. UDP allows addressing of many devices with a single request, however there are no control 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.

Synchronous example

from pymodbus.client import ModbusTcpClient

client = ModbusTcpClient('MyDevice.lan')   # Create client object
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 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, client.write_coil(...) and client.read_coils(...) ) will check whether the client is still connected, and automatically reconnect if not.

Asynchronous example

from pymodbus.client import AsyncModbusTcpClient

client = AsyncModbusTcpClient('MyDevice.lan')    # Create client object
await client.connect()                           # connect to device, reconnect automatically
await client.write_coil(1, True, slave=1)        # set information in device
result = await client.read_coils(2, 3, slave=1)  # get information from device
print(result.bits[0])                            # use information
client.close()                                   # Disconnect device

The line client = AsyncModbusTcpClient('MyDevice.lan') only creates the object; it does not activate anything.

The line await client.connect() connects to the device (or comm port), if this cannot connect successfully within the timeout it throws an exception. If connected successfully reconnecting later is handled automatically

The line await client.write_coil(1, True, slave=1) is an example of a write request, set address 1 to True on device 1 (slave).

The line result = await client.read_coils(2, 3, slave=1) is an example of a read request, get the value of address 2, 3 and 4 (count = 3) from device 1 (slave).

The last line client.close() closes the connection and render the object inactive.

Retry logic for async clients

If no response is received to a request (call), it is retried (parameter retries) times, if not successful an exception response is returned, BUT the connection is not touched.

If 3 consequitve requests (calls) do not receive a response, the connection is terminated.

Development notes

Large parts of the implementation are shared between the different classes, to ensure high stability and efficient maintenance.

The synchronous clients are not thread safe nor is a single client intended to be used from multiple threads. Due to the nature of the modbus protocol, it makes little sense to have client calls split over different threads, however the application can do it with proper locking implemented.

The asynchronous client only runs in the thread where the asyncio loop is created, it does not provide mechanisms to prevent (semi)parallel calls, that must be prevented at application level.

Client device addressing

With TCP, TLS and UDP, the tcp/ip address of the physical device is defined when creating the object. The logical devices represented by the device is addressed with the slave= parameter.

With Serial, the comm port is defined when creating the object. The physical devices are addressed with the slave= parameter.

slave=0 is defined as broadcast in the modbus standard, but pymodbus treats is a normal device.

If an application is expecting multiple responses to a broadcast request, it must call client.execute and deal with the responses.

If no response is expected to a request, the no_response_expected=True argument can be used in the normal API calls, this will cause the call to return imidiatble with None

Client response handling

All simple request calls (mixin) return a unified result independent whether it´s a read, write or diagnostic call.

The application should evaluate the result generically:

try:
    rr = await client.read_coils(1, 1, slave=1)
except ModbusException as exc:
    _logger.error(f"ERROR: exception in pymodbus {exc}")
    raise exc
if rr.isError():
    _logger.error("ERROR: pymodbus returned an error!")
    raise ModbusException(txt)

except ModbusException as exc: happens generally when pymodbus experiences an internal error. There are a few situation where a unexpected response from a device can cause an exception.

rr.isError() is set whenever the device reports a problem.

And in case of read retrieve the data depending on type of request

rr.bits is set for coils / input_register requests
rr.registers is set for other requests

Remark if using no_response_expected=True rr will always be None.

Client interface classes

There are a client class for each type of communication and for asynchronous/synchronous

Serial	`AsyncModbusSerialClient`	`ModbusSerialClient`
TCP	`AsyncModbusTcpClient`	`ModbusTcpClient`
TLS	`AsyncModbusTlsClient`	`ModbusTlsClient`
UDP	`AsyncModbusUdpClient`	`ModbusUdpClient`

Client common

Some methods are common to all client:

class pymodbus.client.base.ModbusBaseClient(framer: FramerType, retries: int, on_connect_callback: Callable[[bool], None] | None, comm_params: CommParams | None = None)

Bases: ModbusClientMixin[Awaitable[ModbusPDU]]

ModbusBaseClient.

ModbusBaseClient is normally not referenced outside pymodbus.

property connected: bool: Return state of connection.

async connect() → bool: Call transport connect.

register(custom_response_class: type[ModbusPDU]) → None

Register a custom response class with the decoder (call sync).

Parameters:: custom_response_class – (optional) Modbus response class.
Raises:: MessageRegisterException – Check exception text.

Use register() to add non-standard responses (like e.g. a login prompt) and have them interpreted automatically.

close() → None: Close connection.

class pymodbus.client.base.ModbusBaseSyncClient(framer: FramerType, retries: int, comm_params: CommParams | None = None)

Bases: ModbusClientMixin[ModbusPDU]

ModbusBaseClient.

ModbusBaseClient is normally not referenced outside pymodbus.

register(custom_response_class: type[ModbusPDU]) → None

Register a custom response class with the decoder.

Parameters:: custom_response_class – (optional) Modbus response class.
Raises:: MessageRegisterException – Check exception text.

Use register() to add non-standard responses (like e.g. a login prompt) and have them interpreted automatically.

idle_time() → float

Time before initiating next transaction (call sync).

Applications can call message functions without checking idle_time(), this is done automatically.

connect() → bool: Connect to other end, overwritten.

close(): Close connection, overwritten.

Client serial

class pymodbus.client.AsyncModbusSerialClient(port: str, framer: FramerType = FramerType.RTU, baudrate: int = 19200, bytesize: int = 8, parity: str = 'N', stopbits: int = 1, handle_local_echo: bool = False, name: str = 'comm', reconnect_delay: float = 0.1, reconnect_delay_max: float = 300, timeout: float = 3, retries: int = 3, on_connect_callback: Callable[[bool], None] | None = None)

Bases: ModbusBaseClient

AsyncModbusSerialClient.

Fixed parameters:

Parameters:: port – Serial port used for communication.

Optional parameters:

Parameters:

framer – Framer name, default FramerType.RTU
baudrate – Bits per second.
bytesize – Number of bits per byte 7-8.
parity – ‘E’ven, ‘O’dd or ‘N’one
stopbits – Number of stop bits 1, 1.5, 2.
handle_local_echo – Discard local echo from dongle.
name – Set communication name, used in logging
reconnect_delay – Minimum delay in seconds.milliseconds before reconnecting.
reconnect_delay_max – Maximum delay in seconds.milliseconds before reconnecting.
timeout – Timeout for connecting and receiving data, in seconds.
retries – Max number of retries per request.
on_connect_callback – Function that will be called just before a connection attempt.

Tip

reconnect_delay doubles automatically with each unsuccessful connect, from reconnect_delay to reconnect_delay_max. Set reconnect_delay=0 to avoid automatic reconnection.

Example:

from pymodbus.client import AsyncModbusSerialClient

async def run():
    client = AsyncModbusSerialClient("dev/serial0")

    await client.connect()
    ...
    client.close()

Please refer to Pymodbus internals for advanced usage.

class pymodbus.client.ModbusSerialClient(port: str, framer: FramerType = FramerType.RTU, baudrate: int = 19200, bytesize: int = 8, parity: str = 'N', stopbits: int = 1, handle_local_echo: bool = False, name: str = 'comm', reconnect_delay: float = 0.1, reconnect_delay_max: float = 300, timeout: float = 3, retries: int = 3)

Bases: ModbusBaseSyncClient

ModbusSerialClient.

Fixed parameters:

Parameters:: port – Serial port used for communication.

Optional parameters:

Parameters:

framer – Framer name, default FramerType.RTU
baudrate – Bits per second.
bytesize – Number of bits per byte 7-8.
parity – ‘E’ven, ‘O’dd or ‘N’one
stopbits – Number of stop bits 0-2.
handle_local_echo – Discard local echo from dongle.
name – Set communication name, used in logging
reconnect_delay – Not used in the sync client
reconnect_delay_max – Not used in the sync client
timeout – Timeout for connecting and receiving data, in seconds.
retries – Max number of retries per request.

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:

from pymodbus.client import ModbusSerialClient

def run():
    client = ModbusSerialClient("dev/serial0")

    client.connect()
    ...
    client.close()

Please refer to Pymodbus internals for advanced usage.

property connected: bool: Check if socket exists.

connect() → bool: Connect to the modbus serial server.

close(): Close the underlying socket connection.

send(request: bytes) → int: Send data on the underlying socket.

recv(size: int | None) → bytes: Read data from the underlying descriptor.

is_socket_open() → bool: Check if socket is open.

Client TCP

class pymodbus.client.AsyncModbusTcpClient(host: str, framer: FramerType = FramerType.SOCKET, port: int = 502, name: str = 'comm', source_address: tuple[str, int] | None = None, reconnect_delay: float = 0.1, reconnect_delay_max: float = 300, timeout: float = 3, retries: int = 3, on_connect_callback: Callable[[bool], None] | None = None)

Bases: ModbusBaseClient

AsyncModbusTcpClient.

Fixed parameters:

Parameters:: host – Host IP address or host name

Optional parameters:

Parameters:

framer – Framer name, default FramerType.SOCKET
port – Port used for communication
name – Set communication name, used in logging
source_address – source address of client
reconnect_delay – Minimum delay in seconds.milliseconds before reconnecting.
reconnect_delay_max – Maximum delay in seconds.milliseconds before reconnecting.
timeout – Timeout for connecting and receiving data, in seconds.
retries – Max number of retries per request.
on_connect_callback – Function that will be called just before a connection attempt.

Tip

reconnect_delay doubles automatically with each unsuccessful connect, from reconnect_delay to reconnect_delay_max. Set reconnect_delay=0 to avoid automatic reconnection.

Example:

from pymodbus.client import AsyncModbusTcpClient

async def run():
    client = AsyncModbusTcpClient("localhost")

    await client.connect()
    ...
    client.close()

Please refer to Pymodbus internals for advanced usage.

class pymodbus.client.ModbusTcpClient(host: str, framer: FramerType = FramerType.SOCKET, port: int = 502, name: str = 'comm', source_address: tuple[str, int] | None = None, reconnect_delay: float = 0.1, reconnect_delay_max: float = 300, timeout: float = 3, retries: int = 3)

Bases: ModbusBaseSyncClient

ModbusTcpClient.

Fixed parameters:

Parameters:: host – Host IP address or host name

Optional parameters:

Parameters:

framer – Framer name, default FramerType.SOCKET
port – Port used for communication
name – Set communication name, used in logging
source_address – source address of client
reconnect_delay – Not used in the sync client
reconnect_delay_max – Not used in the sync client
timeout – Timeout for connecting and receiving data, in seconds.
retries – Max number of retries per request.

Tip

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:

from pymodbus.client import ModbusTcpClient

async def run():
    client = ModbusTcpClient("localhost")

    client.connect()
    ...
    client.close()

Please refer to Pymodbus internals for advanced usage.

property connected: bool: Check if socket exists.

connect(): Connect to the modbus tcp server.

close(): Close the underlying socket connection.

send(request): Send data on the underlying socket.

recv(size: int | None) → bytes: Read data from the underlying descriptor.

is_socket_open() → bool: Check if socket is open.

Client TLS

class pymodbus.client.AsyncModbusTlsClient(host: str, sslctx: ~ssl.SSLContext = <ssl.SSLContext object>, framer: ~pymodbus.framer.base.FramerType = FramerType.TLS, port: int = 802, name: str = 'comm', source_address: tuple[str, int] | None = None, reconnect_delay: float = 0.1, reconnect_delay_max: float = 300, timeout: float = 3, retries: int = 3, on_connect_callback: ~collections.abc.Callable[[bool], None] | None = None)

Bases: AsyncModbusTcpClient

AsyncModbusTlsClient.

Fixed parameters:

Parameters:: host – Host IP address or host name

Optional parameters:

Parameters:

sslctx – SSLContext to use for TLS
framer – Framer name, default FramerType.TLS
port – Port used for communication
name – Set communication name, used in logging
source_address – Source address of client
reconnect_delay – Minimum delay in seconds.milliseconds before reconnecting.
reconnect_delay_max – Maximum delay in seconds.milliseconds before reconnecting.
timeout – Timeout for connecting and receiving data, in seconds.
retries – Max number of retries per request.
on_connect_callback – Function that will be called just before a connection attempt.

Tip

reconnect_delay doubles automatically with each unsuccessful connect, from reconnect_delay to reconnect_delay_max. Set reconnect_delay=0 to avoid automatic reconnection.

Example:

from pymodbus.client import AsyncModbusTlsClient

async def run():
    client = AsyncModbusTlsClient("localhost")

    await client.connect()
    ...
    client.close()

Please refer to Pymodbus internals for advanced usage.

classmethod generate_ssl(certfile: str | None = None, keyfile: str | None = None, password: str | None = None) → SSLContext

Generate sslctx from cert/key/password.

Parameters:

certfile – Cert file path for TLS server request
keyfile – Key file path for TLS server request
password – Password for for decrypting private key file

Remark: - MODBUS/TCP Security Protocol Specification demands TLSv2 at least - verify_mode is set to ssl.NONE

class pymodbus.client.ModbusTlsClient(host: str, sslctx: ~ssl.SSLContext = <ssl.SSLContext object>, framer: ~pymodbus.framer.base.FramerType = FramerType.TLS, port: int = 802, name: str = 'comm', source_address: tuple[str, int] | None = None, reconnect_delay: float = 0.1, reconnect_delay_max: float = 300, timeout: float = 3, retries: int = 3)

Bases: ModbusTcpClient

ModbusTlsClient.

Fixed parameters:

Parameters:: host – Host IP address or host name

Optional parameters:

Parameters:

sslctx – SSLContext to use for TLS
framer – Framer name, default FramerType.TLS
port – Port used for communication
name – Set communication name, used in logging
source_address – Source address of client
reconnect_delay – Not used in the sync client
reconnect_delay_max – Not used in the sync client
timeout – Timeout for connecting and receiving data, in seconds.
retries – Max number of retries per request.

Tip

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:

from pymodbus.client import ModbusTlsClient

async def run():
    client = ModbusTlsClient("localhost")

    client.connect()
    ...
    client.close()

Please refer to Pymodbus internals for advanced usage.

classmethod generate_ssl(certfile: str | None = None, keyfile: str | None = None, password: str | None = None) → SSLContext

Generate sslctx from cert/key/password.

Parameters:

certfile – Cert file path for TLS server request
keyfile – Key file path for TLS server request
password – Password for for decrypting private key file

Remark: - MODBUS/TCP Security Protocol Specification demands TLSv2 at least - verify_mode is set to ssl.NONE

property connected: bool: Connect internal.

connect(): Connect to the modbus tls server.

Client UDP

class pymodbus.client.AsyncModbusUdpClient(host: str, framer: FramerType = FramerType.SOCKET, port: int = 502, name: str = 'comm', source_address: tuple[str, int] | None = None, reconnect_delay: float = 0.1, reconnect_delay_max: float = 300, timeout: float = 3, retries: int = 3, on_connect_callback: Callable[[bool], None] | None = None)

Bases: ModbusBaseClient

AsyncModbusUdpClient.

Fixed parameters:

Parameters:: host – Host IP address or host name

Optional parameters:

Parameters:

framer – Framer name, default FramerType.SOCKET
port – Port used for communication.
name – Set communication name, used in logging
source_address – source address of client,
reconnect_delay – Minimum delay in seconds.milliseconds before reconnecting.
reconnect_delay_max – Maximum delay in seconds.milliseconds before reconnecting.
timeout – Timeout for connecting and receiving data, in seconds.
retries – Max number of retries per request.
on_connect_callback – Function that will be called just before a connection attempt.

Tip

reconnect_delay doubles automatically with each unsuccessful connect, from reconnect_delay to reconnect_delay_max. Set reconnect_delay=0 to avoid automatic reconnection.

Example:

from pymodbus.client import AsyncModbusUdpClient

async def run():
    client = AsyncModbusUdpClient("localhost")

    await client.connect()
    ...
    client.close()

Please refer to Pymodbus internals for advanced usage.

class pymodbus.client.ModbusUdpClient(host: str, framer: FramerType = FramerType.SOCKET, port: int = 502, name: str = 'comm', source_address: tuple[str, int] | None = None, reconnect_delay: float = 0.1, reconnect_delay_max: float = 300, timeout: float = 3, retries: int = 3)

Bases: ModbusBaseSyncClient

ModbusUdpClient.

Fixed parameters:

Parameters:: host – Host IP address or host name

Optional parameters:

Parameters:

framer – Framer name, default FramerType.SOCKET
port – Port used for communication.
name – Set communication name, used in logging
source_address – source address of client,
reconnect_delay – Not used in the sync client
reconnect_delay_max – Not used in the sync client
timeout – Timeout for connecting and receiving data, in seconds.
retries – Max number of retries per request.

Tip

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:

from pymodbus.client import ModbusUdpClient

async def run():
    client = ModbusUdpClient("localhost")

    client.connect()
    ...
    client.close()

Please refer to Pymodbus internals for advanced usage.

property connected: bool: Connect internal.

Modbus calls

Pymodbus makes all standard modbus requests/responses available as simple calls.

Using Modbus<transport>Client.register() custom messagees can be added to pymodbus, and handled automatically.

class pymodbus.client.mixin.ModbusClientMixin

Bases: Generic[T]

ModbusClientMixin.

This is an interface class to facilitate the sending requests/receiving responses like read_coils. execute() allows to make a call with non-standard or user defined function codes (remember to add a PDU in the transport class to interpret the request/response).

Simple modbus message call:

response = client.read_coils(1, 10)
# or
response = await client.read_coils(1, 10)

Advanced modbus message call:

request = ReadCoilsRequest(1,10)
response = client.execute(request)
# or
request = ReadCoilsRequest(1,10)
response = await client.execute(request)

Tip

All methods can be used directly (synchronous) or with await <method> (asynchronous) depending on the client used.

execute(_no_response_expected: bool, _request: ModbusPDU) → T

Execute request (code ???).

Raises:: ModbusException –

Call with custom function codes.

Tip

Response is not interpreted.

read_coils(address: int, count: int = 1, slave: int = 1, no_response_expected: bool = False) → T

Read coils (code 0x01).

Parameters:

address – Start address to read from
count – (optional) Number of coils to read
slave – (optional) Modbus slave ID
no_response_expected – (optional) The client will not expect a response to the request

Raises: