跳到主要内容
版本:1.0.0

EDV21C MQTT 协议说明

本协议定义 EDV21C 的 MQTT 通信:设备上行遥测(occupancy/status/targets/zones/info/fall)、服务器下行配置与控制(reboot/ota/factory_reset)。数据格式 JSON,topic 前缀 edv21c/{device_id}/。

修改说明日期备注
修改5.1 上行 topic(设备 -> 服务器)occupancy、status、targets、zones、info、fall指令,例:edv21c/{device_id}/telemetry/radar/occupancy​改为edv21c/{device_id}/telemetry/occupancy​260608基于260527版本修改为当前服务器实际使用的不包含radar路径的topic
新增 control/factory_reset 恢复出厂设置主题260721支持MQTT远程触发恢复出厂设置,响应到control/result

1. 适用范围​

本文档定义 EDV21C 项目的 MQTT 通信协议,包括:

  1. 设备上行状态与目标数据上报

  2. 服务器下行配置读取与设置

  3. 控制类命令

MQTT 使用单个客户端连接同时完成发布与订阅。

2. 协议概述​

项目说明
网络层Wi-Fi STA
传输层TCP
应用层MQTT
设备角色MQTT Client
数据格式JSON
topic 前缀edv21c/{device_id}/​

3. 设备标识规则​

本协议 topic 中的 {device_id}​ 表示设备标识。

设备标识取设备 Wi-Fi STA MAC,转换为 12 位小写十六进制字符串,不带分隔符。

示例:

84f70312ab56

4. 连接与运行约束​

设备满足以下条件时,才建立 MQTT 连接:

  1. 已启用 MQTT 功能

  2. 已完成路由器 Wi-Fi 名称配置

  3. 已完成 MQTT 服务器地址配置

  4. 已完成 MQTT 服务器端口配置

  5. 控制板当前处于正常通信模式

控制板通信模式取值约定如下:

  • 0​:正常通信模式

  • 1​:TCP 透传模式

说明:

  1. 正常通信模式下,MQTT 正常发布与订阅

  2. TCP 透传模式下,控制板进入 TCP 与雷达串口双向透传

  3. 进入 TCP 透传模式后,MQTT 应主动退出运行态

  4. 处于 TCP 透传模式时,其它通信通道只允许查询控制板当前通信模式并执行模式切换,不允许再向雷达下发普通业务配置

5. Topic 定义​

5.1 上行 topic(设备 -> 服务器)​

Topic用途
edv21c/{device_id}/telemetry/occupancy​专门的有无人结果上报
edv21c/{device_id}/telemetry/status​状态摘要
edv21c/{device_id}/telemetry/targets​当前目标列表
edv21c/{device_id}/telemetry/zones​感应区 / 屏蔽区配置快照
edv21c/{device_id}/telemetry/info​雷达扩展信息
edv21c/{device_id}/telemetry/fall​跌倒状态
edv21c/{device_id}/config/response/device​控制板侧配置响应
edv21c/{device_id}/config/response/radar​雷达侧配置响应
edv21c/{device_id}/control/result​控制命令结果

5.2 下行 topic(服务器 -> 设备)​

Topic用途
edv21c/{device_id}/config/get/device​查询控制板侧配置
edv21c/{device_id}/config/set/device​设置控制板侧配置
edv21c/{device_id}/config/get/radar​查询雷达侧配置
edv21c/{device_id}/config/set/radar​设置雷达侧配置
edv21c/{device_id}/control/reboot​重启控制命令
edv21c/{device_id}/control/ota​OTA 升级命令
edv21c/{device_id}/control/factory_reset​恢复出厂设置

5.3 QoS / Retain 建议​

