GrabBag/App/WorkpieceHole/Doc/工件孔检测TCP通信协议.md

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

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

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

### 3.2 扫描响应（ScanResponse）

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

**消息格式：**
```json
{
  "MessageType": "ScanResponse",
  "Timestamp": "2026-01-27 10:30:00",
  "Data": {
    "Status": "Accepted"
  }
}
```

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

### 3.3 扫描结果（ScanResult）

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

**消息格式：**
```json
{
  "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数组元素）：**
```json
{
  "x": 100.50,  // X坐标（毫米）
  "y": 200.30,  // Y坐标（毫米）
  "z": 50.20    // Z坐标（毫米）
}
```

**孔方向格式（HolesDir数组元素）：**
```json
{
  "x": 0.00,  // X方向分量
  "y": 0.00,  // Y方向分量
  "z": 1.00   // Z方向分量（单位向量）
}
```

**中心点格式（Center）：**
```json
{
  "x": 175.50,  // 中心点X坐标（毫米）
  "y": 275.45,  // 中心点Y坐标（毫米）
  "z": 50.28    // 中心点Z坐标（毫米）
}
```

**方向向量格式（Y_Dir / Z_Dir）：**
```json
{
  "x": 0.00,  // X方向分量
  "y": 1.00,  // Y方向分量
  "z": 0.00   // Z方向分量（单位向量）
}
```

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

### 3.4 错误响应（Error）

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

**消息格式：**
```json
{
  "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：上位机发送扫描请求**
```json
{
  "MessageType": "ScanRequest",
  "Timestamp": "2026-01-27 10:30:00",
  "Data": {}
}
```

**步骤2：系统返回确认响应**
```json
{
  "MessageType": "ScanResponse",
  "Timestamp": "2026-01-27 10:30:00",
  "Data": {
    "Status": "Accepted"
  }
}
```

**步骤3：系统返回检测结果**
```json
{
  "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位（毫米）
   - 方向向量为单位向量