modbus.py

Modbus class

class phox_modbus.modbus.Modbus(port: str = None, baudrate: int = 19200, timeout: int = 0.1, parity: str = 'even', max_serial_latency=0.001)

Bases: object

Modbus class: Open a serial based modbus link. Give standard methods for Modbus functions.

Note

A feedback (sent and received frames…) is provided by registering a function using the register_feedback_handler method

Feedback events are (CRC_error, Frame_OK, Empty_frame, Frame_lenght_error, Unexpected_content, …)

Parameters:

  • port – Serial port name or None (default).

  • baudrate – Serial link baudrate. Default is 19200.

  • timeout – Read timeout in seconds. Default is 0.1s.

  • parity – Serial link parity. Possible valuers are ‘even’ (default) or ‘odd’

  • max_serial_latency – Shall be set to the maximum expected serial latency of the system Default is 0.001s Increase this parameter if peaces of frame are lost in legacy mode

Returns:

A modbus link object

property parity

Get or set the Modbus link parity. Setting to a new value will reconfigure the serial port automatically.

property baudrate

Get or set the Modbus link baudrate. Setting to a new value will reconfigure the serial port automatically.

property timeout

Get or set the Modbus link receive timeout. Setting to a new value will reconfigure the serial port automatically.

property is_open

Get the modbus link state.

register_feedback_handler(handler) → None

Register a feedback output handler.

Parameters:

handler – Function called each time there is a feedback from the Modbus class

open(port=None) → None

Open the Modbus link.

Parameters:

port – Serial port name or None (default).

Raises:

serial.SerialException – Serial port is missing, busy, or can not be configured.

close() → None

Close the Modbus link.

read_registers(device_addr: int, reg_addr: int, nb_reg: int = 1, **kwargs) → list

Implements Modbus function 03: Read holding registers.

Parameters:

  • device_addr – Modbus slave address of the device (0 to 247).

  • reg_addr – Starting address (0x0000 to 0xFFFF).

  • nb_reg – Quantity of registers to read (1 to 125).

Returns list of int:

Registers’ content.

Raises:

  • ValueError – Arguments are out of range.

  • ModbusError – Modbus protocol error or the device answers with an exception.

  • serial.SerialException – Serial port is missing, busy, or can not be configured.

read_register(device_addr: int, reg_addr: int, **kwargs) → int

Implements Modbus function 03: Read holding registers.

Parameters:

  • device_addr – Modbus slave address of the device (0 to 247).

  • reg_addr – Starting address (0x0000 to 0xFFFF).

Returns int:

Register’ value.

Raises:

  • ValueError – Arguments are out of range.

  • ModbusError – Modbus protocol error or the device answers with an exception.

  • serial.SerialException – Serial port is missing, busy, or can not be configured.

write_single_coil(device_addr: int, coil_addr: int, state: str, f_key=None, **kwargs) → None

Implements Modbus function 05 Write single coil.

Parameters:

  • device_addr – Modbus slave address of the device (0 to 247).

  • coil_addr – Coil’s address (0x0000 to 0xFFFF).

  • state – ‘ON’ or ‘OFF’.

  • kwargs – optional f_key argument

Raises:

  • ValueError – Arguments are out of range.

  • ModbusError – Modbus protocol error or the device answers with an exception.

  • serial.SerialException – Serial port is missing, busy, or can not be configured.

write_register(device_addr: int, reg_addr: int, value: int, **kwargs) → None

Implements Modbus function 06: Preset single register.

Parameters:

  • device_addr – Modbus slave address of the device (0 to 247).

  • reg_addr – Starting address (0x0000 to 0xFFFF).

  • value – Value to write (0x0000 to 0xFFFF).

Raises:

  • ValueError – Arguments are out of range.

  • ModbusError – Modbus protocol error or the device answers with an exception.

  • serial.SerialException – Serial port is missing, busy, or can not be configured.

query_data(device_addr: int, value=<class 'int'>, **kwargs) → int

Implements Modbus function 08 > Sub-function 00: Query data.

Parameters:

  • device_addr – Modbus slave address of the device (0 to 247).

  • data – Value to query (0x0000 to 0xFFFF).

returns int: The query data returned value.

Raises:

  • ValueError – Arguments are out of range.

  • ModbusError – Modbus protocol error or the device answers with an exception.

  • serial.SerialException – Serial port is missing, busy, or can not be configured.

