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格式：

```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位（度）