249 lines
6.3 KiB
Markdown
249 lines
6.3 KiB
Markdown
# 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秒）
|
||
|