modbus通信接口

头文件：include/tl_interface.h

1. modbus_set_master_parameter - 设置 Modbus RTU 主站参数

方法：modbus_set_master_parameter(SOCKETFD socketFd, int id, const ModbusMasterParameter& param);

功能描述：配置 Modbus RTU 或 TCP主站参数。此接口用于设置通信协议栈参数。

参数：

socketFd：已连接的句柄。
master_id：主站 ID（0~8）。
param：ModbusMasterParameter 结构体，包含 type（"RTU" 或"TCP"），startAddress，以及嵌套的 RTU 或 TCP 子结构。

返回值：

0：成功
非 0：失败

使用示例：

Python

# 2.1 设置 RTU 主站参数

param_rtu = ModbusMasterParameter()

param_rtu.type = "RTU"

param_rtu.startAddress = True

param_rtu.RTU.slaveId = 2             # 灵巧手从站 ID

param_rtu.RTU.port = 1                # 控制器串口号（根据接线修改）

param_rtu.RTU.baudrate = 115200       # 波特率

param_rtu.RTU.checkBit = "None"

param_rtu.RTU.dataBit = 8

param_rtu.RTU.stopBit = 1

ret = modbus_set_master_parameter(sock, 1, param_rtu)

print_result("modbus_set_master_parameter (id=1, RTU slaveId=2)", ret)

if ret != SUCCESS:

    disconnect_robot(sock)

    return -1

print("  从站ID: %d（灵巧手）" % param_rtu.RTU.slaveId)

2. modbus_open_master - 打开 Modbus 主站

方法：modbus_open_master(SOCKETFD socketFd, int id);

功能描述：激活指定的 Modbus 主站通道，开始总线通信。

参数：

socketFd：已连接的句柄。
master_id：主站 ID（0~8）。

返回值：

0：成功
非 0：失败

使用示例：在打开前先配置Modbus RTU 参数

Python

# 2.2 打开 Modbus 主站

ret = modbus_open_master(sock, 1)

print_result("modbus_open_master (id=1)", ret)

if ret != SUCCESS:

    disconnect_robot(sock)

    return -1

time.sleep(0.5)

3. modbus_write_multiple_holding_registers - 写多个保持寄存器

方法：modbus_write_multiple_holding_registers(SOCKETFD socketFd, int id, int address, const std::vector<int>& data);

参数：

socketFd：已连接的句柄。
master_id：主站 ID（0~8）。
address：寄存器起始地址。
data：待写入的数据列表。

返回值：

0：成功
非 0：失败

使用示例：

Python

import tl_interface as tl

# 建立连接

socket_fd = tl.connect_robot("192.168.1.13", "6001")

# 功能码 10H: 写多个保持寄存器（id=0, 起始地址 10）

write_data = tl.VectorInt([100, 200, 300])

ret = tl.modbus_write_multiple_holding_registers(socket_fd, 0, 10, write_data)

if ret == 0:

    print("  写入数据: " + str(list(write_data)))

else:

    print(f"写多个保持寄存器失败，错误码：{ret}")

4. modbus_read_holding_registers - Modbus RTU 读取多个保持寄存器

方法：modbus_read_holding_registers(SOCKETFD socketFd, int id, int address, int quantity, std::vector<int>& data);

功能描述：使用功能码03读取保持寄存器。

参数：

socketFd：已连接的句柄。
id：主站 ID（0~8）。
address：寄存器起始地址。
quantity: 要读取的寄存器个数。
data: 读取到的数据（输出向量）。

返回值：

0：成功
非 0：失败

使用示例：

Python

print_separator("TCP --- 03H 读保持寄存器")

read_data = VectorInt()

ret = modbus_read_holding_registers(sock, 0, 0, 3, read_data)

print_result("modbus_read_holding_registers (addr=0, qty=3)", ret)

if ret == SUCCESS:

    print("  保持寄存器[0\~2]: ", end="")

    for i in range(len(read_data)):

        print("%d" % read_data[i], end=" ")

    print()

    if len(read_data) > 0 and read_data[0] == 5678:

        print("  [验证] 06H 写入与 03H 读取一致")

5. modbus_write_signal_coil_status - Modbus RTU协议写线圈

方法：modbus_write_signal_coil_status(SOCKETFD socketFd, int id, int address, int data);

功能描述：基于 Modbus RTU协议向指定从站通道写入单路线圈状态，通过寄存器地址与写入数值完成数字量输出点位控制。

