二次开发手册
智能硬件-通讯协议说明书
产品命名规则
智能硬件-通讯协议说明书-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 发布
-
+
首页
计量硬件-通讯协议说明书-v2
# 项目版本: v2.1 *** ## 一、前言 本文档详细说明了智能硬件设备与服务器之间的通信协议规范。主要包含以下内容: 1. 设备标识规则 - 使用 MAC 地址作为设备唯一标识(device_id) - 用于区分不同设备的通信 2. MQTT 与 TCP 通信机制 - 基于发布/订阅模式 (MQTT) 和请求/响应模式 (TCP) - 设备与服务器双向通信 - 支持命令下发与状态上报 3. 命令交互规范 - JSON 格式数据交换 - 完整的命令应答机制 - 标准化的错误处理 4. 适用的产品型号 5. 标准术语定义 1. "硬件终端": 指代智能设备上运行的嵌入式系统,其用于与服务器进行通信以及执行各种控制和监控功能。 2. "服务器端": 指代中心服务器,负责接收智能设备上传的数据、下发控制命令并进行数据处理与存储。 3. "应用终端": 指用户操作界面,如手机应用或网页界面,通过它用户可以发送命令到服务器端并查看设备的状态。 6. 支持的协议 1. MQTT: "硬件终端"作为MQTT客户端 2. TCP Client: "硬件终端"作为TCP客户端 3. HTTP Server: "硬件终端"作为HTTP服务端 ## 二、产品型号说明 ## 三、设备标识 (device_id) 7. 用途:代表终端的唯一编号 8. 默认值:设备的主芯片的唯一id ## 四、通信协议 ### 4.1. MQTT 协议 #### 4.1.1. MQTT 协议概要 9. mqtt 通讯基于2个主题,device_id/device_pub_topic与device_id/device_sub_topic 10. "硬件终端"通过device_id/device_pub_topic主题发布数据,"应用终端"通过该主题接收"硬件终端"的数据 11. "硬件终端"通过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 协议概要 12. TCP Client 代表"硬件终端"作为TCP客户端与"服务器端"进行socket通讯 13. "硬件终端"上电联网完成后,会主动与"服务器端"建立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连接请求(SYN) TCP_Server-->>TCP_Client: 确认连接请求(SYN+ACK) TCP_Client->>TCP_Server: 完成连接建立(ACK) Note over TCP_Client,TCP_Server: TCP连接建立完成 TCP_Client->>TCP_Server: 事件上报 Note right of TCP_Client: 事件通知(如设备状态变化) TCP_Server->>TCP_Client: 发送控制指令 Note right of TCP_Server: 控制命令或参数请求 TCP_Client-->>TCP_Server: 回复执行结果 Note right of TCP_Client: 执行指令并反馈状态 Note over TCP_Client,TCP_Server: 连接保持,可继续通信 Note over TCP_Client,TCP_Server: 任一方可主动断开连接 ``` *TCP Client 采用 ascii 编码通讯内容* ### 4.3. HTTP Server 协议 #### 4.3.1. HTTP Server 协议概要 1. 由于 HTTP 协议的限制,"硬件终端"仅支持通过 HTTP POST 请求。 2. 仅支持控制命令(ctrl_cmd)和参数(set_param、get_param)和状态 (set_status、get_status)请求,不支持主动上报、事件上报等。 3. 推荐所有 HTTP 请求均使用 Content-Type: application/json,且数据体为标准 JSON 格式。 4. 由于默认情况下,设备使用 DHCP 获取 IP 地址,所以设备端默认的 IP 地址是动态的,请通过配网页面查询. 5. 在这个模式下,**硬件终端**采用 STA 模式,**硬件终端**与**应用终端**都需要事先先连接到同一个网络中,才可以实现通讯. #### 4.3.2. HTTP Server 通讯流程 以下流程展示 "应用终端" 通过 HTTP POST 向 "硬件终端" 发送控制指令并获取执行结果: ```mermaid sequenceDiagram participant App_Client participant HW_HTTP_Server App_Client->>HW_HTTP_Server: 发送 HTTP POST 控制指令 Note right of App_Client: 仅支持控制命令/参数设置 HW_HTTP_Server-->>App_Client: 返回执行结果 Note right of HW_HTTP_Server: 处理请求并反馈状态 ``` * App_Client:应用终端(如手机App、Web前端等) * HW_HTTP_Server:硬件终端(设备本身) #### 4.3.3. HTTP 报文与调用示例 ##### HTTP 请求报文 以发送控制命令为例,POST 数据体为 JSON 格式: ``` POST /device_sub_topic HTTP/1.1 Host: 192.168.1.199 Content-Type: application/json Content-Length: 85 { "ctrl_cmd": { "open_relay_cmd": {} } } ``` ##### HTTP 响应报文 ``` HTTP/1.1 200 OK Content-Type: application/json Content-Length: 17 { "ask": true } ``` ##### curl 调用示例 ``` curl -X POST http://192.168.1.199/device_sub_topic \ -H "Content-Type: application/json" \ -d '{"ctrl_cmd":{"open_relay_cmd":{}}}' ``` - 仅支持 POST 方法,路径为 /device_sub_topic - 数据体必须为 JSON 格式 - 典型响应为: - 成功时返回 { "ask": true },失败时返回 { "ask": false }。 - 不支持主动上报,事件上报等请求,收到此类请求将返回 { "unknown_cmd": 0 }。 > 注意: > 1. HTTP Server 仅用于本地局域网内调试或配置,不建议用于公网环境。 > 2. 仅支持控制命令和参数设置,所有查询类和事件上报类请求均不支持。 > 3. 详细命令格式请参考"5.1 控制命令"章节。 ## 五、通讯报文 所有协议都共用同一套通讯报文,TCP_Client,MQTT,HTTP_SERVER等 ### 5.1. 控制命令 控制指令发送成功后,设备终端会返回一个"确认帧"或"否认帧"用于响应控制命令是否执行成功 | 命令 | JSON 格式 | 说明 | | ------ | -------------------------------------------------------------------- | ---------------------- | | OTA更新 | `{"ctrl_cmd":{"ota_cmd":{"url":"http://example.com/firmware.bin"}}}` | 固件升级 | | 恢复出厂设置 | `{"ctrl_cmd":{"factory_params_cmd":{}}}` | 恢复出厂设置 | | 重启设备 | `{"ctrl_cmd":{"restart_cmd":{}}}` | 重启系统 | | 打开继电器 | `{"ctrl_cmd":{"open_relay_cmd":{}}}` | 打开继电器 | | 关闭继电器 | `{"ctrl_cmd":{"close_relay_cmd":{}}}` | 关闭继电器 | | 反转继电器 | `{"ctrl_cmd":{"toggle_relay_cmd":{}}}` | 切换继电器状态 | | 开始电量统计 | `{"ctrl_cmd":{"start_power_stat_cmd":{}}}` | 开始电量统计 | | 结束电量统计 | `{"ctrl_cmd":{"stop_power_stat_cmd":{}}}` | 结束电量统计 | | 打开继电器组 | `{"ctrl_cmd":{"open_relay_group_cmd":1}` | 打开编号 1 的继电器,数字代表继电器 id | | 关闭继电器组 | `{"ctrl_cmd":{"close_relay_group_cmd":2}` | 关闭编号 2 的继电器,数字代表继电器 id | | 切换继电器组 | `{"ctrl_cmd":{"toggle_relay_group_cmd":3}` | 切换编号 3 的继电器,数字代表继电器 id | ### 5.2. 参数设置&参数获取 参数表说明: 1. 参数表中的所有配置项都支持掉电保存 2. 当设备收到参数设置命令后,会返回一个"确认帧"或"否认帧"来表示设置是否成功 3. 当设备收到参数查询命令后,会返回包含查询参数值的应答帧,具体格式请参考: [[#5.6. 消息应答]] | 命令 | 设置参数 | 获取参数 | 默认值 | 说明 | | --------- | ----------------------------------------------------------------------- | ----------------------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | 设备ID | `{"set_param":{"device_id":"dev001"}}` | `{"get_param":{"device_id":{}}}` | WiFi MAC地址 | 设置设备ID后会自动更新:<br>device_sub_topic为"{device_id}/device_sub_topic"、<br>2. device_pub_topic为"{device_id}/device_pub_topic"、<br>3. ap_ssid为"esp_{device_id}" | | MQTT服务器 | `{"set_param":{"mqtt_server":"xxx.xxx.xxx"}}` | `{"get_param":{"mqtt_server":{}}}` | "47.120.74.198" | | | MQTT端口 | `{"set_param":{"mqtt_port":1883}}` | `{"get_param":{"mqtt_port":{}}}` | 1883 | | | MQTT用户名 | `{"set_param":{"mqtt_username":"xxxx"}}` | `{"get_param":{"mqtt_username":{}}}` | "admin" | | | MQTT密码 | `{"set_param":{"mqtt_password":"xxxx"}}` | `{"get_param":{"mqtt_password":{}}}` | "vsykb*&(18" | | | AP密码 | `{"set_param":{"ap_pwd":"xxxx"}}` | `{"get_param":{"ap_pwd":{}}}` | "88888888" | | | 网络调试状态 | `{"set_param":{"net_console_en":true}}` | `{"get_param":{"net_console_en":{}}}` | false | | | 串口调试状态 | `{"set_param":{"com_console_en":true}}` | `{"get_param":{"com_console_en":{}}}` | true | | | 网络调试主题 | `{"set_param":{"device_net_console_topic":"xxxx"}}` | `{"get_param":{"device_net_console_topic":{}}}` | - | | | 软件版本号 | - | `{"get_param":{"soft_ver":{}}}` | 1 | 只读参数 | | 硬件版本号 | - | `{"get_param":{"hard_ver":{}}}` | 1 | 只读参数 | | 协议版本号 | - | `{"get_param":{"protocol_ver":{}}}` | 1 | 只读参数 | | 编译时间 | - | `{"get_param":{"build_datetime":{}}}` | - | 只读参数 | | 参数版本号 | - | `{"get_param":{"param_ver":{}}}` | 1 | 只读参数 | | 完整版本号 | - | `{"get_param":{"full_ver":{}}}` | - | 只读参数 | | WiFi信号强度 | - | `{"get_param":{"rssi_abs":{}}}` | - | 只读参数,单位:dBm | | 设备订阅主题 | `{"set_param":{"device_sub_topic":"device_sub_topic"}}` | `{"get_param":{"device_sub_topic":{}}}` | "device_sub_topic" | 设置设备订阅主题 | | 设备发布主题 | `{"set_param":{"device_pub_topic":"device_pub_topic"}}` | `{"get_param":{"device_pub_topic":{}}}` | "device_pub_topic" | 设置设备发布主题 | | 网络调试主题 | `{"set_param":{"device_net_console_topic":"device_net_console_topic"}}` | `{"get_param":{"device_net_console_topic":{}}}` | "device_net_console_topic" | 设置网络调试主题 | | 心跳包使能 | `{"set_param":{"ping_en":true}}` | `{"get_param":{"ping_en":{}}}` | false | 设置心跳包使能状态 | | 心跳包周期 | `{"set_param":{"ping_interval_s":60}}` | `{"get_param":{"ping_interval_s":{}}}` | 120 | 设置心跳包上报周期,单位,秒 | | WiFi SSID | `{"set_param":{"wifi_ssid":"xxxx"}}` | `{"get_param":{"wifi_ssid":{}}}` | "88888888" | | | WiFi密码 | `{"set_param":{"wifi_pwd":"xxxx"}}` | `{"get_param":{"wifi_pwd":{}}}` | "88888888" | | | 继电器状态 | `{"set_param":{"relay":true}}` | `{"get_param":{"relay":{}}}` | true | | | 过压阈值 | `{"set_param":{"over_voltage_v_th":250}}` | `{"get_param":{"over_voltage_v_th":{}}}` | 260 | 设置过压保护阈值(单位:V) | | 低压阈值 | `{"set_param":{"low_voltage_v_th":200}}` | `{"get_param":{"low_voltage_v_th":{}}}` | 180 | 设置欠压保护阈值(单位:V) | | 过流阈值 | `{"set_param":{"over_current_ma_th":2000}}` | `{"get_param":{"over_current_ma_th":{}}}` | 5100 | 设置过流保护阈值(单位:mA) | | 欠流阈值 | `{"set_param":{"low_current_ma_th":2000}}` | `{"get_param":{"low_current_ma_th":{}}}` | 100 | 欠流保护阈值(单位:mA) | | 过载阈值 | `{"set_param":{"over_power_w_th":2200}}` | `{"get_param":{"over_power_w_th":{}}}` | 1100 | 设置过载保护阈值(单位:W) | | 欠载阈值 | `{"set_param":{"low_power_w_th":2200}}` | `{"get_param":{"low_power_w_th":{}}}` | 100 | 设置欠载保护阈值(单位:W) | | 过温阈值 | `{"set_param":{"over_temperature_c_th":75}}` | `{"get_param":{"over_temperature_c_th":{}}}` | 60 | 设置过温保护阈值(单位:℃) | | 欠温阈值 | `{"set_param":{"low_temperature_c_th":75}}` | `{"get_param":{"low_temperature_c_th":{}}}` | 5 | 设置过温保护阈值(单位:℃) | | 电压值 | - | `{"get_param":{"voltage_v":{}}}` | - | 只读参数,单位:V | | 电流值 | - | `{"get_param":{"current_ma":{}}}` | - | 只读参数,单位:mA | | 功率值 | - | `{"get_param":{"power_w":{}}}` | - | 只读参数,单位:W | | 温度值 | - | `{"get_param":{"temperature_c":{}}}` | - | 只读参数,单位:℃ | | 电流校准参数 | `{"set_param":{"current_calibration":100}}` | `{"get_param":{"current_calibration":{}}}` | 0 | 用于校准BL0937测量电流的误差,正值表示增加,负值表示减少,范围: -1000~1000 | | 电压校准参数 | `{"set_param":{"voltage_calibration":-50}}` | `{"get_param":{"voltage_calibration":{}}}` | -47 | 用于校准BL0937测量电压的误差,正值表示增加,负值表示减少,范围: -1000~1000 | | 温度校准参数 | `{"set_param":{"temperature_calibration":-50}}` | `{"get_param":{"temperature_calibration":{}}}` | 0 | 用于校准温度检测的误差,正值表示增加,负值表示减少,范围: -1000~1000 | | 用电量 | - | `{"get_param":{"power_consumption_w":{}}}` | - | 只读参数,用电量统计值,单位:W,通过开始电量统计和结束电量统计指令控制统计周期 | | 按键锁定 | `{"set_param":{"key_lock":true}}` | `{"get_param":{"key_lock":{}}}` | false | 设置按键锁定状态(true:锁定 false:解锁) | | 使用静态 IP | `{"set_param":{"use_static_ip":true}}` | `{"get_param":{"use_static_ip":{}}}` | true | 是否启用静态 IP,true:启用,false:关闭 | | 静态 IP 地址 | `{"set_param":{"static_ip":"192.168.1.100"}}` | `{"get_param":{"static_ip":{}}}` | 192.168.1.199 | 静态 IP 地址,格式如 "192.168.1.100" | | 网关 IP 地址 | `{"set_param":{"gateway_ip":"192.168.1.1"}}` | `{"get_param":{"gateway_ip":{}}}` | 192.168.1.1 | 网关 IP 地址,格式如 "192.168.1.1" | | 子网掩码 | `{"set_param":{"subnet_mask":"255.255.255.0"}}` | `{"get_param":{"subnet_mask":{}}}` | 255.255.255.0 | 子网掩码,格式如 "255.255.255.0" | | 电量统计状态 | | `{"get_param":{"power_stat_en":{}}}` | | 获取电量统计状态<br>true: 统计中<br>false: 没有统计 | | 用电量 | | `{"get_param":{"power_wh":{}}}` | 0 | 查询当前统计电量 | | 定时打开 | `{"set_param":{"timer_open_relay":10}}` | `{"get_param":{"timer_open_relay":{}}}` | 0 | 设置定时开启继电器倒计时,单位:秒 | | 定时关闭 | `{"set_param":{"timer_close_relay":10}}` | `{"get_param":{"timer_close_relay":{}}}` | 0 | 设置定时关闭继电器倒计时,单位:秒 | | 定时反转 | `{"set_param":{"timer_toggle_relay":10}}` | `{"get_param":{"timer_toggle_relay":{}}}` | 0 | 设置定时反转继电器倒计时,单位:秒 | | 定时打开继电器使能 | `{"set_param":{"timer_open_relay_en":true}}` | `{"get_param":{"timer_open_relay_en":{}}}` | false | 定时打开继电器倒计时使能标志位, true 开始倒计时,当定时结束后,会自动置位为 false,也可以通过这个协议判断当前是否在定时倒计时中 | | 定时关闭继电器使能 | `{"set_param":{"timer_close_relay_en":true}}` | `{"get_param":{"timer_close_relay_en":{}}}` | false | 定时关闭继电器倒计时使能标志位, true 开始倒计时,当定时结束后,会自动置位为 false,也可以通过这个协议判断当前是否在定时倒计时中 | | 定时反转继电器使能 | `{"set_param":{"timer_toggle_relay_en":true}}` | `{"get_param":{"timer_toggle_relay_en":{}}}` | false | 定时反转继电器倒计时使能标志位, true 开始倒计时,当定时结束后,会自动置位为 false,也可以通过这个协议判断当前是否在定时倒计时中 | | | | | | | | | | | | | ### 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: 差 | | 继电器状态 | - | `{"get_status":{"relay":{}}}` | 只读参数,继电器状态:<br>true: 闭合<br>false: 断开 | | 所有继电器状态 | | `{"get_status":{"relays":{}}}` | 获取所有继电器状态 | | 电压值 | - | `{"get_status":{"voltage_v":{}}}` | 只读参数,当前电压值,单位:V | | 电流值 | - | `{"get_status":{"current_ma":{}}}` | 只读参数,当前电流值,单位:mA | | 功率值 | - | `{"get_status":{"power_w":{}}}` | 只读参数,当前功率值,单位:W | | 温度值 | - | `{"get_status":{"temperature_c":{}}}` | 只读参数,当前温度值,单位:℃ | ### 5.4. 事件上报 | 事件类型 | JSON 格式 | 说明 | | ---------- | -------------------------------------------------- | ---------------------- | | OTA 更新完成事件 | `{"event":{"ota_end_evt":更新结果}}` | OTA 升级完成后上报结果 | | 上电事件 | `{"event":{"powerup_evt":""}}` | 设备上电时上报 | | 重启事件 | `{"event":{"reboot_evt":""}}` | 设备重启时上报 | | 恢复出厂设置事件 | `{"event":{"factory_params_evt":""}}` | 恢复出厂设置时上报 | | 系统信息上报事件 | `{"event":{"report_sysinfo_evt":系统信息}}` | 上报系统所有可获取参数 | | 继电器状态变化事件 | `{"event":{"relay_state_change_evt":状态}}` | 继电器状态发生改变时上报 | | 断电事件 | `{"event":{"powerdown_evt":""}}` | 设备断电时上报 | | 电流过流事件 | `{"event":{"current_over_evt":当前电流}}` | 当检测到电流超过阈值时上报 | | 电流欠流事件 | `{"event":{"current_low_evt":当前电流}}` | 当检测到电流低于阈值时上报 | | 过流恢复事件 | `{"event":{"current_oeve_recovery_evt":当前电流}}` | 电流恢复正常后上报 | | 欠流恢复事件 | `{"event":{"current_low_recovery_evt":当前电流}}` | 电流恢复正常后上报 | | 电压过压事件 | `{"event":{"voltage_over_evt":当前电压}}` | 当检测到电压超过阈值时上报 | | 电压欠压事件 | `{"event":{"voltage_low_evt":当前电压}}` | 当检测到电压低于阈值时上报 | | 过压恢复事件 | `{"event":{"voltage_over_recovery_evt":当前电压}}` | 电压恢复正常后上报 | | 欠压恢复事件 | `{"event":{"voltage_low_recovery_evt":当前电压}}` | 电压恢复正常后上报 | | 功率过载事件 | `{"event":{"power_over_evt":当前功率}}` | 当检测到功率超过阈值时上报 | | 功率欠载事件 | `{"event":{"power_low_evt":当前功率}}` | 当检测到功率低于阈值时上报 | | 功率恢复事件 | `{"event":{"power_over_recovery_evt":当前功率}}` | 功率恢复正常后上报 | | 功率欠载恢复事件 | `{"event":{"power_low_recovery_evt":当前功率}}` | 功率恢复正常后上报 | | 温度过温事件 | `{"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:按键编号 | | 按键长按 | `{"event":{"key_id":0,"long_click_evt":{}}}` | 按键0被长按时触发,key_id:按键编号 | | 按键超长按 | `{"event":{"key_id":0,"extra_long_click_evt":{}}}` | 按键0被超长按时触发,key_id:按键编号 | | 按键双击 | `{"event":{"key_id":0,"double_click_evt":{}}}` | 按键0被双击时触发,key_id:按键编号 | | 按键三击 | `{"event":{"key_id":0,"triple_click_evt":{}}}` | 按键0被三击时触发,key_id:按键编号 | | 定时打开完成事件 | `{"event":{"timer_open_relay_done_evt":{}}}` | 定时打开继电器倒计时结束时上报 | | 定时关闭完成事件 | `{"event":{"timer_close_relay_done_evt":{}}}` | 定时关闭继电器倒计时结束时上报 | | 定时反转完成事件 | `{"event":{"timer_toggle_relay_done_evt":{}}}` | 定时反转继电器倒计时结束时上报 | | 输入通道触发 | `{"event":{"in_ch":0,"triggered_evt":{}}}` | 通道0,触发 | | 输入通道释放 | `{"event":{"in_ch":0,"released_evt":{}}}` | 通道0,释放 | | 输入通道状态变化 | `{"event":{"in_ch":0,"state_changed_evt":{}}}` | 通道0,状态变化 | 注意: 1. 按键事件上报中的数值表示按键索引,从0开始 2. 对于多按键产品(如D2_SW),每个按键都有独立的索引 3. 按键事件的触发时间: - 短按:立即触发 - 双击:两次按键间隔小于300ms - 三击:三次按键间隔小于500ms - 长按:按住时间超过3秒 - 超长按:按住时间超过10秒 4. 当按键被锁定时(key_lock=true),所有按键事件将被禁用 ### 5.5. 主动上报 "硬件终端"间隔一定的时间,会往"服务器端",上报的报文 该报文是可选,可使用"参数设置"报文开启或关闭 可通过"参数设置"报文,设置上报时间间隔 | 消息类型 | JSON 格式 | 说明 | 支持型号 | | ---- | ------------------------------------------------------------------------------------------ | -------------------- | ---- | | 心跳包 | `{"report":{"ping": { "device_id": "xxxx", "full_ver": "x.x.x", "rssi_abs": "-70 dBm", "voltage_v": 220, "current_ma": 1000, "power_w": 220, "over_voltage_v_th": 250, "over_current_ma_th": 2000, "over_power_w_th": 2200, "low_voltage_v_th": 200, "low_current_ma_th": 100, "low_power_w_th": 10, "voltage_calibration": 0, "current_calibration": 0, "temperature_c": 25, "over_temperature_c_th": 75, "low_temperature_c_th": 5, "temperature_calibration": 0 }}}` | 包含设备基本信息、电源状态、温度状态等完整信息 | ALL | | | | | | ### 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}}` | ALL | | 未知命令 | `{"unknown_cmd":0}` | 收到未知命令时的应答 | ALL | | | | | | | | | | | ## 六、电量统计功能说明 ### 6.1. 功能概述 电量统计功能用于统计设备在一段时间内的用电量。该功能通过以下方式工作: 1. 通过控制指令开始和结束统计 2. 在统计期间,实时累加用电量 3. 结束统计时,自动清零,为下次统计做准备 ### 6.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: 停止累加并自动清零 ``` ### 6.3. 相关指令说明 | 类型 | 指令 | 说明 | | ---- | ------------------------------------------ | ------------- | | 控制指令 | `{"ctrl_cmd":{"start_power_stat_cmd":{}}}` | 开始电量统计 | | 控制指令 | `{"ctrl_cmd":{"stop_power_stat_cmd":{}}}` | 结束电量统计 | | 状态查询 | `{"get_param":{"power_stat_en":{}}}` | 查询当前是否已开启电量统计 | | 用电量 | `{"get_param":{"power_wh":{}}}` | 查询当前已用电量 | | 电量清零 | `{"ctrl_cmd":{"clean_power_wh_cmd":{}}}` | 统计电量清零 | | | | | | | | | ### 6.4. 工作原理 1. 开始统计: - 收到开始指令后,清零统计值并开始累加用电量 2. 结束统计: - 收到结束指令后,停止统计 - 自动清零统计值,为下次统计做准备 3. 查询结果: - 通过状态查询指令可随时获取当前累计用电量 - 单位为瓦时(Wh) ## 七、定时功能说明 ### 7.1. 功能概述 定时功能用于在设定的时间后自动控制继电器的开、关或反转操作。该功能支持倒计时触发,适用于定时通断电、自动化场景等需求。通过相关指令可设置定时参数、启动/停止定时、查询定时状态等。 ### 7.2. 通信流程 ```mermaid sequenceDiagram participant App as 应用终端 participant Device as 硬件终端 App->>Device: 设置定时打开 {"set_param":{"timer_open_relay":10}} Device-->>App: 返回确认帧 {"ask":true} Note over Device: 启动10秒倒计时 App->>Device: 启用定时打开 {"set_param":{"timer_open_relay_en":true}} Device-->>App: 返回确认帧 {"ask":true} Note over Device: 定时倒计时开始 App->>Device: 查询定时状态 {"get_param":{"timer_open_relay_en":{}}} Device-->>App: 返回当前状态 {"ask_param":{"timer_open_relay_en":true}} Note over Device: 倒计时结束后自动打开继电器 App->>Device: 查询继电器状态 {"get_status":{"relay":{}}} Device-->>App: 返回当前状态 {"ask_status":{"relay":true}} ``` ### 7.3. 相关指令说明 | 类型 | 指令 | 说明 | | -------- | ---------------------------------------------- | ------------------------------------------------------------------ | | 参数设置 | `{"set_param":{"timer_open_relay":10}}` | 设置定时打开继电器倒计时,单位:秒 | | 参数设置 | `{"set_param":{"timer_close_relay":10}}` | 设置定时关闭继电器倒计时,单位:秒 | | 参数设置 | `{"set_param":{"timer_toggle_relay":10}}` | 设置定时反转继电器倒计时,单位:秒 | | 使能设置 | `{"set_param":{"timer_open_relay_en":true}}` | 启用定时打开继电器倒计时,true:开始倒计时,当定时结束后,会自动置位为 false,也可以通过这个协议判断当前是否在定时倒计时中 | | 使能设置 | `{"set_param":{"timer_close_relay_en":true}}` | 启用定时关闭继电器倒计时,true:开始倒计时,当定时结束后,会自动置位为 false,也可以通过这个协议判断当前是否在定时倒计时中 | | 使能设置 | `{"set_param":{"timer_toggle_relay_en":true}}` | 启用定时反转继电器倒计时,true:开始倒计时,当定时结束后,会自动置位为 false,也可以通过这个协议判断当前是否在定时倒计时中 | | 状态查询 | `{"get_param":{"timer_open_relay":{}}}` | 查询定时打开继电器倒计时剩余时间 | | 状态查询 | `{"get_param":{"timer_close_relay":{}}}` | 查询定时关闭继电器倒计时剩余时间 | | 状态查询 | `{"get_param":{"timer_toggle_relay":{}}}` | 查询定时反转继电器倒计时剩余时间 | | 状态查询 | `{"get_param":{"timer_open_relay_en":{}}}` | 查询定时打开继电器倒计时使能状态 | | 状态查询 | `{"get_param":{"timer_close_relay_en":{}}}` | 查询定时关闭继电器倒计时使能状态 | | 状态查询 | `{"get_param":{"timer_toggle_relay_en":{}}}` | 查询定时反转继电器倒计时使能状态 | | 定时打开完成事件 | `{"event":{"timer_open_relay_done_evt":{}}}` | 定时打开继电器倒计时结束时上报 | | 定时关闭完成事件 | `{"event":{"timer_close_relay_done_evt":{}}}` | 定时关闭继电器倒计时结束时上报 | | 定时反转完成事件 | `{"event":{"timer_toggle_relay_done_evt":{}}}` | 定时反转继电器倒计时结束时上报 | ### 7.4. 工作原理 1. 设置定时参数: - 通过参数设置指令设定倒计时时间(单位:秒),如 `{"set_param":{"timer_open_relay":10}}`。 2. 启动定时功能: - 通过使能指令启动倒计时,如 `{"set_param":{"timer_open_relay_en":true}}`,设备开始倒计时。 3. 倒计时过程: - 倒计时期间可随时通过查询指令获取剩余时间和使能状态。 4. 定时动作执行: - 倒计时结束后,自动执行对应的继电器操作(打开、关闭或反转),并自动清除使能标志。 5. 重新设置/中断: - 重新设置倒计时时间或使能状态时,设备会重置倒计时。 - 通过设置使能为 false 可中断当前倒计时。 ### 7.5. 注意事项 1. 定时功能仅在设备正常运行时有效,断电或重启后倒计时会被清零。 2. 每种定时操作(打开、关闭、反转)互相独立,互不影响。 3. 启动定时功能前需先设置倒计时时间,否则倒计时无效。 4. 定时操作完成后,相关使能标志会自动清除,需再次设置才能重新启动。 5. 可通过查询指令随时获取当前倒计时剩余时间及使能状态。
admin
2025年7月1日 01:12
转发文档
收藏文档
上一篇
下一篇
手机扫码
复制链接
手机扫一扫转发分享
复制链接
Markdown文件
分享
链接
类型
密码
更新密码