通用-通讯协议说明书-v1

# 项目版本: 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后会自动更新: device_sub_topic为"{device_id}/device_sub_topic"、 2. device_pub_topic为"{device_id}/device_pub_topic"、 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":{}}}` | | 获取电量统计状态 true: 统计中 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,也可以通过这个协议判断当前是否在定时倒计时中 |
| GPIO 通道去抖时间 | `{"set_param":{"gpio_ch_debounce_ms":100}}` | `{"get_param":{"gpio_ch_debounce_ms":{}}}` | 100 | GPIO 通道去抖时间,单位:ms |
| GPIO 通道触发有效次数 | `{"set_param":{"gpio_ch_tri_cnt":3}}` | `{"get_param":{"gpio_ch_tri_cnt":{}}}` | 3 | GPIO 通道触发有效次数,只有当触发次数大于等于该值时,才认为通道触发有效 |
| GPIO 通道触发模式 | `{"set_param":{"gpio_ch_tri_mode":0}}` | `{"get_param":{"gpio_ch_tri_mode":{}}}` | 0 | 0:低电平触发,1:高电平触发 |
| ADC 通道触发阈值 | `{"set_param":{"adc_ch_tri_th":2048}}` | `{"get_param":{"adc_ch_tri_th":{}}}` | 2048 | ADC 通道触发阈值 |
| ADC 通道去抖时间 | `{"set_param":{"adc_ch_debounce_ms":100}}` | `{"get_param":{"adc_ch_debounce_ms":{}}}` | 100 | ADC 通道去抖时间,单位:ms |
| ADC 通道触发有效次数 | `{"set_param":{"adc_ch_tri_cnt":3}}` | `{"get_param":{"adc_ch_tri_cnt":{}}}` | 3 | ADC 通道触发有效次数,只有当触发次数大于等于该值时,才认为通道触发有效 |
| ADC 通道触发模式 | `{"set_param":{"adc_tri_th_mode":0}}` | `{"get_param":{"adc_tri_th_mode":{}}}` | 0 | 0:大于等于阈值触发,1:小于等于阈值触发 |

### 5.3. 状态设置&状态获取

状态(Status)与参数(Param)的区别:
	1. 状态是运行时的实时数据, 如当前电压、电流等测量值, 这些数据断电后不会保存
	2. 当设备收到状态获取命令后, 会返回对应的状态值, 具体格式请参考: [[#5.6. 消息应答]]

| 命令 | 设置状态 | 获取状态 | 说明 |
| -------- | ---- | ------------------------------------- | ------------------------------------------------------------------ |
| WiFi信号强度 | - | `{"get_status":{"rssi_abs":{}}}` | 只读参数,WiFi信号强度的绝对值: 50: 非常好 60~70: 好 70~80: 一般 80~90: 差 |
| 继电器状态 | - | `{"get_status":{"relay":{}}}` | 只读参数,继电器状态: true: 闭合 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}} | 举例: 发送`{"get_param":{"device_id":{}}}` 返回 `{"ask_param":{"device_id":"dev001"}}` | ALL |
| 获取状态应答 | {"get_status":{"name":val}} | 举例: 发送`{"get_status":{"voltage_v":{}}}` 返回 `{"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. 可通过查询指令随时获取当前倒计时剩余时间及使能状态。