265 lines
6.7 KiB
Markdown
265 lines
6.7 KiB
Markdown
# 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格式：
|
||
|
||
```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）
|
||
|
||
上位机发送扫描指令时，发送此消息到定子定位系统。
|
||
|
||
**消息格式：**
|
||
```json
|
||
{
|
||
"MessageType": "ScanRequest",
|
||
"Timestamp": "2026-02-19 10:30:00",
|
||
"Data": {
|
||
"ScanMode": ""
|
||
}
|
||
}
|
||
```
|
||
|
||
**Data字段说明：**
|
||
| 字段名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| ScanMode | String | 否 | 扫描模式（预留字段） |
|
||
|
||
### 3.2 扫描响应（ScanResponse）
|
||
|
||
定子定位系统收到扫描请求后，立即发送此消息确认收到请求。
|
||
|
||
**消息格式：**
|
||
```json
|
||
{
|
||
"MessageType": "ScanResponse",
|
||
"Timestamp": "2026-02-19 10:30:00",
|
||
"Data": {
|
||
"Status": "Accepted"
|
||
}
|
||
}
|
||
```
|
||
|
||
**Data字段说明：**
|
||
| 字段名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| Status | String | 是 | 请求状态：Accepted-已接受 |
|
||
|
||
### 3.3 扫描结果（ScanResult）
|
||
|
||
定子定位系统完成检测后，发送此消息返回检测结果。
|
||
|
||
**消息格式：**
|
||
```json
|
||
{
|
||
"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旋转角度（度） |
|
||
|
||
```json
|
||
{
|
||
"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）
|
||
|
||
当系统发生错误时，发送此消息通知上位机。
|
||
|
||
**消息格式：**
|
||
```json
|
||
{
|
||
"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：上位机发送扫描请求**
|
||
```json
|
||
{
|
||
"MessageType": "ScanRequest",
|
||
"Timestamp": "2026-02-19 10:30:00",
|
||
"Data": {}
|
||
}
|
||
```
|
||
|
||
**步骤2：系统返回确认响应**
|
||
```json
|
||
{
|
||
"MessageType": "ScanResponse",
|
||
"Timestamp": "2026-02-19 10:30:00",
|
||
"Data": {
|
||
"Status": "Accepted"
|
||
}
|
||
}
|
||
```
|
||
|
||
**步骤3：系统返回检测结果**
|
||
```json
|
||
{
|
||
"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位（度）
|