YangOne/GrabBag

Fork 0

YangSn 457b98ac89 feat:BeltTearing:更新算法(增加了焊缝最小，最大宽度; 最大深度参数)

2026-10-25 17:58:57 +08:00

36 KiB

Raw Blame History

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

版本

版本: 2.1 日期: 2026-10-24

版本历史

版本	日期	修改内容
2.1	2026-10-24	增加算法深度/宽度参数和算法版本，`cameraConfig` 仅保留相机IP；明确TCP配置不提供监听端口读写
1.6	2026-08-10	增加激光线点云二进制实时发送，以及可配置的抽线、抽点功能；算法和成像仍使用完整点云； DETECT_RESULT 始终开启但仅在历史汇总变化时广播；REALTIME_RESULT 由 SET_REALTIME 单独开启
1.5	2026-08-05	增加协议版本字段、完整报警数据、报警复位、重新检测、配置读写和协议能力查询保留1.4字段兼容旧客户端
1.4	2026-02-21	增加CMD汇总表格（实时消息关系以1.6定义为准）
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；监听端口由服务端本地配置管理，不属于本TCP协议的可读写配置字段
客户端主动连接服务器
支持多客户端连接

1.2 协议特点

基于TCP长连接
控制和检测结果使用JSON，激光线点云使用二进制负载
消息头+消息体结构，解决TCP粘包问题
支持命令应答机制
UTF-8编码

1.3 CMD 汇总表

msgType	方向	说明	详细章节
`DETECT_RESULT`	服务器 → 客户端	基础撕裂检测结果上报（历史最大值）结果发生变化时发送给所有客户端	4.1
`REALTIME_RESULT`	服务器 → 客户端	实时检测结果上报（所有撕裂详细数据）仅发送给已开启实时传输的客户端	4.2
`SET_SPEED`	客户端 → 服务器	设置皮带速度（mm/s）	5.1
`SET_CONTROL`	客户端 → 服务器	启动/停止检测	5.2
`SET_REALTIME`	客户端 → 服务器	开启/关闭实时传输	5.3
`RESET_ALARM`	客户端 → 服务器	清除当前报警状态，不重连相机	10.1
`REST_DETECT`	客户端 → 服务器	重新进行检测，与 App 的重置功能一致	10.1
`GET_CONFIG`	客户端 → 服务器	读取当前可调配置	10.2
`SET_CONFIG`	客户端 → 服务器	部分更新并持久化配置	10.2
`GET_PROTOCOL_INFO`	客户端 → 服务器	查询协议版本和能力	10.3
`CONFIG_RESPONSE`	服务器 → 客户端	配置读取或写入成功应答	6.2
`PROTOCOL_INFO`	服务器 → 客户端	协议能力应答	6.3
`CMD_RESPONSE`	服务器 → 客户端	控制命令的统一应答	6.1
`HEARTBEAT`	客户端 → 服务器	心跳消息	9.1
`HEARTBEAT_ACK`	服务器 → 客户端	心跳应答	9.1

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 帧头帧尾定义

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

3. 消息类型

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

{
    "msgType": "消息类型",
    "protocolVersion": "2.1",
    "timestamp": 1699776000000
}

字段	类型	说明
msgType	string	消息类型标识
protocolVersion	string	协议版本；服务器所有输出固定携带 `2.1`
timestamp	int64	时间戳（毫秒级Unix时间戳）

客户端请求建议携带 protocolVersion。未携带或为空时仍接受旧客户端请求；显式携带版本时，必须与服务端主版本相同且不低于 2.1，否则服务器返回错误码1001。

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

4.1 撕裂检测结果上报

消息类型: DETECT_RESULT

服务器始终开启本消息上报逻辑，向所有已连接客户端发送；不受 SET_REALTIME 状态影响。服务端在每次检测任务完成后，处理本批次算法返回的撕裂结果，再更新历史汇总并判断是否发送。

本消息上报算法返回的撕裂结果；服务端不再按宽度或深度阈值做二次过滤。tears[].status 使用算法返回的状态值，不因撕裂是否已经结束而改写。算法返回“新发现”（status=1）、“正在增长”（status=2）或“已结束”（status=3）等状态时，均可能出现在上报数据中。报警确认状态只影响报警输出及 alarm 标志，不从检测结果列表中移除撕裂。

上报时机与历史保留规则：

