倒计时控制器-通讯协议说明书-DWY-v1

# 倒计时控制器通讯协议说明书
版本: v1.0.0

## 一、前言

本文档详细说明了倒计时控制器设备与服务器或应用终端之间的通信协议规范，主要聚焦于与倒计时功能相关的命令和事件。本协议基于智能硬件通用通讯协议，采用JSON格式进行数据交换。

### 适用产品
- D2_RD (倒计时控制器)
- 其他支持倒计时功能的智能硬件产品

## 二、控制命令

### 2.1 倒计时控制命令

| 命令        | JSON 格式                                               | 说明              |
| --------- | ----------------------------------------------------- | --------------- |
| 设置倒计时(分钟) | `{"ctrl_cmd":{"set_countdown_cmd":100}}`              | 设置倒计时时间，单位：分钟   |
| 设置倒计时(秒)  | `{"ctrl_cmd":{"set_countdown_s_cmd":600}}`            | 设置倒计时时间，单位：秒    |
| 开始倒计时     | `{"ctrl_cmd":{"start_countdown_cmd":""}}`             | 启动倒计时，需先设置倒计时时间 |
| 停止倒计时     | `{"ctrl_cmd":{"stop_countdown_cmd":""}}`              | 停止当前倒计时         |
| 启用倒计时显示   | `{"ctrl_cmd":{"countdown_display_enable_cmd":true}}`  | 允许在数码管上显示倒计时    |
| 禁用倒计时显示   | `{"ctrl_cmd":{"countdown_display_disable_cmd":true}}` | 禁止在数码管上显示倒计时    |

> 注: `set_countdown_cmd`和`set_countdown_s_cmd`两个命令功能相似，区别在于单位不同。`set_countdown_cmd`的单位为分钟，适用于较长时间的倒计时；`set_countdown_s_cmd`的单位为秒，适用于精确控制倒计时时间的场景。建议优先使用`set_countdown_s_cmd`进行精确时间控制。

### 2.2 继电器控制命令

| 命令     | JSON 格式                                     | 说明                         |
| ------ | ------------------------------------------- | -------------------------- |
| 打开继电器  | `{"ctrl_cmd":{"open_relay_cmd":{}}}`        | 打开单个继电器                    |
| 关闭继电器  | `{"ctrl_cmd":{"close_relay_cmd":{}}}`       | 关闭单个继电器                    |
| 切换继电器  | `{"ctrl_cmd":{"toggle_relay_cmd":{}}}`      | 切换单个继电器状态                  |
| 设置继电器  | `{"ctrl_cmd":{"set_relay_cmd":true}}`       | 设置单个继电器状态，true为开启，false为关闭 |
| 打开继电器组 | `{"ctrl_cmd":{"open_relay_group_cmd":1}}`   | 打开第一个继电器组                  |
| 关闭继电器组 | `{"ctrl_cmd":{"close_relay_group_cmd":1}}`  | 关闭第一个继电器组                  |
| 切换继电器组 | `{"ctrl_cmd":{"toggle_relay_group_cmd":1}}` | 切换第一个继电器组状态                |
|        |                                             |                            |

### 2.3 系统控制命令

| 命令 | JSON 格式 | 说明 |
| ---- | -------- | ---- |
| OTA更新 | `{"ctrl_cmd":{"ota_cmd":{"url":"http://example.com/firmware.bin"}}}` | 固件升级 |
| 恢复出厂设置 | `{"ctrl_cmd":{"factory_params_cmd":{}}}` | 恢复出厂设置 |
| 重启设备 | `{"ctrl_cmd":{"restart_cmd":{}}}` | 重启系统 |

### 2.4 语音播报命令

| 命令 | JSON 格式 | 说明 |
| ---- | -------- | ---- |
| 语音播报 | `{"ctrl_cmd":{"play_voice_cmd":"要播报的文本内容"}}` | 播放指定文本内容 |
| 提示音播放 | `{"ctrl_cmd":{"play_prompt_voice_cmd":1}}` | 播放提示音(1-5) |
| 警示音播放 | `{"ctrl_cmd":{"play_voice_prompt_cmd":1}}` | 播放警示音(1-5) |
| 铃声播放 | `{"ctrl_cmd":{"play_bell_voice_cmd":1}}` | 播放铃声(1-5) |

## 三、参数设置与获取

### 3.1 基本参数

| 参数 | 设置格式 | 获取格式 | 说明 |
| ---- | -------- | -------- | ---- |
| 设备ID | `{"set_param":{"device_id":"dev001"}}` | `{"get_param":{"device_id":{}}}` | 设置设备ID后会自动更新: 1. device_sub_topic为"{device_id}/device_sub_topic" 2. device_pub_topic为"{device_id}/device_pub_topic" 3. ap_ssid为"esp_{device_id}" |
| WiFi SSID | `{"set_param":{"wifi_ssid":"xxxx"}}` | `{"get_param":{"wifi_ssid":{}}}` | 设置WiFi名称 |
| WiFi密码 | `{"set_param":{"wifi_pwd":"xxxx"}}` | `{"get_param":{"wifi_pwd":{}}}` | 设置WiFi密码 |
| AP密码 | `{"set_param":{"ap_pwd":"xxxx"}}` | `{"get_param":{"ap_pwd":{}}}` | 设置AP模式密码 |

