318 lines
8.4 KiB
Markdown
318 lines
8.4 KiB
Markdown
# 皮带撕裂检测系统 TCP 通信协议
|
||
|
||
## 版本
|
||
版本: 1.2
|
||
日期: 2025-11-30
|
||
|
||
---
|
||
### 版本历史
|
||
|
||
| 版本 | 日期 | 修改内容 | 作者 |
|
||
|------|------------|------------------|-------|
|
||
| 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..."
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 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-停止）|
|
||
|
||
---
|
||
|
||
## 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": "..." |
|
||
| } |
|
||
```
|
||
|
||
---
|
||
|
||
## 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秒尝试重连
|
||
- 最多重连次数: 无限制（或可配置）
|
||
|
||
|
||
---
|
||
|