GrabBag/App/BeltTearing/Doc/撕裂TCP通信协议.md

# 皮带撕裂检测系统 TCP 通信协议

## 版本
版本: 1.3
日期: 2026-02-12

---
### 版本历史

| 版本 | 日期       | 修改内容         | 作者  |
|------|------------|------------------|-------|
| 1.3  | 2026-02-12 | 增加实时传输检测结果功能(SET_REALTIME/REALTIME_RESULT) |  |
| 1.2  | 2025-11-30 | 增加最大撕裂ID字段(maxId) |  |
| 1.1  | 2025-11-16 | 修改协议长度的格式 |  |
| 1.0  | 2025-11-11 | 初始版本         |  |

---

## 1. 协议概述

本协议用于皮带撕裂检测系统的TCP通信，支持撕裂检测结果上报、实时传输检测结果、速度设置、启停控制等功能。

### 1.1 连接参数

- **服务器端**：视觉检测器（皮带撕裂检测系统）
- **客户端**：上位机或其他控制系统
- 服务器默认监听端口: **5800** (可配置)
- 客户端主动连接服务器
- 支持多客户端连接

### 1.2 协议特点

- 基于TCP长连接
- JSON格式数据传输
- 消息头+消息体结构，解决TCP粘包问题
- 支持命令应答机制
- UTF-8编码

---

## 2. 数据帧格式

为解决TCP粘包问题，采用**固定消息头+变长消息体**的帧格式：

```
+----------+------------+----------+----------+
| 帧头(8B) | 长度(8B)   | 数据体   | 帧尾(4B) |
+----------+------------+----------+----------+
```

### 2.1 帧结构说明

| 字段     | 字节数 | 类型          | 说明                                    |
|----------|--------|---------------|----------------------------------------|
| 帧头     | 8      | char[8]       | 固定字符串 `##START#`                   |
| 长度     | 8      | char[8]       | 数据体长度（8位字符串），单位：字节     |
| 数据体   | 可变   | JSON字符串    | UTF-8编码的JSON数据                    |
| 帧尾     | 4      | char[4]       | 固定字符串 `#END`                       |

### 2.2 帧头帧尾定义

```cpp
#define FRAME_HEADER    "##START#"    // 8字节帧头
#define FRAME_TAIL      "#END"         // 4字节帧尾
```

---

## 3. 消息类型

所有消息的JSON数据体都包含以下公共字段：

```json
{
    "msgType": "消息类型",
    "timestamp": 1699776000000
}
```

| 字段       | 类型    | 说明                          |
|------------|---------|------------------------------|
| msgType    | string  | 消息类型标识                  |
| timestamp  | int64   | 时间戳（毫秒级Unix时间戳）     |

---

## 4. 上报消息（服务器 → 客户端）

### 4.1 撕裂检测结果上报

**消息类型**: `DETECT_RESULT`

**JSON格式**:
```json
{
    "msgType": "DETECT_RESULT",
    "timestamp": 1699776000000,
    "count": 3,
    "max": 125,
    "maxId": 12345,
    "visimg": "iVBORw0KGgoAAAANSUhEUgAAAAUA..."
}
```

**字段说明**:

| 字段      | 类型   | 必填 | 说明                                      |
|-----------|--------|------|------------------------------------------|
| msgType   | string | 是   | 固定值 `DETECT_RESULT`                     |
| timestamp | int64  | 是   | 检测时间戳（毫秒）                        |
| count     | int    | 是   | 撕裂个数                                 |
| max       | int    | 是   | 最大撕裂长度（单位：毫米）                |
| maxId     | int    | 是   | 最大撕裂对应的撕裂ID（唯一标识符）        |
| visimg    | string | 是   | Base64编码的检测结果图片（JPEG格式）      |

**示例**:
```json
{
    "msgType": "DETECT_RESULT",
    "timestamp": 1699776000000,
    "count": 2,
    "max": 85,
    "maxId": 10086,
    "visimg": "/9j/4AAQSkZJRgABAQEAYABgAAD..."
}
```

---

### 4.2 实时检测结果上报

当客户端开启实时传输功能后，服务器在每次检测完成时主动上报检测结果，包含所有撕裂的详细数据。

**消息类型**: `REALTIME_RESULT`

**JSON格式**:
```json
{
    "msgType": "REALTIME_RESULT",
    "timestamp": 1699776000000,
    "count": 3,
    "tears": [
        {
            "id": 10001,
            "status": 1,
            "length": 125,
            "width": 30,
            "depth": 8
        },
        {
            "id": 10002,
            "status": 0,
            "length": 85,
            "width": 20,
            "depth": 5
        },
        {
            "id": 10003,
            "status": 1,
            "length": 42,
            "width": 15,
            "depth": 3
        }
    ],
    "visimg": "iVBORw0KGgoAAAANSUhEUgAAAAUA..."
}
```

