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 为固件升级地址 例：`{"ctrl_cmd":{"ota_cmd":{"url":"http://192.168.1.100:8080/firmware.bin"}}}` | ALL |
| 播放语音 | `{"ctrl_cmd":{"play_voice_cmd":"xxxx"}}` | 播放语音，xxxx为要播放的文字内容 举例:{"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}}` | 设置灯光模式 0：常亮 1：闪烁 2：呼吸 | SOD |
| 设置语音模式 | `{"ctrl_cmd":{"set_voice_mode_cmd":0}}` | 设置语音播放模式 | SOD, RD |
| 设置语音音量 | `{"ctrl_cmd":{"set_voice_volume_cmd":5}}` | 设置语音音量级别 范围:1-10 | SOD, RD |
| 设置语音语速 | `{"ctrl_cmd":{"set_voice_speed_cmd":5}}` | 设置语音播放速度 范围:1-10 | SOD, RD |
| 设置语音语调 | `{"ctrl_cmd":{"set_voice_tone_cmd":5}}` | 设置语音音调 范围:1-10 | SOD, RD |
| 播放提示音 | `{"ctrl_cmd":{"play_prompt_voice_cmd":1}}` | 播放预设的提示音 范围:1-5 | SOD, RD |
| 播放铃声 | `{"ctrl_cmd":{"play_bell_voice_cmd":1}}` | 播放预设的铃声 范围:1-5 | SOD, RD |
| 播放警告音 | `{"ctrl_cmd":{"play_warning_voice_cmd":1}}` | 播放预设的警告音 范围: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}}` | 设置灯光状态 0：关闭 1：打开 2：闪烁 3：呼吸 | SOD |
| 灯光闪烁 | `{"ctrl_cmd":{"flash_light_cmd":1}}` | 设置灯光闪烁模式 0：停止闪烁 1：快闪 2：慢闪 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":{}}}` | | 获取电量统计状态 true: 统计中 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信号强度的绝对值: 50: 非常好 60~70: 好 70~80: 一般 80~90: 差 | ALL |
| 继电器状态 | - | `{"get_status":{"relay":{}}}` | 只读参数,继电器状态: true: 闭合 false: 断开 | CONV, SOC_P1, BRK_P1, CBOX_P1, RD, SW |
| 继电器组状态 | `{"set_status":{"relays":[true,false,true]}}` | `{"get_status":{"relays":{}}}` | 获取所有继电器状态数组: 返回格式: [true,false,true] 数组索引从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":{}}}` | 设置/获取所有脱钩锁状态数组: 返回格式: [true,false,true,false,true,false,true,false] 数组索引从0开始，对应锁编号0-7 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}} | 举例: 发送`{"get_param":{"device_id":{}}}` 返回 `{"ask_param":{"device_id":"dev001"}}` | ALL |
| 获取状态应答 | {"get_status":{"name":val}} | 举例: 发送`{"get_status":{"voltage_v":{}}}` 返回 `{"ask_status":{"voltage_v":220}}` 继电器组状态查询: 发送`{"get_status":{"relay_group_status":{}}}` 返回 `{"ask_status":{"relay_group_status":[true,false,true]}}` 脱钩锁状态查询: 发送`{"get_status":{"locks":{}}}` 返回 `{"ask_status":{"locks":[true,false,true,false,true,false,true,false]}}` 单个锁状态查询应答: 发送`{"ctrl_cmd":{"query_lock_cmd":"0"}}` 返回 `{"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]}}` | 批量设置所有锁状态 数组索引0-7对应锁编号0-7 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
- 初始协议版本