### 3.2 网络参数

| 参数 | 设置格式 | 获取格式 | 说明 |
| ---- | -------- | -------- | ---- |
| MQTT服务器 | `{"set_param":{"mqtt_server":"xxx.xxx.xxx"}}` | `{"get_param":{"mqtt_server":{}}}` | 设置MQTT服务器地址 |
| MQTT端口 | `{"set_param":{"mqtt_port":1883}}` | `{"get_param":{"mqtt_port":{}}}` | 设置MQTT服务器端口 |
| MQTT用户名 | `{"set_param":{"mqtt_username":"xxxx"}}` | `{"get_param":{"mqtt_username":{}}}` | 设置MQTT用户名 |
| MQTT密码 | `{"set_param":{"mqtt_password":"xxxx"}}` | `{"get_param":{"mqtt_password":{}}}` | 设置MQTT密码 |
| 心跳包使能 | `{"set_param":{"ping_en":true}}` | `{"get_param":{"ping_en":{}}}` | 设置心跳包使能状态 |
| 心跳包周期 | `{"set_param":{"ping_interval_s":60}}` | `{"get_param":{"ping_interval_s":{}}}` | 设置心跳包上报周期，单位：秒 |

### 3.3 只读参数

| 参数 | 获取格式 | 说明 |
| ---- | -------- | ---- |
| 软件版本号 | `{"get_param":{"soft_ver":{}}}` | 获取软件版本号 |
| 硬件版本号 | `{"get_param":{"hard_ver":{}}}` | 获取硬件版本号 |
| 协议版本号 | `{"get_param":{"protocol_ver":{}}}` | 获取协议版本号 |
| 完整版本号 | `{"get_param":{"full_ver":{}}}` | 获取完整版本号 |
| WiFi信号强度 | `{"get_param":{"rssi_abs":{}}}` | 获取WiFi信号强度，单位：dBm |

### 3.4 语音播报参数

| 参数 | 设置格式 | 获取格式 | 说明 |
| ---- | -------- | -------- | ---- |
| 语音播报开关 | `{"set_param":{"voice_enable_cmd":true}}` | `{"get_param":{"voice_enable_cmd":{}}}` | 开启/关闭语音播报功能 |
| 语音音量 | `{"set_param":{"set_voice_volume_cmd":5}}` | `{"get_param":{"set_voice_volume_cmd":{}}}` | 设置语音音量(0-9) |
| 语音语速 | `{"set_param":{"voice_speed_cmd":5}}` | `{"get_param":{"voice_speed_cmd":{}}}` | 设置语音速度(0-9) |
| 语音音调 | `{"set_param":{"set_voice_tone_cmd":5}}` | `{"get_param":{"set_voice_tone_cmd":{}}}` | 设置语音音调(0-9) |
| 人声模式 | `{"set_param":{"voice_mode_cmd":0}}` | `{"get_param":{"voice_mode_cmd":{}}}` | 设置人声模式(0:标准男声 1:标准女声) |

## 四、事件上报

### 4.1 倒计时事件

| 事件 | JSON 格式 | 说明 | 触发条件 |
| ---- | -------- | ---- | ------- |
| 倒计时开始 | `{"event":{"countdown_start_evt":600}}` | 倒计时开始事件，值为倒计时总秒数 | 当倒计时启动时上报 |
| 倒计时剩余 | `{"event":{"countdown_remain_evt":300}}` | 倒计时剩余事件，值为剩余秒数 | 每分钟上报一次剩余时间 |
| 倒计时停止 | `{"event":{"countdown_stop_evt":true}}` | 倒计时被手动停止事件 | 当倒计时被手动停止时上报 |
| 倒计时完成 | `{"event":{"countdown_finish_evt":true}}` | 倒计时完成事件 | 当倒计时自然结束时上报 |

### 4.2 继电器事件

| 事件      | JSON 格式                                     | 说明        | 触发条件          |
| ------- | ------------------------------------------- | --------- | ------------- |
| 继电器状态变化 | `{"event":{"relay_state_change_evt":true}}` | 继电器状态改变事件 | 当继电器状态发生改变时上报 |

### 4.3 系统事件

| 事件 | JSON 格式 | 说明 | 触发条件 |
| ---- | -------- | ---- | ------- |
| OTA更新完成 | `{"event":{"ota_end_evt":true}}` | OTA升级完成事件 | 当OTA升级完成后上报 |
| 上电事件 | `{"event":{"powerup_evt":""}}` | 设备上电事件 | 设备上电时上报 |
| 重启事件 | `{"event":{"reboot_evt":""}}` | 设备重启事件 | 设备重启时上报 |
| 输入通道触发 | `{"event":{"in_ch_evt":1}}` | 输入通道触发事件 | 当输入通道被触发时上报 |

