YangOne/GrabBag
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
GrabBag/App/WorkpieceHole/Doc/工件孔检测TCP通信协议.md

7.6 KiB
Raw Blame History

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

版本历史

版本 日期 修改内容
1.0 2026-01-27 初始版本，定义基本通信协议

1. 协议概述

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

1.1 通信方式

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

1.2 通信模式

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

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": "2026-01-27 10:30:00",
  "Data": {
    "ScanMode": ""
  }
}

Data字段说明：

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

3.2 扫描响应（ScanResponse）

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

消息格式：

{
  "MessageType": "ScanResponse",
  "Timestamp": "2026-01-27 10:30:00",
  "Data": {
    "Status": "Accepted"
  }
}

Data字段说明：

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

3.3 扫描结果（ScanResult）

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

消息格式：

{
  "MessageType": "ScanResult",
  "Timestamp": "2026-01-27 10:30:01",
  "Data": {
    "WorkpieceType": 1,
    "Holes": [
      {"x": 100.50, "y": 200.30, "z": 50.20},
      {"x": 150.60, "y": 250.40, "z": 50.25},
      {"x": 200.70, "y": 300.50, "z": 50.30},
      {"x": 250.80, "y": 350.60, "z": 50.35}
    ],
    "HolesDir": [
      {"x": 0.00, "y": 0.00, "z": 1.00},
      {"x": 0.00, "y": 0.00, "z": 1.00},
      {"x": 0.00, "y": 0.00, "z": 1.00},
      {"x": 0.00, "y": 0.00, "z": 1.00}
    ],
    "Center": {"x": 175.50, "y": 275.45, "z": 50.28},
    "Y_Dir": {"x": 0.00, "y": 1.00, "z": 0.00},
    "Z_Dir": {"x": 0.00, "y": 0.00, "z": 1.00}
  }
}

Data字段说明：

字段名 类型 必填 说明
WorkpieceType Integer 是 工件类型标识
Holes Array 是 孔位置列表，每个元素包含 x, y, z 坐标
HolesDir Array 是 孔方向列表，每个元素包含 x, y, z 方向向量
Center Object 是 工件中心点坐标
Y_Dir Object 是 工件Y方向向量
Z_Dir Object 是 工件Z方向向量

孔位置格式（Holes数组元素）：

{
  "x": 100.50,  // X坐标（毫米）
  "y": 200.30,  // Y坐标（毫米）
  "z": 50.20    // Z坐标（毫米）
}

孔方向格式（HolesDir数组元素）：

{
  "x": 0.00,  // X方向分量
  "y": 0.00,  // Y方向分量
  "z": 1.00   // Z方向分量（单位向量）
}

中心点格式（Center）：

{
  "x": 175.50,  // 中心点X坐标（毫米）
  "y": 275.45,  // 中心点Y坐标（毫米）
  "z": 50.28    // 中心点Z坐标（毫米）
}

方向向量格式（Y_Dir / Z_Dir）：

{
  "x": 0.00,  // X方向分量
  "y": 1.00,  // Y方向分量
  "z": 0.00   // Z方向分量（单位向量）
}

坐标说明：

  • 所有坐标均为机械臂坐标系下的3D坐标
  • 单位：毫米（mm）
  • 方向向量为单位向量

3.4 错误响应（Error）

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

消息格式：

{
  "MessageType": "Error",
  "Timestamp": "2026-01-27 10:30:00",
  "Data": {
    "ErrorCode": -3,
    "ErrorMessage": "未知消息类型: InvalidType"
  }
}

Data字段说明：

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

4. 通信流程

4.1 正常检测流程

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

4.2 错误处理流程

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

5. 示例

5.1 完整交互示例

步骤1：上位机发送扫描请求

{
  "MessageType": "ScanRequest",
  "Timestamp": "2026-01-27 10:30:00",
  "Data": {}
}

步骤2：系统返回确认响应

{
  "MessageType": "ScanResponse",
  "Timestamp": "2026-01-27 10:30:00",
  "Data": {
    "Status": "Accepted"
  }
}

步骤3：系统返回检测结果

{
  "MessageType": "ScanResult",
  "Timestamp": "2026-01-27 10:30:02",
  "Data": {
    "WorkpieceType": 1,
    "Holes": [
      {"x": 120.50, "y": 180.30, "z": 45.20},
      {"x": 180.60, "y": 180.40, "z": 45.25},
      {"x": 180.70, "y": 240.50, "z": 45.30},
      {"x": 120.80, "y": 240.60, "z": 45.35}
    ],
    "HolesDir": [
      {"x": 0.00, "y": 0.00, "z": 1.00},
      {"x": 0.00, "y": 0.00, "z": 1.00},
      {"x": 0.00, "y": 0.00, "z": 1.00},
      {"x": 0.00, "y": 0.00, "z": 1.00}
    ],
    "Center": {"x": 150.65, "y": 210.45, "z": 45.28},
    "Y_Dir": {"x": 0.00, "y": 1.00, "z": 0.00},
    "Z_Dir": {"x": 0.00, "y": 0.00, "z": 1.00}
  }
}

6. 注意事项

  1. 连接管理

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

  2. 数据解析

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

  3. 错误处理

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

  4. 性能考虑

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

  5. 数据精度

    • 坐标精度：小数点后2位（毫米）
    • 方向向量为单位向量