restart_communication(device_addr: int, **kwargs) → None

Implements Modbus function 08 > Sub-function 01: Restart communication

Raises:
return_diag_register(device_addr: int, **kwargs) → int

Implements Modbus function 08 > Sub-functions 02: Return diag register.

Returns int:

Status

Raises:
force_listen_only(device_addr: int, **kwargs) → None

Implements Modbus function 08 > Sub-function 04: Force listen only

Raises:
diag_read(device_addr: int, subfunction: int, **kwargs) → int

Implements Modbus function 08 > Sub-functions 11 to 18: Return counters.

Parameters:

  • device_addr – Modbus slave address of the device (0 to 247).

  • subfunction – Sub-function (11 to 18).

Returns int:

The requested counter value.

Raises:

  • ValueError – Arguments are out of range.

  • ModbusError – Modbus protocol error or the device answers with an exception.

  • serial.SerialException – Serial port is missing, busy, or can not be configured.

clear_overrun(device_addr: int, **kwargs) → None

Implements Modbus function 08 > Sub-functions 20: Return diag register

Raises:
write_registers(device_addr: int, reg_addr: int, values: int, **kwargs) → None

Implements Modbus function 16: Write multiple registers.

Parameters:

  • device_addr – Modbus slave address of the device (0 to 247).

  • reg_addr – First register’s address (0x0000 to 0xFFFF).

  • values – list of words (0x0000 to 0xFFFF) to write (max 123 words).

Raises:

  • ValueError – Arguments are out of range.

  • ModbusError – Modbus protocol error or the device answers with an exception.

  • serial.SerialException – Serial port is missing, busy, or can not be configured.

read_device_id(device_addr: int, idcode=1, object_id=0, **kwargs) → dict

Implements Modbus function 43 > MEI 14: Read device id.

Parameters:

  • device_addr – Modbus slave address of the device (0 to 247).

  • idcode – Read device ID code (01: basic, 02: regular, 03: extended, 04: specific)

  • object_id – Id of the first requested object

Returns dict:

dictionnay of id objects.

Raises:

  • ValueError – Arguments are out of range.

  • ModbusError – Modbus protocol error or the device answers with an exception.

  • serial.SerialException – Serial port is missing, busy, or can not be configured.

get_comm_event_log(device_addr: int, **kwargs) → dict

Implements Modbus function 12 -> Get Comm Event Log

Parameters:

device_addr – Modbus slave address of the device (0 to 247).

Returns dict:

Status (int), Event count (int), Events (list[64])

Raises:

  • ValueError – Arguments are out of range.

  • ModbusError – Modbus protocol error or the device answers with an exception.

  • serial.SerialException – Serial port is missing, busy, or can not be configured.

get_comm_event_counter(device_addr: int, **kwargs) → dict

Implements Modbus function 11 -> Get Comm Event Counter

Parameters:

device_addr – Modbus slave address of the device (0 to 247).

Returns dict:

Status (int), Event count (int)

Raises:

  • ValueError – Arguments are out of range.

  • ModbusError – Modbus protocol error or the device answers with an exception.

  • serial.SerialException – Serial port is missing, busy, or can not be configured.

report_server_id(device_addr: int, **kwargs) → dict

Implements Modbus function 17 -> Report Server ID

Parameters:

device_addr – Modbus slave address of the device (0 to 247).

Returns dict:

Server ID (str), Run indicator status (‘ON’ or ‘OFF”)

Raises:

  • ValueError – Arguments are out of range.

  • ModbusError – Modbus protocol error or the device answers with an exception.

  • serial.SerialException – Serial port is missing, busy, or can not be configured.

Exceptions

class phox_modbus.modbus.ModbusError

Exception raised in case of Modbus communication error.

class phox_modbus.modbus.SlaveExceptionError

Exceptions that the Modbus device reports.

class phox_modbus.modbus.IllegalRequestError

The slave has received an illegal request.

Can be “Illegal function”, “Illegal address” or “Illegal data value”

class phox_modbus.modbus.MasterReportedError

Exceptions that are detected by the master.

class phox_modbus.modbus.NoResponseError

No response from the slave.

class phox_modbus.modbus.InvalidResponseError

The response does not fulfill the Modbus standard.

Exceptions inherited from pyserial

class serial.SerialException

Base class for serial port related exceptions.

class serial.PortNotOpenError

Port is not open

class serial.SerialTimeoutException

Write timeouts give an exception