TopicQoSRetain说明
telemetry/occupancy​0​0​实时有无人结果
telemetry/status​0​0​实时状态摘要
telemetry/targets​0​0​实时目标快照
telemetry/zones​1​1​区域配置快照
telemetry/info​1​1​雷达信息快照
telemetry/fall​0​0​实时跌倒状态
config/response/*​1​0​请求响应
control/result​1​0​控制结果
config/get/*​1​0​查询请求
config/set/*​1​0​配置请求
control/reboot​1​0​控制请求
control/ota​1​0​OTA控制请求
control/factory_reset​1​0​恢复出厂请求

6. 上行 payload 定义​

6.1 telemetry/status​​

字段类型说明
ts_ms​int64时间戳,毫秒
seq​uint32数据更新序号
occupied​bool当前是否检测到目标
target_count​uint32当前目标条目数
wifi_ready​boolWiFi 是否就绪
mqtt_connected​boolMQTT 连接状态
sw_version​string软件版本
hw_version​string硬件版本
board_info​string板级信息
work_mode​uint32雷达工作模式
report_period_ms​uint32雷达上报周期,ms
comm_mode​uint32控制板通信模式
router_ssid​string路由器 SSID
mqtt_report_period_ms​uint32MQTT 上报周期,ms

示例:

{
"ts_ms": 1747279000123,
"seq": 863,
"device_id": "a0f2629e0918",
"occupied": true,
"fall_state": 0,
"target_count": 2,
"wifi_ready": true,
"mqtt_connected": true,
"sw_version": "V1.3.10",
"hw_version": "V2.0.0",
"board_info": "EDV21C-W-V2.0",
"work_mode": 0,
"report_period_ms": 1000,
"comm_mode": 0,
"router_ssid": "easydetek-2.4G",
"mqtt_report_period_ms": 5000
}

6.2 telemetry/occupancy​​

字段类型说明
ts_ms​int64时间戳
seq​uint32更新序号
occupied​bool当前是否有人
source​string结果来源,固定为 radar​

说明:

  1. 该 topic 专门用于上报最终有无人结果

  2. 服务器只关心有无人状态时,优先订阅该 topic

  3. 该 topic 不携带目标列表和区域配置

示例:

{
"ts_ms": 1747279000234,
"seq": 863,
"occupied": true,
"source": "radar"
}

6.3 telemetry/targets​​

字段类型说明
ts_ms​int64时间戳
seq​uint32更新序号
occupied​bool当前是否有目标
zone_count​uint32当前有结果的感应区数量
zones​array按感应区分组的目标结果

单个感应区结果字段:

字段类型说明
zone_id​uint32感应区 ID
target_count​uint32当前感应区内的目标条目数
targets​array当前感应区的目标列表

单个目标字段:

字段类型说明
target_id​uint32目标 ID
x_mm​int32X 坐标,mm
y_mm​int32Y 坐标,mm
z_mm​int32Z 坐标,mm

6.4 telemetry/zones​​

字段类型说明
ts_ms​int64配置快照时间戳
work_mode​uint32雷达工作模式
report_period_ms​uint32上报周期
detect_boundary​object三维检测边界
sensing_zone_count​uint32感应区数量
sensing_zones​array感应区列表
shield_zone_count​uint32屏蔽区数量
shield_zones​array屏蔽区列表

6.5 telemetry/info​​

字段类型说明
ts_ms​int64时间戳
board_model​string设备型号
sw_version​string软件版本
hw_version​string硬件版本
board_info​string板级信息
mqtt_topic_prefix​stringMQTT Topic 前缀
radar_ext_info​string雷达扩展信息

6.6 telemetry/fall​​

字段类型说明
ts_ms​int64时间戳
fall_state​uint320=正常​,1=疑似跌倒​,2=确认跌倒​

6.7 control/result​​

字段类型说明
req_id​string请求 ID(透传)
ts_ms​int64时间戳
success​bool操作是否成功
action​string操作类型(reboot/ota/factory_reset)
message​string结果说明

7. 下行 payload 定义​

7.1 control/reboot​​

请求字段:

字段类型必选说明
req_id​string是请求 ID
ts_ms​int64是时间戳

请求示例:

{
"req_id": "reboot-001",
"ts_ms": 1747279005000
}

响应(control/result​):

{
"req_id": "reboot-001",
"ts_ms": 1747279005100,
"success": true,
"action": "reboot",
"message": "restarting"
}

7.2 control/ota​​

请求字段:

字段类型必选说明
req_id​string是请求 ID
ts_ms​int64是时间戳
firmware_url​string否固件下载 URL(直接下发时使用)

请求示例:

{
"req_id": "ota-001",
"ts_ms": 1747279006000
}

7.3 control/factory_reset​​

请求字段:

字段类型必选说明
req_id​string是请求 ID
ts_ms​int64是时间戳

说明:

  1. 设备收到后立即响应 control/result​(success=true, action=factory_reset)

  2. 随后执行:雷达复位 → IOT 复位 → 擦除 NVS → 重启

  3. 重启后所有参数恢复出厂默认值

请求示例:

{
"req_id": "factory-reset-001",
"ts_ms": 1747279007000
}

响应(control/result​):

{
"req_id": "factory-reset-001",
"ts_ms": 1747279007100,
"success": true,
"action": "factory_reset",
"message": "resetting"
}