算法返回的撕裂结果会进入历史汇总；当历史汇总发生变化时，发送 DETECT_RESULT。
同一 ID 的长度、宽度、深度或状态发生变化，且该记录仍保留在历史汇总的前5条内时，会触发发送；例如 status 从 2（正在增长）变为 3（已结束），即使长度不变也会发送。未进入保留的前5条且未改变历史最大值时，不保证为其单独发包。
去重依据为 count、maxLength、maxWidth、maxId 和完整的 tears 数组；只有时间戳、图片或 alarm 变化不会触发发送。结果不变时不周期性重复发送。
tears 不是当前帧仍在撕裂的列表，而是自最近一次历史清空以来累计的结果；按 ID 更新记录，再按长度降序、同长度按 ID 升序最多保留5条。撕裂结束或从当前检测结果中消失，不会自动删除历史记录，因此此时 count 不一定归零。
历史为空且尚未成功上报过结果时，不主动发送空结果包；开始检测、RESET_ALARM、成功的 REST_DETECT 会清空历史及去重状态，但清空动作本身不主动广播 count=0。后续检测再次产生有效结果后才重新上报。
客户端若只需要已结束的结果，应检查 tears[].status == 3；不能把收到任意 DETECT_RESULT 当作撕裂已结束。

JSON格式:

{
    "msgType": "DETECT_RESULT",
    "protocolVersion": "2.1",
    "timestamp": 1699776000000,
    "alarm": true,
    "count": 1,
    "max": 125,
    "maxLength": 125,
    "maxWidth": 30,
    "maxId": 12345,
    "tears": [
        {"id":12345,"status":2,"length":125,"width":30,"depth":8}
    ],
    "visimg": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
}

字段说明:

字段	类型	必填	说明
msgType	string	是	固定值 `DETECT_RESULT`
timestamp	int64	是	检测时间戳（毫秒）
protocolVersion	string	是	当前协议版本 `2.1`
alarm	bool	是	本次检测是否需要报警；`true` 表示本次结果中至少有一个有效撕裂未被最近一次 `RESET_ALARM` 清除报警状态，`false` 表示没有有效撕裂或当前有效撕裂均已在最近一次 `RESET_ALARM` 中清除报警状态；不表示撕裂是否结束
count	int	是	本次历史汇总保留的撕裂条数，等于 `tears.length`，最多5条；不是当前正在撕裂的个数
max	int	是	历史最大X方向长度，兼容1.4客户端
maxLength	int	是	历史最大X方向长度（毫米）
maxWidth	int	是	历史最大长度对应撕裂的Y方向宽度（毫米）
maxId	int	是	最大撕裂对应的撕裂ID（唯一标识符）
tears	array	是	最近一次历史清空以来累计的撕裂结果，包含进行中和已结束的记录；最多保留长度最大的5条，字段同4.2
visimg	string	是	JPEG图片的Data URI；无图像时为空字符串

示例:

{
    "msgType": "DETECT_RESULT",
    "timestamp": 1699776000000,
    "count": 2,
    "max": 85,
    "maxId": 10086,
    "visimg": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
}

4.2 实时检测结果上报

当客户端通过 SET_REALTIME 开启实时传输后，服务器在每次检测任务完成时主动上报本批次算法返回的撕裂结果，包含撕裂详细数据；服务端不再按宽度或深度阈值二次过滤。tears[].status 使用算法返回的状态值，可能为“新发现”（status=1）、“正在增长”（status=2）或“已结束”（status=3）等。报警确认状态不会从该列表移除撕裂。该消息只发给已开启实时传输的客户端，与4.1的历史汇总上报不同。

消息类型: REALTIME_RESULT JSON格式:

{
    "msgType": "REALTIME_RESULT",
    "protocolVersion": "2.1",
    "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
        }
    ],
    "visimg": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
}

字段说明:

字段	类型	必填	说明
msgType	string	是	固定值 `REALTIME_RESULT`
protocolVersion	string	是	当前协议版本 `2.1`
timestamp	int64	是	检测时间戳（毫秒）
count	int	是	撕裂个数
tears	array	是	撕裂详细数据列表，元素个数与 count 一致
visimg	string	是	JPEG图片的Data URI；无图像时为空字符串

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 消息
DETECT_RESULT 始终开启上报逻辑，但仅在撕裂信息或汇总值变化时发送；开启实时传输的客户端会在此基础上额外收到 REALTIME_RESULT
当 count 为 0 时，tears 为空数组 []

示例（无撕裂时）:

