Modbus with pymodbus

Hence I can not understand well the usage from the official document, here is the note for pymodbus. This note is written with pymodbus==2.3.0. You can also visit the github page for more information. It's okay that you don't have a modbus slave device, such as PLC. You can use a simlation software as an modbus slave, see modbus: Simulation Tools.

To install the library:

pip install pymodbus

Modbus Simple Introduction

• Modbus point type
  Note that the table below shows the maximum range defined by modbus official spec. However, in most applications, PDU addresses are no bigger then 1000, and the absolute addresses are denoted as 00001, 10001, 30001 and 40001.

  Modbus point type	Absolute Address	PDU Address	Data type	Master Access
  DO(Coil Status)	000001	0~65535	Boolean	Read/Wrtie
  DI(Input Status)	100001	0~65535	Boolean	Read only
  AI(Input Register)	300001	0~65535	unsigned word(2 bytes)	Read only
  AO(Holding Register)	400001	0~65535	unsigned word(2 bytes)	Read/Write

  For AI and AO, each register is 1 word = 16 bits = 2 bytes.
  You have to specify a modbus point type when accessing data by PDU address, which is the case of functions of pymodbus.

• Funtion code
  The library pymodbus already handles the function code of modbus well, but it's good to know there is such a thing in case you may have to sniff the packages for debugging.

  Dec (Hex)	Description
  01 (0x01)	Read DO(Up to 2000 contiguous bits)
  02 (0x02)	Read DI(Up to 2000 contiguous bits)
  03 (0x03)	Read AO(Up to 125 contiguous words)
  04 (0x04)	Read AI(Up to 125 contiguous words)
  05 (0x05)	Write single DO
  15 (0x06)	Write single AO
  16 (0x10)	Write multiple DO(Up to 1968 contiguous bits)
  22 (0x16)	Write multiple AO(Up to 120 contiguous words)

  For AI and AO, each register is 1 word = 16 bits = 2 bytes.

• Exception code
  When a modbus master(client) send a unexpected requests to the modbus slave(server), the slave would return the request with exception code.

  Exception code	Represents	Description
  01	illegal function code
  02	illegal data address
  03	illegal data value
  04	slave device failure
  05	acknowledge	The requests is accepted, but the slave requires much time to finish the task.
  06	slave device busy
  07	negative acknowledge
  08	memory parity error
  10, 0x0A	gateway path unavailable
  11, 0x0B	gatewat target no response
  Exception code reference

Finally pymodbus

Initialize a TCP connection:

from pymodbus.client.sync import ModbusTcpClient
client = ModbusTcpClient(host='192.168.87.87', port=123)

or RTU(serial)

from pymodbus.client.sync import ModbusSerialClient
client = ModbusSerialClient(method='rtu', port='COM8')

ModbusSerialClient() parameters:

• method: The method to use for connection (ascii, rtu, binary)
• port: The serial port to attach to
• stopbits: The number of stop bits to use
• bytesize: The bytesize of the serial messages
• parity: Which kind of parity to use
• baudrate: The baud rate to use for the serial device
• timeout: The timeout between serial requests (default 3s)
• strict: Use Inter char timeout for baudrates <= 19200 (adhere to modbus standards)
  Make a connection.:

# Once it's connected, this function always returns true even the physical connection is dead.
# It returns false after .close()
client.connect()  # returns True if connection established

Read from the connected slave

Read 2 registers from 400001:

res = client.read_holding_registers(address=0, count=2, unit=1)
res.registers # shows the result, type: list

• Reading functions:

  function name	aka
  .read_coils	(DO)Coil Status
  .read_discrete_inputs()	(DI)Input Status
  .read_holding_registers()	(AI)Input Register
  .read_input_registers()	(AO)Holding Register

• Parameters
  Four read funcions listed above have same parameters:
  • address: The starting address to read from. Note that this is absolute address. For example, an address 400001 on a PLC manual is belong to AI. You should read it with relative address by removing leading 4 and ubstract by 1. Here are few examples:

    Absolute	Relative
    40001	0
    400001	0
    30021	20

  • count: The number of registers to read
  • unit: The slave unit(device ID) this request is targeting
• Return:
  • .bits: A list of reading result. Only available for DO and DI.
  • .registers: A list of reading result. Only available for AI and AO.
  • .isError(): True if error.
  • .message: The error meesage. Only availabel if .isError() returns true.

Write to the connected slave

• .write_coil()
• .write_coils()
• .write_register()
• .write_registers()
• Return

Example

Read and writing coil status(DO).

from pymodbus.client.sync import ModbusTcpClient
import random
import time

SERVER_IP = 'localhost' # aka modbus slave
SERVER_PORT = 502
ADDRESS_START  = 0000
ADDRESS_LENGTH = 10
DEVICE_ID = 1


client = ModbusTcpClient(host=SERVER_IP, port=SERVER_PORT)
if not client.connect() :  # .connect() returns True if connection established
  print("[Error] Fail to connect to modbus slave %s:%d." % (SERVER_IP, SERVER_PORT))
  exit()

# client.read_coils(address, count, unit)
t1 = time.time()
coil_response = client.read_coils(address=ADDRESS_START, count=ADDRESS_LENGTH, unit=DEVICE_ID) # the unit is the device ID
t2 = time.time()
print("[INFO] Read time cost {:7f} second.".format(t2-t1))
if coil_response.isError():  # .isError() returns True if the modbus slave returns exception
  print("[Error] The modbus slave connected but exception code returned: %d." % coil_response.exception_code)
else:
  # coil_response has attribute .bits if no error return from the modbus slave
  print("[INFO] Read success, coil response:", coil_response.bits)

# write an random value
print("[INFO] Now writing a random boolean value to address= {}.".format(ADDRESS_START))
rand_value = random.choice([True,False])
coil_response = client.write_coil(address=ADDRESS_START, value=rand_value, unit=DEVICE_ID)
if coil_response.isError():
  print("[Error] The modbus slave connected but exception code returned: %d." % coil_response.exception_code)
else:
  coil_response = client.read_coils(address=ADDRESS_START, count=1, unit=DEVICE_ID)
  if not coil_response.isError() and coil_response.bits[0] == rand_value:
    print("[INFO] Write success. The value read is the same as the value that just wrote.")
    print("[INFO] Coil response:", coil_response.bits)

client.close()