YangOne/GrabBag
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
GrabBag/App/AutoLoading/Doc/TCP_PROTOCOL.md

481 lines
15 KiB
Markdown
Raw Normal View History

合并了编译脚本，并且根据脚本对项目一些宏做了调整
2026-04-10 20:02:57 +08:00
# 自动装车视觉检测系统 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毫秒时间戳 |
Reference in New Issue Copy Permalink