# 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, like the following synchronous example:

    from pymodbus.client import ModbusTcpClient

    client = ModbusTcpClient('MyDevice.lan')   # Create client object
    client.connect()                           # connect to device, reconnect automatically
    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

and a 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.

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 used as broadcast in order to address all devices. However experience shows that modern devices do not allow broadcast, mostly because it is inheriently dangerous. With `slave=0` the application can get upto 254 responses on a single request!

The simple request calls (mixin) do NOT support broadcast, if an application wants to use broadcast it must call `client.execute` and deal with the responses.

## 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

## 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 serial

class pymodbus.client.AsyncModbusSerialClient(port: str, framer: Framer = Framer.RTU, baudrate: int = 19200, bytesize: int = 8, parity: str = 'N', stopbits: int = 1, **kwargs: Any)

  Bases: `ModbusBaseClient`, `Protocol`

  AsyncModbusSerialClient.

  Fixed parameters:

  Parameters:

    port – Serial port used for communication.

  Optional parameters:

  Parameters:

    - 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.

  Common optional parameters:

  Parameters:

    - framer – Framer enum name

    - timeout – Timeout for a request, in seconds.

    - retries – Max number of retries per request.

    - retry_on_empty – Retry on empty response.

    - broadcast_enable – True to treat id 0 as broadcast address.

    - reconnect_delay – Minimum delay in seconds.milliseconds before reconnecting.

    - reconnect_delay_max – Maximum delay in seconds.milliseconds before reconnecting.

    - on_reconnect_callback – Function that will be called just before a reconnection attempt.

    - no_resend_on_retry – Do not resend request when retrying due to missing response.

    - kwargs – Experimental parameters.

  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.

  async connect() → bool

    Connect Async client.

  close(reconnect: bool = False) → None

    Close connection.

class pymodbus.client.ModbusSerialClient(port: str, framer: Framer = Framer.RTU, baudrate: int = 19200, bytesize: int = 8, parity: str = 'N', stopbits: int = 1, strict: bool = True, **kwargs: Any)

  Bases: `ModbusBaseSyncClient`

  ModbusSerialClient.

  Fixed parameters:

  Parameters:

    port – Serial port used for communication.

  Optional parameters:

  Parameters:

    - 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.

  Common optional parameters:

  Parameters:

    - framer – Framer enum name

    - timeout – Timeout for a request, in seconds.

    - retries – Max number of retries per request.

    - retry_on_empty – Retry on empty response.

    - strict – Strict timing, 1.5 character between requests.

    - broadcast_enable – True to treat id 0 as broadcast address.

    - reconnect_delay – Minimum delay in seconds.milliseconds before reconnecting.

    - reconnect_delay_max – Maximum delay in seconds.milliseconds before reconnecting.

    - on_reconnect_callback – Function that will be called just before a reconnection attempt.

    - no_resend_on_retry – Do not resend request when retrying due to missing response.

    - kwargs – Experimental parameters.

  Example:

      from pymodbus.client import ModbusSerialClient

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

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

  Please refer to Pymodbus internals for advanced usage.

  Remark: There are no automatic reconnect as with AsyncModbusSerialClient

  property connected

    Connect internal.

  connect()

    Connect to the modbus serial server.

  close()

    Close the underlying socket connection.

  send(request)

    Send data on the underlying socket.

    If receive buffer still holds some data then flush it.

    Sleep if last send finished less than 3.5 character times ago.

  recv(size)

    Read data from the underlying descriptor.

  is_socket_open()

    Check if socket is open.

### Client TCP

