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: pymodbus.pdu.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: Optional[pymodbus.pdu.ModbusRequest] = None) → pymodbus.pdu.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: Optional[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: Optional[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: Optional[str] = None, certfile: Optional[str] = None, keyfile: Optional[str] = None, password: Optional[str] = None, server_hostname: Optional[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: Optional[str] = None, certfile: Optional[str] = None, keyfile: Optional[str] = None, password: Optional[str] = None, server_hostname: Optional[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: Optional[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: Optional[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) → pymodbus.diag_message.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) → pymodbus.diag_message.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) → pymodbus.diag_message.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) → pymodbus.diag_message.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) → pymodbus.diag_message.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) → pymodbus.diag_message.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) → pymodbus.diag_message.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) → pymodbus.diag_message.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) → pymodbus.diag_message.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) → pymodbus.diag_message.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) → pymodbus.diag_message.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) → pymodbus.diag_message.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) → pymodbus.diag_message.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) → pymodbus.diag_message.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) → pymodbus.diag_message.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) → pymodbus.diag_message.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) → pymodbus.diag_message.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: pymodbus.pdu.ModbusRequest) → pymodbus.pdu.ModbusResponse¶ Execute request.
- Parameters
request – Request to send
- Raises
-
mask_write_register
(*args, **kwargs) → pymodbus.register_write_message.MaskWriteRegisterResponse¶ Mask write register.
- Args
- Returns
A deferred response handle
-
read_coils
(address: int, count: int = 1, slave: int = 0, **kwargs: any) → pymodbus.bit_read_message.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) → pymodbus.bit_read_message.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) → pymodbus.other_message.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) → pymodbus.register_read_message.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) → pymodbus.register_read_message.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) → pymodbus.register_read_message.ReadWriteMultipleRegistersResponse¶ Read/Write registers
- Parameters
args –
kwargs –
- Returns
A deferred response handle
-
write_coil
(address: int, value: bool, slave: int = 0, **kwargs: any) → pymodbus.bit_write_message.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) → pymodbus.bit_write_message.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) → pymodbus.register_write_message.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) → pymodbus.register_write_message.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
-