GrabBag/App/Workpiece/Doc/上位机和3D相机控制器TCP通信协议.md

# Workpiece工件检测系统 - TCP通信协议


## 版本历史

| 版本 | 日期 | 修改内容 |
|------|------|----------|
| 1.0 | 2025-12-14 | 初始版本，定义基本通信协议 |

---

## 1. 协议概述

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

### 1.1 通信方式
- **传输协议**: TCP/IP
- **数据格式**: JSON
- **端口**: 7800（默认）
- **编码**: UTF-8

### 1.2 通信模式
- 服务端：Workpiece工件检测系统
- 客户端：上位机控制系统

## 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": "2025-12-14 17:10:25",
  "Data": {
    "ScanMode": ""
  }
}
```

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

### 3.2 扫描响应（ScanResponse）

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

**消息格式：**
```json
{
  "MessageType": "ScanResponse",
  "Timestamp": "2025-12-14 17:10:25",
  "Data": {
    "Status": "Accepted"
  }
}
```

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

### 3.3 扫描结果（ScanResult）

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

**消息格式：**
```json
{
  "MessageType": "ScanResult",
  "Timestamp": "2025-12-14 17:10:26",
  "Data": {
    "WorkpieceType": 1,
    "1": {
      "P1": [100.50, 200.30, 50.20],
      "P2": [100.60, 250.40, 50.25],
      "P3": [100.70, 300.50, 50.30]
    },
    "2": {
      "P1": [150.80, 300.60, 50.35],
      "P2": [200.90, 300.70, 50.40],
      "P3": [250.10, 300.80, 50.45]
    },
    "3": {
      "P1": [250.20, 300.90, 50.50],
      "P2": [250.30, 250.10, 50.55],
      "P3": [250.40, 200.20, 50.60]
    },
    "4": {
      "P1": [250.50, 200.30, 50.65],
      "P2": [200.60, 200.40, 50.70],
      "P3": [150.70, 200.50, 50.75]
    },
    "Center": [175.50, 250.60, 50.80],
    "Lengths": {
      "len_A1": 123.45,
      "len_A2": 234.56,
      "len_B1": 345.67,
      "len_B2": 456.78
    }
  }
}
```

**Data字段说明：**

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| WorkpieceType | Integer | 是 | 工件类型：1/2/3/4等 |
| 1 | Object | 是 | 边1角点组（3个点） |
| 2 | Object | 是 | 边2角点组（3个点） |
| 3 | Object | 是 | 边3角点组（3个点） |
| 4 | Object | 是 | 边4角点组（3个点） |
| Center | Array | 是 | 工件中心点坐标 [x, y, z] |
| Lengths | Object | 是 | 四个方向的长度信息 |

**角点组格式：**
每个角点组（1/2/3/4）包含3个点，格式为：
```json
{
  "P1": [x, y, z],
  "P2": [x, y, z],
  "P3": [x, y, z]
}
```

**长度信息格式：**
```json
{
  "len_A1": 123.45,  // A1长度（从工件中心135度方向）
  "len_A2": 234.56,  // A2长度（从工件中心225度方向）
  "len_B1": 345.67,  // B1长度（从工件中心45度方向）
  "len_B2": 456.78   // B2长度（从工件中心315度方向）
}
```

**坐标说明：**
- 所有坐标均为机械臂坐标系下的3D坐标
- 单位：毫米（mm）
- 格式：[x, y, z]

### 3.4 错误响应（Error）

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

**消息格式：**
```json
{
  "MessageType": "Error",
  "Timestamp": "2025-12-14 17:10:25",
  "Data": {
    "ErrorCode": -3,
    "ErrorMessage": "未知消息类型: InvalidType"
  }
}
```

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

## 4. 通信流程

### 4.1 正常检测流程

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

### 4.2 错误处理流程

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


## 5. 注意事项

1. **连接管理**
   - 客户端应实现断线重连机制
   - 建议使用心跳机制保持连接活跃

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

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

4. **性能考虑**
   - 单次检测时间约为500ms-2s
   - 建议客户端设置合理的超时时间（建议10秒）