**字段说明**:

| 字段      | 类型   | 必填 | 说明                                      |
|-----------|--------|------|------------------------------------------|
| msgType   | string | 是   | 固定值 `REALTIME_RESULT`                   |
| timestamp | int64  | 是   | 检测时间戳（毫秒）                        |
| count     | int    | 是   | 撕裂个数                                 |
| tears     | array  | 是   | 撕裂详细数据列表，元素个数与 count 一致    |
| visimg    | string | 是   | Base64编码的检测结果图片（JPEG格式）      |

**tears 数组元素字段说明**:

| 字段      | 类型   | 必填 | 说明                                      |
|-----------|--------|------|------------------------------------------|
| id        | int    | 是   | 撕裂ID（唯一标识符）                      |
| status    | int    | 是   | 撕裂状态（0-未知，1-新发现，2-正在增长，3-已结束，4-无效） |
| length    | int    | 是   | 撕裂长度（单位：毫米）                    |
| width     | int    | 是   | 撕裂宽度（单位：毫米）                    |
| depth     | int    | 是   | 撕裂深度（单位：毫米，-1表示贯穿型撕裂）   |

**status 状态值定义**（对应 `ESG_tearStatus`）:

| 值 | 枚举名                      | 说明           |
|----|------------------------------|----------------|
| 0  | keSG_tearStatus_Uknown       | 未知           |
| 1  | keSG_tearStatus_New           | 新发现的撕裂   |
| 2  | keSG_tearStatus_Growing       | 正在增长的撕裂 |
| 3  | keSG_tearStatus_Ended         | 撕裂已结束     |
| 4  | keSG_tearStatus_Invalid       | 无效撕裂（可能被合并） |

**说明**:
- 实时传输功能需要客户端通过 `SET_REALTIME` 命令开启
- 开启后，服务器每次完成一帧检测即上报一次结果
- 关闭实时传输后，服务器停止上报 `REALTIME_RESULT` 消息
- `REALTIME_RESULT` 与 `DETECT_RESULT` 独立，互不影响
- 当 count 为 0 时，tears 为空数组 `[]`

**示例**（无撕裂时）:
```json
{
    "msgType": "REALTIME_RESULT",
    "timestamp": 1699776000000,
    "count": 0,
    "tears": [],
    "visimg": "/9j/4AAQSkZJRgABAQEAYABgAAD..."
}
```

---

## 5. 控制命令（客户端 → 服务器）

### 5.1 设置速度命令

**消息类型**: `SET_SPEED`

**JSON格式**:
```json
{
    "msgType": "SET_SPEED",
    "timestamp": 1699776000000,
    "speed": 1000
}
```

**字段说明**:

| 字段      | 类型   | 必填 | 说明                          |
|-----------|--------|------|------------------------------|
| msgType   | string | 是   | 固定值 `SET_SPEED`            |
| timestamp | int64  | 是   | 命令时间戳（毫秒）             |
| speed     | int    | 是   | 速度值（单位：mm/s，范围：0-5000） |

---

### 5.2 启停控制命令

**消息类型**: `SET_CONTROL`

**JSON格式**:
```json
{
    "msgType": "SET_CONTROL",
    "timestamp": 1699776000000,
    "control": true
}
```

**字段说明**:

| 字段      | 类型   | 必填 | 说明                          |
|-----------|--------|------|------------------------------|
| msgType   | string | 是   | 固定值 `SET_CONTROL`          |
| timestamp | int64  | 是   | 命令时间戳（毫秒）             |
| control   | bool   | 是   | 启停状态（true-启动，false-停止）|

---

### 5.3 实时传输控制命令

**消息类型**: `SET_REALTIME`

**JSON格式**:
```json
{
    "msgType": "SET_REALTIME",
    "timestamp": 1699776000000,
    "enable": true
}
```

**字段说明**:

| 字段      | 类型   | 必填 | 说明                                  |
|-----------|--------|------|--------------------------------------|
| msgType   | string | 是   | 固定值 `SET_REALTIME`                 |
| timestamp | int64  | 是   | 命令时间戳（毫秒）                     |
| enable    | bool   | 是   | 实时传输开关（true-开启，false-关闭）   |

**说明**:
- 开启后，服务器每次检测完成即通过 `REALTIME_RESULT` 消息上报结果
- 关闭后，服务器停止实时上报
- 默认状态为关闭
- 服务器通过 `CMD_RESPONSE` 应答该命令

---

## 6. 应答消息（服务器 → 客户端）

所有控制命令都需要应答，应答格式统一。

### 6.1 命令应答格式

**消息类型**: `CMD_RESPONSE`

**JSON格式**:
```json
{
    "msgType": "CMD_RESPONSE",
    "timestamp": 1699776000000,
    "cmdType": "SET_SPEED",
    "result": true,
    "errorCode": 0,
    "errorMsg": ""
}
```

