# Page 1

采集端通信协议规范
采集端通信协议规范
版本: 2.1.3
日期: 2026-02-07
基于: Intro.md (PUB-SUB 模式), ZMQ 协议帧设计规范.md (v1.5.0)
1. 协议概述
1.1 设计背景
随着系统架构演进，新的下位硬件将承担相机采集和预处理功能，替代原有PipelineV1 中的采
集和预处理模块。本协议定义了ConfigServer 与采集端之间的通信规范，确保系统平滑迁移。
版本2.1.0 变更：
•
修改了温度数据上传格式
•
增加了一维数据的标识方法
•
将float 格式统一为int 格式
版本2.1.2 变更：
•
增加了发送配置的定义
版本2.1.3 变更：
•
增加了描述插图
•
修改了部分表述
1.2 设计原则
简单性: 采用PUB-SUB 单向通信模式，降低实现复杂度
高效性: 针对温度矩阵传输优化，支持实时数据流
可扩展性: 支持参数动态配置和功能扩展
1.
2.
3.


# Page 2

可靠性: 完善的错误处理和状态监控机制
兼容性: 完全兼容Intro.md 中的下位机协议
1.3 协议适用范围
•
ConfigServer 向采集端下发配置参数
•
采集端向ConfigServer 返回预处理数据
•
采集端状态监控与健康检查
•
实时图像流传输
•
多设备管理（基于设备ID）
2. 系统架构与数据流
2.1 系统架构
4.
5.


# Page 3

2.2 数据流说明
2.2.1 命令下发流 (ConfigServer → 采集端)
•
配置参数更新: 通过主题 
 下发
•
控制命令: 通过主题 
 下发
•
文件传输: 通过主题 
 下发
•
设备注册响应: 通过主题 
 下发
2.2.2 数据返回流 (采集端 → ConfigServer)
•
设备注册: 通过主题 
 上报
•
命令结果: 通过主题 
 上报
•
状态信息: 通过主题 
 上报
•
处理完成回执: 通过主题 
 上报
•
帧数据: 通过主题 
 上报
graph TD
    A[上位机/UI] --> B[ConfigServer]
    B --> C[采集端硬件]
    C --> D[相机采集]
    D --> E[预处理模块]
    E --> F[温度矩阵输出]
    F --> B
    B --> G[Pipeline预测器]
    
    subgraph "PUB-SUB通信"
        H[ConfigServer PUB] --> I[发布命令/配置]
        J[ConfigServer SUB] --> K[接收数据/状态]
        L[采集端 SUB] --> M[接收命令/配置]
        N[采集端 PUB] --> O[发布数据/状态]
    end
    
    style C fill:#e1f5e1
    style G fill:#fff3e0
    style H fill:#e3f2fd
    style J fill:#f3e5f5
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{deviceId}/setting
{deviceId}/command
{deviceId}/file
{deviceId}/ready
register
result
status
changed
acquisition.*
Plain Text


# Page 4

2.2.3 数据转发流 (ConfigServer → Pipeline 预测器)
•
预处理后的温度矩阵
•
触发事件信息
2.3 端口配置
端口说明:
•
5511 端口: ConfigServer 作为PUB 发布者，采集端作为SUB 订阅者
•
5512 端口: ConfigServer 作为SUB 订阅者，采集端作为PUB 发布者
3. PUB-SUB 协议设计
3.1 帧结构
采用标准的PUB-SUB 帧结构，基于ZMTP 3.0 协议：
方向
ConfigServer
端口
采集端端口
用途
主题示例
下发命令
5511 (PUB)
5512 (SUB)
命令下发
device001/se
tting
接收数据
5511 (SUB)
5512 (PUB)
数据上报
, 
result
register


# Page 5

3.2 ZMTP 握手流程
GREETING 格式（64 字节）：
┌──────────────────────────────────────────────────────────────────────
───┐
│                        ZMQ Multipart Message (PUB-SUB)               
   │
├──────────────┬──────────────┬────────────────────────────────────────
───┤
│   Frame 0    │   Frame 1    │                 Frame 2                
   │
