GrabBag/App/GrabBag/Doc/拆包TCP通信协议.md

拆包TCP 通信协议

协议版本

• 版本：v1.1
• 更新日期：2025-12-17

版本历史

版本	日期	变更内容
v1.1	2025-12-17	补充忙碌状态功能
v1.0	2025-12-14	初始版本，定义最新协议格式

---

协议格式

请求格式

@,视觉号,视觉模版号,启动信息,$

参数说明：

• 视觉号：相机编号（1, 2, ...）
• 视觉模版号：包裹模板编号（对应配置文件中的 pkg_N）
• 启动信息：触发命令，目前支持 Trig

示例：

@,1,3,Trig,$      # 触发 1 号相机，使用 3 号模板
@,2,5,Trig,$      # 触发 2 号相机，使用 5 号模板

---

响应格式

@,状态码,X,Y,Z,U,结果标志,$

参数说明：

• 状态码：固定为 1
• X：目标 X 坐标（mm）
• Y：目标 Y 坐标（mm）
• Z：目标 Z 坐标（mm）
• U：目标旋转角度（度）
• 结果标志：检测结果状态码

结果标志定义：

状态码	含义	说明
0	空托盘	检测到空托盘，无包裹
1	检测成功	检测到包裹，返回坐标
2	检测失败	检测过程出错（相机未连接、参数错误等）
3	设备忙碌	设备正在检测中，拒绝新请求

---

响应示例

1. 检测成功（有包裹）

@,1,123.45,678.90,100.00,45.50,1,$

说明： 检测到包裹，坐标为 (123.45, 678.90, 100.00)，旋转角度 45.50°

2. 空托盘

@,1,0,0,0,0,0,$

说明： 检测到空托盘，无包裹

3. 检测失败

@,1,0,0,0,0,2,$

说明： 检测失败，可能原因：

• 相机未连接
• 无效的相机编号
• 包裹模板未找到
• 启动检测失败

4. 设备忙碌

@,1,0,0,0,0,3,$

设备正在检测中，拒绝新的触发请求

---

使用流程

典型检测流程

1. 客户端发送触发命令
   → @,1,3,Trig,$

2. 服务端检查状态
   - 如果设备忙碌 → 返回 @,1,0,0,0,0,3,$
   - 如果设备就绪 → 开始检测

3. 检测完成后返回结果
   - 有包裹 → @,1,X,Y,Z,U,1,$
   - 空托盘 → @,1,0,0,0,0,0,$
   - 失败   → @,1,0,0,0,0,2,$

注意事项

1. 并发控制：设备同时只能处理一个检测请求，如果设备正在检测，新请求会返回忙碌状态（3）
2. 模板切换：指定模板编号会自动切换到对应的工位、相机和包裹配置
3. 坐标系：返回的坐标已经过手眼标定转换，为机械臂坐标系
4. 超时处理：建议客户端设置合理的超时时间（如 30 秒）