{
    "msgType": "REALTIME_RESULT",
    "protocolVersion": "2.1",
    "timestamp": 1699776000000,
    "count": 0,
    "tears": [],
    "visimg": "/9j/4AAQSkZJRgABAQEAYABgAAD..."
}

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

5.1 设置速度命令

消息类型: SET_SPEED

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格式:

{
    "msgType": "SET_CONTROL",
    "timestamp": 1699776000000,
    "control": true
}

字段说明:

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

5.3 实时传输控制命令

消息类型: SET_REALTIME

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格式:

{
    "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              |
  |  }                             |
  |                                |
  |<--- DETECT_RESULT -------------|  (基础结果始终上报)
  |  { ... }                       |
  |                                |
  |<--- 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              |
  |  }                             |
  |                                |
  |    (仅停止 REALTIME_RESULT，     |
  |     DETECT_RESULT 继续上报)      |

8. TCP粘包处理

8.1 发送端处理

将JSON数据转换为UTF-8字节数组
计算数据长度（字节数）

构造完整数据帧：

帧头(8字节 "##START#") + 长度(8字节字符串) + JSON数据 + 帧尾(4字节 "#END")

发送完整数据帧

8.2 接收端处理

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

9. 连接管理

9.1 心跳机制

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

心跳消息: HEARTBEAT

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

心跳应答: HEARTBEAT_ACK

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

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

9.2 断线重连

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

10. 2.1 增强命令

本节按 BeltTearingServer 的请求解析、配置读写、检测及应答逻辑说明。JSON 仍使用第2章的帧格式；以下示例中的配置值仅用于展示字段，不代表默认值。

请求公共字段：

字段	类型	必填	说明
msgType	string	是	命令类型，取本节对应的固定字符串；`REST_DETECT` 为实际命令拼写，不是 `RESET_DETECT`
protocolVersion	string	否	客户端协议版本，建议传 `2.1`；未传或为空时按旧客户端兼容处理，显式传入不兼容版本时返回错误码1001
timestamp	int64	否	客户端发送时间，毫秒级 Unix 时间戳；本节命令不使用此字段决定执行时机，响应时间由服务器重新生成
requestId	string	否	配置读写请求的关联标识，仅 `GET_CONFIG`、`SET_CONFIG` 成功返回的 `CONFIG_RESPONSE` 原样回传；未传时返回空字符串，不用于命令去重

10.1 报警复位与重新检测

报警复位请求：

{"msgType":"RESET_ALARM","protocolVersion":"2.1","timestamp":1699776000000}

RESET_ALARM 无额外业务字段，不需要传撕裂 ID。该命令是对当前报警状态的整体清除，不是确认某个撕裂，也不表示撕裂已经结束或物理故障已经处理完成。复位时刻当前结果中的撕裂，如果在后续检测中持续存在，不会重复触发 alarm=true；如果某个撕裂不再出现在后续结果中，服务端会移除对应的报警抑制记录，之后同一撕裂再次出现时可以重新触发报警。撕裂是否结束仍以算法返回的 tears[].status 为准，status=3 才表示“已结束”。命令同时清空 TCP 历史最大值、历史撕裂列表、发送去重状态及 Modbus 报警数据。

此命令不停止相机、不重连相机、不清空点云队列或算法缓存，也不把撕裂改为“已结束”。复位时刻已存在的撕裂仍会出现在实时结果和图像中，后续检测也可重新填入 DETECT_RESULT.tears，但在持续存在期间不会因此再次触发 alarm=true。复位本身不主动发送空的 DETECT_RESULT，不能依靠收到 count=0 判断复位是否成功，应以命令应答为准。

重新检测请求：

{"msgType":"REST_DETECT","protocolVersion":"2.1","timestamp":1699776000000}

REST_DETECT 无额外业务字段。服务端要求相机设备已初始化；若当前正在检测，先停止检测流，再清空旧点云队列、激光线计数、点云发送抽线计数及算法结果缓存，重新启动检测流。成功后执行与 RESET_ALARM 相同的报警清理；不会关闭或重新打开相机设备。相机未初始化、停止检测失败或重新启动检测失败时，返回相应错误码，不执行后续成功路径的报警清理。

两个命令的应答（示例为报警复位成功）：

{
  "msgType":"CMD_RESPONSE",
  "protocolVersion":"2.1",
  "timestamp":1699776000000,
  "cmdType":"RESET_ALARM",
  "result":true,
  "errorCode":0,
  "errorMsg":""
}

