GrabBag/App/Workpiece/Doc/上位机和3D相机控制器TCP通信协议.md

Workpiece工件检测系统 - TCP通信协议

版本历史

版本	日期	修改内容
1.0	2025-12-14	初始版本，定义基本通信协议

---

1. 协议概述

本文档定义了上位机与Workpiece工件检测系统之间的TCP/IP通信协议。协议采用JSON格式进行数据交换，支持扫描请求、结果返回和错误通知。

1.1 通信方式

• 传输协议: TCP/IP
• 数据格式: JSON
• 端口: 7800（默认）
• 编码: UTF-8

1.2 通信模式

• 服务端：Workpiece工件检测系统
• 客户端：上位机控制系统

2. 协议格式

所有消息均采用统一的JSON格式：

{
  "MessageType": "消息类型标识",
  "Timestamp": "时间戳",
  "Data": {
    // 数据内容
  }
}

2.1 字段说明

字段名	类型	必填	说明
MessageType	String	是	消息类型标识，见下表
Timestamp	String	是	时间戳，格式：yyyy-MM-dd HH:mm:ss
Data	Object	是	消息数据内容，根据MessageType不同而不同

2.2 消息类型（MessageType）

类型值	方向	说明
ScanRequest	上位机→相机	上位机请求开始扫描
ScanResponse	相机→上位机	相机响应扫描请求（确认收到）
ScanResult	相机→上位机	相机发送扫描结果数据
Error	相机→上位机	错误信息通知

3. 消息定义

3.1 扫描请求（ScanRequest）

上位机点击扫描指令时，发送此消息到工件检测系统。

消息格式：

{
  "MessageType": "ScanRequest",
  "Timestamp": "2025-12-14 17:10:25",
  "Data": {
    "ScanMode": ""
  }
}

Data字段说明：

字段名	类型	必填	说明
ScanMode	String	否	扫描模式（预留字段）

3.2 扫描响应（ScanResponse）

工件检测系统收到扫描请求后，立即发送此消息确认收到请求。

消息格式：

{
  "MessageType": "ScanResponse",
  "Timestamp": "2025-12-14 17:10:25",
  "Data": {
    "Status": "Accepted"
  }
}

Data字段说明：

字段名	类型	必填	说明
Status	String	是	请求状态：Accepted-已接受

3.3 扫描结果（ScanResult）

工件检测系统完成检测后，发送此消息返回检测结果。

消息格式：

{
  "MessageType": "ScanResult",
  "Timestamp": "2025-12-14 17:10:26",
  "Data": {
    "WorkpieceType": 1,
    "1": {
      "P1": [100.50, 200.30, 50.20],
      "P2": [100.60, 250.40, 50.25],
      "P3": [100.70, 300.50, 50.30]
    },
    "2": {
      "P1": [150.80, 300.60, 50.35],
      "P2": [200.90, 300.70, 50.40],
      "P3": [250.10, 300.80, 50.45]
    },
    "3": {
      "P1": [250.20, 300.90, 50.50],
      "P2": [250.30, 250.10, 50.55],
      "P3": [250.40, 200.20, 50.60]
    },
    "4": {
      "P1": [250.50, 200.30, 50.65],
      "P2": [200.60, 200.40, 50.70],
      "P3": [150.70, 200.50, 50.75]
    },
    "Center": [175.50, 250.60, 50.80],
    "Lengths": {
      "len_A1": 123.45,
      "len_A2": 234.56,
      "len_B1": 345.67,
      "len_B2": 456.78
    }
  }
}

Data字段说明：

字段名	类型	必填	说明
WorkpieceType	Integer	是	工件类型：1/2/3/4等
1	Object	是	边1角点组（3个点）
2	Object	是	边2角点组（3个点）
3	Object	是	边3角点组（3个点）
4	Object	是	边4角点组（3个点）
Center	Array	是	工件中心点坐标 [x, y, z]
Lengths	Object	是	四个方向的长度信息

角点组格式： 每个角点组（1/2/3/4）包含3个点，格式为：

{
  "P1": [x, y, z],
  "P2": [x, y, z],
  "P3": [x, y, z]
}

长度信息格式：

{
  "len_A1": 123.45,  // A1长度（从工件中心135度方向）
  "len_A2": 234.56,  // A2长度（从工件中心225度方向）
  "len_B1": 345.67,  // B1长度（从工件中心45度方向）
  "len_B2": 456.78   // B2长度（从工件中心315度方向）
}

坐标说明：

• 所有坐标均为机械臂坐标系下的3D坐标
• 单位：毫米（mm）
• 格式：[x, y, z]

3.4 错误响应（Error）

当系统发生错误时，发送此消息通知上位机。

消息格式：

{
  "MessageType": "Error",
  "Timestamp": "2025-12-14 17:10:25",
  "Data": {
    "ErrorCode": -3,
    "ErrorMessage": "未知消息类型: InvalidType"
  }
}

Data字段说明：

字段名	类型	必填	说明
ErrorCode	Integer	是	错误码
ErrorMessage	String	是	错误描述信息

4. 通信流程

4.1 正常检测流程

上位机                          工件检测系统
  |                                  |
  |-------- ScanRequest ------------>|
  |                                  |
  |<------ ScanResponse -------------|
  |                                  |
  |                                  | (执行检测)
  |                                  |
  |<------- ScanResult --------------|
  |                                  |

4.2 错误处理流程

上位机                          工件检测系统
  |                                  |
  |-------- ScanRequest ------------>|
  |                                  |
  |                                  | (检测失败)
  |                                  |
  |<--------- Error -----------------|
  |                                  |

5. 注意事项

1. 连接管理

   • 客户端应实现断线重连机制
   • 建议使用心跳机制保持连接活跃

2. 数据解析

   • 所有JSON数据必须使用UTF-8编码
   • 接收数据时应处理粘包和分包情况

3. 错误处理

   • 客户端应正确处理所有错误码
   • 网络异常时应有重试机制

4. 性能考虑

   • 单次检测时间约为500ms-2s
   • 建议客户端设置合理的超时时间（建议10秒）