class pymodbus.client.AsyncModbusTcpClient(host: str, port: int = 502, framer: Framer = Framer.SOCKET, source_address: tuple[str, int] | None = None, **kwargs: Any)

  Bases: `ModbusBaseClient`, `Protocol`

  AsyncModbusTcpClient.

  Fixed parameters:

  Parameters:

    host – Host IP address or host name

  Optional parameters:

  Parameters:

    - port – Port used for communication

    - source_address – source address of client

  Common optional parameters:

  Parameters:

    - framer – Framer enum name

    - timeout – Timeout for a request, in seconds.

    - retries – Max number of retries per request.

    - retry_on_empty – Retry on empty response.

    - broadcast_enable – True to treat id 0 as broadcast address.

    - reconnect_delay – Minimum delay in seconds.milliseconds before reconnecting.

    - reconnect_delay_max – Maximum delay in seconds.milliseconds before reconnecting.

    - on_reconnect_callback – Function that will be called just before a reconnection attempt.

    - no_resend_on_retry – Do not resend request when retrying due to missing response.

    - kwargs – Experimental parameters.

  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.

  async connect() → bool

    Initiate connection to start client.

  close(reconnect: bool = False) → None

    Close connection.

class pymodbus.client.ModbusTcpClient(host: str, port: int = 502, framer: Framer = Framer.SOCKET, source_address: tuple[str, int] | None = None, **kwargs: Any)

  Bases: `ModbusBaseSyncClient`

  ModbusTcpClient.

  Fixed parameters:

  Parameters:

    host – Host IP address or host name

  Optional parameters:

  Parameters:

    - port – Port used for communication

    - source_address – source address of client

  Common optional parameters:

  Parameters:

    - framer – Framer enum name

    - timeout – Timeout for a request, in seconds.

    - retries – Max number of retries per request.

    - retry_on_empty – Retry on empty response.

    - broadcast_enable – True to treat id 0 as broadcast address.

    - reconnect_delay – Minimum delay in seconds.milliseconds before reconnecting.

    - reconnect_delay_max – Maximum delay in seconds.milliseconds before reconnecting.

    - on_reconnect_callback – Function that will be called just before a reconnection attempt.

    - no_resend_on_retry – Do not resend request when retrying due to missing response.

    - kwargs – Experimental parameters.

  Example:

      from pymodbus.client import ModbusTcpClient

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

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

  Please refer to Pymodbus internals for advanced usage.

  Remark: There are no automatic reconnect as with AsyncModbusTcpClient

  property connected: bool

    Connect internal.

  connect()

    Connect to the modbus tcp server.

  close()

    Close the underlying socket connection.

  send(request)

    Send data on the underlying socket.

  recv(size)

    Read data from the underlying descriptor.

  is_socket_open()

    Check if socket is open.

### Client TLS