字段	类型	说明
msgType	string	固定值 `CMD_RESPONSE`
protocolVersion	string	服务端协议版本，当前为 `2.1`
timestamp	int64	服务器生成应答的时间，毫秒级 Unix 时间戳
cmdType	string	原请求命令，`RESET_ALARM` 或 `REST_DETECT`
result	bool	`true` 表示命令执行成功，`false` 表示失败
errorCode	int	成功为0；未注册命令回调为2；重新检测还可能返回相机设备接口的错误码
errorMsg	string	成功为空字符串；失败为错误描述

上述应答不回传 requestId，也不包含复位后的撕裂列表。

10.2 配置读取与部分更新

读取请求：无额外业务字段，返回服务端当前内存中的对外配置，不是直接回读配置文件。

{"msgType":"GET_CONFIG","protocolVersion":"2.1","requestId":"cfg-1"}

写入请求：config 必须为 JSON 对象；可只提交需要修改的配置组和字段。

以下字段与 BeltTearingApp 参数页面当前发送的字段一致。该页面当前通过旧协议 WriteConfig 的 setAlgorithmParams 命令发送；使用本文 SET_CONFIG 时，将同样的字段放入对应配置分组即可。

{
  "msgType":"SET_CONFIG",
  "protocolVersion":"2.1",
  "requestId":"cfg-2",
  "config":{
    "algorithmParams":{"scanXScale":1.0,"scanYScale":1.0,"differnceBinTh":1.0,"tearingMinLen":5.0,"tearingMinGap":2.0,"tearingMinDepth":2.0,"tearingMinYWidth":2.0,"tearingMaxYWidth":150.0,"sameGapTh":2.0,"gapChkWin":5},
    "cameraConfig":{"cameraIP":"192.168.1.100"},
    "queueProcessParam":{"maxQueueSize":300,"generationInterval":100,"imageLineCount":300},
    "pointCloudSendParam":{"enabled":true,"lineStep":5,"pointStep":4}
  }
}

成功应答示例：GET_CONFIG 和 SET_CONFIG 成功时均返回当前配置。算法版本只读，位于 config.algorithmVersion；监听端口不属于该配置对象。

{
  "msgType":"CONFIG_RESPONSE",
  "protocolVersion":"2.1",
  "timestamp":1699776000000,
  "requestId":"cfg-1",
  "result":true,
  "reconnectRequired":false,
  "config":{
    "algorithmVersion":"algorithm-version",
    "algorithmParams":{"tearingMinLen":5.0,"tearingMinDepth":2.0,"tearingMinYWidth":2.0,"tearingMaxYWidth":150.0},
    "cameraConfig":{"cameraIP":"192.168.1.100"},
    "queueProcessParam":{"maxQueueSize":300,"generationInterval":100,"imageLineCount":300},
    "pointCloudSendParam":{"enabled":true,"lineStep":5,"pointStep":4}
  }
}

config 顶层字段（读取时返回，写入时除标为只读的字段外均可选）：

字段	类型	说明
algorithmParams	object	算法参数，本节列出与参数页面对应的字段，见下表
algorithmVersion	string	只读，服务端调用 `sg_beltTearingVersion()` 获取的实际算法版本；不是软件版本或TCP协议版本，不参与配置写入或XML持久化
cameraConfig	object	第一台相机的配置；未配置相机时读取结果为 `{}`
queueProcessParam	object	激光线缓存、检测触发和成像窗口参数
pointCloudSendParam	object	点云二进制发送开关及抽样参数；不改变算法和成像所使用的完整点云

serverPort、tcpPort 不属于本文配置协议：GET_CONFIG 不返回这两个字段，SET_CONFIG 不会修改监听端口。客户端即使提交同名字段，也会作为未识别字段忽略。监听端口仅由服务端本地配置管理。旧式 serverInfoResponse.serverInfo.port 若存在，仅用于报告旧通道服务端信息，不是可写配置。

config.algorithmParams 字段：

