modbus — Modbus协议

Modbus是标准的串行通信协议驱动， Python 轻应用的驱动目前基于RS232/485串口的RTU模式能力，暂不支持ASCII/TCP模式。

开发可以通过组件API，在设备端快速对接支持Modbus协议器件的进行读写。

---

使用示例

import modbus as mb

# 主/从机初始化modbus，串口1，波特率为9600， 奇偶校验为0， 响应超时为500ms
mb.init(1, 9600, 0, 500)

# 主机写保持寄存器： 设备ID是1，寄存器地址为1，寄存器数据为2， 响应超时为持续等待
mb.writeHoldingRegister(1, 1, 2, -1)

# 主机读多个保持寄存器： 设备ID是2，寄存器起始地址为0，连续读入10个寄存器数据， 响应超时为持续等待
data = bytearray(20)
mb.readHoldingRegisters(2, 0, 10, data, -1)

# 从机读数据帧，其中ret[0]为状态码，ret[1]为接收到的数据
ret = mb.recv()

# 从机发送响应帧, 其中 1 为从机ID，resp为响应信息，格式为：功能码（function）+ 寄存器数值
resp = bytearray(10)
dev_id = 1
mb.send(dev_id, resp)

函数接口

ModBus工业协议标准接口

modbus.PARITY()

奇偶校验枚举值

• PARITY_NONE = 0

• PARITY_ODD = 1

• PARITY_EVEN = 2

modbus.STATUS()

读写操作状态码枚举值

• MB_SUCCESS = 0

• MB_MUTEX_ERROR = 1

• MB_INVALID_SLAVE_ADDR = 2

• MB_INVALID_PARAM = 3

• MB_RESPOND_EXCEPTION = 4

• MB_RESPOND_LENGTH_ERR = 5

• MB_RESPOND_FRAME_ERR = 6

• MB_RESPOND_TIMEOUT = 7

• MB_CANNOT_GET_HANDLER = 8

• MB_SLAVE_NO_RESPOND = 9

• MB_FRAME_SEND_ERR = 10

• MB_SERIAL_INIT_FAILED = 11

• MB_SERIAL_UNINIT_FAILED = 12

• MB_FUNCTION_CODE_NOT_SUPPORT = 13

modbus.init(port, baud_rate, parity, timeout)

初始化modbus协议

参数

• port(int) – 必选参数，RS485串口端口号

• baud_rate(int) – 可选参数，波特率，默认值为9600

• parity(int) – 可选参数，奇偶校验信息，默认值为0。可选值参考奇偶校验信息（PARITY）

• timeout(int) – 可选参数，相应等待超时，单位是毫秒（ms），-1表示永久等待。默认值为200

返回

0: 成功，其他: 失败，返回结果具体含义参考 STATUS 信息

引发

OSError – EBUSY 或 EINVAL

modbus.deinit()

释放modbus协议

返回

0: 成功，其他: 失败，返回结果具体含义参考 STATUS 信息

引发

OSError – EBADF

modbus.writeHoldingRegister(slave_addr, register_addr, register_value, timeout)

向从机写单个保持寄存器

参数

• slave_addr(int) – 请求的从机地址，0代表广播

• register_addr(int) – 写寄存器的地址

• register_value(int) – 写寄存器的数据

• timeout(int) – 请求超时时间，单位是毫秒（ms），-1表示永久等待。

返回

tuple，4元组中的条目格式为:

• status: 请求状态，0表示成功，其他表示失败

• resp_addr: 响应地址

• resp_value: 响应数据

• exception_code: 响应异常代码

引发

RuntimeError – EINVAL

modbus.writeMultipleHoldingRegisters(slave_addr, start_addr, reg_quantity, data, timeout)

向从机多个保持寄存器中写入数据。

参数

• slave_addr(int) – 请求的从机地址，0代表广播。

• start_addr(int) – 待写寄存器的起始地址

• reg_quantity(int) – 待写寄存器的数量，表示操作多少个寄存器

• data(bytearray) – 写寄存器的数据，注意每个寄存器包含高低两个字节

• timeout(int) – 请求超时时间，单位是毫秒（ms），-1表示永久等待。

返回

tuple，4元组中的条目格式为:

• status: 请求状态，0表示成功，其他表示失败。具体数值参考 STATUS

• resp_addr: 响应地址

• resp_quantity: 真实完成寄存器操作的数量

• exception_code: 异常代码

引发

ValueError – EINVAL

modbus.writeCoil(slave_addr, coil_addr, coil_value, timeout)

向从机某个线圈中写入数据

参数

• slave_addr(int) – 请求的从机地址，0代表广播。

• coil_addr(int) – 写线圈的地址

• coil_value(int) – 写线圈的数据

• timeout(int) – 请求超时时间，单位是毫秒（ms）。-1表示永久等待。