## 五、倒计时显示状态

D2_RD产品(倒计时控制器)支持在数码管上显示倒计时和工作状态：

| 显示状态 | 描述 |
| ------- | ---- |
| 初始状态 | 显示固定的"-"符号 |
| 断网状态 | 显示闪烁的"-"符号 |
| 配网状态 | 显示快速闪烁的"-"符号 |
| 联网状态 | 显示固定的"-"符号 |
| 倒计时状态 | 显示倒计时时间，格式为"HH:MM"，冒号每秒闪烁一次 |

## 六、工作流程示例

### 6.1 设置并启动倒计时

```mermaid
sequenceDiagram
    participant App as 应用终端
    participant Device as 倒计时控制器
    
    App->>Device: {"ctrl_cmd":{"set_countdown_s_cmd":300}}
    Device-->>App: {"ask":true}
    Note right of Device: 设置5分钟倒计时
    
    App->>Device: {"ctrl_cmd":{"start_countdown_cmd":""}}
    Device-->>App: {"ask":true}
    Note right of Device: 开始倒计时，同时显示在数码管上
    
    Device->>App: {"event":{"countdown_start_evt":300}}
    Note right of Device: 上报倒计时开始事件
    
    Device->>App: {"event":{"countdown_remain_evt":240}}
    Note right of Device: 每分钟上报剩余时间
    
    Device->>App: {"event":{"countdown_remain_evt":180}}
    Device->>App: {"event":{"countdown_remain_evt":120}}
    Device->>App: {"event":{"countdown_remain_evt":60}}
    
    Device->>App: {"event":{"countdown_finish_evt":true}}
    Note right of Device: 倒计时结束事件
```

### 6.2 手动停止倒计时

```mermaid
sequenceDiagram
    participant App as 应用终端
    participant Device as 倒计时控制器
    
    App->>Device: {"ctrl_cmd":{"set_countdown_s_cmd":300}}
    Device-->>App: {"ask":true}
    
    App->>Device: {"ctrl_cmd":{"start_countdown_cmd":""}}
    Device-->>App: {"ask":true}
    Device->>App: {"event":{"countdown_start_evt":300}}
    
    Device->>App: {"event":{"countdown_remain_evt":240}}
    
    App->>Device: {"ctrl_cmd":{"stop_countdown_cmd":""}}
    Device-->>App: {"ask":true}
    Device->>App: {"event":{"countdown_stop_evt":true}}
    Note right of Device: 倒计时被手动停止
```

## 七、按键操作说明

设备支持以下按键操作：

| 操作方式 | 功能描述 | 触发条件 |
| ---- | --------------------------------------- | ---------- |
| 单击 | 1. 在AP配网模式下：退出配网模式 2. 在正常模式下：切换继电器状态 | 快速按下并释放按键 |
| 长按 | 1. 在正常模式下：进入AP配网模式 2. 在AP配网模式下：无效 | 按住按键超过6秒 |
| 超长按 | 恢复出厂设置并重启设备 | 按住按键超过20秒 |
| 双击 | 预留功能 | 快速连续按下两次按键 |

> 注：
> 1. 在AP配网模式下，数码管会快速闪烁"-"符号
> 2. 进入AP配网模式后，设备将创建一个名为"esp_{device_id}"的WiFi热点
> 3. 恢复出厂设置会清除所有配置参数，包括WiFi配置、MQTT配置等
> 4. 设备重启后将回到初始状态，需要重新配置网络连接

## 八、注意事项

### 8.1 倒计时功能注意事项

1. 当设置新的倒计时时间后，需要发送开始倒计时命令才会启动倒计时
2. 倒计时显示只在D2_RD设备上支持，可通过启用/禁用倒计时显示命令控制是否在数码管上显示倒计时
3. 倒计时状态会在断电后丢失，设备重启后需重新设置并启动倒计时
4. 当倒计时运行时，若再次调用设置倒计时命令，将会更新时间但不会自动开始，需要再次发送开始命令
5. 建议使用秒级倒计时命令`set_countdown_s_cmd`实现更精确的时间控制
6. 输入通道触发事件可用于外部开关或传感器的状态监测
7. 继电器控制命令可与倒计时功能配合使用，实现定时控制功能

### 8.2 语音播报功能注意事项

1. 语音播报功能需要先开启语音播报开关才能使用
2. 语音播报支持中文文本，使用GBK编码
3. 提示音、警示音和铃声播放命令的参数范围为1-5，超出范围的值将被忽略
4. 语音播报相关参数修改后会立即生效并保存
5. 语音播报开关默认为开启状态
6. 语音相关参数的默认值均为5（中等级别）
7. 语音播报可以与倒计时功能配合使用，实现倒计时语音提醒功能
8. 在倒计时完成时，可以通过语音播报功能播放提示音或自定义文本