Module pyModbusTCP.client

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

class pyModbusTCP.client.ModbusClient

class pyModbusTCP.client.ModbusClient(host=None, port=None, unit_id=None, timeout=None, debug=None, auto_open=None, auto_close=None)

Modbus TCP client

__init__(host=None, port=None, unit_id=None, timeout=None, debug=None, auto_open=None, auto_close=None)

Constructor

Modbus server params (host, port) can be set here or with host(), port() functions. Same for debug option.

Use functions avoid to launch ValueError except if params is incorrect.

Parameters:
  • host (str) – hostname or IPv4/IPv6 address server address (optional)
  • port (int) – TCP port number (optional)
  • unit_id (int) – unit ID (optional)
  • timeout (float) – socket timeout in seconds (optional)
  • debug (bool) – debug state (optional)
  • auto_open (bool) – auto TCP connect (optional)
  • auto_close (bool) – auto TCP close (optional)
Returns:

Object ModbusClient
Return type:

ModbusClient
Raises:

ValueError – if a set parameter value is incorrect
auto_close(state=None)

Get or set automatic TCP close mode (after each request)

Parameters:state (bool or None) – auto_close state or None for get value
Returns:auto_close state or None if set fail
Return type:bool or None
auto_open(state=None)

Get or set automatic TCP connect mode

Parameters:state (bool or None) – auto_open state or None for get value
Returns:auto_open state or None if set fail
Return type:bool or None
close()

Close TCP connection

Returns:close status (True for close/None if already close)
Return type:bool or None
debug(state=None)

Get or set debug mode

Parameters:state (bool or None) – debug state or None for get value
Returns:debug state or None if set fail
Return type:bool or None
host(hostname=None)

Get or set host (IPv4/IPv6 or hostname like ‘plc.domain.net’)

Parameters:hostname (str or None) – hostname or IPv4/IPv6 address or None for get value
Returns:hostname or None if set fail
Return type:str or None
is_open()

Get status of TCP connection

Returns:status (True for open)
Return type:bool
last_error()

Get last error code

Returns:last error code
Return type:int
last_error_txt()

Get last error as human readable text

Returns:last error as string
Return type:str
last_except()

Get last exception code

Returns:last exception code
Return type:int
last_except_txt(verbose=False)

Get last exception code as human readable text

Parameters:verbose (bool) – set to True for detailed information about exception
Returns:last exception as string
Return type:str
mode(mode=None)

Get or set modbus mode (TCP or RTU)

Parameters:mode (int) – mode (MODBUS_TCP/MODBUS_RTU) to set or None for get value
Returns:mode or None if set fail
Return type:int or None
open()

Connect to modbus server (open TCP connection)

Returns:connect status (True if open)
Return type:bool
port(port=None)

Get or set TCP port

Parameters:port (int or None) – TCP port number or None for get value
Returns:TCP port or None if set fail
Return type:int or None
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_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
timeout(timeout=None)

Get or set timeout field

Parameters:timeout (float or None) – socket timeout in seconds or None for get value
Returns:timeout or None if set fail
Return type:float or None
unit_id(unit_id=None)

Get or set unit ID field

Parameters:unit_id (int or None) – unit ID (0 to 255) or None for get value
Returns:unit ID or None if set fail
Return type:int or None
version()

Get package version

Returns:current version of the package (like “0.0.1”)
Return type: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 or None if fail
Return type:

bool or None
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 or None if fail
Return type:

bool 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 or None if fail
Return type:

bool or None
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 or None if fail
Return type:

bool or None