pymodbus.client
Pymodbus offers clients with transport protocols for
Serial (RS-485) typically using a dongle
TCP
TLS
UDP
possibility to add a custom transport protocol
communication in 2 versions:
synchronous client
,asynchronous client
using asyncio.
Using pymodbus client to set/get information from a device (server) is done in a few simple steps, like the following synchronous example:
# create client object
client = ModbusSerial("/dev/tty")
# connect to device
client.connect()
# set/set information
rr = client.read_coils(0x01)
client.write_coil(0x01, values)
# disconnect device
client.close()
and a asynchronous example:
# create client object
async_client = AsyncModbusSerial("/dev/tty")
# connect to device
await async_client.connect()
# set/set information
rr = await async_client.read_coils(0x01)
await async_client.write_coil(0x01, values)
# disconnect device
await async_client.close()
Large parts of the implementation are shared between the different classes, to ensure high stability and efficient maintenance.
Client setup.
- class pymodbus.client.base.ModbusBaseClient(framer: str = None, timeout: str | int = 3, retries: str | int = 3, retry_on_empty: bool = False, close_comm_on_error: bool = False, strict: bool = True, broadcast_enable: bool = False, reconnect_delay: int = 300000, **kwargs: any)
ModbusBaseClient
Parameters common to all clients:
- Parameters
framer – (optional) Modbus Framer class.
timeout – (optional) Timeout for a request.
retries – (optional) Max number of retries pr request.
retry_on_empty – (optional) Retry on empty response.
close_comm_on_error – (optional) Close connection on error.
strict – (optional) Strict timing, 1.5 character between requests.
broadcast_enable – (optional) True to treat id 0 as broadcast address.
reconnect_delay – (optional) Delay in milliseconds before reconnecting.
kwargs – (optional) Experimental parameters.
Tip
Common parameters and all external methods for all clients are documented here, and not repeated with each client.
Tip
reconnect_delay doubles automatically with each unsuccessful connect. Set reconnect_delay=0 to avoid automatic reconnection.
ModbusBaseClient
is normally not referenced outsidepymodbus
, unless you want to make a custom client.Custom client class must inherit
ModbusBaseClient
, example:from pymodbus.client import ModbusBaseClient class myOwnClient(ModbusBaseClient): def __init__(self, **kwargs): super().__init__(kwargs) def run(): client = myOwnClient(...) client.connect() rr = client.read_coils(0x01) client.close()
Application methods, common to all clients:
- register(custom_response_class: ModbusResponse) 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.
- connect() None
Connect to the modbus remote host (call sync/async).
- Raises
ModbusException – Different exceptions, check exception text.
Remark Retries are handled automatically after first successful connect.
- is_socket_open() bool
Return whether socket/serial is open or not (call sync).
- idle_time() int
Time before initiatiating next transaction (call sync).
Applications can call message functions without checking idle_time(), this is done automatically.
- reset_delay() None
Reset wait time before next reconnect to minimal period (call sync).
- execute(request: ModbusRequest = None) ModbusResponse
Execute request and get response (call sync/async).
- Parameters
request – The request to process
- Returns
The result of the request execution
- Raises
ConnectionException – Check exception text.
- close() None
Close the underlying socket connection (call sync/async).
Serial RS-485 transport.
- class pymodbus.client.serial.AsyncModbusSerialClient(port: str, framer: ~pymodbus.framer.ModbusFramer = <class 'pymodbus.framer.rtu_framer.ModbusRtuFramer'>, baudrate: int = 19200, bytesize: int = 8, parity: chr = 'N', stopbits: int = 1, handle_local_echo: bool = False, **kwargs: any)
AsyncModbusSerialClient.
- Parameters
port – Serial port used for communication.
framer – (optional) Framer class.
baudrate – (optional) Bits pr second.
bytesize – (optional) Number of bits pr byte 7-8.
parity – (optional) ‘E’ven, ‘O’dd or ‘N’one
stopbits – (optional) Number of stop bits 0-2¡.
handle_local_echo – (optional) Discard local echo from dongle.
kwargs – (optional) Experimental parameters
The serial communication is RS-485 based, and usually used vith a usb RS485 dongle.
Example:
from pymodbus.client import AsyncModbusSerialClient async def run(): client = AsyncModbusSerialClient("dev/serial0") await client.connect() ... await client.close()
- class pymodbus.client.serial.ModbusSerialClient(port: str, framer: ~pymodbus.framer.ModbusFramer = <class 'pymodbus.framer.rtu_framer.ModbusRtuFramer'>, baudrate: int = 19200, bytesize: int = 8, parity: chr = 'N', stopbits: int = 1, handle_local_echo: bool = False, **kwargs: any)
ModbusSerialClient.
- Parameters
port – Serial port used for communication.
framer – (optional) Framer class.
baudrate – (optional) Bits pr second.
bytesize – (optional) Number of bits pr byte 7-8.
parity – (optional) ‘E’ven, ‘O’dd or ‘N’one
stopbits – (optional) Number of stop bits 0-2¡.
handle_local_echo – (optional) Discard local echo from dongle.
kwargs – (optional) Experimental parameters
The serial communication is RS-485 based, and usually used vith a usb RS485 dongle.
Example:
from pymodbus.client import ModbusSerialClient def run(): client = ModbusSerialClient("dev/serial0") client.connect() ... client.close()
TCP transport.
- class pymodbus.client.tcp.AsyncModbusTcpClient(host: str, port: int = 502, framer: ~pymodbus.framer.ModbusFramer = <class 'pymodbus.framer.socket_framer.ModbusSocketFramer'>, source_address: ~typing.Tuple[str, int] = None, **kwargs: any)
AsyncModbusTcpClient.
- Parameters
host – Host IP address or host name
port – (optional) Port used for communication.
framer – (optional) Framer class.
source_address – (optional) source address of client,
kwargs – (optional) Experimental parameters
Example:
from pymodbus.client import AsyncModbusTcpClient async def run(): client = AsyncModbusTcpClient("localhost") await client.connect() ... await client.close()
- class pymodbus.client.tcp.ModbusTcpClient(host: str, port: int = 502, framer: ~pymodbus.framer.ModbusFramer = <class 'pymodbus.framer.socket_framer.ModbusSocketFramer'>, source_address: ~typing.Tuple[str, int] = None, **kwargs: any)
ModbusTcpClient.
- Parameters
host – Host IP address or host name
port – (optional) Port used for communication.
framer – (optional) Framer class.
source_address – (optional) source address of client,
kwargs – (optional) Experimental parameters
Example:
from pymodbus.client import ModbusTcpClient async def run(): client = ModbusTcpClient("localhost") client.connect() ... client.close()
TLS transport.
- class pymodbus.client.tls.AsyncModbusTlsClient(host: str, port: int = 802, framer: ~pymodbus.framer.ModbusFramer = <class 'pymodbus.framer.tls_framer.ModbusTlsFramer'>, sslctx: str = None, certfile: str = None, keyfile: str = None, password: str = None, server_hostname: str = None, **kwargs: any)
AsyncModbusTlsClient.
- Parameters
host – Host IP address or host name
port – (optional) Port used for communication.
framer – (optional) Framer class.
source_address – (optional) Source address of client,
sslctx – (optional) SSLContext to use for TLS
certfile – (optional) Cert file path for TLS server request
keyfile – (optional) Key file path for TLS server request
password – (optional) Password for for decrypting private key file
server_hostname – (optional) Bind certificate to host,
kwargs – (optional) Experimental parameters.
Example:
from pymodbus.client import AsyncModbusTlsClient async def run(): client = AsyncModbusTlsClient("localhost") await client.connect() ... await client.close()
- class pymodbus.client.tls.ModbusTlsClient(host: str, port: int = 802, framer: ~pymodbus.framer.ModbusFramer = <class 'pymodbus.framer.tls_framer.ModbusTlsFramer'>, sslctx: str = None, certfile: str = None, keyfile: str = None, password: str = None, server_hostname: str = None, **kwargs: any)
ModbusTlsClient.
- Parameters
host – Host IP address or host name
port – (optional) Port used for communication.
framer – (optional) Framer class.
source_address – (optional) Source address of client,
sslctx – (optional) SSLContext to use for TLS
certfile – (optional) Cert file path for TLS server request
keyfile – (optional) Key file path for TLS server request
password – (optional) Password for for decrypting private key file
server_hostname – (optional) Bind certificate to host,
kwargs – (optional) Experimental parameters.
Example:
from pymodbus.client import ModbusTlsClient async def run(): client = ModbusTlsClient("localhost") client.connect() ... client.close()
UDP transport.
- class pymodbus.client.udp.AsyncModbusUdpClient(host: str, port: int = 502, framer: ~pymodbus.framer.ModbusFramer = <class 'pymodbus.framer.socket_framer.ModbusSocketFramer'>, source_address: ~typing.Tuple[str, int] = None, **kwargs: any)
AsyncModbusUdpClient.
- Parameters
host – Host IP address or host name
port – (optional) Port used for communication.
framer – (optional) Framer class.
source_address – (optional) source address of client,
kwargs – (optional) Experimental parameters
Example:
from pymodbus.client import AsyncModbusUdpClient async def run(): client = AsyncModbusUdpClient("localhost") await client.connect() ... await client.close()
- class pymodbus.client.udp.ModbusUdpClient(host: str, port: int = 502, framer: ~pymodbus.framer.ModbusFramer = <class 'pymodbus.framer.socket_framer.ModbusSocketFramer'>, source_address: ~typing.Tuple[str, int] = None, **kwargs: any)
ModbusUdpClient.
- Parameters
host – Host IP address or host name
port – (optional) Port used for communication.
framer – (optional) Framer class.
source_address – (optional) source address of client,
kwargs – (optional) Experimental parameters
Example:
from pymodbus.client import ModbusUdpClient async def run(): client = ModbusUdpClient("localhost") client.connect() ... client.close()
Client device 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
ModbusClientMixin.
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> depending on the instantiated client.
- diag_change_ascii_input_delimeter(slave: int = 0, **kwargs: any) ChangeAsciiInputDelimiterResponse
Diagnose change ASCII input delimiter (function code 0x08 - 0x03).
- Parameters
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises
- diag_clear_counters(slave: int = 0, **kwargs: any) ClearCountersResponse
Diagnose clear counters (function code 0x08 - 0x0A).
- Parameters
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises
- diag_clear_overrun_counter(slave: int = 0, **kwargs: any) ClearOverrunCountResponse
Diagnose Clear Overrun Counter and Flag (function code 0x08 - 0x14).
- Parameters
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises
- diag_force_listen_only(slave: int = 0, **kwargs: any) ForceListenOnlyModeResponse
Diagnose force listen only (function code 0x08 - 0x04).
- Parameters
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises
- diag_getclear_modbus_response(slave: int = 0, **kwargs: any) GetClearModbusPlusResponse
Diagnose Get/Clear modbus plus request (function code 0x08 - 0x15).
- Parameters
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises
- diag_query_data(msg: bytearray, slave: int = 0, **kwargs: any) ReturnQueryDataResponse
Diagnose query data (function code 0x08 - 0x00).
- Parameters
msg – Message to be returned
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises
- diag_read_bus_char_overrun_count(slave: int = 0, **kwargs: any) ReturnSlaveBusCharacterOverrunCountResponse
Diagnose read Bus Character Overrun Count (function code 0x08 - 0x12).
- Parameters
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises
- diag_read_bus_comm_error_count(slave: int = 0, **kwargs: any) ReturnBusCommunicationErrorCountResponse
Diagnose read Bus Communication Error Count (function code 0x08 - 0x0C).
- Parameters
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises
- diag_read_bus_exception_error_count(slave: int = 0, **kwargs: any) ReturnBusExceptionErrorCountResponse
Diagnose read Bus Exception Error Count (function code 0x08 - 0x0D).
- Parameters
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises
- diag_read_bus_message_count(slave: int = 0, **kwargs: any) ReturnBusMessageCountResponse
Diagnose read bus message count (function code 0x08 - 0x0B).
- Parameters
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises
- diag_read_diagnostic_register(slave: int = 0, **kwargs: any) ReturnDiagnosticRegisterResponse
Diagnose read diagnostic register (function code 0x08 - 0x02).
- Parameters
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises
- diag_read_iop_overrun_count(slave: int = 0, **kwargs: any) ReturnIopOverrunCountResponse
Diagnose read Iop overrun count (function code 0x08 - 0x13).
- Parameters
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises
- diag_read_slave_busy_count(slave: int = 0, **kwargs: any) ReturnSlaveBusyCountResponse
Diagnose read Slave Busy Count (function code 0x08 - 0x11).
- Parameters
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises
- diag_read_slave_message_count(slave: int = 0, **kwargs: any) ReturnSlaveMessageCountResponse
Diagnose read Slave Message Count (function code 0x08 - 0x0E).
- Parameters
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises
- diag_read_slave_nak_count(slave: int = 0, **kwargs: any) ReturnSlaveNAKCountResponse
Diagnose read Slave NAK Count (function code 0x08 - 0x10).
- Parameters
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises
- diag_read_slave_no_response_count(slave: int = 0, **kwargs: any) ReturnSlaveNoReponseCountResponse
Diagnose read Slave No Response Count (function code 0x08 - 0x0F).
- Parameters
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises
- diag_restart_communication(toggle: bool, slave: int = 0, **kwargs: any) RestartCommunicationsOptionResponse
Diagnose restart communication (function code 0x08 - 0x01).
- Parameters
toggle – True if toogled.
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises
- execute(request: ModbusRequest) ModbusResponse
Execute request.
- Parameters
request – Request to send
- Raises
- mask_write_register(*args, **kwargs) MaskWriteRegisterResponse
Mask write register.
- Args
- Returns
A deferred response handle
- read_coils(address: int, count: int = 1, slave: int = 0, **kwargs: any) ReadCoilsResponse
Read coils (function code 0x01).
- Parameters
address – Start address to read from
count – (optional) Number of coils to read
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises
- read_discrete_inputs(address: int, count: int = 1, slave: int = 0, **kwargs: any) ReadDiscreteInputsResponse
Read discrete inputs (function code 0x02).
- Parameters
address – Start address to read from
count – (optional) Number of coils to read
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises
- read_exception_status(slave: int = 0, **kwargs: any) ReadExceptionStatusResponse
Read Exception Status (function code 0x07).
- Parameters
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises
- read_holding_registers(address: int, count: int = 1, slave: int = 0, **kwargs: any) ReadHoldingRegistersResponse
Read holding registers (function code 0x03).
- Parameters
address – Start address to read from
count – (optional) Number of coils to read
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises
- read_input_registers(address: int, count: int = 1, slave: int = 0, **kwargs: any) ReadInputRegistersResponse
Read input registers (function code 0x04).
- Parameters
address – Start address to read from
count – (optional) Number of coils to read
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises
- readwrite_registers(*args, **kwargs) ReadWriteMultipleRegistersResponse
Read/Write registers
- Parameters
args –
kwargs –
- Returns
A deferred response handle
- write_coil(address: int, value: bool, slave: int = 0, **kwargs: any) WriteSingleCoilResponse
Write single coil (function code 0x05).
- Parameters
address – Start address to read from
value – Boolean to write
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises
- write_coils(address: int, values: List[bool], slave: int = 0, **kwargs: any) WriteMultipleCoilsResponse
Write coils (function code 0x0F).
- Parameters
address – Start address to read from
values – List of booleans to write
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises
- write_register(address: int, value: Union[int, float, str], slave: int = 0, **kwargs: any) WriteSingleRegisterResponse
Write register (function code 0x06).
- Parameters
address – Start address to read from
value – Value to write
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises
- write_registers(address: int, values: List[Union[int, float, str]], slave: int = 0, **kwargs: any) WriteMultipleRegistersResponse
Write registers (function code 0x10).
- Parameters
address – Start address to read from
values – List of booleans to write
slave – (optional) Modbus slave unit ID
kwargs – (optional) Experimental parameters.
- Raises