GrabBag/App/StatorPosition/Doc/定子定位TCP通信协议.md

StatorPosition 电机定子定位系统 - TCP通信协议

版本历史

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

---

1. 协议概述

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

1.1 通信方式

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

1.2 通信模式

• 服务端：StatorPosition电机定子定位系统
• 客户端：上位机控制系统

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-02-19 10:30:00",
  "Data": {
    "ScanMode": ""
  }
}

Data字段说明：

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

3.2 扫描响应（ScanResponse）

定子定位系统收到扫描请求后，立即发送此消息确认收到请求。

消息格式：

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

Data字段说明：

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

3.3 扫描结果（ScanResult）

定子定位系统完成检测后，发送此消息返回检测结果。

消息格式：

{
  "MessageType": "ScanResult",
  "Timestamp": "2026-02-19 10:30:01",
  "Data": {
    "Stators": [
      {"objID": 1, "x": 100.50, "y": 200.30, "z": 50.20, "roll": 0.00, "pitch": 0.00, "yaw": 45.00},
      {"objID": 2, "x": 150.60, "y": 250.40, "z": 50.25, "roll": 0.00, "pitch": 0.00, "yaw": 90.00}
    ]
  }
}

Data字段说明：

字段名	类型	必填	说明
Stators	Array	是	定子抓取位置列表

定子位置格式（Stators数组元素）：

字段名	类型	说明
objID	Integer	定子物体ID
x	Double	X坐标（毫米）
y	Double	Y坐标（毫米）
z	Double	Z坐标（毫米）
roll	Double	Roll旋转角度（度）
pitch	Double	Pitch旋转角度（度）
yaw	Double	Yaw旋转角度（度）

{
  "objID": 1,
  "x": 100.50,    // X坐标（毫米）
  "y": 200.30,    // Y坐标（毫米）
  "z": 50.20,     // Z坐标（毫米）
  "roll": 0.00,   // Roll旋转角度（度）
  "pitch": 0.00,  // Pitch旋转角度（度）
  "yaw": 45.00    // Yaw旋转角度（度）
}

坐标说明：

• 所有坐标均为机械臂坐标系下的3D坐标（经过手眼标定变换）
• 位置单位：毫米（mm）
• 角度单位：度（°）
• objID 标识不同的定子实体

3.4 错误响应（Error）

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

消息格式：

{
  "MessageType": "Error",
  "Timestamp": "2026-02-19 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-02-19 10:30:00",
  "Data": {}
}

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

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

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

{
  "MessageType": "ScanResult",
  "Timestamp": "2026-02-19 10:30:02",
  "Data": {
    "Stators": [
      {"objID": 1, "x": 120.50, "y": 180.30, "z": 45.20, "roll": 0.00, "pitch": 0.00, "yaw": 30.00},
      {"objID": 2, "x": 180.60, "y": 180.40, "z": 45.25, "roll": 0.00, "pitch": 0.00, "yaw": 60.00},
      {"objID": 3, "x": 240.70, "y": 280.50, "z": 45.30, "roll": 0.00, "pitch": 0.00, "yaw": 90.00}
    ]
  }
}

6. 注意事项

1. 连接管理

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

2. 数据解析

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

3. 错误处理

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

4. 性能考虑

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

5. 数据精度

   • 坐标精度：小数点后2位（毫米）
   • 角度精度：小数点后2位（度）