4G 设备接入协议文档

版本：v1.0
更新时间：2026-06-29
平台：中净 IoT 管理平台

1. 架构概述

                         EMQX (MQTT Broker 5.8.9)
                        /                      \
                  (设备主动上报)            (平台指令下发)
                       |                          |
          HTTP Webhooks (POST)           EMQX REST API v5
                       |                          |
            MqttWebhookController       EmqxRestClient.publish()
              /      |      \                 |
         telemetry  event  status      cmd/{deviceKey}/set
             |         |       |
        TelemetryBuffer    |     Redis (device:status:{key})
             |     MqttEventWorker
        TDengine (batch      |
          写入 5s 定时)   AlertRecord 持久化

接入信息

项目	值
MQTT Broker 地址	`mqtt.iot.devyunmu.com:1883`（TCP）
协议	MQTT v3.1.1 / v5.0
传输层	TCP，无 TLS（设备端 4G 模块需确认支持）
认证方式	平台预注册 deviceKey，连接时平台进行二次校验

2. MQTT 连接规范

2.1 连接参数

参数	要求
Client ID	设备的 `deviceKey`，长度 8~32 位大写字母和数字，正则可表示为 `[A-Z0-9]{8,32}`
Username	可为空
Password	平台全局固定密钥 `iot_default_secret`（此为默认值，可在平台配置中修改）
Keep Alive	建议 60 秒
Clean Session	`true`（设备不持久化离线消息）

2.2 认证流程

设备 → EMQX: CONNECT(clientId=DEVICE001, password=***)
  ↓
EMQX → 平台: GET /iot/mqtt/auth?clientid=DEVICE001&password=***
  ↓
平台: 1. 查询 MySQL iot_device 表验证 deviceKey 是否存在
      2. 校验 password === iot_default_secret
      3. 返回 200 → EMQX 允许连接

认证端点 GET /iot/mqtt/auth 已在网关白名单中，无需鉴权
认证通过后设备自动绑定，无需额外的注册报文

2.3 上下线状态

设备上线：EMQX 自动触发 client.connected 事件 → 平台更新 Redis device:status:{deviceKey} → {online} → 记录日志
设备下线：EMQX 自动触发 client.disconnected 事件 → 平台更新 Redis 状态 → {offline} → 记录日志
检测依赖 MQTT Keep Alive + EMQX 心跳超时（1.5 倍 Keep Alive 间隔）

3. 数据上报

设备通过发布任意 MQTT Topic 上报数据，EMQX 通过规则引擎将消息内容转发到平台的 HTTP Webhook 接口。设备无需关心 Topic，只需正确填写 JSON Body。

3.1 遥测数据（Telemetry）

接口：POST /iot/mqtt/telemetry

设备周期性上报运行状态，频率建议 30~300 秒/次（按业务场景调整）。

请求体（JSON）：

{
  "deviceKey": "DEVICE001",
  "temperature": 25.5,
  "workStatus": 1,
  "heaterStatus": 1,
  "pumpStatus": 0,
  "workCountdown": 3600,
  "workDuration": 7200,
  "signalStrength": -65,
  "fwVersion": "1.2.0",
  "ts": 1719648000000
}

字段说明：

字段	类型	必填	说明
`deviceKey`	String	是	设备编号，8~32 位大写字母数字
`temperature`	Double	否	当前温度（℃），范围 -20~150
`workStatus`	Integer	否	工作状态：0=待机, 1=加热中, 2=喷洒中
`heaterStatus`	Integer	否	加热器状态：0=关闭, 1=开启
`pumpStatus`	Integer	否	水泵状态：0=关闭, 1=开启
`workCountdown`	Integer	否	剩余工作时间（秒）
`workDuration`	Integer	否	已工作时间（秒）
`signalStrength`	Integer	否	信号强度（RSSI），范围 -120~-30 dBm
`fwVersion`	String	否	固件版本号，格式 major.minor.patch
`ts`	Long	否	数据采集时间戳（epoch ms），缺省时平台填充接收时间

处理流程：

平台接收后写入 TelemetryBuffer（内存队列，容量 10000）
每 5 秒批量写入 TDengine 时序库 iot.telemetry 超级表，每个设备自动创建子表
同步更新 Redis 哈希 device:status:{deviceKey}，提供毫秒级实时状态查询
后台触发 DiagnosticService 校验告警规则（如温度超过阈值自动产生告警记录）