参数：

socketFd：已连接的句柄。
id：主站通道编号（0~8）。
address：起始寄存器地址。
data：写入的参数

返回值：

0：成功
非 0：失败

使用示例：

Python

print_separator("TCP --- 05H 写单线圈")

ret = modbus_write_signal_coil_status(sock, 0, 0, 0xFF00)

print_result("modbus_write_signal_coil_status (addr=0, ON)", ret)

time.sleep(0.2)

6. modbus_write_signal_holding_registers - Modbus RTU协议写保持寄存器

方法：modbus_write_signal_holding_registers(SOCKETFD socketFd, int id, int address, int data);

功能描述：通过 Modbus RTU总线协议，对指定通讯通道的保持寄存器地址写入单个寄存器数值。

参数：

socketFd：已连接的句柄。
id：主站通道编号（0~8）。
address：起始寄存器地址。
data：写入的参数

返回值：

0：成功
非 0：失败

使用示例：

Python

print_separator("Modbus-RTU --- 06H 写单寄存器")

ret = modbus_write_signal_holding_registers(sock, 0, 0, 5678)

print_result("modbus_write_signal_holding_registers (addr=0, val=5678)", ret)

7. modbus_read_coil_status - Modbus读线圈状态

方法：modbus_read_coil_status(SOCKETFD socketFd, int id, int address, int quantity, std::vector<int>& data);

功能描述：通过 Modbus RTU总线协议功能码01H读取线圈（离散输出）状态；每个线圈返回 0 (断开) /1 (闭合)。

参数：

socketFd：已连接的句柄。
id：主站通道编号（0~8）。
address：起始线圈地址。
quantity：需要读取的线圈数量。
data：输出参数，存放读到的线圈状态，每个元素取值为 0 或 1。

返回值：

0：成功
非 0：失败

使用示例：

Python

print_separator("Modbus-RTU --- 01H 读线圈状态")

read_data = VectorInt()

ret = modbus_read_coil_status(sock, 0, 0, 1, read_data)

print_result("modbus_read_coil_status (addr=0, qty=1)", ret)

if ret == SUCCESS and len(read_data) > 0:

    print("  线圈[0] = %d" % read_data[0])

8. modbus_read_input_status - Modbus读取输入状态

方法：modbus_read_input_status(SOCKETFD socketFd, int id, int address, int quantity, std::vector<int>& data);

功能描述：通过 Modbus RTU 总线协议，功能码02H，读取离散输入（输入状态），每个点位为比特位，取值0/1；离散输入为从站侧只读点位，不可写入。

参数：

socketFd：已连接的句柄。
id：主站通道编号（0~8）。
address：起始离散输入地址。
quantity：待读取的离散输入点位数量。
data：输出参数，存储读到的离散输入状态，每个元素取值为 0 或 1。

返回值：

0：成功
非 0：失败

使用示例：

Python

print_separator("Modbus-RTU --- 02H 读输入状态")

read_data = VectorInt()

ret = modbus_read_input_status(sock, 0, 0, 4, read_data)

print_result("modbus_read_input_status (addr=0, qty=4)", ret)

if ret == SUCCESS:

    print("  输入状态: ", end="")

    for i in range(len(read_data)):

        print("%d" % read_data[i], end=" ")

    print()

9. modbus_read_input_registers - Modbus 读输入寄存器

方法：modbus_read_input_registers(SOCKETFD socketFd, int id, int address, int quantity, std::vector<int>& data);

功能描述：通过 Modbus RTU 总线协议，功能码04H，读取从站的输入寄存器。输入寄存器为从站只读 16位寄存器，常用于采集传感器、模拟量等外部数据。

参数：

socketFd：已连接的句柄。
id：主站通道编号（0~8）。
address：输入寄存器的起始地址。
quantity：待读取的输入寄存器数量。
data：输出参数。

返回值：

0：成功
非 0：失败

使用示例：

Python

print_separator("Modbus-RTU --- 04H 读输入寄存器")

read_data = VectorInt()

ret = modbus_read_input_registers(sock, 0, 0, 3, read_data)

print_result("modbus_read_input_registers (addr=0, qty=3)", ret)

if ret == SUCCESS:

    print("  输入寄存器: ", end="")

    for i in range(len(read_data)):

        print("%d" % read_data[i], end=" ")

    print()