协议字段	类型	取值要求	含义
`scanXScale`	number	有限数且 > 0	X精度 (mm)：X方向精度参数
`scanYScale`	number	有限数且 > 0	Y精度 (mm)：Y方向精度参数
`differnceBinTh`	number	有限数且 ≥ 0	撕裂斜率 (mm/mm)：撕裂斜率参数
`tearingMinLen`	number	有限数且 ≥ 0	最小长度 (mm)：撕裂最小长度参数
`tearingMinGap`	number	有限数且 ≥ 0	撕裂的间隔 (mm)：撕裂间隔参数
`tearingMinDepth`	number	有限数且 ≥ 0	最小撕裂深度 (mm)：非贯穿型撕裂的最小检测深度，传入算法；本程序缺省值为2.0
`tearingMinYWidth`	number	有限数且 ≥ 0	最小撕裂宽度 (mm)：传入算法的最小宽度；本程序缺省值为2.0
`tearingMaxYWidth`	number	有限数且 > 0，且 ≥ `tearingMinYWidth`	最大撕裂宽度 (mm)：传入算法的最大宽度；本程序缺省值为150.0
`sameGapTh`	number	有限数且 ≥ 0	sameGapTh (mm)：同一间隙判定参数
`gapChkWin`	int	> 0	gapChkWin (点)：间隙检查窗口参数

config.cameraConfig 字段：

协议字段	类型	含义
`cameraIP`	string	相机IP地址：第一台相机的网络地址；`SET_CONFIG` 可修改

config.queueProcessParam 字段：

协议字段	类型	取值要求	含义
`maxQueueSize`	int	> 0	队列大小 (条)：激光线缓存队列的最大数量
`generationInterval`	int	> 0	生成间隔 (条)：累计接收多少条激光线后执行一次检测
`imageLineCount`	int	> 0	成像线数 (条)：生成结果图使用的激光线数量

config.pointCloudSendParam 字段：

协议字段	类型	取值要求	含义
`enabled`	bool	`true` / `false`	启用发送：是否发送激光线点云
`lineStep`	int	> 0	抽线步长 (N)：每隔 N 条激光线发送一条
`pointStep`	int	> 0	抽点步长 (N)：每隔 N 个点发送一个点

部分更新、校验与生效规则：

未提交的字段保留原值；建议按上述配置分组提交。
tearingMinDepth、tearingMinYWidth 和 tearingMaxYWidth 同时支持旧的 WriteConfig / setAlgorithmParams 通道和本文的 GET_CONFIG / SET_CONFIG。旧XML缺少这些属性时采用上表缺省值；部分更新最大/最小宽度时按合并后的完整参数校验。这些阈值由算法处理，服务端不再应用独立的最小宽度或最小深度后过滤参数。
int 字段应发送 JSON 整数，并满足表中的取值要求。
未识别的字段及只读字段不会被写入；algorithmVersion 为只读字段；serverPort、tcpPort 不受协议配置写入；空的 config: {} 不表示恢复默认配置。
SET_CONFIG 成功表示配置已保存，不代表相机已按新地址完成重连。
修改 cameraIP 后需要由客户端安排相机重连；REST_DETECT 只重新启动检测流程，不能代替相机设备重连。

成功应答：GET_CONFIG 和 SET_CONFIG 均返回 CONFIG_RESPONSE，只发给请求客户端。config 的字段结构即以上各表，内容取发送应答时的当前内存配置；客户端不应把自己提交的部分对象当作服务端完整配置。

字段	类型	说明
msgType	string	固定值 `CONFIG_RESPONSE`
protocolVersion	string	服务端协议版本，当前为 `2.1`
timestamp	int64	服务器生成应答的时间，毫秒级 Unix 时间戳
requestId	string	原配置请求的关联标识；请求未传时为空字符串
result	bool	成功固定为 `true`；配置失败不使用本消息返回 `false`，而是返回 `CMD_RESPONSE`
reconnectRequired	bool	读取配置时固定为 `false`；按本节页面参数，写入时表示 `cameraIP` 是否发生变化
config	object	服务端当前可对外读取的完整配置，包含只读字段；不是配置文件全部内容

算法版本位于 CONFIG_RESPONSE.config.algorithmVersion。GET_CONFIG 和 SET_CONFIG 成功应答均返回此字段。旧应用通道的 configResponse 和 serverInfoResponse 在响应顶层返回 algorithmVersion，已有的 version / serverInfo.version 仍表示服务端软件版本。BeltTearingApp 参数页面分别显示软件版本和算法版本；旧服务端未返回算法版本时显示“未提供”。

失败应答：沿用6.1的 CMD_RESPONSE 字段，cmdType 为 GET_CONFIG 或 SET_CONFIG，result=false，errorMsg 为具体失败原因；失败应答不回传 requestId。