3.2 事件上报（Event）

接口：POST /iot/mqtt/event

设备在发生特定事件时主动上报。

请求体（JSON）：

{
  "deviceKey": "DEVICE001",
  "eventType": "overheat",
  "message": "设备温度过高，当前值：95.2℃",
  "severity": 2,
  "ts": 1719648000000
}

支持的 eventType：

eventType	说明	处理逻辑
`overheat`	过热告警	1. 发布 `AlarmTriggeredEvent` 领域事件 2. 持久化 `iot_alert_record`（severity 默认 2）
`offline`	设备离线	1. 更新 `iot_device.last_online_at` 2. 发布 `DeviceDisconnectedEvent`
`ota_result`	OTA 升级结果	1. 更新 `iot_device_ota_task.status` 2. status=2 成功 / 3 失败 3. 失败时创建告警记录

severity 级别：

值	级别
1	提示（Info）
2	警告（Warning）
3	严重（Critical）

3.3 上下线状态通知

接口：POST /iot/mqtt/status

由 EMQX 内置事件自动触发，设备无需主动调用。

请求体（JSON）：

{
  "deviceKey": "DEVICE001",
  "statusEvent": "client.connected",
  "ts": 1719648000000
}

statusEvent 取值：

值	说明
`client.connected`	设备上线
`client.disconnected`	设备断开（含 Keep Alive 超时）

4. 指令下发（Downlink）

平台通过 EMQX REST API 向指定设备下发指令。

4.1 设备订阅 Topic

设备需订阅以下 Topic 接收平台指令：

cmd/{deviceKey}/set

例如 cmd/DEVICE001/set。

4.2 指令格式

Topic：cmd/{deviceKey}/set
QoS：1（建议）
Payload（JSON）：

{
  "cmdId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "START",
  "params": {
    "temperature": 60,
    "duration": 7200
  },
  "issuedAt": 1719648000000
}

4.3 指令类型

type	说明	params
`START`	启动设备	`{"temperature": 60, "duration": 7200}`
`STOP`	停止设备	`{}`
`SET_TEMPERATURE`	设置目标温度	`{"temperature": 60}`
`SET_PUMP_DUTY`	设置水泵占空比	`{"duty": 80}`（0~100）
`SET_WORK_DURATION`	设置工作时长	`{"duration": 3600}`（秒）
`MAINTENANCE`	维护模式	`{"action": "reset"}`
`QUERY_STATUS`	查询设备状态	`{}`（设备应回复完整遥测数据）
`OTA_UPGRADE`	OTA 升级	`{"url": "http://...", "md5": "abcdef...", "version": "2.0.0"}`
`OTA_QUERY_VERSION`	查询当前固件版本	`{}`

4.4 设备响应

设备在收到指令后，应根据指令类型进行相应操作，并通过遥测上报或事件上报反馈执行结果：

即时指令（START/STOP/SET_TEMPERATURE）：设备执行后在下一次遥测上报时反映状态变更
查询指令（QUERY_STATUS）：设备应立即上报一次完整遥测数据
OTA 指令：升级完成后通过 ota_result 事件上报结果

5. OTA 升级流程

平台                                           设备
  |                                              |
  |  1. 上传固件包（文件服务）                      |
  |  2. 创建 OTA 任务                              |
  |  3. 推送 OTA_UPGRADE 指令 cmd/{key}/set        |
  | ---------------------------------------------> |
  |                                              |
  |                4. 设备下载固件包                |
  |                5. 校验 MD5                     |
  |                6. 安装升级                     |
  |                7. 上报 ota_result 事件         |
  | <--------------------------------------------- |
  |                                              |
  |  8. 更新 iot_device_ota_task.status           |
  |  9. 更新 iot_device.fw_version                |
  |                                              |

数据表结构

iot_ota_package（固件包）：

字段	类型	说明
version	String	版本号，如 `1.2.0`
file_url	String	固件下载地址
file_md5	String	文件 MD5 校验值
file_size	Long	文件大小（字节）
release_note	String	更新说明
status	String	0=草稿, 1=已发布, 2=已归档

iot_device_ota_task（升级任务）：