class pymodbus.client.AsyncModbusTlsClient(host: str, port: int = 802, framer: Framer = Framer.TLS, sslctx: SSLContext | None = None, certfile: str | None = None, keyfile: str | None = None, password: str | None = None, server_hostname: str | None = None, **kwargs: Any)

  Bases: `AsyncModbusTcpClient`

  AsyncModbusTlsClient.

  Fixed parameters:

  Parameters:

    host – Host IP address or host name

  Optional parameters:

  Parameters:

    - port – Port used for communication

    - source_address – Source address of client

    - sslctx – SSLContext to use for TLS

    - certfile – Cert file path for TLS server request

    - keyfile – Key file path for TLS server request

    - password – Password for for decrypting private key file

    - server_hostname – Bind certificate to host

  Common optional parameters:

  Parameters:

    - framer – Framer enum name

    - timeout – Timeout for a request, in seconds.

    - retries – Max number of retries per request.

    - retry_on_empty – Retry on empty response.

    - broadcast_enable – True to treat id 0 as broadcast address.

    - reconnect_delay – Minimum delay in seconds.milliseconds before reconnecting.

    - reconnect_delay_max – Maximum delay in seconds.milliseconds before reconnecting.

    - on_reconnect_callback – Function that will be called just before a reconnection attempt.

    - no_resend_on_retry – Do not resend request when retrying due to missing response.

    - kwargs – Experimental parameters.

  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.

  async connect() → bool

    Initiate connection to start client.

  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, port: int = 802, framer: Framer = Framer.TLS, sslctx: SSLContext | None = None, certfile: str | None = None, keyfile: str | None = None, password: str | None = None, server_hostname: str | None = None, **kwargs: Any)

  Bases: `ModbusTcpClient`

  ModbusTlsClient.

  Fixed parameters:

  Parameters:

    host – Host IP address or host name

  Optional parameters:

  Parameters:

    - port – Port used for communication

    - source_address – Source address of client

    - sslctx – SSLContext to use for TLS

    - certfile – Cert file path for TLS server request

    - keyfile – Key file path for TLS server request

    - password – Password for decrypting private key file

    - server_hostname – Bind certificate to host

    - kwargs – Experimental parameters

  Common optional parameters:

  Parameters:

    - framer – Framer enum name

    - timeout – Timeout for a request, in seconds.

    - retries – Max number of retries per request.

    - retry_on_empty – Retry on empty response.

    - broadcast_enable – True to treat id 0 as broadcast address.

    - reconnect_delay – Minimum delay in seconds.milliseconds before reconnecting.

    - reconnect_delay_max – Maximum delay in seconds.milliseconds before reconnecting.

    - on_reconnect_callback – Function that will be called just before a reconnection attempt.

    - no_resend_on_retry – Do not resend request when retrying due to missing response.

    - kwargs – Experimental parameters.

  Example:

      from pymodbus.client import ModbusTlsClient

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

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

  Please refer to Pymodbus internals for advanced usage.

  Remark: There are no automatic reconnect as with AsyncModbusTlsClient

  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, port: int = 502, framer: Framer = Framer.SOCKET, source_address: tuple[str, int] | None = None, **kwargs: Any)

  Bases: `ModbusBaseClient`, `Protocol`, `DatagramProtocol`

  AsyncModbusUdpClient.

  Fixed parameters:

  Parameters:

    host – Host IP address or host name

  Optional parameters:

  Parameters:

    - port – Port used for communication.

    - source_address – source address of client,

  Common optional parameters:

  Parameters:

    - framer – Framer enum name

    - timeout – Timeout for a request, in seconds.

    - retries – Max number of retries per request.

    - retry_on_empty – Retry on empty response.

    - broadcast_enable – True to treat id 0 as broadcast address.

    - reconnect_delay – Minimum delay in seconds.milliseconds before reconnecting.

    - reconnect_delay_max – Maximum delay in seconds.milliseconds before reconnecting.

    - on_reconnect_callback – Function that will be called just before a reconnection attempt.

    - no_resend_on_retry – Do not resend request when retrying due to missing response.

    - kwargs – Experimental parameters.

  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.

  property connected

    Return true if connected.

