智慧工地平台对接，执法记录仪&可视化智能安全帽 MQTT 设备对接协议

发布时间: 2026-09-01 11:22:11

执法记录仪&可视化智能安全帽 MQTT 设备对接协议

1 适用范围

本协议规范云平台、 EMQX 中间服务、硬件终端（执法仪、可视化安全帽）、流媒体服务之间全流程数据交互标准，覆盖设备配置、音视频预览 / 回放、录像上传、报警上报、定位采集等业务场景。

2 参与方说明

1. 硬件终端：执法记录仪、可视化智能安全帽，负责采集音视频、 GPS 定位、视频报警、本地录像存储；

2. EMQX 中间服务： MQTT 消息转发中间件，承载终端与云平台双向信令中转，具备公网固定 IP；

3. 云平台：业务管理后台，下发各类配置、音视频 / 录像控制指令、查询设备历史数据，具备公网固定 IP；

4. 流媒体服务：独立音视频码流服务，接收终端推送实时 / 回放码流，对外提供 HTTP 拉流地址。

3 通信基础规则

1. 信令传输协议： MQTT， QoS=0；

2. 数据格式：纯 JSON，无加密传输；

3. 链路部署：云平台、 EMQX 均配置公网 IP，终端主动发起 MQTT 长连接；

4. 码流传输：实时预览、历史回放音视频码流由流媒体服务独立承载， HTTP URL 拉流；

5. 时间统一格式： YYYY-MM-DD HH:mm:ss ；码率单位： kbps；帧率单位： fps。

4 MQTT Topic 统一规范

消息流向

Topic 模板

用途

终端上行（终端→ EMQX→

云平台）

/device/{deviceId}/up

终端主动上报：设备属性、报警、定位、

录像目录、上传结果

平台下行（云平台→ EMQX→终端）

平台下发：参数配置、预览 / 回放 / 上传

控制、查询指令

deviceId ：设备唯一序列号，单设备独立 Topic 隔离消息；所有消息 QoS=0。

5 通用消息结构

5.1 平台下行通用指令模板

所有平台下发指令统一使用该外层结构

{"msgType": "指令标识 ",

: ,

"msgId" "D202607140001"

: ,

"deviceId" "V20260714001"

"timestamp": "2026-07-14 10:30:20",

"data": {} }

字段	类型	说明
msgType	string	业务消息类型标识
msgId	string	下行指令唯一流水号，用于应答关联
deviceId	string	设备唯一编号
timestamp	string	消息生成时间
data	object	业务参数载荷

5.2 通用应答消息（终端上行）

所有下行指令，终端必须上行返回该应答报文， Topic： /device/{deviceId}/up msgType： common_ack

{

"msgType": "common_ack",

: ,

"deviceId" "V20260714001"

: ,

"downMsgId" "D202607140001"

"result": 0,

"resultDesc": "操作成功 ",

"timestamp": "2026-07-14 10:30:25" }

字段	类型	说明
downMsgId	string	对应下行指令 msgId
result	int	0 = 成功； 1 = 失败； 2 = 设备不支持； 3 = 会话失效
resultDesc	string	操作结果文字描述

一、终端音视频参数设置

功能简介

云平台下发配置，统一修改设备实时流、存储流编码、分辨率、关键帧、 OSD 字幕、音频开关等音视频基础参数。

下行 MQTT 消息

msgType： av_param_set

