二次开发手册
智能硬件-通讯协议说明书
产品命名规则
智能硬件-通讯协议说明书-v2
智能硬件-通讯协议说明书-v3
智能硬件-通讯协议说明书-WPP-v3
倒计时控制器-通讯协议说明书-DWY-v1
云喇叭-通讯协议说明书-v1
计量硬件-通讯协议说明书-WPP-v4
计量硬件-通讯协议说明书-v1
报警器-通讯协议说明书-v1
ARMS
config
tcp-config
mqtt-config
rules
常见问题
如何对接到自己的私有服务器
如何配网
计量硬件-通讯协议说明书-v1
250428
250429
远程开关-说明书
产品需求
计量报警控制设备-需求规划
计量硬件-通讯协议说明书-v2
智能硬件测试教程 HTTP Server 版本
智能硬件测试教程 MQTT Client 版本
智能硬件测试教程 TCP Client 版本
引进新的工业品类
开发新的工业品
尝试与店家沟通
推进智能硬件品类
推进扫码支付品类
推进自助系统品类
完善 SmartHW 项目代码
DTU 项目开发
寻找软硬件供应商
构建产品体系
尝试询问淘宝商家是否愿意推广我的品类
智能硬件新增两款温度计品类
hex版本管理
硬件利润分析
通用-通讯协议说明书-v1
Untitled
智能硬件-通讯协议说明书-WPP-v3
计量硬件-通讯协议说明书-WPP-v4
logic
d2-rc-v1.0-logic
sub-protocol
protocol-rc-v1.5.0
protocol-rc-v1.6.0
protocol-rc-v1.7.0
protocol-rd-v1.5.0
protocol-lock-v1.0.0
protocol-v1.8
protocol-rd-v1.9.0
本文档使用 MrDoc 发布
-
+
首页
protocol-v1.8
# 项目版本: v1.8 *** ## 一、前言 本文档详细说明了智能硬件设备与服务器之间的通信协议规范。主要包含以下内容: 1. 设备标识规则 - 使用 MAC 地址作为设备唯一标识(device_id) - 用于区分不同设备的通信 2. MQTT 与 TCP 通信机制 - 基于发布/订阅模式 (MQTT) 和请求/响应模式 (TCP) - 设备与服务器双向通信 - 支持命令下发与状态上报 3. 命令交互规范 - JSON 格式数据交换 - 完整的命令应答机制 - 标准化的错误处理 4. 动态Ping配置功能(新增) - 用户可动态配置ping消息包含的字段 - 支持从参数和状态对象中选择任意字段 - 特殊字段如WiFi信号强度的动态计算 5. 适用的产品型号 6. 标准术语定义 1. "硬件终端": 指代智能设备上运行的嵌入式系统,其用于与服务器进行通信以及执行各种控制和监控功能。 2. "服务器端": 指代中心服务器,负责接收智能设备上传的数据、下发控制命令并进行数据处理与存储。 3. "应用终端": 指用户操作界面,如手机应用或网页界面,通过它用户可以发送命令到服务器端并查看设备的状态。 7. 支持的协议 1. MQTT: "硬件终端"作为MQTT客户端 2. TCP Client: "硬件终端"作为TCP客户端 3. HTTP Server: "硬件终端"作为HTTP服务端 ## 二、产品型号说明 | 产品型号 | 完整名称 | 硬件能力 | 主要用途 | |---------|---------|---------|---------| | CONV | D2_CONV | 继电器控制、LED指示、按键输入 | 通用转换器设备 | | SOC_P1 | D2_SOC_P1 | 继电器控制、LED指示、电源监控、按键输入 | 智能插座with电量监测 | | BRK_P1 | D2_BRK_P1 | 继电器控制、LED指示、按键输入 | 智能断路器 | | SOD | D2_SOD | LED指示、语音输出、按键输入 | 智能声光设备 | | CBOX_P1 | D2_CBOX_P1 | 继电器控制、LED指示、按键输入 | 智能控制盒 | | RD | D2_RD | 继电器控制、LED指示、语音输出、倒计时显示、按键输入、输入通道 | 智能倒计时器设备 | | SW | D2_SW | 继电器控制、LED指示、按键输入 | 智能开关 | | RC | D2_RC | 脱钩锁控制 | 智能租赁柜 | ## 三、设备标识 (device_id) 8. 用途:代表终端的唯一编号 9. 默认值:设备的主芯片的唯一id ## 四、通信协议 ### 4.1. MQTT 协议 #### 4.1.1. MQTT 协议概要 10. mqtt 通讯基于2个主题,device_id/device_pub_topic与device_id/device_sub_topic 11. "硬件终端"通过device_id/device_pub_topic主题发布数据,"应用终端"通过该主题接收"硬件终端"的数据 12. "硬件终端"通过device_id/device_sub_topic主题接收数据,"应用终端"通过该主题发送数据 ***node***: mqtt主题由device_id动态构成,修改device_id时,将自动修改这两个主题 #### 4.1.2. MQTT 通讯框图 以下图表,展示了"硬件终端"的"事件上报"与"控制终端"的"应用命令请求"或"参数请求"对应的通讯流程图. ```mermaid sequenceDiagram participant HW_MQTT_Client participant MQTT_Server participant APP_MQTT_Client HW_MQTT_Client->>MQTT_Server: 发布消息到 device_pub_topic Note right of HW_MQTT_Client: 事件上报 MQTT_Server->>APP_MQTT_Client: 转发消息 APP_MQTT_Client->>MQTT_Server: 发布控制指令到 device_sub_topic Note right of APP_MQTT_Client: 控制命令或参数请求 MQTT_Server->>HW_MQTT_Client: 转发指令 Note right of MQTT_Server: 设备执行指令 HW_MQTT_Client-->>MQTT_Server: 回复确认或失败信息 MQTT_Server-->>APP_MQTT_Client: 转发应答结果 ``` * HW_MQTT_Client: 硬件终端,MQTT客户端 * MQTT_Server: MQTT 服务器端,一般指客户在阿里云,华为云等云平台构建的MQTT服务器终端 * APP_MQTT_Client: 应用终端,也是MQTT客户端,一般由手机小程序充当 ### 4.2. TCP Client 协议 #### 4.2.1. TCP Client 协议概要 13. TCP Client 代表"硬件终端"作为TCP客户端与"服务器端"进行socket通讯 14. "硬件终端"上电联网完成后,会主动与"服务器端"建立socket #### 4.2.2. TCP Client 通讯框图 以下图表,展示了"硬件终端"的"事件上报"与"应用终端"的"控制命令请求"或"参数请求"对应的通讯流程图. ```mermaid sequenceDiagram participant TCP_Client participant TCP_Server Note over TCP_Server: TCP Server启动并监听端口 Note over TCP_Client: 硬件终端上电初始化 TCP_Client->>TCP_Server: 建立TCP连接 TCP_Server-->>TCP_Client: 连接确认 TCP_Client->>TCP_Server: 发送事件上报数据 TCP_Server-->>TCP_Client: 数据应答 TCP_Server->>TCP_Client: 下发控制指令 TCP_Client-->>TCP_Server: 控制指令执行应答 ``` * TCP_Client: 硬件终端,作为TCP客户端 * TCP_Server: 服务器端,作为TCP服务器 ### 4.3. HTTP Server 协议 #### 4.3.1. HTTP Server 协议概要 15. HTTP Server 代表"硬件终端"启动HTTP服务器,等待其他客户端连接 16. 客户端通过HTTP协议发送POST请求到硬件终端 17. 硬件终端处理请求并返回HTTP响应 #### 4.3.2. HTTP Server 通讯框图 ```mermaid sequenceDiagram participant HTTP_Client participant HTTP_Server Note over HTTP_Server: HTTP Server在硬件终端启动 Note over HTTP_Client: 应用终端作为客户端 HTTP_Client->>HTTP_Server: 发送HTTP POST请求 (控制指令或参数设置) HTTP_Server-->>HTTP_Client: 返回HTTP响应 HTTP_Client->>HTTP_Server: 发送HTTP GET请求 (状态查询或参数获取) HTTP_Server-->>HTTP_Client: 返回HTTP响应 (包含设备状态或参数) ``` * HTTP_Client: 应用终端,如手机APP、网页客户端等 * HTTP_Server: 硬件终端,运行HTTP服务器 ## 五、报文格式 ### 5.1. 控制指令 | 命令 | JSON 格式 | 说明 | 支持型号 | | -------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- | | 打开继电器 | `{"ctrl_cmd":{"open_relay_cmd":"xxxx"}}` | 打开继电器,xxxx为继电器编号,从0开始,如: {"ctrl_cmd":{"open_relay_cmd":"0"}} | CONV, SOC_P1, BRK_P1, CBOX_P1, RD, SW | | 关闭继电器 | `{"ctrl_cmd":{"close_relay_cmd":"xxxx"}}` | 关闭继电器,xxxx为继电器编号,从0开始,如: {"ctrl_cmd":{"close_relay_cmd":"0"}} | CONV, SOC_P1, BRK_P1, CBOX_P1, RD, SW | | 设置继电器状态 | `{"ctrl_cmd":{"set_relay_cmd":true}}` | 设置继电器状态,true: 闭合, false: 断开 | CONV, SOC_P1, BRK_P1, CBOX_P1, RD, SW | | 切换继电器状态 | `{"ctrl_cmd":{"toggle_relay_cmd":"xxxx"}}` | 切换继电器状态,如果当前是闭合的,切换为断开,反之亦然 | CONV, SOC_P1, BRK_P1, CBOX_P1, RD, SW | | 开锁单个脱钩锁 | `{"ctrl_cmd":{"unlock_lock_cmd":"x"}}` | 开锁单个脱钩锁,x为锁编号(0-7),如: {"ctrl_cmd":{"unlock_lock_cmd":"0"}} | RC | | 查询单个锁状态 | `{"ctrl_cmd":{"query_lock_cmd":"x"}}` | 查询单个脱钩锁状态,x为锁编号(0-7),如: {"ctrl_cmd":{"query_lock_cmd":"0"}} | RC | | 恢复出厂设置 | `{"ctrl_cmd":{"factory_params_cmd":"xxxx"}}` | 恢复出厂设置,xxxx参数可以为任意字符串 | ALL | | 重启系统 | `{"ctrl_cmd":{"restart_cmd":"xxxx"}}` | 重启系统,xxxx参数可以为任意字符串 | ALL | | OTA 更新 | `{"ctrl_cmd":{"ota_cmd":{"url":"xxxx"}}}` | OTA 升级,url 为固件升级地址<br>例:`{"ctrl_cmd":{"ota_cmd":{"url":"http://192.168.1.100:8080/firmware.bin"}}}` | ALL | | 播放语音 | `{"ctrl_cmd":{"play_voice_cmd":"xxxx"}}` | 播放语音,xxxx为要播放的文字内容<br>举例:{"ctrl_cmd":{"play_voice_cmd":"欢迎使用智能设备"}} | SOD, RD | | 语音使能 | `{"ctrl_cmd":{"voice_enable_cmd":true}}` | 启用或禁用语音输出功能 | SOD, RD | | 灯光使能 | `{"ctrl_cmd":{"light_enable_cmd":true}}` | 启用或禁用灯光控制功能 | SOD | | 设置灯光模式 | `{"ctrl_cmd":{"set_light_mode_cmd":1}}` | 设置灯光模式<br>0:常亮<br>1:闪烁<br>2:呼吸 | SOD | | 设置语音模式 | `{"ctrl_cmd":{"set_voice_mode_cmd":0}}` | 设置语音播放模式 | SOD, RD | | 设置语音音量 | `{"ctrl_cmd":{"set_voice_volume_cmd":5}}` | 设置语音音量级别<br>范围:1-10 | SOD, RD | | 设置语音语速 | `{"ctrl_cmd":{"set_voice_speed_cmd":5}}` | 设置语音播放速度<br>范围:1-10 | SOD, RD | | 设置语音语调 | `{"ctrl_cmd":{"set_voice_tone_cmd":5}}` | 设置语音音调<br>范围:1-10 | SOD, RD | | 播放提示音 | `{"ctrl_cmd":{"play_prompt_voice_cmd":1}}` | 播放预设的提示音<br>范围:1-5 | SOD, RD | | 播放铃声 | `{"ctrl_cmd":{"play_bell_voice_cmd":1}}` | 播放预设的铃声<br>范围:1-5 | SOD, RD | | 播放警告音 | `{"ctrl_cmd":{"play_warning_voice_cmd":1}}` | 播放预设的警告音<br>范围:1-5 | SOD, RD | | 启动倒计时 | `{"ctrl_cmd":{"start_countdown_cmd":"xxxx"}}` | 启动倒计时功能 | RD | | 停止倒计时 | `{"ctrl_cmd":{"stop_countdown_cmd":"xxxx"}}` | 停止倒计时功能 | RD | | 设置倒计时秒数 | `{"ctrl_cmd":{"set_countdown_s_cmd":60}}` | 设置倒计时时间(秒),设置的时间为倒计时总时长 | RD | | 允许倒计时显示 | `{"ctrl_cmd":{"countdown_display_enable_cmd":true}}` | 启用倒计时数码管显示功能 | RD | | 禁止倒计时显示 | `{"ctrl_cmd":{"countdown_display_disable_cmd":true}}` | 禁用倒计时数码管显示功能 | RD | | 设置倒计时分钟数 | `{"ctrl_cmd":{"set_countdown_cmd":10}}` | 设置倒计时时间(分钟),设置的时间为倒计时总时长 | RD | | 灯光控制 | `{"ctrl_cmd":{"set_light_cmd":1}}` | 设置灯光状态<br>0:关闭<br>1:打开<br>2:闪烁<br>3:呼吸 | SOD | | 灯光闪烁 | `{"ctrl_cmd":{"flash_light_cmd":1}}` | 设置灯光闪烁模式<br>0:停止闪烁<br>1:快闪<br>2:慢闪<br>3:双闪 | SOD | | 开始电量统计 | `{"ctrl_cmd":{"start_power_stat_cmd":{}}}` | 开始电量统计功能 | SOC_P1 | | 结束电量统计 | `{"ctrl_cmd":{"stop_power_stat_cmd":{}}}` | 结束电量统计功能 | SOC_P1 | | 打开继电器组 | `{"ctrl_cmd":{"open_relay_group_cmd":1}}` | 打开指定编号的继电器组 | CONV, SOC_P1, BRK_P1, CBOX_P1, RD, SW | | 关闭继电器组 | `{"ctrl_cmd":{"close_relay_group_cmd":1}}` | 关闭指定编号的继电器组 | CONV, SOC_P1, BRK_P1, CBOX_P1, RD, SW | | 切换继电器组状态 | `{"ctrl_cmd":{"toggle_relay_group_cmd":1}}` | 切换指定编号继电器组的状态 | CONV, SOC_P1, BRK_P1, CBOX_P1, RD, SW | | 清零电量统计 | `{"ctrl_cmd":{"clean_power_wh_cmd":{}}}` | 手动清零电量统计值 | SOC_P1 | ### 5.2. 参数设置&参数获取 | 参数名 | 设置参数 | 获取参数 | 默认值 | 说明 | 支持型号 | | ------------- | -------------------------------------------------------------------- | --------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | 设备 ID | `{"set_param":{"device_id":"dev001"}}` | `{"get_param":{"device_id":{}}}` | 使用 ESP32 芯片 ID | | ALL | | AP SSID | `{"set_param":{"ap_ssid":"SmartDevice_AP"}}` | `{"get_param":{"ap_ssid":{}}}` | "SmartDevice" | | ALL | | AP 密码 | `{"set_param":{"ap_pwd":"12345678"}}` | `{"get_param":{"ap_pwd":{}}}` | "12345678" | | ALL | | 软件版本 | - | `{"get_param":{"soft_ver":{}}}` | 当前版本 | 只读参数 | ALL | | 硬件版本 | - | `{"get_param":{"hard_ver":{}}}` | 当前版本 | 只读参数 | ALL | | 协议版本 | - | `{"get_param":{"protocol_ver":{}}}` | 当前版本 | 只读参数 | ALL | | 参数版本 | - | `{"get_param":{"param_ver":{}}}` | 当前版本 | 只读参数 | ALL | | 编译日期时间 | - | `{"get_param":{"build_datetime":{}}}` | 编译时日期时间 | 只读参数 | ALL | | 完整版本信息 | - | `{"get_param":{"full_ver":{}}}` | 版本信息 | 只读参数,包含所有版本信息的组合字符串 | ALL | | MQTT 服务器 | `{"set_param":{"mqtt_server":"mqtt.example.com"}}` | `{"get_param":{"mqtt_server":{}}}` | "192.168.1.45" | | ALL | | MQTT 端口 | `{"set_param":{"mqtt_port":1883}}` | `{"get_param":{"mqtt_port":{}}}` | 1883 | | ALL | | MQTT 用户名 | `{"set_param":{"mqtt_username":"user"}}` | `{"get_param":{"mqtt_username":{}}}` | "" | | ALL | | MQTT 密码 | `{"set_param":{"mqtt_password":"pass"}}` | `{"get_param":{"mqtt_password":{}}}` | "" | | ALL | | MQTT 客户端 ID | `{"set_param":{"client_id":"client001"}}` | `{"get_param":{"client_id":{}}}` | 基于 MAC 地址生成 | | ALL | | 设备订阅主题 | `{"set_param":{"device_sub_topic":"dev001/sub"}}` | `{"get_param":{"device_sub_topic":{}}}` | "dev001/sub" | | ALL | | 设备发布主题 | `{"set_param":{"device_pub_topic":"dev001/pub"}}` | `{"get_param":{"device_pub_topic":{}}}` | "dev001/pub" | | ALL | | 网络控制台主题 | `{"set_param":{"device_net_console_topic":"dev001/console"}}` | `{"get_param":{"device_net_console_topic":{}}}` | "dev001/console" | | ALL | | TCP 服务器 | `{"set_param":{"tcp_server":"192.168.1.45"}}` | `{"get_param":{"tcp_server":{}}}` | "192.168.1.45" | | ALL | | TCP 端口 | `{"set_param":{"tcp_port":8080}}` | `{"get_param":{"tcp_port":{}}}` | 8080 | | ALL | | HTTP 端口 | `{"set_param":{"http_port":80}}` | `{"get_param":{"http_port":{}}}` | 80 | | ALL | | OTA 标志 | `{"set_param":{"ota_f":true}}` | `{"get_param":{"ota_f":{}}}` | true | OTA 升级标志位,true:允许 OTA,false:禁止 OTA | ALL | | 网络控制台使能 | `{"set_param":{"net_console_en":true}}` | `{"get_param":{"net_console_en":{}}}` | false | 启用网络控制台功能,可通过 MQTT 发送调试命令 | ALL | | 串口控制台使能 | `{"set_param":{"com_console_en":true}}` | `{"get_param":{"com_console_en":{}}}` | true | 启用串口控制台功能,可通过串口发送调试命令 | ALL | | Ping 功能使能 | `{"set_param":{"ping_en":true}}` | `{"get_param":{"ping_en":{}}}` | true | 启用 Ping 主动上报功能 | ALL | | Ping 上报间隔 | `{"set_param":{"ping_interval_s":30}}` | `{"get_param":{"ping_interval_s":{}}}` | 60 | Ping 消息上报间隔,单位:秒 | ALL | | Ping 字段配置 | `{"set_param":{"ping_fields":["device_id","full_ver","rssi_abs","voltage_v"]}}` | `{"get_param":{"ping_fields":{}}}` | ["device_id","full_ver","rssi_abs"] | 配置ping消息包含的字段列表(JSON数组格式,推荐)或逗号分隔字符串(兼容格式),可选择任意param或status字段,支持特殊字段如rssi_abs | ALL | | WiFi SSID | `{"set_param":{"wifi_ssid":"xxxx"}}` | `{"get_param":{"wifi_ssid":{}}}` | "88888888" | | ALL | | WiFi密码 | `{"set_param":{"wifi_pwd":"xxxx"}}` | `{"get_param":{"wifi_pwd":{}}}` | "88888888" | | ALL | | 继电器状态 | `{"set_param":{"relay":true}}` | `{"get_param":{"relay":{}}}` | true | | CONV, SOC_P1, BRK_P1, CBOX_P1, RD, SW | | 过压阈值 | `{"set_param":{"over_voltage_v_th":250}}` | `{"get_param":{"over_voltage_v_th":{}}}` | 260 | 设置过压保护阈值(单位:V) | SOC_P1 | | 低压阈值 | `{"set_param":{"low_voltage_v_th":200}}` | `{"get_param":{"low_voltage_v_th":{}}}` | 180 | 设置欠压保护阈值(单位:V) | SOC_P1 | | 过流阈值 | `{"set_param":{"over_current_ma_th":2000}}` | `{"get_param":{"over_current_ma_th":{}}}` | 5100 | 设置过流保护阈值(单位:mA) | SOC_P1 | | 欠流阈值 | `{"set_param":{"low_current_ma_th":2000}}` | `{"get_param":{"low_current_ma_th":{}}}` | 100 | 欠流保护阈值(单位:mA) | SOC_P1 | | 过载阈值 | `{"set_param":{"over_power_w_th":2200}}` | `{"get_param":{"over_power_w_th":{}}}` | 1100 | 设置过载保护阈值(单位:W) | SOC_P1 | | 欠载阈值 | `{"set_param":{"low_power_w_th":2200}}` | `{"get_param":{"low_power_w_th":{}}}` | 100 | 设置欠载保护阈值(单位:W) | SOC_P1 | | 过温阈值 | `{"set_param":{"over_temperature_c_th":75}}` | `{"get_param":{"over_temperature_c_th":{}}}` | 60 | 设置过温保护阈值(单位:℃) | RD | | 欠温阈值 | `{"set_param":{"low_temperature_c_th":75}}` | `{"get_param":{"low_temperature_c_th":{}}}` | 5 | 设置过温保护阈值(单位:℃) | RD | | 电压值 | - | `{"get_param":{"voltage_v":{}}}` | - | 只读参数,单位:V | SOC_P1 | | 电流值 | - | `{"get_param":{"current_ma":{}}}` | - | 只读参数,单位:mA | SOC_P1 | | 功率值 | - | `{"get_param":{"power_w":{}}}` | - | 只读参数,单位:W | SOC_P1 | | 温度值 | - | `{"get_param":{"temperature_c":{}}}` | - | 只读参数,单位:℃ | RD | | 电流校准参数 | `{"set_param":{"current_calibration":100}}` | `{"get_param":{"current_calibration":{}}}` | 0 | 用于校准BL0937测量电流的误差,正值表示增加,负值表示减少,范围: -1000~1000 | SOC_P1 | | 电压校准参数 | `{"set_param":{"voltage_calibration":-50}}` | `{"get_param":{"voltage_calibration":{}}}` | -47 | 用于校准BL0937测量电压的误差,正值表示增加,负值表示减少,范围: -1000~1000 | SOC_P1 | | 温度校准参数 | `{"set_param":{"temperature_calibration":-50}}` | `{"get_param":{"temperature_calibration":{}}}` | 0 | 用于校准温度检测的误差,正值表示增加,负值表示减少,范围: -1000~1000 | RD | | 用电量 | - | `{"get_param":{"power_consumption_w":{}}}` | - | 只读参数,用电量统计值,单位:W,通过开始电量统计和结束电量统计指令控制统计周期 | SOC_P1 | | 按键锁定 | `{"set_param":{"key_lock":true}}` | `{"get_param":{"key_lock":{}}}` | false | 设置按键锁定状态(true:锁定 false:解锁) | ALL | | 使用静态 IP | `{"set_param":{"use_static_ip":true}}` | `{"get_param":{"use_static_ip":{}}}` | true | 是否启用静态 IP,true:启用,false:关闭 | ALL | | 静态 IP 地址 | `{"set_param":{"static_ip":"192.168.1.100"}}` | `{"get_param":{"static_ip":{}}}` | 192.168.1.199 | 静态 IP 地址,格式如 "192.168.1.100" | ALL | | 网关 IP 地址 | `{"set_param":{"gateway_ip":"192.168.1.1"}}` | `{"get_param":{"gateway_ip":{}}}` | 192.168.1.1 | 网关 IP 地址,格式如 "192.168.1.1" | ALL | | 子网掩码 | `{"set_param":{"subnet_mask":"255.255.255.0"}}` | `{"get_param":{"subnet_mask":{}}}` | 255.255.255.0 | 子网掩码,格式如 "255.255.255.0" | ALL | | 电量统计状态 | | `{"get_param":{"power_stat_en":{}}}` | | 获取电量统计状态<br>true: 统计中<br>false: 没有统计 | SOC_P1 | | 用电量 | | `{"get_param":{"power_wh":{}}}` | 0 | 查询当前统计电量 | SOC_P1 | | 定时打开 | `{"set_param":{"timer_open_relay":10}}` | `{"get_param":{"timer_open_relay":{}}}` | 0 | 设置定时开启继电器倒计时,单位:秒 | CONV, SOC_P1, BRK_P1, CBOX_P1,SW | | 定时关闭 | `{"set_param":{"timer_close_relay":10}}` | `{"get_param":{"timer_close_relay":{}}}` | 0 | 设置定时关闭继电器倒计时,单位:秒 | CONV, SOC_P1, BRK_P1, CBOX_P1,SW | | 定时反转 | `{"set_param":{"timer_toggle_relay":10}}` | `{"get_param":{"timer_toggle_relay":{}}}` | 0 | 设置定时反转继电器倒计时,单位:秒 | CONV, SOC_P1, BRK_P1, CBOX_P1, SW | | 定时打开继电器使能 | `{"set_param":{"timer_open_relay_en":true}}` | `{"get_param":{"timer_open_relay_en":{}}}` | false | 定时打开继电器倒计时使能标志位, true 开始倒计时,当定时结束后,会自动置位为 false,也可以通过这个协议判断当前是否在定时倒计时中 | CONV, SOC_P1, BRK_P1, CBOX_P1, SW | | 定时关闭继电器使能 | `{"set_param":{"timer_close_relay_en":true}}` | `{"get_param":{"timer_close_relay_en":{}}}` | false | 定时关闭继电器倒计时使能标志位, true 开始倒计时,当定时结束后,会自动置位为 false,也可以通过这个协议判断当前是否在定时倒计时中 | CONV, SOC_P1, BRK_P1, CBOX_P1, SW | | 定时反转继电器使能 | `{"set_param":{"timer_toggle_relay_en":true}}` | `{"get_param":{"timer_toggle_relay_en":{}}}` | false | 定时反转继电器倒计时使能标志位, true 开始倒计时,当定时结束后,会自动置位为 false,也可以通过这个协议判断当前是否在定时倒计时中 | CONV, SOC_P1, BRK_P1, CBOX_P1, SW | | GPIO 通道去抖时间 | `{"set_param":{"gpio_ch_debounce_ms":100}}` | `{"get_param":{"gpio_ch_debounce_ms":{}}}` | 100 | GPIO 通道去抖时间,单位:ms | RD | | GPIO 通道触发有效次数 | `{"set_param":{"gpio_ch_tri_cnt":3}}` | `{"get_param":{"gpio_ch_tri_cnt":{}}}` | 3 | GPIO 通道触发有效次数,只有当触发次数大于等于该值时,才认为通道触发有效 | RD | | GPIO 通道触发模式 | `{"set_param":{"gpio_ch_tri_mode":0}}` | `{"get_param":{"gpio_ch_tri_mode":{}}}` | 0 | 0:低电平触发,1:高电平触发 | RD | | ADC 通道触发阈值 | `{"set_param":{"adc_ch_tri_th":2048}}` | `{"get_param":{"adc_ch_tri_th":{}}}` | 2048 | ADC 通道触发阈值 | RD | | ADC 通道去抖时间 | `{"set_param":{"adc_ch_debounce_ms":100}}` | `{"get_param":{"adc_ch_debounce_ms":{}}}` | 100 | ADC 通道去抖时间,单位:ms | RD | | ADC 通道触发有效次数 | `{"set_param":{"adc_ch_tri_cnt":3}}` | `{"get_param":{"adc_ch_tri_cnt":{}}}` | 3 | ADC 通道触发有效次数,只有当触发次数大于等于该值时,才认为通道触发有效 | RD | | ADC 通道触发模式 | `{"set_param":{"adc_tri_th_mode":0}}` | `{"get_param":{"adc_tri_th_mode":{}}}` | 0 | 0:大于等于阈值触发,1:小于等于阈值触发 | RD | | 语音使能 | `{"set_param":{"voice_enable":true}}` | `{"get_param":{"voice_enable":{}}}` | true | 启用或禁用语音输出功能 | SOD, RD | | 语音音量 | `{"set_param":{"voice_volume":5}}` | `{"get_param":{"voice_volume":{}}}` | 5 | 设置语音音量级别(1-10) | SOD, RD | | 语音语速 | `{"set_param":{"voice_speed":5}}` | `{"get_param":{"voice_speed":{}}}` | 5 | 设置语音播放速度(1-10) | SOD, RD | | 语音语调 | `{"set_param":{"voice_tone":5}}` | `{"get_param":{"voice_tone":{}}}` | 5 | 设置语音音调(1-10) | SOD, RD | | 语音模式 | `{"set_param":{"voice_mode":0}}` | `{"get_param":{"voice_mode":{}}}` | 0 | 设置语音播放模式 | SOD, RD | | 倒计时显示使能 | `{"set_param":{"countdown_display_enable":true}}` | `{"get_param":{"countdown_display_enable":{}}}}` | true | 启用或禁用倒计时数码管显示 | RD | | LED控制使能 | `{"set_param":{"light_ctrl_en":true}}` | `{"get_param":{"light_ctrl_en":{}}}` | false | 启用或禁用LED控制功能 | SOD | | LED闪烁频率 | `{"set_param":{"light_hz_ms":500}}` | `{"get_param":{"light_hz_ms":{}}}` | 500 | 设置LED闪烁周期,单位:毫秒 | SOD | ### 5.3. 状态设置&状态获取 状态(Status)与参数(Param)的区别: 1. 状态是运行时的实时数据, 如当前电压、电流等测量值, 这些数据断电后不会保存 2. 当设备收到状态获取命令后, 会返回对应的状态值, 具体格式请参考: [[#5.6. 消息应答]] | 命令 | 设置状态 | 获取状态 | 说明 | 支持型号 | | -------- | --------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------- | ------------------------------------- | | WiFi信号强度 | - | `{"get_status":{"rssi_abs":{}}}` | 只读参数,WiFi信号强度的绝对值:<br>50: 非常好<br>60~70: 好<br>70~80: 一般<br>80~90: 差 | ALL | | 继电器状态 | - | `{"get_status":{"relay":{}}}` | 只读参数,继电器状态:<br>true: 闭合<br>false: 断开 | CONV, SOC_P1, BRK_P1, CBOX_P1, RD, SW | | 继电器组状态 | `{"set_status":{"relays":[true,false,true]}}` | `{"get_status":{"relays":{}}}` | 获取所有继电器状态数组:<br>返回格式: [true,false,true]<br>数组索引从0开始,对应继电器编号0,1,2... | CONV, SOC_P1, BRK_P1, CBOX_P1, RD, SW | | 电压值 | - | `{"get_status":{"voltage_v":{}}}` | 只读参数,当前电压值,单位:V | SOC_P1 | | 电流值 | - | `{"get_status":{"current_ma":{}}}` | 只读参数,当前电流值,单位:mA | SOC_P1 | | 功率值 | - | `{"get_status":{"power_w":{}}}` | 只读参数,当前功率值,单位:W | SOC_P1 | | 温度值 | - | `{"get_status":{"temperature_c":{}}}` | 只读参数,当前温度值,单位:℃ | | | 倒计时显示状态 | - | `{"get_status":{"countdown_display_enable":{}}}` | 只读参数,倒计时显示是否启用 | RD | | 倒计时显示值 | - | `{"get_status":{"countdown_display_value":{}}}` | 只读参数,当前倒计时显示值 | RD | | LED控制状态 | - | `{"get_status":{"light_ctrl_en":{}}}` | 只读参数,LED控制是否启用 | SOD | | LED闪烁频率 | - | `{"get_status":{"light_hz_ms":{}}}` | 只读参数,LED闪烁频率,单位:毫秒 | SOD | | 脱钩锁状态组 | `{"set_status":{"locks":[true,false,true,false,true,true,true,true]}}` | `{"get_status":{"locks":{}}}` | 设置/获取所有脱钩锁状态数组:<br>返回格式: [true,false,true,false,true,false,true,false]<br>数组索引从0开始,对应锁编号0-7<br>true: 开锁操作/开锁状态, false: 保持当前状态/锁定状态 | RC | ### 5.4. 事件上报 | 事件类型 | JSON 格式 | 说明 | 支持型号 | | ---------- | ---------------------------------------------------- | ---------------------- | ------------------------------------- | | OTA 更新完成事件 | `{"event":{"ota_end_evt":"更新结果"}}` | OTA 升级完成后上报结果 | ALL | | 上电事件 | `{"event":{"powerup_evt":""}}` | 设备上电时上报 | ALL | | 重启事件 | `{"event":{"reboot_evt":""}}` | 设备重启时上报 | ALL | | 恢复出厂设置事件 | `{"event":{"factory_params_evt":""}}` | 恢复出厂设置时上报 | ALL | | 系统信息上报事件 | `{"event":{"report_sysinfo_evt":"系统信息"}}` | 上报系统所有可获取参数 | ALL | | 继电器状态变化事件 | `{"event":{"relay_state_change_evt":"状态"}}` | 继电器状态发生改变时上报 | CONV, SOC_P1, BRK_P1, CBOX_P1, RD, SW | | 断电事件 | `{"event":{"powerdown_evt":""}}` | 设备断电时上报 | ALL | | 电流过流事件 | `{"event":{"current_over_evt":"当前电流"}}` | 当检测到电流超过阈值时上报 | SOC_P1 | | 电流欠流事件 | `{"event":{"current_low_evt":"当前电流"}}` | 当检测到电流低于阈值时上报 | SOC_P1 | | 过流恢复事件 | `{"event":{"current_oeve_recovery_evt":"当前电流"}}` | 电流恢复正常后上报 | SOC_P1 | | 欠流恢复事件 | `{"event":{"current_low_recovery_evt":"当前电流"}}` | 电流恢复正常后上报 | SOC_P1 | | 电压过压事件 | `{"event":{"voltage_over_evt":"当前电压"}}` | 当检测到电压超过阈值时上报 | SOC_P1 | | 电压欠压事件 | `{"event":{"voltage_low_evt":"当前电压"}}` | 当检测到电压低于阈值时上报 | SOC_P1 | | 过压恢复事件 | `{"event":{"voltage_over_recovery_evt":"当前电压"}}` | 电压恢复正常后上报 | SOC_P1 | | 欠压恢复事件 | `{"event":{"voltage_low_recovery_evt":"当前电压"}}` | 电压恢复正常后上报 | SOC_P1 | | 功率过载事件 | `{"event":{"power_over_evt":"当前功率"}}` | 当检测到功率超过阈值时上报 | SOC_P1 | | 功率欠载事件 | `{"event":{"power_low_evt":"当前功率"}}` | 当检测到功率低于阈值时上报 | SOC_P1 | | 功率恢复事件 | `{"event":{"power_over_recovery_evt":"当前功率"}}` | 功率恢复正常后上报 | SOC_P1 | | 功率欠载恢复事件 | `{"event":{"power_low_recovery_evt":"当前功率"}}` | 功率恢复正常后上报 | SOC_P1 | | 温度过温事件 | `{"event":{"temperature_over_evt":"当前温度"}}` | 温度过温后上报 | | | 温度欠温事件 | `{"event":{"temperature_low_evt":"当前温度"}}` | 温度低温后上报 | | | 过温恢复事件 | `{"event":{"temperature_over_recovery_evt":"当前温度"}}` | 温度过温恢复后上报 | | | 欠温恢复事件 | `{"event":{"temperature_low_recovery_evt":"当前温度"}}` | 温度低温恢复后上报 | | | 按键短按 | `{"event":{"key_id":0,"short_click_evt":{}}}` | 按键0被短按时触发,key_id:按键编号 | ALL | | 按键长按 | `{"event":{"key_id":0,"long_click_evt":{}}}` | 按键0被长按时触发,key_id:按键编号 | ALL | | 按键超长按 | `{"event":{"key_id":0,"extra_long_click_evt":{}}}` | 按键0被超长按时触发,key_id:按键编号 | ALL | | 按键双击 | `{"event":{"key_id":0,"double_click_evt":{}}}` | 按键0被双击时触发,key_id:按键编号 | ALL | | 按键三击 | `{"event":{"key_id":0,"triple_click_evt":{}}}` | 按键0被三击时触发,key_id:按键编号 | ALL | | 定时打开完成事件 | `{"event":{"timer_open_relay_done_evt":{}}}` | 定时打开继电器倒计时结束时上报 | CONV, SOC_P1, BRK_P1, CBOX_P1, SW | | 定时关闭完成事件 | `{"event":{"timer_close_relay_done_evt":{}}}` | 定时关闭继电器倒计时结束时上报 | CONV, SOC_P1, BRK_P1, CBOX_P1, SW | | 定时反转完成事件 | `{"event":{"timer_toggle_relay_done_evt":{}}}` | 定时反转继电器倒计时结束时上报 | CONV, SOC_P1, BRK_P1, CBOX_P1, SW | | 输入通道触发 | `{"event":{"in_ch":0,"triggered_evt":{}}}` | 通道0,触发 | RD | | 输入通道释放 | `{"event":{"in_ch":0,"released_evt":{}}}` | 通道0,释放 | RD | | 输入通道状态变化 | `{"event":{"in_ch":0,"state_changed_evt":{}}}` | 通道0,状态变化 | RD | | 脱钩锁状态变化事件 | `{"event":{"locks":[true,false,true,false,true,false,true,false]}}` | 当任意脱钩锁状态发生变化时,上报所有锁的当前状态 | RC | | 单个脱钩锁状态变化事件 | `{"event":{"lock_id":0,"lock_state_changed_evt":true}}` | 当特定脱钩锁状态发生变化时上报,lock_id表示锁编号(0-7),true表示开锁状态,false表示锁定状态 | RC | 注意: 1. 按键事件上报中的数值表示按键索引,从0开始 2. 对于多按键产品(如D2_SW),每个按键都有独立的索引 3. 按键事件的触发时间: - 短按:立即触发 - 双击:两次按键间隔小于300ms - 三击:三次按键间隔小于500ms - 长按:按住时间超过3秒 - 超长按:按住时间超过10秒 4. 当按键被锁定时(key_lock=true),所有按键事件将被禁用 5. 对于RC产品: - 脱钩锁编号从0开始(锁编号: 0-7) - 锁状态: true=开锁状态, false=锁定状态 - 脱钩锁控制通过脉冲信号实现开锁操作,不支持上锁操作 - 批量锁状态变化时,上报所有8个锁的状态数组 - 单个锁状态变化时,上报具体的锁编号和状态 ### 5.5. 主动上报 "硬件终端"间隔一定的时间,会往"服务器端",上报的报文 该报文是可选,可使用"参数设置"报文开启或关闭 可通过"参数设置"报文,设置上报时间间隔 **v1.8新增**: 支持动态配置ping消息包含的字段 | 消息类型 | JSON 格式 | 说明 | 支持型号 | | ---- | ------------------------------------------------------------------------------------------ | -------------------- | ---- | | 心跳包 | 动态格式,根据ping_fields参数配置决定包含的字段,具体格式见下方示例 | 包含可配置的设备信息字段,支持从参数和状态对象中选择任意字段 | ALL | #### 5.5.1. Ping字段配置功能 **功能概述**: - 通过`ping_fields`参数动态配置ping消息包含的字段 - 支持选择任意param(参数)或status(状态)对象中的字段 - 支持特殊的动态计算字段,如WiFi信号强度(rssi_abs) - 字段名称以逗号分隔的字符串格式配置 **默认配置**: ```json "ping_fields": "device_id,full_ver,rssi_abs" ``` **配置示例**: 1. **基础配置**: ```json {"set_param":{"ping_fields":"device_id,full_ver,rssi_abs"}} ``` 生成的ping消息: ```json {"ping":{"device_id":"ESP32_123456","full_ver":"v2.1.0","rssi_abs":68}} ``` 2. **扩展配置(SOC_P1产品)**: ```json {"set_param":{"ping_fields":"device_id,full_ver,voltage_v,current_ma,power_w,temperature_c"}} ``` 生成的ping消息: ```json {"ping":{"device_id":"ESP32_123456","full_ver":"v2.1.0","voltage_v":220.5,"current_ma":1024,"power_w":225.5,"temperature_c":25.3}} ``` 3. **参数和状态混合配置**: ```json {"set_param":{"ping_fields":"device_id,mqtt_server,ping_interval_s,rssi_abs,relay,voltage_v"}} ``` 生成的ping消息: ```json {"ping":{"device_id":"ESP32_123456","mqtt_server":"192.168.1.45","ping_interval_s":60,"rssi_abs":72,"relay":true,"voltage_v":220.8}} ``` 4. **最小化配置**: ```json {"set_param":{"ping_fields":["device_id","rssi_abs"]}} ``` 生成的ping消息: ```json {"ping":{"device_id":"ESP32_123456","rssi_abs":65}} ``` **支持的字段类型**: 1. **参数字段(Param)**: - 基础信息:`device_id`, `full_ver`, `soft_ver`, `hard_ver`, `protocol_ver`, `param_ver` - 网络配置:`wifi_ssid`, `mqtt_server`, `mqtt_port`, `tcp_server`, `tcp_port` - 功能设置:`ping_en`, `ping_interval_s`, `ping_fields`, `relay`, `key_lock` - 阈值参数:`over_voltage_v_th`, `low_voltage_v_th`, `over_current_ma_th`, `low_current_ma_th` - 更多参数请参考完整的参数列表... 2. **状态字段(Status)**: - 实时测量:`voltage_v`, `current_ma`, `power_w`, `temperature_c` - 设备状态:`relay`, `relays`, `locks`, `countdown_display_enable` - 更多状态请参考完整的状态列表... 3. **特殊字段**: - `rssi_abs`: WiFi信号强度绝对值,动态计算获得 **特殊字段说明**: | 字段名 | 类型 | 说明 | 示例值 | |--------|------|------|---------| | rssi_abs | 动态计算 | WiFi信号强度绝对值,通过abs(WiFi.RSSI())获得 | 68 (表示-68dBm的绝对值) | **配置注意事项**: 1. 字段名必须与param或status对象中的字段名完全匹配 2. 多个字段用逗号分隔,支持空格(会自动去除) 3. 不存在的字段名会被忽略并记录日志 4. 空配置或无效配置会使用默认配置 5. 数组类型字段暂不支持动态配置 6. 配置更改后立即生效,不需要重启设备 ### 5.6. 消息应答 终端收到服务器下发的消息后,会根据消息执行结果返回对应的应答帧。 应答帧格式如下: | 消息类型 | JSON 格式 | 说明 | 支持型号 | | ------ | --------------------------- | -------------------------------------------------------------------------------------- | ---- | | 确认应答 | `{"ask":true}` | 命令执行成功的应答 | ALL | | 否认应答 | `{"ask":false}` | 命令执行失败的应答 | ALL | | 获取参数应答 | {"get_param":{"name":val}} | 举例:<br>发送`{"get_param":{"device_id":{}}}`<br>返回 `{"ask_param":{"device_id":"dev001"}}` | ALL | | 获取状态应答 | {"get_status":{"name":val}} | 举例:<br>发送`{"get_status":{"voltage_v":{}}}`<br>返回 `{"ask_status":{"voltage_v":220}}`<br>继电器组状态查询:<br>发送`{"get_status":{"relay_group_status":{}}}`<br>返回 `{"ask_status":{"relay_group_status":[true,false,true]}}`<br>脱钩锁状态查询:<br>发送`{"get_status":{"locks":{}}}`<br>返回 `{"ask_status":{"locks":[true,false,true,false,true,false,true,false]}}`<br>单个锁状态查询应答:<br>发送`{"ctrl_cmd":{"query_lock_cmd":"0"}}`<br>返回 `{"ask_status":{"lock_0":true}}` | ALL | | 未知命令 | `{"unknown_cmd":0}` | 收到未知命令时的应答 | ALL | | | | | | | | | | | ## 六、动态Ping配置功能详解(新增) ### 6.1. 功能概述 动态Ping配置功能允许用户自定义ping心跳消息包含的字段内容,实现按需上报,减少不必要的数据传输,提高通信效率。该功能基于PingFieldManager类实现,支持从设备的参数(param)和状态(status)对象中选择任意字段进行组合上报。 **核心特性**: - **灵活配置**:支持任意param和status字段的自由组合 - **双格式支持**:同时支持JSON数组格式(推荐)和逗号分隔字符串格式(兼容) - **动态生效**:配置更改后立即生效,无需重启设备 - **特殊字段**:支持动态计算字段如WiFi信号强度 - **向后兼容**:默认配置保持与旧版本一致的行为 - **高效实现**:采用缓存优化,避免重复解析配置 ### 6.2. 技术架构 ```mermaid graph TB A[ping_fields参数配置] --> B[PingFieldManager] B --> C[配置解析] C --> D[字段分类] D --> E[Param字段] D --> F[Status字段] D --> G[特殊字段] E --> H[动态字段添加] F --> H G --> H H --> I[生成Ping消息] I --> J[发送到服务器] ``` **关键组件**: 1. **PingFieldManager**: 核心管理器,负责解析配置和构建消息 2. **配置解析器**: 将逗号分隔的字符串解析为字段列表 3. **字段解析器**: 识别字段类型(param/status/特殊字段) 4. **消息构建器**: 动态构建JSON ping消息 5. **缓存机制**: 优化重复配置的解析性能 ### 6.3. 使用流程 #### 6.3.1. 基础配置流程 ```mermaid sequenceDiagram participant App as 应用终端 participant Device as 硬件终端 participant Manager as PingFieldManager participant Param as Param对象 participant Status as Status对象 App->>Device: 配置ping字段 {"set_param":{"ping_fields":"device_id,voltage_v,relay"}} Device-->>App: 返回确认 {"ask":true} Note over Device: 配置已保存到参数对象 Device->>Manager: 解析配置字符串 Manager->>Manager: 分割字段列表 Manager->>Param: 检查param字段 Manager->>Status: 检查status字段 Note over Manager: 配置解析完成并缓存 Note over Device: 定时器触发ping上报 Device->>Manager: 构建ping消息 Manager->>Param: 获取device_id字段 Manager->>Status: 获取voltage_v和relay字段 Manager->>Manager: 构建JSON消息 Manager-->>Device: 返回构建的ping消息 Device->>App: 发送ping消息 {"ping":{"device_id":"ESP32_123456","voltage_v":220.5,"relay":true}} ``` #### 6.3.2. 实时配置更新流程 ```mermaid sequenceDiagram participant App as 应用终端 participant Device as 硬件终端 participant Manager as PingFieldManager Note over App,Manager: 设备正在使用默认配置发送ping消息 App->>Device: 更新配置 {"set_param":{"ping_fields":"device_id,rssi_abs,temperature_c"}} Device-->>App: 确认更新 {"ask":true} Note over Device: 下一次ping触发时 Device->>Manager: 构建ping消息 Manager->>Manager: 检测到配置变化,重新解析 Note over Manager: 新配置立即生效 Manager-->>Device: 返回新格式的ping消息 Device->>App: 发送新格式ping {"ping":{"device_id":"ESP32_123456","rssi_abs":72,"temperature_c":25.8}} ``` ### 6.4. 配置格式规范 #### 6.4.1. 支持的配置格式 ping_fields参数支持两种配置格式: **1. JSON数组格式(推荐):** ```json {"set_param":{"ping_fields":["device_id","full_ver","rssi_abs"]}} ``` **2. 逗号分隔字符串格式(兼容):** ```json {"set_param":{"ping_fields":"device_id,full_ver,rssi_abs"}} ``` #### 6.4.2. JSON数组格式详解 **语法规则**: 1. 使用JSON数组格式:`["field1","field2","field3",...]` 2. 每个字段名必须是字符串类型 3. 字段名前后的空格会被自动去除 4. 空字段名或非字符串元素会被忽略 5. 不存在的字段名会被跳过并记录警告日志 #### 6.4.3. 字符串格式兼容性 **语法规则**: 1. 字段名使用英文逗号(`,`)分隔 2. 字段名前后的空格会被自动去除 3. 空字段名会被忽略 4. 重复字段名会被去重处理 5. 不存在的字段名会被跳过并记录警告日志 **有效配置示例**: ```json // 紧凑格式 "ping_fields": "device_id,full_ver,rssi_abs" // 带空格格式(推荐,便于阅读) "ping_fields": "device_id, full_ver, voltage_v, current_ma" // 混合字段类型 "ping_fields": "device_id, mqtt_server, relay, voltage_v, rssi_abs" ``` **无效配置处理**: ```json // 空配置 - 使用默认配置 "ping_fields": "" // 全部为无效字段 - 使用默认配置 "ping_fields": "invalid_field1,invalid_field2" // 部分有效字段 - 只包含有效字段 "ping_fields": "device_id,invalid_field,voltage_v" // 结果只包含device_id和voltage_v ``` ### 6.5. 字段类型详解 #### 6.5.1. 参数字段(Param Fields) 参数字段来源于设备的参数配置对象,通常是设备的配置信息和设置值。 **常用参数字段**: ```json { // 设备标识 "device_id": "ESP32_123456", "full_ver": "v2.1.0_20250819_ESP32", // 网络配置 "wifi_ssid": "MyNetwork", "mqtt_server": "192.168.1.45", "mqtt_port": 1883, // 功能设置 "ping_en": true, "ping_interval_s": 60, "relay": true, // 阈值配置 "over_voltage_v_th": 260, "low_voltage_v_th": 180 } ``` #### 6.5.2. 状态字段(Status Fields) 状态字段来源于设备的实时状态对象,通常是设备的运行时数据和测量值。 **常用状态字段**: ```json { // 实时测量值 "voltage_v": 220.5, "current_ma": 1024, "power_w": 225.5, "temperature_c": 25.3, // 设备状态 "relay": true, "relays": [true, false, true], // 控制状态 "countdown_display_enable": true, "countdown_display_value": 120 } ``` #### 6.5.3. 特殊字段(Special Fields) 特殊字段是系统动态计算或获取的字段,不存储在param或status对象中。 | 字段名 | 数据类型 | 计算方法 | 说明 | 示例值 | |--------|----------|----------|------|--------| | rssi_abs | number | abs(WiFi.RSSI()) | WiFi信号强度绝对值,数值越小信号越强 | 68 | **未来可扩展的特殊字段**: - `uptime_s`: 设备运行时间(秒) - `free_heap`: 剩余内存大小(字节) - `cpu_usage`: CPU使用率(百分比) ### 6.6. 应用场景示例 #### 6.6.1. 最小化传输场景 **需求**:仅传输设备基础标识信息,减少数据传输量 **配置**: ```json {"set_param":{"ping_fields":["device_id","rssi_abs"]}} ``` **效果**: ```json {"ping":{"device_id":"ESP32_123456","rssi_abs":65}} ``` #### 6.6.2. 电源监控场景(SOC_P1产品) **需求**:重点监控设备的电源状态和基础信息 **配置**: ```json {"set_param":{"ping_fields":["device_id","full_ver","voltage_v","current_ma","power_w","over_voltage_v_th","low_voltage_v_th"]}} ``` **效果**: ```json {"ping":{"device_id":"ESP32_123456","full_ver":"v2.1.0","voltage_v":220.5,"current_ma":1024,"power_w":225.5,"over_voltage_v_th":260,"low_voltage_v_th":180}} ``` #### 6.6.3. 网络诊断场景 **需求**:监控设备的网络连接状态和配置 **配置**: ```json {"set_param":{"ping_fields":["device_id","wifi_ssid","mqtt_server","mqtt_port","rssi_abs","static_ip"]}} ``` **效果**: ```json {"ping":{"device_id":"ESP32_123456","wifi_ssid":"MyNetwork","mqtt_server":"192.168.1.45","mqtt_port":1883,"rssi_abs":72,"static_ip":"192.168.1.199"}} ``` #### 6.6.4. 继电器状态监控场景 **需求**:实时监控继电器状态和相关参数 **配置**: ```json {"set_param":{"ping_fields":["device_id","relay","relays","timer_open_relay_en","timer_close_relay_en"]}} ``` **效果**: ```json {"ping":{"device_id":"ESP32_123456","relay":true,"relays":[true,false,true],"timer_open_relay_en":false,"timer_close_relay_en":false}} ``` ### 6.7. 性能优化机制 #### 6.7.1. 配置缓存 **机制说明**: - PingFieldManager采用配置字符串缓存机制 - 只有当配置发生变化时才重新解析 - 避免每次构建ping消息时都解析配置字符串 **实现细节**: ```cpp void PingFieldManager::parseConfig(const char* config) { std::string config_str(config); // 缓存优化:如果配置没有变化,不需要重新解析 if (_config_parsed && config_str == _last_config) { return; } _last_config = config_str; // 执行解析逻辑... } ``` #### 6.7.2. 内存预分配 **机制说明**: - 根据字段数量预分配vector容量 - 减少动态内存分配的开销 **实现细节**: ```cpp // 预分配空间 _param_fields.reserve(fields.size()); _status_fields.reserve(fields.size()); ``` #### 6.7.3. 懒加载状态更新 **机制说明**: - 只有在需要status字段时才调用GetAllStatus()更新状态 - 避免不必要的状态读取操作 ### 6.8. 错误处理机制 #### 6.8.1. 配置错误处理 1. **空配置**: 使用默认配置 2. **无效字段**: 跳过并记录日志 3. **格式错误**: 容错处理,尽量解析有效部分 #### 6.8.2. 运行时错误处理 1. **字段获取失败**: 跳过该字段,继续处理其他字段 2. **内存不足**: 记录错误日志,返回部分结果 3. **类型转换错误**: 记录警告日志,跳过该字段 #### 6.8.3. 日志记录 **调试日志示例**: ``` [PingFieldManager] 解析Ping字段配置: device_id,full_ver,invalid_field,voltage_v [PingFieldManager] 解析到 4 个字段 [PingFieldManager] 添加字段: device_id [PingFieldManager] 添加字段: full_ver [PingFieldManager] 添加字段: invalid_field [PingFieldManager] 添加字段: voltage_v [PingFieldManager] 未知字段: invalid_field ``` ### 6.9. 兼容性说明 #### 6.9.1. 向后兼容 - **默认行为保持不变**: 未配置ping_fields时使用默认值"device_id,full_ver,rssi_abs" - **旧版本消息格式**: 新版本设备可以发送与旧版本相同格式的ping消息 - **参数结构兼容**: 新增的ping_fields参数不影响现有参数结构 #### 6.9.2. 版本升级路径 1. **从v1.5升级到v1.8**: - 自动添加ping_fields参数,默认值保持旧版行为 - 现有ping消息格式保持不变 - 可逐步启用新的字段配置功能 2. **配置迁移**: - 无需特殊迁移操作 - 设备升级后自动适配新功能 ## 七、电量统计功能说明 ### 7.1. 功能概述 电量统计功能用于统计设备在一段时间内的用电量。该功能通过以下方式工作: 1. 通过控制指令开始和结束统计 2. 在统计期间,实时累加用电量 3. 结束统计时,自动清零,为下次统计做准备 **支持型号**: SOC_P1 ### 7.2. 通信流程 ```mermaid sequenceDiagram participant App as 应用终端 participant Device as 硬件终端 App->>Device: 发送开始统计指令 {"ctrl_cmd":{"start_power_stat_cmd":{}}} Device-->>App: 返回确认帧 {"ask":true} Note over Device: 清零统计值并开始累加 App->>Device: 查询当前用电量 {"get_param":{"power_wh":{}}} Device-->>App: 返回当前累计值 {"ask_param":{"power_wh":数值}} App->>Device: 发送结束统计指令 {"ctrl_cmd":{"stop_power_stat_cmd":{}}} Device-->>App: 返回确认帧 {"ask":true} Note over Device: 停止累加并自动清零 ``` ### 7.3. 相关指令说明 | 类型 | 指令 | 说明 | 支持型号 | | ---- | ------------------------------------------ | ------------- | -------- | | 控制指令 | `{"ctrl_cmd":{"start_power_stat_cmd":{}}}` | 开始电量统计 | SOC_P1 | | 控制指令 | `{"ctrl_cmd":{"stop_power_stat_cmd":{}}}` | 结束电量统计 | SOC_P1 | | 状态查询 | `{"get_param":{"power_stat_en":{}}}` | 查询当前是否已开启电量统计 | SOC_P1 | | 用电量 | `{"get_param":{"power_wh":{}}}` | 查询当前已用电量 | SOC_P1 | | 电量清零 | `{"ctrl_cmd":{"clean_power_wh_cmd":{}}}` | 统计电量清零 | SOC_P1 | | | | | | | | | | | ### 7.4. 工作原理 1. 开始统计: - 收到开始指令后,清零统计值并开始累加用电量 2. 结束统计: - 收到结束指令后,停止统计 - 自动清零统计值,为下次统计做准备 3. 查询结果: - 通过状态查询指令可随时获取当前累计用电量 - 单位为瓦时(Wh) ## 八、脱钩锁控制功能说明 ### 8.1. 功能概述 脱钩锁控制功能专用于RC产品(智能租赁柜),用于控制多个独立的脱钩锁。该功能通过以下方式工作: 1. 支持8个独立的脱钩锁控制 2. **只提供开锁功能,不提供锁定功能** 3. 通过脉冲信号控制锁的开启 4. 实时监测锁的状态反馈 5. **支持批量操作和单个操作两种模式** **支持型号**: RC ### 8.2. 硬件特性 - **锁数量**: 8个独立脱钩锁 - **控制方式**: 脉冲信号控制(默认100ms脉冲宽度) - **状态反馈**: 实时状态检测 - **锁编号**: 0-7(对应数组索引0-7) - **功能限制**: 仅支持开锁操作,不支持上锁操作 ### 8.3. 控制方式说明 #### 8.3.1. 批量操作(推荐使用) 通过 `set_status` 指令进行批量锁控制,适合需要同时操作多个锁的场景: ```json {"set_status":{"locks":[true,false,true,false,true,true,true,true]}} ``` - 数组中 `true` 表示对该位置的锁执行开锁操作 - 数组中 `false` 表示保持该锁当前状态不变 - 数组索引0-7对应锁编号0-7 #### 8.3.2. 单个操作 通过 `ctrl_cmd` 指令进行单个锁控制,适合单独操作某个锁的场景: ```json {"ctrl_cmd":{"unlock_lock_cmd":"0"}} // 开锁编号为0的锁 {"ctrl_cmd":{"query_lock_cmd":"0"}} // 查询编号为0的锁状态 ``` ### 8.4. 通信流程 #### 8.4.1. 批量脱钩锁控制流程 ```mermaid sequenceDiagram participant App as 应用终端 participant Device as RC设备 App->>Device: 批量设置锁状态 {"set_status":{"locks":[true,false,true,false,true,true,true,true]}} Device-->>App: 返回确认帧 {"ask":true} Note over Device: 根据数组状态对相应的锁执行开锁操作 Device->>App: 上报锁状态变化事件 {"event":{"locks":[true,false,true,false,true,true,true,true]}} App->>Device: 查询所有锁状态 {"get_status":{"locks":{}}} Device-->>App: 返回所有锁状态 {"ask_status":{"locks":[true,false,true,false,true,true,true,true]}} ``` #### 8.4.2. 单个脱钩锁控制流程 ```mermaid sequenceDiagram participant App as 应用终端 participant Device as RC设备 App->>Device: 开锁单个脱钩锁 {"ctrl_cmd":{"unlock_lock_cmd":"0"}} Device-->>App: 返回确认帧 {"ask":true} Note over Device: 对锁0执行开锁操作 Device->>App: 上报单个锁状态变化 {"event":{"lock_id":0,"lock_state_changed_evt":true}} Device->>App: 上报所有锁状态变化 {"event":{"locks":[true,false,true,false,true,false,true,false]}} App->>Device: 查询单个锁状态 {"ctrl_cmd":{"query_lock_cmd":"0"}} Device-->>App: 返回单个锁状态 {"ask_status":{"lock_0":true}} ``` #### 8.4.3. 锁状态查询流程 ```mermaid sequenceDiagram participant App as 应用终端 participant Device as RC设备 App->>Device: 查询所有锁状态 {"get_status":{"locks":{}}} Device-->>App: 返回所有锁状态 {"ask_status":{"locks":[true,false,true,false,true,false,true,false]}} Note over App: 锁编号0-7,true表示开锁状态,false表示锁定状态 ``` ### 8.5. 相关指令说明 | 类型 | 指令 | 说明 | 支持型号 | | ---- | ----------------------------------------------- | --------------------------- | ---- | | 状态设置 | `{"set_status":{"locks":[true,false,true,false,true,true,true,true]}}` | 批量设置所有锁状态<br>数组索引0-7对应锁编号0-7<br>true: 开锁操作, false: 保持当前状态 | RC | | 状态查询 | `{"get_status":{"locks":{}}}` | 查询所有锁的状态数组 | RC | | 单个开锁 | `{"ctrl_cmd":{"unlock_lock_cmd":"0"}}` | 开锁单个脱钩锁,参数为锁编号(0-7) | RC | | 单个查询 | `{"ctrl_cmd":{"query_lock_cmd":"0"}}` | 查询单个脱钩锁状态,参数为锁编号(0-7) | RC | ### 8.6. 事件说明 | 事件类型 | JSON 格式 | 说明 | 支持型号 | | ------- | ----------------------------------------------- | ------------- | ---- | | 批量锁状态变化事件 | `{"event":{"locks":[true,false,true,false,true,false,true,false]}}` | 任意锁状态发生变化时上报所有锁状态 | RC | | 单个锁状态变化事件 | `{"event":{"lock_id":0,"lock_state_changed_evt":true}}` | 特定锁状态变化时上报,包含锁编号和状态 | RC | ### 8.7. 工作原理 1. **脉冲控制机制**: - 每个锁通过独立的输出引脚发送控制脉冲 - 脉冲宽度默认为100ms - 脉冲电平可配置(默认高电平有效) - 只支持开锁脉冲,不支持上锁脉冲 2. **状态反馈机制**: - 每个锁配备独立的状态检测引脚 - 实时监测锁的开启/锁定状态 - 状态变化时自动上报事件 3. **批量控制优化**: - 支持通过状态设置同时控制多个锁 - 只有设置为true的锁执行开锁操作 - 设置为false的锁保持当前状态不变 4. **单个控制支持**: - 支持通过控制命令操作单个锁 - 解决JSON标准语法不支持设置单个数组元素的限制 - 提供单个锁状态查询功能 5. **安全机制**: - 每次操作后自动检测状态 - 操作失败时上报相应的错误事件 - 支持重试机制 6. **使用说明**: - 锁编号从0开始(0-7),对应数组索引0-7 - 只能执行开锁操作,不能执行锁定操作 - 状态数组中true表示开锁状态,false表示锁定状态 - 批量操作适合多锁同时控制场景 - 单个操作适合精确控制单个锁场景 ## 九、定时功能说明 ### 9.1. 功能概述 定时功能允许设备按预设时间自动执行继电器操作,包括定时打开、定时关闭和定时反转。该功能适用于需要延时控制的应用场景。 **支持型号**: CONV, SOC_P1, BRK_P1, CBOX_P1, SW ### 9.2. 定时器类型 | 定时器类型 | 功能说明 | 参数设置 | 使能控制 | |---------|---------|---------|---------| | 定时打开继电器 | 在设定时间后自动打开继电器 | `timer_open_relay` | `timer_open_relay_en` | | 定时关闭继电器 | 在设定时间后自动关闭继电器 | `timer_close_relay` | `timer_close_relay_en` | | 定时反转继电器 | 在设定时间后自动切换继电器状态 | `timer_toggle_relay` | `timer_toggle_relay_en` | ### 9.3. 使用流程 1. **设置定时时间**:通过参数设置指令配置倒计时间(单位:秒) 2. **启动定时器**:将对应的使能标志位设置为true开始倒计时 3. **监控状态**:通过查询使能标志位了解当前定时状态 4. **自动执行**:倒计时结束后自动执行对应操作并上报事件 ### 9.4. 通信流程 ```mermaid sequenceDiagram participant App as 应用终端 participant Device as 硬件终端 App->>Device: 设置定时时间 {"set_param":{"timer_open_relay":30}} Device-->>App: 返回确认帧 {"ask":true} App->>Device: 启动定时器 {"set_param":{"timer_open_relay_en":true}} Device-->>App: 返回确认帧 {"ask":true} Note over Device: 开始30秒倒计时 App->>Device: 查询定时状态 {"get_param":{"timer_open_relay_en":{}}} Device-->>App: 返回当前状态 {"ask_param":{"timer_open_relay_en":true}} Note over Device: 倒计时结束,自动打开继电器 Device->>App: 上报定时完成事件 {"event":{"timer_open_relay_done_evt":{}}} Device->>App: 上报继电器状态变化 {"event":{"relay_state_change_evt":"true"}} App->>Device: 再次查询定时状态 {"get_param":{"timer_open_relay_en":{}}} Device-->>App: 返回停止状态 {"ask_param":{"timer_open_relay_en":false}} ``` ### 9.5. 注意事项 1. **互斥性**:同一时间只能有一个定时器处于活动状态 2. **自动复位**:定时器执行完成后,使能标志位自动复位为false 3. **状态监控**:可通过查询使能标志位实时了解定时器状态 4. **中断操作**:可通过将使能标志位手动设置为false来中断定时操作 ## 十、MP3音频功能说明 ### 10.1. 功能概述 MP3音频功能支持音频文件的上传、管理和播放。该功能使用专用的MP3协议进行文件传输和播放控制。 **支持型号**: RD ### 10.2. 主要功能 - **文件上传**:支持分块传输大文件 - **文件管理**:支持文件列表查询和删除 - **播放控制**:支持播放、停止、暂停等操作 - **校验机制**:支持文件完整性校验 ### 10.3. 相关指令 | 功能 | 指令格式 | 说明 | 支持型号 | |------|---------|------|---------| | 开始上传 | `{"ctrl_cmd":{"mp3_upload_start_cmd":{"filename":"test.mp3","file_size":1024}}}` | 开始文件上传会话 | RD | | 数据传输 | `{"ctrl_cmd":{"mp3_upload_data_cmd":{"session_id":"xxx","chunk_index":0,"data":"base64data"}}}` | 传输文件数据块 | RD | | 完成上传 | `{"ctrl_cmd":{"mp3_upload_finish_cmd":{"session_id":"xxx"}}}` | 结束上传会话 | RD | | 播放文件 | `{"ctrl_cmd":{"mp3_play_cmd":{"filename":"test.mp3"}}}` | 播放指定文件 | RD | | 停止播放 | `{"ctrl_cmd":{"mp3_stop_cmd":{}}}` | 停止当前播放 | RD | | 暂停播放 | `{"ctrl_cmd":{"mp3_pause_cmd":{}}}` | 暂停当前播放 | RD | | 恢复播放 | `{"ctrl_cmd":{"mp3_resume_cmd":{}}}` | 恢复播放 | RD | | 文件列表 | `{"ctrl_cmd":{"mp3_list_cmd":{}}}` | 获取文件列表 | RD | | 删除文件 | `{"ctrl_cmd":{"mp3_delete_cmd":{"filename":"test.mp3"}}}` | 删除指定文件 | RD | ## 十一、版本历史 ### v1.8 (当前版本) - **动态Ping配置功能**: - 新增`ping_fields`参数,支持动态配置ping消息包含的字段 - 支持从param和status对象中选择任意字段组合 - 新增特殊字段支持,如`rssi_abs`(WiFi信号强度绝对值) - 基于PingFieldManager类实现高效的字段管理 - 支持配置缓存优化,避免重复解析 - 完全向后兼容,默认行为保持与v1.5一致 - **参数管理增强**: - 新增`ping_fields`参数:`"device_id,full_ver,rssi_abs"`(默认) - 支持逗号分隔的字段配置语法 - 智能字段类型识别和验证 - 错误配置的容错处理机制 - **消息格式优化**: - Ping消息格式从固定结构变为动态可配置 - 支持最小化传输以节省带宽 - 支持扩展监控以获取更多设备信息 - 保持JSON消息格式标准和一致性 - **技术架构改进**: - 引入PingFieldManager管理器模式 - 配置解析和消息构建逻辑分离 - 缓存机制提升性能表现 - 完善的日志记录和错误处理 ### v1.5 - **脱钩锁功能完善**: - 新增单个锁控制命令,解决JSON无法设置单个数组元素的限制 - 支持批量操作(set_status)和单个操作(ctrl_cmd)两种模式 - 新增单个锁状态变化事件上报 - 术语修正:从"三态锁"更名为"脱钩锁" - 锁编号从0开始(0-7) - 强调仅支持开锁功能,移除所有锁定操作 - **控制指令优化**: - 新增 `unlock_lock_cmd`: 单个脱钩锁开锁控制 - 新增 `query_lock_cmd`: 单个脱钩锁状态查询 - 移除错误的锁定相关命令 - **事件上报增强**: - 新增单个锁状态变化事件:`lock_state_changed_evt` - 保留批量锁状态变化事件,支持双重上报机制 - **应答格式完善**: - 新增单个锁状态查询的应答格式示例 ### v1.4 - **重大更正**: 修正RC产品脱钩锁实现方式 - **功能更正**: RC产品只支持开锁功能,不支持锁定功能 - **实现方式更正**: 脱钩锁通过status状态设置控制,而非ctrl_cmd控制命令 - **批量操作**: 支持通过`set_status`进行批量锁控制 - **事件上报**: 锁状态变化时上报所有锁的状态数组 - **编号修正**: 锁编号从0开始(0-7),不是从1开始 - **术语修正**: 将"三态锁"更正为"脱钩锁" - **移除错误命令**: 移除不存在的锁控制命令(unlock_single_lock_cmd等) ### v1.3 - 新增RC产品类型支持(智能租赁柜) - 新增三态锁控制功能 - 新增锁相关的控制指令和事件上报 - 新增锁状态查询功能 - 完善产品型号说明表 - 更新状态查询和事件上报章节 ### v1.2 - 完善多产品硬件抽象层支持 - 优化参数和状态管理结构 - 增加MP3音频功能支持 - 完善定时功能说明 - 更新电量统计功能 ### v1.1 - 基础协议框架 - 多种通信协议支持 - 基础参数和状态管理 ### v1.0 - 初始协议版本
admin
2025年8月19日 17:04
转发文档
收藏文档
上一篇
下一篇
手机扫码
复制链接
手机扫一扫转发分享
复制链接
Markdown文件
分享
链接
类型
密码
更新密码