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 outside pymodbus, 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

ModbusException

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

ModbusException

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

ModbusException

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

ModbusException

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

ModbusException

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

ModbusException

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

ModbusException

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

ModbusException

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

ModbusException

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

ModbusException

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

ModbusException

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

ModbusException

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

ModbusException

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

ModbusException

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

ModbusException

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

ModbusException

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

ModbusException

execute(request: pymodbus.pdu.ModbusRequest) → pymodbus.pdu.ModbusResponse

Execute request.

Parameters

request – Request to send

Raises

ModbusException

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

ModbusException

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

ModbusException

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

ModbusException

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

ModbusException

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

ModbusException

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

ModbusException

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

ModbusException

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

ModbusException

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

ModbusException