GrabBag/App/RodAndBarPosition/Doc/MODBUS_PROTOCOL.md

棒材定位系统 Modbus TCP 通信协议

1. 系统架构

• 视觉系统：作为 Modbus TCP Server（默认端口 502）
• 外部客户端：连接到视觉系统进行检测触发和结果读取

2. 连接参数

参数	值
协议	Modbus TCP
端口	502（默认）
角色	Server（被动等待连接）

3. 寄存器定义

地址	寄存器数	类型	读/写	说明
0	1	uint16	R/W	控制命令（写入后自动清零，命令见下表）
1	1	uint16	R	状态码
2	2	float	R	X（中心点 X 坐标，mm）
4	2	float	R	Y（中心点 Y 坐标，mm）
6	2	float	R	Z（中心点 Z 坐标，mm）
8	2	float	R	Roll（绕X轴旋转角，度）
10	2	float	R	Pitch（绕Y轴旋转角，度）
12	2	float	R	Yaw（绕Z轴旋转角，度）

浮点数编码：IEEE 754 单精度浮点数，每个 float 占 2 个 uint16 寄存器，字节序由网络配置决定

坐标系：XYZ 为机械臂坐标系下的值（已经过手眼标定转换），RPY 为 ZYX 外旋欧拉角

3.1 控制命令（地址 0）

命令值	说明
1	触发相机1执行检测
2	触发相机2执行检测
10	读取下一个缓存棒材结果（从上次检测结果中依次获取）

4. 状态码定义

状态码	说明
0	正在检测
1	成功（地址 2~13 数据有效）
2	检测失败
3	结果为空 / 无更多缓存结果

5. 通信流程

5.1 触发检测

1. 外部客户端写入地址 0，值为相机编号（1 或 2）
2. 视觉系统自动清零地址 0，并将地址 1 设为 0（正在检测）
3. 视觉系统触发对应相机的检测
4. 检测完成后自动输出第一个棒材结果（地址 1=1，地址 2~13=坐标）

5.2 读取结果

1. 检测完成后，视觉系统写入：
   • 地址 1：状态码（1=成功，2=失败，3=空结果）
   • 地址 2~13：第一个棒材的 X, Y, Z, Roll, Pitch, Yaw（仅状态码为 1 时有效）
2. 外部客户端轮询地址 1，当值从 0 变为非零时表示检测完成
3. 状态码为 1 时，读取地址 2~13 获取定位结果

5.3 典型时序（单棒材）

客户端                              视觉系统
  |                                    |
  |--- 写入 地址0 = 1 (触发相机1)  ------>|
  |                                    |-- 清零地址0，地址1=0(正在检测)
  |                                    |-- 执行检测...
  |                                    |
  |<-- 读取 地址1 = 0 (正在检测) --------|
  |                                    |
  |<-- 读取 地址1 = 1 (检测成功) --------|
  |                                    |-- 写入地址1=1, 地址2~13=第1个棒材结果
  |<-- 读取 地址2~13 (XYZ+RPY) ---------|
  |                                    |

5.4 读取多棒材结果时序

当检测到多个棒材时，可通过写命令 10 依次获取后续结果：

客户端                              视觉系统
  |                                    |
  |--- 写入 地址0 = 1 (触发相机1) ------>|
  |                                    |-- 清零地址0，地址1=0(正在检测)
  |                                    |-- 执行检测（发现N个棒材）...
  |                                    |
  |<-- 读取 地址1 = 1 (成功) -----------|
  |                                    |-- 自动输出第1个棒材结果
  |<-- 读取 地址2~13 (棒材1坐标) --------|
  |                                    |
  |--- 写入 地址0 = 10 (读取下一个) ---->|
  |                                    |-- 输出第2个棒材结果
  |<-- 读取 地址1 = 1 (成功) -----------|
  |<-- 读取 地址2~13 (棒材2坐标) --------|
  |                                    |
  |--- 写入 地址0 = 10 (继续读取) ------>|
  |                                    |-- 无更多结果
  |<-- 读取 地址1 = 3 (无更多结果) ------|
  |                                    |

注意：触发新的检测（写1或写2）后，缓存索引自动归零，写10将重新从第2个棒材开始读取。

6. 注意事项

1. 触发寄存器写入后会自动清零，无需客户端手动清零
2. 检测完成后自动输出第一个棒材结果；写命令 10 可依次获取第2、3...个结果
3. 坐标数据为机械臂坐标系下的值（已经过手眼标定转换）
4. 欧拉角为 ZYX 外旋顺序（从轴向方向和法向方向构建旋转矩阵提取）
5. 浮点数字节序（大端/小端）由网络配置中的 byteOrder 参数决定