# 自动装车视觉检测系统 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毫秒时间戳 |