字段	类型	说明
device_key	String	设备编号
package_id	Long	关联固件包 ID
status	String	0=待升级, 1=升级中, 2=成功, 3=失败
progress	Integer	进度 0~100
error_msg	String	失败原因
start_time	DateTime	任务开始时间
finish_time	DateTime	完成时间

6. 平台 REST API（设备管理）

设备在平台中的管理接口（需 Bearer Token 鉴权，通过 Web 管理后台调用）。

6.1 设备管理

方法	端点	说明
GET	`/device/list`	分页查询设备列表
POST	`/device`	新增设备（预注册 deviceKey）
PUT	`/device`	修改设备信息
DELETE	`/device/{ids}`	批量删除
PUT	`/device/{id}/name`	重命名
GET	`/device/{id}/status`	查询设备实时状态
GET	`/device/list/online`	在线设备统计
POST	`/device/{deviceId}/command`	下发控制指令

6.2 设备绑定

方法	端点	说明
GET	`/binding/list`	分页查询绑定关系
POST	`/binding`	绑定设备到用户
DELETE	`/binding/{ids}`	解绑
GET	`/binding/device/{deviceKey}`	查询指定设备绑定关系
GET	`/binding/user`	查询当前用户绑定设备

6.3 遥测数据

方法	端点	说明
GET	`/device-data/{deviceId}/realtime`	实时遥测（从 Redis 读取）
GET	`/device-data/{deviceId}/history`	历史遥测（从 TDengine 读取
GET	`/device-data/{deviceId}/events`	设备事件
GET	`/device-data/{deviceId}/daily-summary`	日汇总数据

6.4 告警管理

方法	端点	说明
GET	`/alert/rule/list`	告警规则列表
POST	`/alert/rule`	新增告警规则
PUT	`/alert/rule`	修改告警规则
GET	`/alert/record/list`	告警记录
PUT	`/alert/record/{id}/ack`	确认告警

6.5 OTA 管理

方法	端点	说明
GET	`/ota/package/list`	固件包列表
POST	`/ota/package`	上传固件包
PUT	`/ota/package/{id}/publish`	发布固件包
GET	`/ota/task/list`	OTA 任务列表
POST	`/ota/task`	创建升级任务

7. 附录

7.1 deviceKey 校验规则

长度：8~32 字符
字符集：大写英文字母 A-Z + 数字 0-9
正则：^[A-Z0-9]{8,32}$
示例：HD4G24060001、SMART202600001

7.2 温度范围

正常范围：-20℃ ~ 150℃
超过 85℃ 触发过热告警（overheat 事件）

7.3 信号强度等级（RSSI）

范围	等级
-50 dBm 以上	极好
-50 ~ -70 dBm	良好
-70 ~ -85 dBm	一般
-85 ~ -100 dBm	较差
-100 dBm 以下	极差

7.4 固件版本号格式

遵循语义化版本：major.minor.patch[-suffix]

示例：1.0.0、2.1.3-beta
比较规则：从左至右逐段比较数值

7.5 速率限制

遥测上报频率建议 ≥ 10 秒间隔
事件上报无严格要求，但单设备建议 ≤ 10 次/秒
平台 TelemetryBuffer 容量 10000 条，超过时丢弃最旧数据

7.6 MQTT Topic 预留

Topic	方向	用途
`cmd/{deviceKey}/set`	平台 → 设备	指令下发，设备必须订阅
任意 Topic	设备 → 平台	数据上报（EMQX 规则引擎转发，设备无需关心 Topic）

目录

4G 设备接入协议文档

1. 架构概述

接入信息

2. MQTT 连接规范

2.1 连接参数

2.2 认证流程

2.3 上下线状态

3. 数据上报

3.1 遥测数据（Telemetry）

3.2 事件上报（Event）

3.3 上下线状态通知

4. 指令下发（Downlink）

4.1 设备订阅 Topic

4.2 指令格式

4.3 指令类型

4.4 设备响应

5. OTA 升级流程

数据表结构

6. 平台 REST API（设备管理）

6.1 设备管理

6.2 设备绑定

6.3 遥测数据

6.4 告警管理

6.5 OTA 管理

7. 附录

7.1 deviceKey 校验规则

7.2 温度范围

7.3 信号强度等级（RSSI）

7.4 固件版本号格式

7.5 速率限制

7.6 MQTT Topic 预留