返回

tuple，4元组中的条目格式为:

• status: 请求状态，0表示成功，其他表示失败

• resp_addr: 响应地址

• resp_value: 响应数据

• exception_code: 异常代码

引发

OSError – EINVAL

modbus.writeMultipleCoils(slave_addr, start_addr, reg_quantity, data, timeout)

向从机多个线圈中写入数据。

参数

• slave_addr(int) – 请求的从机地址，0代表广播。

• start_addr(int) – 待写寄存器的起始地址

• reg_quantity(int) – 待写寄存器的数量，表示操作多少个寄存器

• data(bytearray) – 写寄存器的数据，注意每个寄存器包含高低两个字节

• timeout(int) – 请求超时时间，单位是毫秒（ms），-1表示永久等待。

返回

tuple，4元组中的条目格式为:

• status: 请求状态，0表示成功，其他表示失败。具体数值参考 STATUS

• resp_addr: 响应地址

• resp_quantity: 真实完成寄存器操作的数量

• exception_code: 异常代码

引发

ValueError – EINVAL

modbus.readHoldingRegisters(slave_addr, start_addr, reg_quantity, data, timeout)

读取多个保持寄存器中的数据

参数

• slave_addr(int) – 请求的从机地址，0代表广播。

• start_addr(int) – 待读寄存器的起始地址

• reg_quantity(int) – 待读寄存器的数量，表示操作多少个寄存器

• data(bytearray) – 读寄存器的数据，注意每个寄存器包含高低两个字节

• timeout(int) – 请求超时时间，单位是毫秒（ms），-1表示永久等待。

返回

tuple，2元组中的条目格式为:

• status: 请求状态，0表示成功，其他表示失败

• respond_count: 读取到数据的字节数，该数值不大于data的长度

引发

OSError – EINVAL

modbus.readInputRegisters(slave_addr, start_addr, reg_quantity, data, timeout)

读取多个输入寄存器中的数据

参数

• slave_addr(int) – 请求的从机地址，0代表广播。

• start_addr(int) – 待读寄存器的起始地址

• reg_quantity(int) – 待读寄存器的数量，表示操作多少个寄存器

• data(bytearray) – 读寄存器的数据，注意每个寄存器包含高低两个字节

• timeout(int) – 请求超时时间，单位是毫秒（ms），-1表示永久等待。

返回

tuple，2元组中的条目格式为:

• status: 请求状态，0表示成功，其他表示失败

• respond_count: 读取到数据的字节数，该数值不大于data的长度

引发

OSError – EINVAL

modbus.readDiscreteInputs(slave_addr, start_addr, reg_quantity, data, timeout)

读取多个离散输入中的数据

参数

• slave_addr(int) – 请求的从机地址，0代表广播。

• start_addr(int) – 待读寄存器的起始地址

• reg_quantity(int) – 待读寄存器的数量，表示操作多少个寄存器

• data(bytearray) – 读寄存器的数据，注意每个寄存器包含高低两个字节

• timeout(int) – 请求超时时间，单位是毫秒（ms），-1表示永久等待。

返回

tuple，2元组中的条目格式为:

• status: 请求状态，0表示成功，其他表示失败

• respond_count: 读取到数据的字节数，该数值不大于data的长度

引发

OSError – EINVAL

modbus.readCoils(slave_addr, start_addr, reg_quantity, data, timeout)

读取多个线圈中的数据

参数

• slave_addr(int) – 请求的从机地址，0代表广播。

• start_addr(int) – 待读寄存器的起始地址

• reg_quantity(int) – 待读寄存器的数量，表示操作多少个寄存器

• data(bytearray) – 读寄存器的数据，注意每个寄存器包含高低两个字节

• timeout(int) – 请求超时时间，单位是毫秒（ms），-1表示永久等待。

返回

tuple，2元组中的条目格式为:

• status: 请求状态，0表示成功，其他表示失败

• respond_count: 读取到数据的字节数，该数值不大于data的长度

引发

OSError – EINVAL

modbus.recv()

接收主机发送的请求命令，轮训间隔由 init 函数的 timeout参数决定

参数

空 –

返回

tuple，2元组中的条目格式为:

• status: 请求状态，0表示成功，其他表示失败

• bytes: 接收到的数据，包含CRC校验数据

引发

OSError – EINVAL

modbus.send(slave_addr, data, timeout)

发送响应数据给主机

参数

• slave_addr(int) – 响应请求的从机地址

• data(bytearray) – 响应数据，格式为： fucntion + resp data

• timeout(int) – 发送超时时间，单位是毫秒（ms），-1表示永久等待。

返回

tuple，2元组中的条目格式为:

• status: 请求状态，0表示成功，其他表示失败

• length: 发送的响应帧的长度，包含CRC校验长度

引发

OSError – EINVAL