│   (Topic)    │   (Data)     │               (可选扩展)                 
 │
├──────────────┼──────────────┼────────────────────────────────────────
───┤
│   主题字符串  │  序列化数据  │               扩展数据                   │
└──────────────┴──────────────┴────────────────────────────────────────
───┘
1
2
3
4
5
6
7
8
客户端（采集端）            服务端（ConfigServer）
      │                              │
      │ 1. GREETING (10 bytes)       │
      │─────────────────────────────>│
      │                              │
      │                        2. GREETING (10 bytes)
      │<─────────────────────────────│
      │                              │
      │ 3. READY (Command + Metadata) │
      │─────────────────────────────>│
      │                              │
      │                        4. READY (Command + Metadata)
      │<─────────────────────────────│
      │                              │
      │           握手完成，开始消息传输          │
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Plain Text
Plain Text


# Page 6

•
签名（10 字节）：
•
版本（2 字节）：
（ZMTP 3.0）
•
机制（20 字节）："NULL" + 16 个0
•
as_server（1 字节）：0x00（客户端）或0x01（服务端）
•
填充（31 字节）：0
3.3 主题命名规范
3.3.1 设备专属主题
•
 - 配置参数下发
•
 - 控制命令下发
•
 - 文件传输
•
 - 设备就绪信号
•
 - 成功响应
•
 - 错误响应
3.3.2 通用主题
•
 - 设备注册
•
 - 检测结果
•
 - 状态信息
•
 - 处理完成回执
•
 - 触发帧数据
•
 - 蒙版帧数据
•
 - 采集状态
3.3.3 主题匹配规则
•
前缀匹配：订阅 
 将接收所有 
 开头的消息
•
精确匹配：订阅 
 只接收 
 消息
4. 参数下发协议
0xFF 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x01 0x7F
{3, 0}
{deviceId}/setting
{deviceId}/command
{deviceId}/file
{deviceId}/ready
{deviceId}/response/success
{deviceId}/response/error
register
result
status
changed
acquisition.frame.triggered
acquisition.frame.masked
acquisition.status
device001/
device001/
register
register


# Page 7

4.1 命令帧结构
所有命令通过PUB-SUB 模式下发：
4.2 命令定义
4.2.1 配置更新命令 (
主题)
用于向采集端下发完整的配置参数。根据一维/ 二维的任务需求, 传递变长参数
当使用一维任务时,Camera 配置项的DeviceId 一定是-1, 代表不使用相机
Topic 格式: 
Payload 格式 (JSON 二维示例):
Frame 0: Topic (主题字符串，如 "device001/setting")
Frame 1: Payload (参数数据，JSON格式)
1
2
setting
{deviceId}/setting
Plain Text


# Page 8

{
  "RequestId": "req_config_001",
  "PipelineId": "line1",
  "timestamp": "2026-02-03T08:30:00Z",
  "value": 10,
  "config": {
    "Version": 2,
    "Command": "ConfigureAcquisition",
    "RequestId": "req_config_001",
    "PipelineId": "line1",
    "Parameters": {
      "Basic": {
        "PipelineId": "line1",
        "PipelineType": "TemperatureDetection",
        "Mode": "Detect",
        "ConfigTag": "stand",
        "StrictnessLevel": 1,
        "IsCustomMode": false
      },
      "Camera": {
        "DeviceId": 1,
        "Width": 384,
        "Height": 288,
        "VideoMode": "TMP",
        "Fps": 30,
        "Exposure": 10000,
        "AutoExposure": false,
        "CaptureTimeoutMs": 100
      },
      "Mask": {
        "Enabled": true,
        "Threshold": 30.0,
        "Width": 185,
        "Height": 70,
        "Angle": 0.0,
        "TargetWidth": 185,
        "TargetHeight": 70
      },
      "RegionOfInterest": {
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
JSON


# Page 9

        "X": 0,
        "Y": 0,
        "Width": 160,
        "Height": 40
      },
      "Trigger": {
        "TriggerGpioLine": 1,
        "Mode": "External",
        "DelayMs": 0,
        "BurstCount": 1,
        "InternalIntervalMs": 100,
        "TemperatureThreshold": 45.0,
        "DebounceIntervalMs": 0,
        "TriggerRoi": {"X":0,"Y":0,"Width":0,"Height":0},
        "TriggerCondition": "Average"
      },
      "Output": {
        "OutputGpioLine": 2,
        "AlarmGpioLine": 3,
        "AlarmHoldMs": 1000,
        "AlarmDebounceMs": 200
      },
      "Storage": {
        "StoreNgImagesOnly": true
      },
      "Training": {
        "Enabled": false,
        "SampleThreshold": 20,
        "MaxCachedSamples": 200,
        "AutoTrigger": true
      },
      "System": {
        "ProcessingTimeoutMs": 100,
        "MaxProcessingQueueSize": 10,
        "EnableDataForwarding": true,
        "CommunicationMode": "PUB_SUB"
      }
    }
  }
}
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79