{

"msgType": "av_param_set",

: ,

"msgId" "D202607140002"

: ,

"deviceId" "V20260714001"

"timestamp": "2026-07-14 10:32:10",

"data": {

"realEncodeMode": 1,

"realResolution": 5,

"realKeyFrameInterval": 50,

"realFps": 25,

"realBitrate": 2048,

"storeEncodeMode": 1,

"storeResolution": 5,

"storeKeyFrameInterval": 50,

"storeFps": 25,

"storeBitrate": 4096,

"osdConfig": 31,

"audioEnable": 1

}

关键字段说明

字段	取值说明
realEncodeMode	0=CBR 固定码率， 1=VBR 可变码率， 2=ABR 平均码率
realResolution	5=720P， 6=1080P
osdConfig	位掩码， bit0 = 时间、 bit1 = 设备编号、 bit2 = 通道号、 bit3 = 经纬度
audioEnable	0 = 关闭音频， 1 = 开启音频

终端响应

上行推送 common_ack 通用应答。

二、报警录像 / 图像分析 / 休眠唤醒参数设置

功能简介

配置报警录像存储阈值、 AI 图像分析阈值（超员、疲劳）、设备休眠唤醒触发规则与定时唤醒时段。

下行 MQTT 消息

msgType： alarm_sleep_param_set

关键字段说明

字段	说明
alarmStoreThreshold	报警录像存储占用百分比阈值
wakeMode	位掩码： bit0 = 条件唤醒、 bit1 = 定时唤醒、 bit2 = 手动唤醒
wakeTrigger	触发唤醒条件：紧急报警、碰撞、设备开盖

终端响应

上行推送 common_ack 通用应答。

三、查询终端属性

功能简介

平台下发查询指令，请求设备上报全部音视频硬件能力参数。

下行 MQTT 消息

msgType： query_device_attr

功能简介

终端收到查询属性指令后，主动上报硬件编码、声道、采样率、最大音视频通道等硬件能力，上行 Topic。

上行 MQTT 消息

msgType： upload_device_attr

{

: ,

"msgType": "upload_device_attr", "deviceId" "V20260714001"

"refMsgId" "D202607140004"

"timestamp": "2026-07-	14 10:40:05",
"data": { "audioCodec": 19, "audioChannel": 1, "audioSampleRate": 0	,
"audioBitDepth": 1, "audioFrameLen": 960	,
"audioOutSupport": 1	,
"videoCodec": 86, "maxAudioChannel": 1	,
"maxVideoChannel": 4 } }

关键字段说明

字段	说明
refMsgId	对应查询指令的下行 msgId
videoCodec	86=H.264， 66=H.265
maxVideoChannel	设备最大支持视频通道数量

五、视频报警信息上报

功能简介

设备实时检测视频信号丢失、画面遮挡、存储故障、 AI 疲劳 / 打电话 / 超员等报警，主动上报云平台。

上行 MQTT 消息

msgType： video_alarm_upload

{

: ,

"msgType": "video_alarm_upload", "deviceId" "V20260714001"

"timestamp": "2026-07-14 10:45:22",

"data": {

"alarmMask": 32,

"videoLostMask": 0,

"videoCoverMask": 0,

"storageFaultMask": 0,

"driveAlarmType": 1,

"fatigueLevel": 70

}

关键字段说明

字段	说明
alarmMask	位掩码： bit4 = 超员报警， bit5 = 异常驾驶报警
driveAlarmType	bit0 = 疲劳、 bit1 = 打电话、 bit2 = 抽烟
fatigueLevel	疲劳等级 0~100，数值越大疲劳程度越高

六、实时音视频预览请求

功能简介

平台下发预览指令，指定流媒体地址、通道、码流类型，设备主动连接流媒体推送实时音视频码流。

下行 MQTT 消息

msgType： real_stream_req

{

: ,

"msgType": "real_stream_req", "msgId" "D202607140005"

: ,

"deviceId" "V20260714001"

"timestamp": "2026-07-14 10:50:10",

"data": {

"streamIp": "120.xx.xx.xx",

"tcpPort": 8554,

"udpPort": 8555,

"channelId": 1,

"avType": 0,

"streamType": 0

}

关键字段说明

字段	取值说明
avType	0 = 音视频， 1 = 仅视频， 2 = 仅音频
streamType	0 = 主码流， 1 = 子码流

终端响应

上行推送 common_ack 通用应答，随后建立连接推送 RTP 码流至流媒体服务。

七、实时音视频流启停 / 码流切换控制

功能简介

预览过程中控制通道关闭、码流切换、暂停 / 恢复传输、关闭双向对讲。

下行 MQTT 消息

msgType： real_stream_ctrl

{

: ,

"msgType": "real_stream_ctrl", "msgId" "D202607140006"

: ,

"deviceId" "V20260714001"

"timestamp": "2026-07-14 10:52:00",

"data": {

"channelId": 1,

"ctrlCmd": 1,

"closeAvType": 0,

"switchStreamType": 1

}

关键字段说明

ctrlCmd	控制含义
0	关闭音视频传输
1	切换码流
2	暂停码流
3	恢复码流
4	关闭双向对讲

终端响应

上行推送 common_ack 通用应答。

八、查询录像文件（平台下发前置指令）

功能简介

平台按通道、时间、报警类型查询设备本地存储录像列表。

下行 MQTT 消息

msgType： query_record_list

{

: ,

"msgType": "query_record_list", "msgId" "D202607140007"

: ,

"deviceId" "V20260714001"

"timestamp": "2026-07-14 11:00:00",

"data": {

"channelId": 1,

"startTime": "2026-07-13 00:00:00",

"endTime": "2026-07-14 11:00:00",

"alarmFlag": 0,

"avType": 0,

"streamType": 0,

"memType": 1

}

九、终端返回录像文件

功能简介

终端收到录像查询指令后，上报匹配条件的本地录像文件清单。

上行 MQTT 消息

msgType： upload_record_list

文本框: "startTime": "2026-07-14 09:00:00",
"endTime": "2026-07-14 09:05:00",
"alarmFlag": 32,
"avType": 0,
"streamType": 1,
"memType": 1,
"fileSize": 8192000
}
]
}
}

字段	说明
totalCount	符合条件录像总条数
fileSize	录像文件大小，单位字节

十、获取录像回放请求下发

功能简介

平台下发历史录像回放指令，指定回放时段、倍速、存储介质，设备推送历史码流至流媒体服务。

下行 MQTT 消息

msgType： record_play_req

{

"msgType": "record_play_req",

: ,

"msgId" "D202607140008"

: ,

"deviceId" "V20260714001"

"timestamp": "2026-07-14 11:10:00",

"data": {

"streamIp": "120.xx.xx.xx",

"tcpPort": 8554,

"udpPort": 8555,

"channelId": 1,

"avType": 0,

"streamType": 1,

"memType": 1,

"playMode": 0,

"speed": 1,

"startTime": "2026-07-14 09:00:00",

"endTime": "2026-07-14 09:05:00"

}

playMode	回放模式
0	正常回放
1	快进回放
2	关键帧快退
3	仅关键帧播放
4	单帧上传

终端响应

上行推送 common_ack 通用应答，推送历史码流至流媒体。

十一、录像文件上传指令下发

功能简介

平台下发 FTP 服务器信息，设备通过 FTP 协议将完整录像文件上传至云端存储。

下行 MQTT 消息

msgType： record_upload_req

{

: ,

"msgType": "record_upload_req", "msgId" "D202607140009"

: ,

"deviceId" "V20260714001"

"timestamp": "2026-07-14 11:20:00", "data": {

"ftpIp": "120.xx.xx.xx",

"ftpPort": 21,

: ,

"ftpUser" "video01"

"ftpPwd" "Video@123"

: ,

"filePath" "/record/20260714/"

"channelId": 1,

"startTime": "2026-07-14 09:00:00",

"endTime": "2026-07-14 09:05:00",

"allowNetMask": 7

}

allowNetMask	网络权限掩码
bit0	WiFi 允许上传
bit1	局域网允许上传
bit2	4G 移动网络允许上传

终端响应

上行推送 common_ack 通用应答，启动 FTP 上传任务。

十二、文件上传完成结果上报

功能简介

设备 FTP 录像上传结束后，主动上报上传成功 / 失败状态、文件大小。

上行 MQTT 消息

msgType： upload_record_result

{

: ,

"msgType": "upload_record_result", "deviceId" "V20260714001"

"refMsgId" "D202607140009"

"timestamp": "2026-07-14 11:28:30", "data": {

"result": 0,

"desc": "文件上传完成 ",

"fileSize": 8192000 }

}

result	状态
0	上传成功
1	上传失败
2	本地录像文件不存在

十三、HTTP URL 拉流播放请求

功能简介

云平台前端、播放器客户端通过 HTTP 地址直接从流媒体服务拉取实时 / 回放音视频码流，无需 MQTT 信令交互。

标准 URL 格式

URL 示例

URL 参数说明

分段参数	说明
deviceId	设备唯一编号
channel	逻辑视频通道号
avType	0 = 音视频， 1 = 纯视频， 2 = 纯音频
token	64 位时效访问口令， 24 小时自动更新

HTTP 客户端请求示例

文本框: GET /V20260714001.1.0.ABC123XYZ64TOKEN HTTP/1.1 Host: 120.xx.xx.xx:8080
User-Agent: VideoPlayer/1.0

十四、设备实时定位上报

功能简介

终端定时主动上报 GPS 经纬度、网络信号强度、定位精度、行驶速度等定位数据。

上行 MQTT 消息

msgType： gps_real_upload

{

"msgType": "gps_real_upload",

: ,

"deviceId" "V20260714001"

"timestamp": "2026-07-14 11:35:20",

"data": {

"longitude": 120.123456,

"latitude": 30.654321,

"signalRssi": -65,

"posAccuracy": 5,

"speed": 0,

"direction": 0

}

字段	说明
signalRssi	4G/WiFi 信号强度，负数，数值越大信号越好
posAccuracy	定位误差，单位米
speed	移动速度 km/h

十五、设备历史定位查询

1. 平台下发查询指令

msgType： query_history_gps

2. 终端上行返回历史定位轨迹

msgType： upload_history_gps

文本框: } }

附件：全量消息类型清单

消息流向	msgType	业务功能
终端上行	common_ack	所有下行指令通用应答
平台下行	av_param_set	终端音视频参数配置
平台下行	alarm_sleep_param_set	报警录像、 AI 分析、休眠唤醒参数配置
平台下行	query_device_attr	查询终端硬件音视频属性
终端上行	upload_device_attr	上报终端硬件音视频能力
终端上行	video_alarm_upload	视频各类报警主动上报
平台下行	real_stream_req	实时音视频预览请求
平台下行	real_stream_ctrl	预览流启停、码流切换控制
平台下行	query_record_list	查询本地录像文件目录
终端上行	upload_record_list	返回录像文件列表
平台下行	record_play_req	历史录像回放下发请求
平台下行	record_upload_req	FTP 录像文件上传指令
终端上行	upload_record_result	录像文件上传完成上报
终端上行	gps_real_upload	设备实时定位定时上报
平台下行	query_history_gps	查询设备历史定位轨迹
终端上行	upload_history_gps	返回设备历史定位数据