class pymodbus.client.ModbusUdpClient(host: str, port: int = 502, framer: Framer = Framer.SOCKET, source_address: tuple[str, int] | None = None, **kwargs: Any)

  Bases: `ModbusBaseSyncClient`

  ModbusUdpClient.

  Fixed parameters:

  Parameters:

    host – Host IP address or host name

  Optional parameters:

  Parameters:

    - port – Port used for communication.

    - source_address – source address of client,

  Common optional parameters:

  Parameters:

    - framer – Framer enum name

    - timeout – Timeout for a request, in seconds.

    - retries – Max number of retries per request.

    - retry_on_empty – Retry on empty response.

    - broadcast_enable – True to treat id 0 as broadcast address.

    - reconnect_delay – Minimum delay in seconds.milliseconds before reconnecting.

    - reconnect_delay_max – Maximum delay in seconds.milliseconds before reconnecting.

    - on_reconnect_callback – Function that will be called just before a reconnection attempt.

    - no_resend_on_retry – Do not resend request when retrying due to missing response.

    - kwargs – Experimental parameters.

  Example:

      from pymodbus.client import ModbusUdpClient

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

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

  Please refer to Pymodbus internals for advanced usage.

  Remark: There are no automatic reconnect as with AsyncModbusUdpClient

  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(_request: ModbusRequest) → 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 = 0, **kwargs: Any) → T

    Read coils (code 0x01).

    Parameters:

      - address – Start address to read from

      - count – (optional) Number of coils to read

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  read_discrete_inputs(address: int, count: int = 1, slave: int = 0, **kwargs: Any) → T

    Read discrete inputs (code 0x02).

    Parameters:

      - address – Start address to read from

      - count – (optional) Number of coils to read

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  read_holding_registers(address: int, count: int = 1, slave: int = 0, **kwargs: Any) → T

    Read holding registers (code 0x03).

    Parameters:

      - address – Start address to read from

      - count – (optional) Number of coils to read

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  read_input_registers(address: int, count: int = 1, slave: int = 0, **kwargs: Any) → T

    Read input registers (code 0x04).

    Parameters:

      - address – Start address to read from

      - count – (optional) Number of coils to read

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  write_coil(address: int, value: bool, slave: int = 0, **kwargs: Any) → T

    Write single coil (code 0x05).

    Parameters:

      - address – Address to write to

      - value – Boolean to write

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  write_register(address: int, value: int, slave: int = 0, **kwargs: Any) → T

    Write register (code 0x06).

    Parameters:

      - address – Address to write to

      - value – Value to write

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  read_exception_status(slave: int = 0, **kwargs: Any) → T

    Read Exception Status (code 0x07).

    Parameters:

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  diag_query_data(msg: bytes, slave: int = 0, **kwargs: Any) → T

    Diagnose query data (code 0x08 sub 0x00).

    Parameters:

      - msg – Message to be returned

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  diag_restart_communication(toggle: bool, slave: int = 0, **kwargs: Any) → T

    Diagnose restart communication (code 0x08 sub 0x01).

    Parameters:

      - toggle – True if toggled.

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  diag_read_diagnostic_register(slave: int = 0, **kwargs: Any) → T

    Diagnose read diagnostic register (code 0x08 sub 0x02).

    Parameters:

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  diag_change_ascii_input_delimeter(slave: int = 0, **kwargs: Any) → T

    Diagnose change ASCII input delimiter (code 0x08 sub 0x03).

    Parameters:

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  diag_force_listen_only(slave: int = 0, **kwargs: Any) → T

    Diagnose force listen only (code 0x08 sub 0x04).

    Parameters:

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  diag_clear_counters(slave: int = 0, **kwargs: Any) → T

    Diagnose clear counters (code 0x08 sub 0x0A).

    Parameters:

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  diag_read_bus_message_count(slave: int = 0, **kwargs: Any) → T

    Diagnose read bus message count (code 0x08 sub 0x0B).

    Parameters:

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  diag_read_bus_comm_error_count(slave: int = 0, **kwargs: Any) → T

    Diagnose read Bus Communication Error Count (code 0x08 sub 0x0C).

    Parameters:

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  diag_read_bus_exception_error_count(slave: int = 0, **kwargs: Any) → T

    Diagnose read Bus Exception Error Count (code 0x08 sub 0x0D).

    Parameters:

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  diag_read_slave_message_count(slave: int = 0, **kwargs: Any) → T

    Diagnose read Slave Message Count (code 0x08 sub 0x0E).

    Parameters:

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  diag_read_slave_no_response_count(slave: int = 0, **kwargs: Any) → T

    Diagnose read Slave No Response Count (code 0x08 sub 0x0F).

    Parameters:

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  diag_read_slave_nak_count(slave: int = 0, **kwargs: Any) → T

    Diagnose read Slave NAK Count (code 0x08 sub 0x10).

    Parameters:

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  diag_read_slave_busy_count(slave: int = 0, **kwargs: Any) → T

    Diagnose read Slave Busy Count (code 0x08 sub 0x11).

    Parameters:

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  diag_read_bus_char_overrun_count(slave: int = 0, **kwargs: Any) → T

    Diagnose read Bus Character Overrun Count (code 0x08 sub 0x12).

    Parameters:

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  diag_read_iop_overrun_count(slave: int = 0, **kwargs: Any) → T

    Diagnose read Iop overrun count (code 0x08 sub 0x13).

    Parameters:

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  diag_clear_overrun_counter(slave: int = 0, **kwargs: Any) → T

    Diagnose Clear Overrun Counter and Flag (code 0x08 sub 0x14).

    Parameters:

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  diag_getclear_modbus_response(slave: int = 0, **kwargs: Any) → T

    Diagnose Get/Clear modbus plus (code 0x08 sub 0x15).

    Parameters:

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  diag_get_comm_event_counter(**kwargs: Any) → T

    Diagnose get event counter (code 0x0B).

    Parameters:

      kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  diag_get_comm_event_log(**kwargs: Any) → T

    Diagnose get event counter (code 0x0C).

    Parameters:

      kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  write_coils(address: int, values: list[bool] | bool, slave: int = 0, **kwargs: Any) → T

    Write coils (code 0x0F).

    Parameters:

      - address – Start address to write to

      - values – List of booleans to write, or a single boolean to write

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  write_registers(address: int, values: list[int] | int, slave: int = 0, **kwargs: Any) → T

    Write registers (code 0x10).

    Parameters:

      - address – Start address to write to

      - values – List of values to write, or a single value to write

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  report_slave_id(slave: int = 0, **kwargs: Any) → T

    Report slave ID (code 0x11).

    Parameters:

      - slave – (optional) Modbus slave ID

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  read_file_record(records: list[tuple], **kwargs: Any) → T

    Read file record (code 0x14).

    Parameters:

      - records – List of (Reference type, File number, Record Number, Record Length)

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  write_file_record(records: list[tuple], **kwargs: Any) → T

    Write file record (code 0x15).

    Parameters:

      - records – List of (Reference type, File number, Record Number, Record Length)

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  mask_write_register(address: int = 0, and_mask: int = 65535, or_mask: int = 0, **kwargs: Any) → T

    Mask write register (code 0x16).

    Parameters:

      - address – The mask pointer address (0x0000 to 0xffff)

      - and_mask – The and bitmask to apply to the register address

      - or_mask – The or bitmask to apply to the register address

      - kwargs – (optional) Experimental parameters.

    Raises:

      ModbusException –

  readwrite_registers(read_address: int = 0, read_count: int = 0, write_address: int = 0, values: list[int] | int = 0, slave: int = 0, **kwargs) → T

    Read/Write registers (code 0x17).

    Parameters:

      - read_address – The address to start reading from

      - read_count – The number of registers to read from address

      - write_address – The address to start writing to

      - values – List of values to write, or a single value to write

      - slave – (optional) Modbus slave ID

      - kwargs –

    Raises:

      ModbusException –

  read_fifo_queue(address: int = 0, **kwargs: Any) → T

    Read FIFO queue (code 0x18).

    Parameters:

      - address – The address to start reading from

      - kwargs –

    Raises:

      ModbusException –

  read_device_information(read_code: int | None = None, object_id: int = 0, **kwargs: Any) → T

    Read FIFO queue (code 0x2B sub 0x0E).

    Parameters:

      - read_code – The device information read code

      - object_id – The object to read from

      - kwargs –

    Raises:

      ModbusException –

  class DATATYPE(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

    Bases: `Enum`

    Datatype enum (name and number of bytes), used for convert_* calls.

  classmethod convert_from_registers(registers: list[int], data_type: DATATYPE) → int | float | str

    Convert registers to int/float/str.

    Parameters:

      - registers – list of registers received from e.g. read_holding_registers()

      - data_type – data type to convert to

    Returns:

      int, float or str depending on “data_type”

    Raises:

      ModbusException – when size of registers is not 1, 2 or 4

  classmethod convert_to_registers(value: int | float | str, data_type: DATATYPE) → list[int]

    Convert int/float/str to registers (16/32/64 bit).

    Parameters:

      - value – value to be converted

      - data_type – data type to be encoded as registers

    Returns:

      List of registers, can be used directly in e.g. write_registers()

    Raises:

      TypeError – when there is a mismatch between data_type and value