481 lines
15 KiB
Markdown
481 lines
15 KiB
Markdown
# 自动装车视觉检测系统 TCP/IP 通信协议
|
||
|
||
**协议版本**: v1.0
|
||
**文档日期**: 2026-03-14
|
||
**维护单位**: 自动装车视觉检测系统开发组
|
||
|
||
## 1. 协议概述
|
||
|
||
### 1.1 通信方式
|
||
- **协议类型**: TCP/IP
|
||
- **数据格式**: JSON
|
||
- **编码方式**: UTF-8
|
||
- **端口**: 默认 6800（可配置）
|
||
- **连接模式**: 长连接，支持心跳保活
|
||
|
||
### 1.2 角色定义
|
||
- **服务端**: 视觉检测系统（本系统）
|
||
- **客户端**: 小车控制器
|
||
|
||
### 1.3 通信流程
|
||
```
|
||
客户端 服务端
|
||
| |
|
||
|-------- 建立TCP连接 ------------------->|
|
||
|<------- 连接确认 -----------------------|
|
||
| |
|
||
|-------- 发送检测请求（JSON）----------->|
|
||
| |
|
||
| 处理检测任务 |
|
||
| 执行视觉算法 |
|
||
| |
|
||
|<------- 返回检测结果（JSON）------------|
|
||
| |
|
||
|-------- 心跳包 ----------------------->|
|
||
|<------- 心跳响应 ----------------------|
|
||
| |
|
||
```
|
||
|
||
## 2. 消息格式定义
|
||
|
||
### 2.1 通用消息结构
|
||
|
||
所有消息均为JSON格式，包含以下基本字段：
|
||
|
||
```json
|
||
{
|
||
"msgType": "请求类型或响应类型",
|
||
"timestamp": "时间戳（毫秒）",
|
||
"seq": "请求序号",
|
||
"data": {
|
||
// 具体数据内容
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.2 字段说明
|
||
|
||
| 字段名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| msgType | string | 是 | 消息类型标识 |
|
||
| timestamp | long | 是 | 消息发送时间戳（Unix毫秒） |
|
||
| seq | int | 是 | 请求序号，从1开始递增，响应使用相同序号 |
|
||
| data | object | 是 | 消息数据体 |
|
||
|
||
## 3. 消息类型定义
|
||
|
||
### 3.1 消息类型枚举
|
||
|
||
| msgType | 说明 | 方向 |
|
||
|---------|------|------|
|
||
| HEARTBEAT_REQ | 心跳请求 | 客户端→服务端 |
|
||
| HEARTBEAT_RESP | 心跳响应 | 服务端→客户端 |
|
||
| TAIL_DETECT_REQ | 车尾检测请求 | 客户端→服务端 |
|
||
| TAIL_DETECT_RESP | 车尾检测响应 | 服务端→客户端 |
|
||
| MIDDLE_DETECT_REQ | 车厢中段检测请求 | 客户端→服务端 |
|
||
| MIDDLE_DETECT_RESP | 车厢中段检测响应 | 服务端→客户端 |
|
||
| ERROR_RESP | 错误响应 | 服务端→客户端 |
|
||
|
||
## 4. 完整检测流程
|
||
|
||
从车尾到车头的完整检测通信流程：
|
||
|
||
```
|
||
客户端（小车控制器） 服务端（视觉检测系统）
|
||
| |
|
||
|========== 1. 建立连接 ========================|
|
||
| |
|
||
|-------- HEARTBEAT_REQ (seq=1) -------------->|
|
||
|<------- HEARTBEAT_RESP (seq=1) --------------|
|
||
| |
|
||
|========== 2. 车尾入口检测 ====================|
|
||
| |
|
||
| 小车到达车尾入口 |
|
||
|-------- TAIL_DETECT_REQ (seq=2) ------------>|
|
||
| 处理检测 |
|
||
|<------- TAIL_DETECT_RESP (seq=2) -----------|
|
||
| 返回：偏移-15.5mm，角度2.3° |
|
||
| |
|
||
| 调整姿态，进入车厢 |
|
||
| |
|
||
|========== 3. 中段导航检测（循环）=============|
|
||
| |
|
||
| 前进1米 |
|
||
|-------- MIDDLE_DETECT_REQ (seq=3) --------->|
|
||
| forwardDistance=1000 |
|
||
| 处理检测 |
|
||
|<------- MIDDLE_DETECT_RESP (seq=3) ---------|
|
||
| 返回：偏移-8.2mm，角度1.5° |
|
||
| hasFrontWall=false |
|
||
| |
|
||
| 调整方向，继续前进1米 |
|
||
|-------- MIDDLE_DETECT_REQ (seq=4) --------->|
|
||
| forwardDistance=2000 |
|
||
| 处理检测 |
|
||
|<------- MIDDLE_DETECT_RESP (seq=4) ---------|
|
||
| 返回：偏移-5.0mm，角度0.8° |
|
||
| hasFrontWall=false |
|
||
| |
|
||
| 调整方向，继续前进1米 |
|
||
|-------- MIDDLE_DETECT_REQ (seq=5) --------->|
|
||
| forwardDistance=3000 |
|
||
| 处理检测 |
|
||
| 扫描到前端 |
|
||
|<------- MIDDLE_DETECT_RESP (seq=5) ---------|
|
||
| 返回：偏移-2.5mm，角度0.3° |
|
||
| hasFrontWall=true |
|
||
| frontDistance=2500mm |
|
||
| 车厢宽度=2400mm |
|
||
| 左右侧边界直线 |
|
||
| 左侧加强筋×2 |
|
||
| 右侧加强筋×2 |
|
||
| |
|
||
|========== 4. 获得完整车厢信息 ================|
|
||
| |
|
||
| 进行装载规划 |
|
||
| |
|
||
|-------- HEARTBEAT_REQ (seq=6) ------------->|
|
||
|<------- HEARTBEAT_RESP (seq=6) -------------|
|
||
| |
|
||
```
|
||
|
||
**流程说明**：
|
||
|
||
1. **建立连接**：客户端连接服务端，通过心跳确认通信正常
|
||
2. **车尾检测**：小车到达车尾入口，检测偏移和角度，调整后进入车厢
|
||
3. **中段导航**：小车在车厢内前进，每前进一定距离进行一次检测
|
||
- 未检测到前端时：只返回偏移、角度等导航数据
|
||
- 检测到前端时：返回完整车厢信息（边界、宽度、加强筋）
|
||
4. **完成检测**：获得完整车厢空间信息，进行装载规划
|
||
|
||
## 5. 心跳协议
|
||
|
||
### 5.1 心跳请求 (HEARTBEAT_REQ)
|
||
|
||
**客户端 → 服务端**
|
||
|
||
```json
|
||
{
|
||
"msgType": "HEARTBEAT_REQ",
|
||
"timestamp": 1678886400000,
|
||
"seq": 1,
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
### 5.2 心跳响应 (HEARTBEAT_RESP)
|
||
|
||
**服务端 → 客户端**
|
||
|
||
```json
|
||
{
|
||
"msgType": "HEARTBEAT_RESP",
|
||
"timestamp": 1678886400100,
|
||
"seq": 1,
|
||
"data": {
|
||
"status": "OK"
|
||
}
|
||
}
|
||
```
|
||
|
||
**说明**:
|
||
- 心跳间隔建议: 30秒
|
||
- 超时时间: 90秒（3个心跳周期）
|
||
- 超时后自动断开连接
|
||
|
||
## 6. 检测协议
|
||
|
||
### 6.1 阶段一：车尾检测
|
||
|
||
#### 6.1.1 车尾检测请求 (TAIL_DETECT_REQ)
|
||
|
||
**客户端 → 服务端**
|
||
|
||
```json
|
||
{
|
||
"msgType": "TAIL_DETECT_REQ",
|
||
"timestamp": 1678886400000,
|
||
"seq": 2,
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
#### 6.1.2 车尾检测响应 (TAIL_DETECT_RESP)
|
||
|
||
**服务端 → 客户端**
|
||
|
||
```json
|
||
{
|
||
"msgType": "TAIL_DETECT_RESP",
|
||
"timestamp": 1678886401500,
|
||
"seq": 2,
|
||
"data": {
|
||
"result": "SUCCESS",
|
||
"errorCode": 0,
|
||
"errorMsg": "",
|
||
"detectData": {
|
||
"lateralOffset": -15.5,
|
||
"offsetDirection": "LEFT",
|
||
"rotationAngle": 2.3
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应参数说明**:
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| result | string | 检测结果：SUCCESS-成功，FAILED-失败 |
|
||
| errorCode | int | 错误码，0表示成功 |
|
||
| errorMsg | string | 错误信息 |
|
||
| detectData | object | 检测数据对象 |
|
||
|
||
**detectData 字段说明**:
|
||
|
||
| 字段名 | 类型 | 单位 | 说明 |
|
||
|--------|------|------|------|
|
||
| lateralOffset | double | mm | 左右偏移距离，负值表示左偏，正值表示右偏 |
|
||
| offsetDirection | string | - | 偏移方向：LEFT-左偏，RIGHT-右偏，CENTER-居中 |
|
||
| rotationAngle | double | 度 | 偏转角度，逆时针为正，顺时针为负 |
|
||
|
||
### 6.2 阶段二：车厢中段检测
|
||
|
||
#### 6.2.1 车厢中段检测请求 (MIDDLE_DETECT_REQ)
|
||
|
||
**客户端 → 服务端**
|
||
|
||
```json
|
||
{
|
||
"msgType": "MIDDLE_DETECT_REQ",
|
||
"timestamp": 1678886410000,
|
||
"seq": 3,
|
||
"data": {
|
||
"forwardDistance": 1000.0
|
||
}
|
||
}
|
||
```
|
||
|
||
**请求参数说明**:
|
||
|
||
| 字段名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| forwardDistance | double | 是 | 前进距离（mm） |
|
||
|
||
#### 6.2.2 车厢中段检测响应 (MIDDLE_DETECT_RESP)
|
||
|
||
**服务端 → 客户端**
|
||
|
||
**情况1：未检测到车厢前端 (hasFrontWall=false)**
|
||
|
||
```json
|
||
{
|
||
"msgType": "MIDDLE_DETECT_RESP",
|
||
"timestamp": 1678886411500,
|
||
"seq": 3,
|
||
"data": {
|
||
"result": "SUCCESS",
|
||
"errorCode": 0,
|
||
"errorMsg": "",
|
||
"detectData": {
|
||
"lateralOffset": -8.2,
|
||
"offsetDirection": "LEFT",
|
||
"forwardAngle": 1.5,
|
||
"frontDistance": -1,
|
||
"hasFrontWall": false
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**情况2：检测到车厢前端 (hasFrontWall=true)**
|
||
|
||
```json
|
||
{
|
||
"msgType": "MIDDLE_DETECT_RESP",
|
||
"timestamp": 1678886411500,
|
||
"seq": 3,
|
||
"data": {
|
||
"result": "SUCCESS",
|
||
"errorCode": 0,
|
||
"errorMsg": "",
|
||
"detectData": {
|
||
"lateralOffset": -8.2,
|
||
"offsetDirection": "LEFT",
|
||
"forwardAngle": 1.5,
|
||
"frontDistance": 3500.0,
|
||
"hasFrontWall": true,
|
||
"leftSideLine": {
|
||
"startPoint": {"x": 0.0, "y": -1200.0, "z": 0.0},
|
||
"endPoint": {"x": 5000.0, "y": -1200.0, "z": 0.0}
|
||
},
|
||
"rightSideLine": {
|
||
"startPoint": {"x": 0.0, "y": 1200.0, "z": 0.0},
|
||
"endPoint": {"x": 5000.0, "y": 1200.0, "z": 0.0}
|
||
},
|
||
"compartmentWidth": 2400.0,
|
||
"leftRibs": [
|
||
{
|
||
"ribId": 1,
|
||
"distanceToFront": 1500.0,
|
||
"width": 120.0,
|
||
"height": 80.0
|
||
},
|
||
{
|
||
"ribId": 2,
|
||
"distanceToFront": 3000.0,
|
||
"width": 120.0,
|
||
"height": 80.0
|
||
}
|
||
],
|
||
"rightRibs": [
|
||
{
|
||
"ribId": 1,
|
||
"distanceToFront": 1500.0,
|
||
"width": 120.0,
|
||
"height": 80.0
|
||
},
|
||
{
|
||
"ribId": 2,
|
||
"distanceToFront": 3000.0,
|
||
"width": 120.0,
|
||
"height": 80.0
|
||
}
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**detectData 字段说明**:
|
||
|
||
| 字段名 | 类型 | 单位 | 说明 |
|
||
|--------|------|------|------|
|
||
| lateralOffset | double | mm | 左右偏移距离 |
|
||
| offsetDirection | string | - | 偏移方向：LEFT-左偏，RIGHT-右偏，CENTER-居中 |
|
||
| forwardAngle | double | 度 | 前进方向角，相对于车厢中心线 |
|
||
| frontDistance | double | mm | 到车厢前端的距离，-1表示未检测到 |
|
||
| hasFrontWall | bool | - | 是否检测到车厢前端 |
|
||
| leftSideLine | object | - | 左侧车厢直线（仅hasFrontWall=true时有效） |
|
||
| rightSideLine | object | - | 右侧车厢直线（仅hasFrontWall=true时有效） |
|
||
| compartmentWidth | double | mm | 车厢宽度（仅hasFrontWall=true时有效） |
|
||
| leftRibs | array | - | 左侧加强筋数组（仅hasFrontWall=true时有效） |
|
||
| rightRibs | array | - | 右侧加强筋数组（仅hasFrontWall=true时有效） |
|
||
|
||
**侧边线对象 (SideLine)**:
|
||
|
||
| 字段名 | 类型 | 单位 | 说明 |
|
||
|--------|------|------|------|
|
||
| startPoint | object | mm | 起点坐标 {x, y, z} |
|
||
| endPoint | object | mm | 终点坐标 {x, y, z} |
|
||
|
||
**加强筋对象 (ReinforcementRib)**:
|
||
|
||
| 字段名 | 类型 | 单位 | 说明 |
|
||
|--------|------|------|------|
|
||
| ribId | int | - | 加强筋编号 |
|
||
| distanceToFront | double | mm | 距离车厢前端的距离 |
|
||
| width | double | mm | 加强筋宽度 |
|
||
| height | double | mm | 凸起高度 |
|
||
|
||
## 7. 错误响应
|
||
|
||
### 7.1 错误响应格式 (ERROR_RESP)
|
||
|
||
**服务端 → 客户端**
|
||
|
||
```json
|
||
{
|
||
"msgType": "ERROR_RESP",
|
||
"timestamp": 1678886401000,
|
||
"seq": 2,
|
||
"data": {
|
||
"errorCode": 1001,
|
||
"errorMsg": "相机连接失败",
|
||
"errorDetail": "Camera device not found: Camera-01"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7.2 错误码定义
|
||
|
||
| 错误码 | 错误类型 | 说明 |
|
||
|--------|----------|------|
|
||
| 0 | SUCCESS | 成功 |
|
||
| 1001 | CAMERA_ERROR | 相机错误 |
|
||
| 1002 | ALGORITHM_ERROR | 算法处理错误 |
|
||
| 1003 | TIMEOUT_ERROR | 检测超时 |
|
||
| 1004 | INVALID_REQUEST | 无效请求 |
|
||
| 1005 | SYSTEM_BUSY | 系统繁忙 |
|
||
| 1006 | CALIBRATION_ERROR | 标定数据错误 |
|
||
| 1007 | DATA_PARSE_ERROR | 数据解析错误 |
|
||
| 1008 | NETWORK_ERROR | 网络通信错误 |
|
||
| 1009 | DETECTION_FAILED | 检测失败（未检测到目标） |
|
||
| 1010 | LOW_CONFIDENCE | 置信度过低 |
|
||
| 9999 | UNKNOWN_ERROR | 未知错误 |
|
||
|
||
## 8. 坐标系定义
|
||
|
||
### 8.1 世界坐标系
|
||
|
||
- **原点**: 车厢尾部中心点
|
||
- **X轴**: 车厢长度方向，指向车头为正
|
||
- **Y轴**: 车厢宽度方向，指向右侧为正
|
||
- **Z轴**: 车厢高度方向，向上为正
|
||
- **单位**: 毫米 (mm)
|
||
|
||
### 8.2 角度定义
|
||
|
||
- **偏转角 (rotationAngle)**: 小车相对于车厢中心线的旋转角度
|
||
- 逆时针旋转为正
|
||
- 顺时针旋转为负
|
||
- 范围: [-180°, 180°]
|
||
|
||
- **前进方向角 (forwardAngle)**: 小车前进方向相对于车厢中心线的夹角
|
||
- 向右偏为正
|
||
- 向左偏为负
|
||
- 范围: [-90°, 90°]
|
||
|
||
## 9. 通信约定
|
||
|
||
### 9.1 连接管理
|
||
|
||
1. **连接建立**: 客户端主动连接服务端
|
||
2. **连接保持**: 通过心跳机制保持连接
|
||
3. **断线重连**: 客户端负责断线重连，重连间隔建议5秒
|
||
4. **连接超时**: 90秒无心跳自动断开
|
||
|
||
### 9.2 消息发送
|
||
|
||
1. **消息编码**: UTF-8
|
||
2. **消息分隔**: 每条JSON消息以换行符 `\n` 结尾
|
||
3. **消息大小**: 单条消息不超过 10MB
|
||
4. **消息顺序**: 保证请求-响应的顺序性
|
||
|
||
### 9.3 超时设置
|
||
|
||
| 操作类型 | 超时时间 | 说明 |
|
||
|----------|----------|------|
|
||
| 连接超时 | 10秒 | TCP连接建立超时 |
|
||
| 心跳超时 | 90秒 | 3个心跳周期 |
|
||
| 车尾检测 | 30秒 | 单次检测超时 |
|
||
| 中段检测 | 30秒 | 单次检测超时 |
|
||
| 前端检测 | 60秒 | 全扫描检测超时 |
|
||
|
||
### 9.4 并发控制
|
||
|
||
1. **单连接模式**: 每个客户端只能建立一个TCP连接
|
||
2. **串行处理**: 同一连接的检测请求串行处理
|
||
3. **队列机制**: 多个请求进入队列等待处理
|
||
4. **最大队列**: 队列最大长度为10，超出返回系统繁忙错误
|
||
|
||
## 10. 数据精度要求
|
||
|
||
| 数据类型 | 精度 | 说明 |
|
||
|----------|------|------|
|
||
| 位置坐标 | 0.1mm | 小数点后1位 |
|
||
| 偏移距离 | 0.1mm | 小数点后1位 |
|
||
| 角度 | 0.1° | 小数点后1位 |
|
||
| 置信度 | 0.01 | 小数点后2位 |
|
||
| 时间戳 | 1ms | Unix毫秒时间戳 |
|