**字段说明**:

| 字段       | 类型   | 必填 | 说明                               |
|------------|--------|------|------------------------------------|
| msgType    | string | 是   | 固定值 `CMD_RESPONSE`              |
| timestamp  | int64  | 是   | 应答时间戳（毫秒）                  |
| cmdType    | string | 是   | 原始命令类型（如 `SET_SPEED`）      |
| result     | bool   | 是   | 执行结果（true-成功，false-失败）   |
| errorCode  | int    | 是   | 错误码（成功时为0）                 |
| errorMsg   | string | 是   | 错误描述（成功时为空字符串）         |

---

## 7. 通信流程

### 7.1 速度设置流程

```
客户端                           服务器
  |                                |
  |-------- SET_SPEED ----------->|
  |  {                             |
  |    "msgType": "SET_SPEED",     |
  |    "speed": 1000               |
  |  }                             |
  |                                |
  |<------ CMD_RESPONSE ----------|
  |  {                             |
  |    "cmdType": "SET_SPEED",     |
  |    "result": true,             |
  |    "errorCode": 0              |
  |  }                             |
```

### 7.2 启停控制流程

```
客户端                           服务器
  |                                |
  |------- SET_CONTROL ---------->|
  |  {                             |
  |    "msgType": "SET_CONTROL",   |
  |    "control": true             |
  |  }                             |
  |                                |
  |<------ CMD_RESPONSE ----------|
  |  {                             |
  |    "cmdType": "SET_CONTROL",   |
  |    "result": true,             |
  |    "errorCode": 0              |
  |  }                             |
  |                                |
  |<------ TEAR_RESULT -----------|  (周期性上报)
  |  {                             |
  |    "count": 2,                 |
  |    "max": 85,                  |
  |    "visimg": "..."             |
  |  }                             |
```

### 7.3 实时传输控制流程

```
客户端                           服务器
  |                                |
  |------ SET_REALTIME ---------->|
  |  {                             |
  |    "msgType": "SET_REALTIME",  |
  |    "enable": true              |
  |  }                             |
  |                                |
  |<------ CMD_RESPONSE ----------|
  |  {                             |
  |    "cmdType": "SET_REALTIME",  |
  |    "result": true,             |
  |    "errorCode": 0              |
  |  }                             |
  |                                |
  |<--- REALTIME_RESULT ----------|  (每次检测完成即上报)
  |  {                             |
  |    "msgType": "REALTIME_RESULT"|
  |    "count": 2,                 |
  |    "tears": [                  |
  |      {"id":1,"status":1,       |
  |       "length":85,"width":20,  |
  |       "depth":5},              |
  |      {"id":2,"status":0,       |
  |       "length":42,"width":15,  |
  |       "depth":3}               |
  |    ],                          |
  |    "visimg": "..."             |
  |  }                             |
  |                                |
  |<--- REALTIME_RESULT ----------|  (持续上报...)
  |  { ... }                       |
  |                                |
  |------ SET_REALTIME ---------->|  (关闭实时传输)
  |  {                             |
  |    "msgType": "SET_REALTIME",  |
  |    "enable": false             |
  |  }                             |
  |                                |
  |<------ CMD_RESPONSE ----------|
  |  {                             |
  |    "cmdType": "SET_REALTIME",  |
  |    "result": true,             |
  |    "errorCode": 0              |
  |  }                             |
  |                                |
  |    (服务器停止上报)              |
```

---

## 8. TCP粘包处理

### 8.1 发送端处理

1. 将JSON数据转换为UTF-8字节数组
2. 计算数据长度（字节数）
3. 构造完整数据帧：
   ```
   帧头(8字节 "##START#") + 长度(8字节字符串) + JSON数据 + 帧尾(4字节 "#END")
   ```
4. 发送完整数据帧

### 8.2 接收端处理

1. 维护接收缓冲区
2. 查找帧头（字符串 `##START#`）
3. 读取数据长度（8字节字符串）
4. 根据长度读取完整数据体
5. 验证帧尾（字符串 `#END`）
6. 解析JSON数据
7. 处理剩余缓冲区数据（可能包含下一帧）

---

## 9. 连接管理

### 9.1 心跳机制

为保持连接活跃，建议实现心跳机制：

**心跳消息**: `HEARTBEAT`

```json
{
    "msgType": "HEARTBEAT",
    "timestamp": 1699776000000
}
```

**心跳应答**: `HEARTBEAT_ACK`

```json
{
    "msgType": "HEARTBEAT_ACK",
    "timestamp": 1699776000000
}
```

- 心跳间隔: 30秒
- 超时时间: 90秒（3次心跳未收到则断开）

### 9.2 断线重连

- 客户端检测到连接断开后，每隔5秒尝试重连
- 最多重连次数: 无限制（或可配置）


---