Modbus通信接口

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

方法： modbus_set_master_parameter(master_id: int, param: ModbusMasterParameter)

功能描述： 通过已经初始化的机器人控制类对象，配置内置的 Modbus 主站（Master）通信协议栈参数。该函数下发后，底层会根据结构体中声明的链路类型（RTU 或 TCP）以及对应的物理参数，动态初始化控制器的硬件通道。此接口是读写外部工具手或 PLC 数据的绝对前置步骤。

参数：

• master_id：主站通道编号，整型格式（int）。有效取值范围为 0 ~ 8。
• param：Modbus 参数配置对象，底层 nrc.ModbusMasterParameter 结构体格式。包含总线协议类型、地址映射基准及串口/网口嵌套属性。

返回值：

• int：状态码
  • 0：配置成功。代表 Modbus 总线参数已成功下发并生效。
  • 非 0 整型值：配置失败。代表主站 ID 越界或参数配置不合法。
  • -1：网络未连接拦截（类内部 socket_fd 无效）或运行时未知异常。

使用示例：

import nrc_interface as nrc

# 1. 实例化并配满底层 Modbus RTU 核心参数结构体
param = nrc.ModbusMasterParameter()
param.type = "RTU"
param.startAddress = True  # True 代表地址从 0 开始

# 配置嵌套的 RTU 串口硬件参数（纳博特控制器物理串口2）
param.RTU.slaveId = 2
param.RTU.port = 2
param.RTU.baudrate = 115200
param.checkBit = "None"
param.RTU.dataBit = 8
param.RTU.stopBit = 1

# 2. 调用底层核心接口，一键下发配置到 1 号主站通道
ret = nrc.modbus_set_master_parameter(socket_fd, 1, param)

# 3. 校验指令执行状态
if ret == 0:
    print("成功: Modbus RTU 参数配置成功，总线物理层已顺利初始化就绪！")
else:
    print(f"错误: 设置 Modbus RTU 参数失败，底层错误代码: {ret}。")

2. modbus_open_master - 打开 Modbus 主站

方法： modbus_open_master(socket_fd: int, id: int)

功能描述： 通知机械臂控制器正式打开并使能指定的 Modbus 主站通道。该函数下发后，物理总线通电激活动作，协议栈内核启动，控制器开始按照先前配置好的波特率等参数在总线上进行硬件轮询与握手。该接口必须在参数配置成功后、读写寄存器前调用。

参数：

• socket_fd：已连接的机械臂常规指令通道句柄，整型格式（int）。
• id：准备打开的主站通道编号，整型格式（int），有效取值范围为 0 ~ 8。

返回值：

• int：状态码
  • 0：打开成功，总线进入就绪态。
  • 非 0 整型值：打开失败。代表通道未提前配置参数、硬件通道被占用或触发物理通信异常。
  • -1：通信断开异常。

使用示例：

import nrc_interface as nrc

# 1. 调用底层接口正式打开 1 号 Modbus 主站通道
ret = nrc.modbus_open_master(socket_fd, 1)

# 2. 校验总线使能状态
if ret == 0:
    print("成功: Modbus 1 号主站已成功打开，总线硬件轮询已激活！")
else:
    print(f"错误: 打开 Modbus 主站失败，底层错误代码: {ret}。")

# 完整 Modbus Rtu 使用示例见示例1所示。

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

方法： modbus_write_multiple_holding_registers(socket_fd: int, id: int, address: int, data: VectorInt)

功能描述： 通过 Modbus 协议的 16 号功能码（Write Multiple Registers），向指定主站通道下的从站设备批量写入连续的保持寄存器数据。通常用于向末端夹爪、灵巧手、执行机构等总线外设一键下发复合控制字（如运行速度、目标位置、力矩限制等）。

参数：

• socket_fd：已连接的机械臂常规指令通道句柄，整型格式（int）。
• id：主站通道编号，整型格式（int），有效取值范围为 0 ~ 8。
• address：待写入的目标保持寄存器起始物理地址，整型格式（int）。
• data：需要写入的 16 位整型数据容器，底层 VectorInt 格式。

返回值：

• int：状态码
  • 0：批量写入成功，从站设备已成功接收并响应写入指令。
  • 非 0 整型值：写入失败。代表寄存器地址越界、写入数据超限或硬件总线超时未响应。
  • -1：通信断开异常。

使用示例：

import nrc_interface as nrc

# 1. 准备待写入的数据列表并转换为底层 VectorInt 类型
control_data = [20000, 0, 0, 0, 0]
arm_data = nrc.VectorInt()
for val in control_data:
    arm_data.push_back(int(val))

# 2. 调用底层核心接口批量写入 1135 起始地址（指定 1 号主站通道）
ret = nrc.modbus_write_multiple_holding_registers(socket_fd, 1, 1135, arm_data)

# 3. 校验寄存器写入状态
if ret == 0:
    print(f"成功: Modbus 批量写入寄存器成功 -> 起始地址: 1135, 数据: {control_data}")
else:
    print(f"错误: 批量写入 Modbus 寄存器失败，底层错误代码: {ret}。")

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

方法： modbus_read_holding_registers(socket_fd: int, id: int, address: int, quantity: int, data: VectorInt)

功能描述： 通过 Modbus 协议的 03 号功能码（Read Holding Registers），从指定主站通道下的从站设备中连续读取多个保持寄存器的当前数值。

参数：

• socket_fd：已连接的机械臂常规指令通道句柄，整型格式（int）。
• id：主站通道编号，整型格式（int），有效取值范围为 0 ~ 8。
• address：待读取的目标保持寄存器起始物理地址，整型格式（int）。
• quantity：连续读取的寄存器个数/数量，整型格式（int）。
• data：接收读取数据的容器，底层空 VectorInt 对象。

返回值：

• int：执行码
  • 0：读取成功，读取到的物理数据已被成功存入传入的 data 容器中。
  • 非 0 整型值：读取失败。代表目标从站未响应、读取数量超出上限或硬件通信超时。
  • -1：通信断开异常。

使用示例：

import nrc_interface as nrc

# 1. 创建用于接收数据的底层空 VectorInt 容器
read_back = nrc.VectorInt()

# 2. 调用底层接口读取 1 号主站下 1155 起始地址的连续 5 个寄存器值
ret = nrc.modbus_read_holding_registers(socket_fd, 1, 1155, 5, read_back)

# 3. 校验并打印读取到的物理数据
if ret == 0:
    print(f"成功: Modbus 批量读取寄存器成功 -> 起始地址: 1155, 数据: {list(read_back)}")
else:
    print(f"错误: 读取 Modbus 寄存器失败，底层错误代码: {ret}。")