Module pyModbusTCP.client

pyModbusTCP Client

This module provide the ModbusClient class used to deal with modbus server.

class ModbusClient

class pyModbusTCP.client.ModbusClient(host='localhost', port=502, unit_id=1, timeout=30.0, debug=False, auto_open=True, auto_close=False)

Modbus TCP client.

__init__(host='localhost', port=502, unit_id=1, timeout=30.0, debug=False, auto_open=True, auto_close=False)

Constructor.

Parameters:
  • host (str) – hostname or IPv4/IPv6 address server address

  • port (int) – TCP port number

  • unit_id (int) – unit ID

  • timeout (float) – socket timeout in seconds

  • debug (bool) – debug state

  • auto_open (bool) – auto TCP connect

  • auto_close (bool) – auto TCP close)

Returns:

Object ModbusClient

Return type:

ModbusClient

property auto_close

Get or set automatic TCP close after each request mode (True = turn on).

property auto_open

Get or set automatic TCP connect mode (True = turn on).

close()

Close current TCP connection.

custom_request(pdu)

Send a custom modbus request.

Parameters:

pdu (bytes) – a modbus PDU (protocol data unit)

Returns:

modbus frame PDU or None if error

Return type:

bytes or None

property debug

Get or set the debug flag (True = turn on).

property host

Get or set the server to connect to.

This can be any string with a valid IPv4 / IPv6 address or hostname. Setting host to a new value will close the current socket.

property is_open

Get current status of the TCP connection (True = open).

property last_error

Last error code.

property last_error_as_txt

Human-readable text that describe last error.

property last_except

Return the last modbus exception code.

property last_except_as_full_txt

Verbose human-readable text that describe last modbus exception.

property last_except_as_txt

Short human-readable text that describe last modbus exception.

open()

Connect to modbus server (open TCP connection).

Returns:

connect status (True on success)

Return type:

bool

property port

Get or set the current TCP port (default is 502).

Setting port to a new value will close the current socket.

read_coils(bit_addr, bit_nb=1)

Modbus function READ_COILS (0x01).

Parameters:
  • bit_addr (int) – bit address (0 to 65535)

  • bit_nb (int) – number of bits to read (1 to 2000)

Returns:

bits list or None if error

Return type:

list of bool or None

read_device_identification(read_code=1, object_id=0)

Modbus function Read Device Identification (0x2B/0x0E).

Parameters:
  • read_code (int) – read device id code, 1 to 3 for respectively: basic, regular and extended stream access, 4 for one specific identification object individual access (default is 1)

  • object_id (int) – object id of the first object to obtain (default is 0)

Returns:

a DeviceIdentificationResponse instance with the data or None if the requests fails

Return type:

DeviceIdentificationResponse or None

read_discrete_inputs(bit_addr, bit_nb=1)

Modbus function READ_DISCRETE_INPUTS (0x02).

Parameters:
  • bit_addr (int) – bit address (0 to 65535)

  • bit_nb (int) – number of bits to read (1 to 2000)

Returns:

bits list or None if error

Return type:

list of bool or None

read_holding_registers(reg_addr, reg_nb=1)

Modbus function READ_HOLDING_REGISTERS (0x03).

Parameters:
  • reg_addr (int) – register address (0 to 65535)

  • reg_nb (int) – number of registers to read (1 to 125)

Returns:

registers list or None if fail

Return type:

list of int or None

read_input_registers(reg_addr, reg_nb=1)

Modbus function READ_INPUT_REGISTERS (0x04).

Parameters:
  • reg_addr (int) – register address (0 to 65535)

  • reg_nb (int) – number of registers to read (1 to 125)

Returns:

registers list or None if fail

Return type:

list of int or None

property timeout

Get or set requests timeout (default is 30 seconds).

The argument may be a floating point number for sub-second precision. Setting timeout to a new value will close the current socket.

property unit_id

Get or set the modbus unit identifier (default is 1).

Any int from 0 to 255 is valid.

property version

Return the current package version as a str.

write_multiple_coils(bits_addr, bits_value)

Modbus function WRITE_MULTIPLE_COILS (0x0F).

Parameters:
  • bits_addr (int) – bits address (0 to 65535)

  • bits_value (list) – bits values to write

Returns:

True if write ok

Return type:

bool

write_multiple_registers(regs_addr, regs_value)

Modbus function WRITE_MULTIPLE_REGISTERS (0x10).

Parameters:
  • regs_addr (int) – registers address (0 to 65535)

  • regs_value (list) – registers values to write

Returns:

True if write ok

Return type:

bool

write_read_multiple_registers(write_addr, write_values, read_addr, read_nb=1)

Modbus function WRITE_READ_MULTIPLE_REGISTERS (0x17).

Parameters:
  • write_addr (int) – write registers address (0 to 65535)

  • write_values (list) – registers values to write

  • read_addr (int) – read register address (0 to 65535)

  • read_nb (int) – number of registers to read (1 to 125)

Returns:

registers list or None if fail

Return type:

list of int or None

write_single_coil(bit_addr, bit_value)

Modbus function WRITE_SINGLE_COIL (0x05).

Parameters:
  • bit_addr (int) – bit address (0 to 65535)

  • bit_value (bool) – bit value to write

Returns:

True if write ok

Return type:

bool

write_single_register(reg_addr, reg_value)

Modbus function WRITE_SINGLE_REGISTER (0x06).

Parameters:
  • reg_addr (int) – register address (0 to 65535)

  • reg_value (int) – register value to write

Returns:

True if write ok

Return type:

bool

class DeviceIdentificationResponse

class pyModbusTCP.client.DeviceIdentificationResponse(conformity_level: int = 0, more_follows: int = 0, next_object_id: int = 0, objects_by_id: ~typing.Dict[int, bytes] = <factory>)

Modbus TCP client function read_device_identification() response struct.

Parameters:
  • conformity_level (int) – this represents supported access and object type

  • more_follows (int) – for stream request can be set to 0xff if other objects are available (0x00 in other cases)

  • next_object_id (int) – the next object id to be asked by following transaction

  • objects_by_id (dict) – a dictionary with requested object (dict keys are object id as int)

__init__(conformity_level: int = 0, more_follows: int = 0, next_object_id: int = 0, objects_by_id: ~typing.Dict[int, bytes] = <factory>) None