# Page 10

Payload 格式 (JSON 一维示例):


# Page 11

{
  "RequestId": "req_config_001",
  "PipelineId": "line1",
  "timestamp": "2026-02-03T08:30:00Z",
  "value": 10,
  "config": {
    "Version": 2,
    "Command": "ConfigureAcquisition",
    "RequestId": "req_config_001",
    "PipelineId": "line1",
    "Parameters": {
      "Basic": {
        "PipelineId": "line1",
        "PipelineType": "TemperatureDetection",
        "Mode": "Detect",
        "ConfigTag": "stand",
        "StrictnessLevel": 1,
        "IsCustomMode": false
      },
      "Camera": {
        "DeviceId": -1
      },
      "Settings": {
        "mode": "RUN",
        "high_timer_limit":5,
        "timer_c_limit":5,
        "buffer_size": 5,
        "trigger_temp_limit": 5,
        "left_window_range": 5,
        "start_points_to_remove": 5,
        "reference_length": 5,
        "ng_count_limit":5,
        "trigger":0
      }
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
JSON


# Page 12

4.2.2 部分参数更新命令
通过 
 主题下发，使用简化格式：
Payload 格式:
4.2.3 控制命令 (
主题)
通过 
 主题下发控制命令：
{deviceId}/setting
{
  "RequestId": "req_update_001",
  "PipelineId": "line1",
  "timestamp": "2026-02-03T08:31:00Z",
  "command": "UpdateParameters",
  "parameters": {
    "Mask.Threshold": 35.0,
    "Trigger.DelayMs": 50,
    "Camera.Fps": 25
  }
}
1
2
3
4
5
6
7
8
9
10
11
command
{deviceId}/command
JSON


# Page 13

命令名称
说明
参数
Payload 示例
StartAcquisition
启动采集
{"mode": 
"Detect"}
{"command": 
"StartAcquisition"
, "PipelineId": 
"line1", "mode": 
"Detect"}
StopAcquisition
停止采集
无
{"command": 
"StopAcquisition",
 "PipelineId": 
"line1"}
PauseAcquisition
暂停采集
无
{"command": 
"PauseAcquisition"
, "PipelineId": 
"line1"}
ResumeAcquisitio
n
恢复采集
无
{"command": 
"ResumeAcquisition
", "PipelineId": 
"line1"}
GetStatus
获取状态
无
{"command": 
"GetStatus", 
"PipelineId": 
"line1"}
GetConfiguration
获取配置
无
{"command": 
"GetConfiguration"
, "PipelineId": 
"line1"}
SwitchPipelineMod
e
切换配方模式
{"mode": 
"stand"}
{"command": 
"SwitchPipelineMod
e", "PipelineId": 
"line1", "mode": 
"stand"}


# Page 14

4.3 参数详细说明
一维专用参数说明 (Settings):
ResetStats
重置统计数据
无
{"command": 
"ResetStats", 
"PipelineId": 
"line1"}
GetScreenshot
请求实时截图
无
{"command": 
"GetScreenshot", 
"PipelineId": 
"line1"}
参数名
类型
说明
mode
string
指示工作状态：
STOP/RUN/NOP
buffer_size
int
单包采集最长时间(ms) = X/10
trigger_temp_limit
int
触发温度下限
start_points_to_remove
int
起始移除点数，过滤触发后前 
N 点
reference_length
int
预处理对齐长度
high_timer_limit
int
高位滤波计时参数
timer_c_limit
int
滤波计时上限参数
ng_count_limit
int
连续NG 数- 停止采集触发
lsize_start
int
向右切片起点
rsize_start
int
向左切片起点
trigger
int
触发方式(0- 外部,1- 内部)


# Page 15

一维触发方式说明
外部触发
mode 为RUN 时, 始终准备采集, 当mode 为STOP 时, 任何时候不进行采集
DI 收到电平变化信号(低-> 高)
触发中断/ 定时滤波(high_timer_limit 代表高电平持续时间ms)
满足滤波时间开始采集
收集温度点, 当采集到连续三个(常量)高于触发温度trigger_temp_limit 时
认为正在采集, 将数据放入数组
终止采集有两种方式:
1.buffer_size 被塞满,
2. 连续采集ng_count_limit 个低于trigger_temp_limit 的温度点
切片数组, 传递[lsize_start,-rsize_start]
数组打包后进入消息发送队列


# Page 16

内部触发
mode 为RUN 时, 始终准备采集, 当mode 为STOP 时, 任何时候不进行采集
采集流程始终进行, 内部维护数组状态锁, 长度为3 的循环缓冲区
收集温度点, 当采集到连续三个(常量)高于触发温度trigger_temp_limit 时
认为正在采集, 将循环缓冲区写入数组前三位, 从第四位起继续输入
终止采集有两种方式:
1.buffer_size 被塞满,
2. 连续采集ng_count_limit 个低于trigger_temp_limit 的温度点
切片数组, 传递[lsize_start,-rsize_start]
数组打包后进入消息发送队列
二维专用参数说明:
基本参数 (Basic)
相机参数 (Camera)
参数名
类型
默认值
说明
PipelineId
string
"line1"
管线标识
PipelineType
string
"TemperatureDe
tection"
管线类型
Mode
string
"Detect"
运行模式: Detect/Train
ConfigTag
string
"stand"
配置标签: 
loose/stand/strict/ultra/custom
StrictnessLevel
int
1
严格等级: 0-3
IsCustomMode
bool
false
是否为自定义模式


# Page 17

蒙版参数 (Mask)
触发参数 (Trigger)
参数名
类型
默认值
说明
DeviceId
int
1
相机设备ID
Width
int
384
分辨率宽度
Height
int
288
分辨率高度
VideoMode
string
"TMP"
视频模式: 
TMP/Y16/YUV
Fps
int
30
帧率
Exposure
int
10000
曝光时间(微秒)
AutoExposure
bool
false
自动曝光
CaptureTimeoutMs
int
100
采集超时时间
参数名
类型
默认值
说明
Enabled
bool
true
是否启用蒙版
Threshold
int
30
蒙版阈值(°C)
Width
int
185
蒙版宽度
Height
int
70
蒙版高度
Angle
int
0
旋转角度
TargetWidth
int
185
目标输出宽度
TargetHeight
int
70
目标输出高度


# Page 18

ROI 参数
参数名
类型
默认值
说明
TriggerGpioLine
int
0
触发GPIO 线路(0 表示
禁用)
Mode
string
"External"
触发模式: 
Internal/External
DelayMs
int
0
触发延迟(毫秒)
BurstCount
int
1
连拍次数
InternalIntervalMs
int
100
内部触发间隔(毫秒)
TemperatureThresho
ld
int
45
内部触发温度阈值(°C)
DebounceIntervalMs
int
0
外部触发消抖间隔(毫
秒)
TriggerRoi
Rect
0,0,0,0
触发专用ROI 区域
TriggerCondition
string
"Average"
触发条件: 
Max/Average
参数名
类型
默认值
说明
RegionOfInterest
Rect
0,0,160,40
算法处理边界, 非必传


# Page 19



# Page 20

二维触发方式说明
外部触发
TriggerGpioLine 收到电平变化信号(低-> 高)
触发中断/ 定时滤波DebounceIntervalMs
DelayMs 后开始采集, 连续采集BurstCount 张
对截取图像进行阈值过滤, 低于Threshold 的值, 被替换为0
使用积分图计算,TargetWidth * TargetHeight 的最佳位置(X,Y)
返回被TargetWidth * TargetHeight 裁剪的原始图像, 写入int[][]中
数组打包后进入消息发送队列
内部触发
采集流程始终进行
计算图像中TriggerRoi 中的Max/Average, 若大于TemperatureThreshold, 则发生内部触发
DelayMs 后开始采集, 连续采集BurstCount 张, 每次采集间隔至少InternalIntervalMs 毫秒
对截取图像进行阈值过滤, 低于Threshold 的值, 被替换为0
使用积分图计算,TargetWidth * TargetHeight 的最佳位置(X,Y)
返回被TargetWidth * TargetHeight 裁剪的原始图像, 写入int[][]中
数组打包后进入消息发送队列
5. 数据返回协议
5.1 数据帧结构
采集端返回数据采用PUB-SUB 模式：


# Page 21

Frame 0: Topic (数据主题)
Frame 1: Data (序列化数据，JSON 格式)
5.2 数据主题定义
所有上报数据必须携带 
 以支持多设备区分。
5.3 数据格式定义
5.3.1 DeviceRegisterEvent（设备注册）
设备启动时发送的注册信息。
字段定义:
PipelineId
主题
说明
数据格式
发送频率
register
设备注册信息
DeviceRegisterEvent
启动时一次
result
检测结果数据
AcquisitionResultEve
nt
每3 秒（长帧）
result
检测状态
AcquisitionStatusEve
nt
每3
条长帧后（短帧）
changed
处理完成回执
ChangedEvent
命令处理后
status
状态信息
StatusEvent
每5 秒
acquisition.frame
.triggered
触发帧数据
AcquisitionFrameEve
nt
触发时
acquisition.frame
.masked
蒙版帧数据
AcquisitionFrameEve
nt
每帧
acquisition.statu
s
采集状态
AcquisitionStatusEve
nt
每1 秒


# Page 22

5.3.3 ChangedEvent（处理完成回执）
命令处理完成后的回执。
字段定义:
5.3.4 AcquisitionFrameEvent（帧数据）
基于PipelineFrameEvent 的简化版本，用于传输帧数据。
MessagePack(若采用简化帧)字段定义:
{
  "PipelineId": "逻辑管线ID",
  "deviceId": "设备唯一标识符(UUID)",
  "sessionRuntimeHours": 0,
  "totalRuntimeHours": 0,
  "version": "1.0.0",
  "status": "Ready",
  "capabilities": ["PUB_SUB"],
  "preferredMode": "PUB_SUB"
}
1
2
3
4
5
6
7
8
9
10
{
  "PipelineId": "逻辑管线ID",
  "deviceId": "设备ID",
  "RequestId": "关联的请求ID",
  "changed": "setting/file/command",
  "status": "OK/ERROR",
  "sessionRuntimeHours": 0,
  "totalRuntimeHours": 0,
  "errorMessage": "错误信息（如有）"
}
1
2
3
4
5
6
7
8
9
10
JSON
JSON


# Page 23

字段索引
字段名
类型
说明
必选
0
Version
int
协议版本(2)
✓
1
Timestamp
long
时间戳(毫秒)
✓
2
PipelineId
string
管线ID
✓
3
FrameNum
ber
long
帧序号
✓
4
Width
int
图像宽度
✓
5
Height
int
图像高度
✓
6
ImageData
byte[]
图像数据(JPEG)
✗
7
MinTemper
ature
int
全图最低温度(°C)
✓
8
MaxTempe
rature
int
全图最高温度(°C)
✓
9
AvgTemper
ature
int
全图平均温度(°C)
✓
10
RoiTemper
ature
int
ROI 区域温度(°C), 用于提示当前触发区
域温度
✓
11
FrameType
string
帧类型
✓
12
EventId
string
事件ID(UUID)
✓
13
Format
string
数据格式
✓
14
RoiRegion
int[]
ROI 区域[x,y,w,h]
✗
15
Temperatu
reMatrix
int[][]
原始温度矩阵。格式：
。外层代表行，内层
代表列。数据为整数（实际温度 * 
10），例如 345 代表 34.5°C。
[ [row1], 
[row2], ... ]
✗
16
Is2D
bool
维度标志位。
: 二维矩阵数据；
: 一维线性数据（此时高度为
1，格式为 
）。
true
false
[[]]
✓


# Page 24

数据格式说明:
•
温度数值: 为了提高传输效率，
 中的数值采用整数表示。转换公式：
。
•
矩阵结构:
◦
二维模式 (
): 
，外层数组的每个
元素代表图像的一行。
◦
一维模式 (
): 
，外层数组仅包含一个元素（即高度
为1）。
JSON 示例 (二维数据):
JSON 示例 (一维数据):
TemperatureMatrix
真实温度 = 整数值 / 10.0
Is2D=true
[[r1c1, r1c2...], [r2c1, r2c2...]]
Is2D=false
[[v1, v2, v3...]]
{
  "Version": 2,
  "Timestamp": 1706941200000,
  "PipelineId": "line1",
  "FrameNumber": 100,
  "Width": 4,
  "Height": 3,
  "MinTemperature": 250,
  "MaxTemperature": 450,
  "AvgTemperature": 350,
  "RoiTemperature": 360,
  "FrameType": "Masked",
  "EventId": "uuid-123",
  "Format": "JSON",
  "Is2D": true,
  "TemperatureMatrix": [
    [250, 260, 270, 280],
    [300, 310, 320, 330],
    [400, 410, 420, 450]
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
JSON


# Page 25

帧类型 (FrameType):
•
: 触发时的原始帧
•
: 蒙版处理后的帧
•
: 热力图图像
•
: 实时流帧
5.3.5 AcquisitionStatusEvent（采集状态）
采集端状态信息。
字段定义:
{
  "Version": 2,
  "Timestamp": 1706941200000,
  "PipelineId": "line1",
  "FrameNumber": 101,
  "Width": 4,
  "Height": 1,
  "MinTemperature": 250,
  "MaxTemperature": 300,
  "AvgTemperature": 275,
  "RoiTemperature": 275,
  "FrameType": "Masked",
  "EventId": "uuid-456",
  "Format": "JSON",
  "Is2D": false,
  "TemperatureMatrix": [
    [250, 260, 280, 300]
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
Triggered
Masked
Heatmap
Live
JSON


# Page 26

运行状态 (Status):
•
: 空闲
•
: 运行中
•
: 暂停
•
: 错误
•
: 初始化中
•
: 注册中
6. 命令与响应格式
6.1 响应传输方式
由于PUB-SUB 是单向通信，响应通过特定的响应主题发布：
•
成功响应: 
•
错误响应: 
字段名
类型
说明
Version
int
协议版本
Timestamp
long
时间戳
PipelineId
string
管线ID
Status
string
运行状态
Mode
string
当前模式
FrameRate
int
当前帧率
TemperatureRange
int[]
温度范围[min,max]
HardwareStatus
object
硬件状态
ErrorCount
int
错误计数
Uptime
long
运行时间(秒)
Idle
Running
Paused
Error
Initializing
Registering
{deviceId}/response/success
{deviceId}/response/error


# Page 27

6.2 响应格式
6.2.1 通用响应结构
响应必须包含 
 和 
 以确保发送端能够正确匹配异步结果。
6.2.2 命令响应示例
ConfigureAcquisition 响应:
RequestId
PipelineId
{
  "Version": 2,
  "Timestamp": 1706941200000,
  "RequestId": "对应请求ID",
  "PipelineId": "逻辑管线ID",
  "Success": true,
  "ErrorCode": 0,
  "ErrorMessage": null,
  "CommunicationMode": "PUB_SUB",
  "Data": {
    "Message": "Success"
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "RequestId": "req_config_001",
  "Success": true,
  "ErrorCode": 0,
  "ErrorMessage": null,
  "CommunicationMode": "PUB_SUB",
  "Data": {
    "PipelineId": "line1",
    "AppliedParameters": ["Basic", "Camera", "Mask", "Trigger"],
    "Timestamp": 1706941200000
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
JSON
JSON


# Page 28

GetStatus 响应:
6.3 异步响应处理
由于PUB-SUB 是异步通信，需要以下机制确保可靠性：
请求ID 匹配: 每个命令包含唯一RequestId，响应中携带相同ID
超时机制: 发送命令后等待响应，超时后重试
重试策略: 失败后按指数退避重试
状态同步: 定期同步设备状态，确保一致性
7. 错误处理与状态码
7.1 错误代码 definition
{
  "RequestId": "req_status_001",
  "Success": true,
  "ErrorCode": 0,
  "ErrorMessage": null,
  "CommunicationMode": "PUB_SUB",
  "Data": {
    "PipelineId": "line1",
    "Status": "Running",
    "Mode": "Detect",
    "FrameRate": 29.5,
    "TemperatureRange": [20.5, 45.3],
    "Uptime": 3600,
    "ErrorCount": 0
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
1.
2.
3.
4.
JSON


# Page 29

7.2 错误响应示例
错误代码
错误类型
说明
2001
参数验证错误
参数格式或范围错误
2002
配置应用失败
配置无法应用到硬件
2003
硬件通信错误
与相机或GPIO 通信失败
2004
预处理错误
蒙版处理或ROI 裁剪失败
2005
资源不足
内存或存储空间不足
2006
状态冲突
命令与当前状态冲突
2007
超时错误
操作超时
2008
数据格式错误
数据格式不支持
2101
通信模式错误
仅支持PUB_SUB 模式
2102
主题解析错误
PUB-SUB 主题解析失败
2103
设备注册失败
设备注册过程失败
2104
订阅失败
主题订阅失败
2105
发布失败
消息发布失败
{
  "RequestId": "req_config_001",
  "Success": false,
  "ErrorCode": 2101,
  "ErrorMessage": "仅支持PUB_SUB通信模式",
  "CommunicationMode": "PUB_SUB",
  "Data": {
    "SupportedModes": ["PUB_SUB"],
    "RequestedMode": "PUB_SUB"
  }
}
1
2
3
4
5
6
7
8
9
10
11
JSON


# Page 30

7.3 错误恢复策略
网络错误: 自动重连，恢复订阅
数据错误: 丢弃错误数据，记录日志
配置错误: 回退到上次有效配置
硬件错误: 进入安全模式，报告错误
8. 设备注册与管理
8.1 设备注册流程
8.2 设备状态管理
ConfigServer 维护设备状态表：
1.
2.
3.
4.
采集端                     ConfigServer
   │                           │
   │ 1. 连接PUB/SUB Socket      │
   │───────────────────────────>│
   │                           │
   │ 2. 发送register消息        │
   │───────────────────────────>│
   │ (主题: register)           │
   │                           │
   │ 3. 注册设备                │
   │<───────────────────────────│
   │                           │
   │ 4. 发送ready信号           │
   │<───────────────────────────│
   │ (主题: {deviceId}/ready)   │
   │                           │
   │ 5. 设备激活，开始通信       │
   │                           │
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
Plain Text


# Page 31

8.3 心跳与健康检查
设备心跳: 采集端每5 秒发送status 消息
健康检查: ConfigServer 监控设备活跃状态
超时处理: 30 秒无消息视为离线
自动恢复: 离线设备重新注册
字段
类型
说明
DeviceId
string
设备唯一标识符
Status
string
设备状态
LastActiveTime
datetime
最后活跃时间
SessionRuntimeHours
int
本次会话运行时长
TotalRuntimeHours
int
累计运行时长
Version
string
设备版本
Capabilities
array
设备能力列表
Subscriptions
array
已订阅主题
1.
2.
3.
4.