errorCode	含义
1	`SET_CONFIG` 缺少 `config` 对象，或已处理字段类型/取值校验不通过
2	配置读写回调不可用，或写入时配置服务不可用
3	配置持久化失败
1001	请求显式携带不兼容的协议版本

10.3 协议能力查询

请求：无额外业务字段，不需要传能力列表。

{"msgType":"GET_PROTOCOL_INFO","protocolVersion":"2.1"}

应答：服务器向请求客户端返回 PROTOCOL_INFO，不广播，也不回传 requestId。

字段	类型	说明
msgType	string	固定值 `PROTOCOL_INFO`
protocolVersion	string	当前协议版本，固定为 `2.1`
timestamp	int64	服务器生成应答的时间，毫秒级 Unix 时间戳
protocolName	string	协议名称，固定为 `BeltTearingTCP`
minCompatibleVersion	string	最低兼容客户端协议版本，固定为 `2.1`；显式版本校验要求主版本相同且次版本不低于1
softwareVersion	string	服务端软件版本，由 `BELTTEARING_VERSION_STRING` 和 `BELTTEARING_VERSION_BUILD` 用 `.` 拼接；不是协议版本，也不包含构建时间
algorithmVersion	string	实际算法库通过 `sg_beltTearingVersion()` 返回的版本
capabilities	array	服务端支持的能力标识列表，当前固定返回下表中的8项；表示支持能力，不表示对应实时传输已开启

capabilities 各项含义：

能力标识	含义
DETECT_RESULT_V2	支持增强检测结果，包含报警标志、历史最大长宽及撕裂明细；实际消息类型仍为 `DETECT_RESULT`
RESET_ALARM	支持清除当前报警状态，避免当前持续存在的撕裂重复触发报警
REST_DETECT	支持不关闭相机设备的检测流重启与缓存重置
GET_CONFIG	支持读取当前对外配置
SET_CONFIG	支持部分更新并保存配置
REALTIME_RESULT	支持实时检测结果消息，需通过 `SET_REALTIME` 为该客户端开启
DEPTH_PSEUDOCOLOR	声明支持深度伪彩图像；不是本节可直接发送的命令
POINT_CLOUD_STREAMING	支持第11章的激光线点云二进制传输，由 `pointCloudSendParam.enabled` 控制

11. 激光线点云实时发送

激光线点云与 JSON 控制响应共用同一条协议 TCP 连接。客户端需要根据首字节区分 JSON 帧（##START#）和点云二进制帧（0x05）。点云共用以下外层帧：

字段	字节数	类型	说明
dataType	1	uint8	点云固定为 `0x05`
payloadLength	4	uint32	点云负载长度，大端序
payload	可变	binary	见下表
frameTail	11	char[11]	固定为 `___END___\r\n`

点云负载版本 1 的字段均采用大端序，浮点数为 IEEE 754 双精度：

字段	字节数	类型	说明
formatVersion	1	uint8	点云负载格式版本，当前为 1
frameIndex	8	uint64	相机激光线帧号
timestamp	8	uint64	相机时间戳
originalPointCount	4	uint32	抽点前点数
sampledPointCount	4	uint32	本包实际点数
lineStep	4	uint32	当前抽线步长
pointStep	4	uint32	当前抽点步长
points	`sampledPointCount * 28`	repeated	每点依次为 `int32 pointIndex`、`double x`、`double y`、`double z`

抽线计数发生在完整激光线进入算法队列之后，抽点仅在构造 TCP 负载时执行，不会改变算法输入、点云缓存或二维图像生成数据。

36 KiB Raw Blame History Unescape Escape

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

版本

版本历史

1. 协议概述

1.1 连接参数

1.2 协议特点

1.3 CMD 汇总表

2. 数据帧格式

2.1 帧结构说明

2.2 帧头帧尾定义

3. 消息类型

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

4.1 撕裂检测结果上报

4.2 实时检测结果上报

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

5.1 设置速度命令

5.2 启停控制命令

5.3 实时传输控制命令

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

6.1 命令应答格式

7. 通信流程

7.1 速度设置流程

7.2 启停控制流程

7.3 实时传输控制流程

8. TCP粘包处理

8.1 发送端处理

8.2 接收端处理

9. 连接管理

9.1 心跳机制

9.2 断线重连

10. 2.1 增强命令

10.1 报警复位与重新检测

10.2 配置读取与部分更新

10.3 协议能力查询

11. 激光线点云实时发送

36 KiB

Raw Blame History