protocol-rd-v1.5.0

# RD产品专用协议: v1.5.0
***

## 一、前言

本文档详细说明了RD产品（D2_RD智能倒计时器设备）与服务器之间的通信协议规范。主要包含以下内容:

1. 设备标识规则
   - 使用 MAC 地址作为设备唯一标识(device_id)
   - 用于区分不同设备的通信

2. MQTT 与 TCP 通信机制
   - 基于发布/订阅模式 (MQTT) 和请求/响应模式 (TCP)
   - 设备与服务器双向通信
   - 支持命令下发与状态上报

3. 命令交互规范
   - JSON 格式数据交换
   - 完整的命令应答机制
   - 标准化的错误处理

4. 支持的协议
	1. MQTT: "硬件终端"作为MQTT客户端
	2. TCP Client: "硬件终端"作为TCP客户端
	3. HTTP Server: "硬件终端"作为HTTP服务端

5. 标准术语定义
	1. "硬件终端": 指代智能设备上运行的嵌入式系统，其用于与服务器进行通信以及执行各种控制和监控功能。
	2. "服务器端": 指代中心服务器，负责接收智能设备上传的数据、下发控制命令并进行数据处理与存储。
	3. "应用终端": 指用户操作界面，如手机应用或网页界面，通过它用户可以发送命令到服务器端并查看设备的状态。

## 二、产品型号说明

| 产品型号 | 完整名称 | 硬件能力 | 主要用途 |
|---------|---------|---------|---------|
| RD | D2_RD | 继电器控制、LED指示、语音输出、倒计时显示、按键输入、输入通道、MP3播放 | 智能倒计时器设备 |

## 三、RD产品硬件特性

### 3.1. 继电器控制能力
- 支持4路继电器控制
- 每路继电器可独立控制开关状态
- 支持继电器组批量操作

### 3.2. 语音和音频功能
- 支持TTS语音播放功能
- 支持MP3音频文件播放
- 语音参数可调节（音量、语速、语调）
- 支持预设提示音、铃声、警告音播放

### 3.3. 倒计时显示
- 数码管倒计时显示功能
- 可设置倒计时时间（秒、分钟）
- 显示功能可启用/禁用

### 3.4. 输入通道监控
- 支持GPIO和ADC输入通道监控
- 可配置触发阈值和去抖时间
- 支持多种触发模式

### 3.6. 按键输入
- 支持多种按键操作（短按、长按、双击、三击等）
- 按键锁定功能

## 四、设备标识 (device_id)

用途：代表终端的唯一编号
默认值：设备的主芯片的唯一id

## 五、通信协议

### 5.1. MQTT 协议
#### 5.1.1. MQTT 协议概要
mqtt 通讯基于2个主题,device_id/device_pub_topic与device_id/device_sub_topic
"硬件终端"通过device_id/device_pub_topic主题发布数据,"应用终端"通过该主题接收"硬件终端"的数据
"硬件终端"通过device_id/device_sub_topic主题接收数据,"应用终端"通过该主题发送数据
***node***: mqtt主题由device_id动态构成,修改device_id时,将自动修改这两个主题

#### 5.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客户端,一般由手机小程序充当

### 5.2. TCP Client 协议
#### 5.2.1. TCP Client 协议概要
TCP Client 代表"硬件终端"作为TCP客户端与"服务器端"进行socket通讯
"硬件终端"上电联网完成后,会主动与"服务器端"建立socket

#### 5.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服务器

### 5.3. HTTP Server 协议
#### 5.3.1. HTTP Server 协议概要
HTTP Server 代表"硬件终端"启动HTTP服务器，等待其他客户端连接
客户端通过HTTP协议发送POST请求到硬件终端
硬件终端处理请求并返回HTTP响应

#### 5.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服务器

## 六、报文格式

### 6.1. 控制指令

| 命令 | JSON 格式 | 说明 |
| -------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| 打开继电器 | `{"ctrl_cmd":{"open_relay_cmd":"xxxx"}}` | 打开继电器,xxxx为继电器编号,从0开始,如: {"ctrl_cmd":{"open_relay_cmd":"0"}} |
| 关闭继电器 | `{"ctrl_cmd":{"close_relay_cmd":"xxxx"}}` | 关闭继电器,xxxx为继电器编号,从0开始,如: {"ctrl_cmd":{"close_relay_cmd":"0"}} |
| 设置继电器状态 | `{"ctrl_cmd":{"set_relay_cmd":true}}` | 设置继电器状态,true: 闭合, false: 断开 |
| 切换继电器状态 | `{"ctrl_cmd":{"toggle_relay_cmd":"xxxx"}}` | 切换继电器状态,如果当前是闭合的,切换为断开,反之亦然 |
| 恢复出厂设置 | `{"ctrl_cmd":{"factory_params_cmd":"xxxx"}}` | 恢复出厂设置,xxxx参数可以为任意字符串 |
| 重启系统 | `{"ctrl_cmd":{"restart_cmd":"xxxx"}}` | 重启系统,xxxx参数可以为任意字符串 |
| OTA 更新 | `{"ctrl_cmd":{"ota_cmd":{"url":"xxxx"}}}` | OTA 升级，url 为固件升级地址 例：`{"ctrl_cmd":{"ota_cmd":{"url":"http://192.168.1.100:8080/firmware.bin"}}}` |
| 播放语音 | `{"ctrl_cmd":{"play_voice_cmd":"xxxx"}}` | 播放语音，xxxx为要播放的文字内容 举例:{"ctrl_cmd":{"play_voice_cmd":"欢迎使用智能设备"}} |
| 语音使能 | `{"ctrl_cmd":{"voice_enable_cmd":true}}` | 启用或禁用语音输出功能 |
| 设置语音模式 | `{"ctrl_cmd":{"set_voice_mode_cmd":0}}` | 设置语音播放模式 |
| 设置语音音量 | `{"ctrl_cmd":{"set_voice_volume_cmd":5}}` | 设置语音音量级别 范围:1-10 |
| 设置语音语速 | `{"ctrl_cmd":{"set_voice_speed_cmd":5}}` | 设置语音播放速度 范围:1-10 |
| 设置语音语调 | `{"ctrl_cmd":{"set_voice_tone_cmd":5}}` | 设置语音音调 范围:1-10 |
| 播放提示音 | `{"ctrl_cmd":{"play_prompt_voice_cmd":1}}` | 播放预设的提示音 范围:1-5 |
| 播放铃声 | `{"ctrl_cmd":{"play_bell_voice_cmd":1}}` | 播放预设的铃声 范围:1-5 |
| 播放警告音 | `{"ctrl_cmd":{"play_warning_voice_cmd":1}}` | 播放预设的警告音 范围:1-5 |
| 启动倒计时 | `{"ctrl_cmd":{"start_countdown_cmd":"xxxx"}}` | 启动倒计时功能 |
| 停止倒计时 | `{"ctrl_cmd":{"stop_countdown_cmd":"xxxx"}}` | 停止倒计时功能 |
| 设置倒计时秒数 | `{"ctrl_cmd":{"set_countdown_s_cmd":60}}` | 设置倒计时时间(秒),设置的时间为倒计时总时长 |
| 允许倒计时显示 | `{"ctrl_cmd":{"countdown_display_enable_cmd":true}}` | 启用倒计时数码管显示功能 |
| 禁止倒计时显示 | `{"ctrl_cmd":{"countdown_display_disable_cmd":true}}` | 禁用倒计时数码管显示功能 |
| 设置倒计时分钟数 | `{"ctrl_cmd":{"set_countdown_cmd":10}}` | 设置倒计时时间(分钟),设置的时间为倒计时总时长 |
| 打开继电器组 | `{"ctrl_cmd":{"open_relay_group_cmd":1}}` | 打开指定编号的继电器组 |
| 关闭继电器组 | `{"ctrl_cmd":{"close_relay_group_cmd":1}}` | 关闭指定编号的继电器组 |
| 切换继电器组状态 | `{"ctrl_cmd":{"toggle_relay_group_cmd":1}}` | 切换指定编号继电器组的状态 |

### 6.2. 参数设置&参数获取

| 参数名           | 设置参数                                                                 | 获取参数                                                | 默认值                        | 说明                                                                                                                                                            |
| ------------- | -------------------------------------------------------------------- | --------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 设备 ID         | `{"set_param":{"device_id":"dev001"}}`                              | `{"get_param":{"device_id":{}}}`                    | 使用 ESP32 芯片 ID             |                                                                                                                                                               |
| AP SSID       | `{"set_param":{"ap_ssid":"SmartDevice_AP"}}`                        | `{"get_param":{"ap_ssid":{}}}`                      | "SmartDevice"              |                                                                                                                                                               |
| AP 密码         | `{"set_param":{"ap_pwd":"12345678"}}`                               | `{"get_param":{"ap_pwd":{}}}`                       | "12345678"                 |                                                                                                                                                               |
| 软件版本          | -                                                                    | `{"get_param":{"soft_ver":{}}}`                     | 当前版本                       | 只读参数                                                                                                                                                          |
| 硬件版本          | -                                                                    | `{"get_param":{"hard_ver":{}}}`                     | 当前版本                       | 只读参数                                                                                                                                                          |
| 协议版本          | -                                                                    | `{"get_param":{"protocol_ver":{}}}`                 | 当前版本                       | 只读参数                                                                                                                                                          |
| 参数版本          | -                                                                    | `{"get_param":{"param_ver":{}}}`                    | 当前版本                       | 只读参数                                                                                                                                                          |
| 编译日期时间        | -                                                                    | `{"get_param":{"build_datetime":{}}}`               | 编译时日期时间                    | 只读参数                                                                                                                                                          |
| 完整版本信息        | -                                                                    | `{"get_param":{"full_ver":{}}}`                     | 版本信息                       | 只读参数,包含所有版本信息的组合字符串                                                                                                                                             |
| MQTT 服务器      | `{"set_param":{"mqtt_server":"mqtt.example.com"}}`                  | `{"get_param":{"mqtt_server":{}}}`                  | "192.168.1.45"             |                                                                                                                                                               |
| MQTT 端口       | `{"set_param":{"mqtt_port":1883}}`                                  | `{"get_param":{"mqtt_port":{}}}`                    | 1883                       |                                                                                                                                                               |
| MQTT 用户名      | `{"set_param":{"mqtt_username":"user"}}`                            | `{"get_param":{"mqtt_username":{}}}`                | ""                         |                                                                                                                                                               |
| MQTT 密码       | `{"set_param":{"mqtt_password":"pass"}}`                            | `{"get_param":{"mqtt_password":{}}}`                | ""                         |                                                                                                                                                               |
| MQTT 客户端 ID   | `{"set_param":{"client_id":"client001"}}`                           | `{"get_param":{"client_id":{}}}`                    | 基于 MAC 地址生成               |                                                                                                                                                               |
| 设备订阅主题        | `{"set_param":{"device_sub_topic":"dev001/sub"}}`                   | `{"get_param":{"device_sub_topic":{}}}`             | "dev001/sub"               |                                                                                                                                                               |
| 设备发布主题        | `{"set_param":{"device_pub_topic":"dev001/pub"}}`                   | `{"get_param":{"device_pub_topic":{}}}`             | "dev001/pub"               |                                                                                                                                                               |
| 网络控制台主题       | `{"set_param":{"device_net_console_topic":"dev001/console"}}`       | `{"get_param":{"device_net_console_topic":{}}}`     | "dev001/console"           |                                                                                                                                                               |
| TCP 服务器       | `{"set_param":{"tcp_server":"192.168.1.45"}}`                       | `{"get_param":{"tcp_server":{}}}`                   | "192.168.1.45"             |                                                                                                                                                               |
| TCP 端口        | `{"set_param":{"tcp_port":8080}}`                                   | `{"get_param":{"tcp_port":{}}}`                     | 8080                       |                                                                                                                                                               |
| HTTP 端口       | `{"set_param":{"http_port":80}}`                                    | `{"get_param":{"http_port":{}}}`                    | 80                         |                                                                                                                                                               |
| OTA 标志        | `{"set_param":{"ota_f":true}}`                                      | `{"get_param":{"ota_f":{}}}`                        | true                       | OTA 升级标志位,true:允许 OTA,false:禁止 OTA                                                                                                                            |
| 网络控制台使能       | `{"set_param":{"net_console_en":true}}`                             | `{"get_param":{"net_console_en":{}}}`               | false                      | 启用网络控制台功能,可通过 MQTT 发送调试命令                                                                                                                                      |
| 串口控制台使能       | `{"set_param":{"com_console_en":true}}`                             | `{"get_param":{"com_console_en":{}}}`               | true                       | 启用串口控制台功能,可通过串口发送调试命令                                                                                                                                         |
| Ping 功能使能     | `{"set_param":{"ping_en":true}}`                                    | `{"get_param":{"ping_en":{}}}`                      | true                       | 启用 Ping 主动上报功能                                                                                                                                             |
| Ping 上报间隔     | `{"set_param":{"ping_interval_s":30}}`                              | `{"get_param":{"ping_interval_s":{}}}`              | 60                         | Ping 消息上报间隔,单位:秒                                                                                                                                             |
| 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":{"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"                                                                                                                                     |
| 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:小于等于阈值触发                                                                                                                                        |
| 语音使能          | `{"set_param":{"voice_enable":true}}`                               | `{"get_param":{"voice_enable":{}}}`                 | true                       | 启用或禁用语音输出功能                                                                                                                                                  |
| 语音音量          | `{"set_param":{"voice_volume":5}}`                                  | `{"get_param":{"voice_volume":{}}}`                 | 5                          | 设置语音音量级别(1-10)                                                                                                                                               |
| 语音语速          | `{"set_param":{"voice_speed":5}}`                                   | `{"get_param":{"voice_speed":{}}}`                  | 5                          | 设置语音播放速度(1-10)                                                                                                                                               |
| 语音语调          | `{"set_param":{"voice_tone":5}}`                                    | `{"get_param":{"voice_tone":{}}}`                   | 5                          | 设置语音音调(1-10)                                                                                                                                                 |
| 语音模式          | `{"set_param":{"voice_mode":0}}`                                    | `{"get_param":{"voice_mode":{}}}`                   | 0                          | 设置语音播放模式                                                                                                                                                     |
| 倒计时显示使能       | `{"set_param":{"countdown_display_enable":true}}`                   | `{"get_param":{"countdown_display_enable":{}}}}`    | true                       | 启用或禁用倒计时数码管显示                                                                                                                                                |

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

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

| 命令 | 设置状态 | 获取状态 | 说明 |
| -------- | --------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------- |
| WiFi信号强度 | - | `{"get_status":{"rssi_abs":{}}}` | 只读参数,WiFi信号强度的绝对值: 50: 非常好 60~70: 好 70~80: 一般 80~90: 差 |
| 继电器状态 | - | `{"get_status":{"relay":{}}}` | 只读参数,继电器状态: true: 闭合 false: 断开 |
| 继电器组状态 | `{"set_status":{"relays":[true,false,true]}}` | `{"get_status":{"relays":{}}}` | 获取所有继电器状态数组: 返回格式: [true,false,true] 数组索引从0开始，对应继电器编号0,1,2... |
| 倒计时显示状态 | - | `{"get_status":{"countdown_display_enable":{}}}` | 只读参数,倒计时显示是否启用 |
| 倒计时显示值 | - | `{"get_status":{"countdown_display_value":{}}}` | 只读参数,当前倒计时显示值 |

### 6.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":{"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":{"in_ch":0,"triggered_evt":{}}}`           | 通道0,触发                 |
| 输入通道释放     | `{"event":{"in_ch":0,"released_evt":{}}}`            | 通道0,释放                 |
| 输入通道状态变化   | `{"event":{"in_ch":0,"state_changed_evt":{}}}`       | 通道0,状态变化               |

注意：
1. 按键事件上报中的数值表示按键索引，从0开始
2. 按键事件的触发时间：
   - 短按：立即触发
   - 双击：两次按键间隔小于300ms
   - 三击：三次按键间隔小于500ms
   - 长按：按住时间超过3秒
   - 超长按：按住时间超过10秒
3. 当按键被锁定时（key_lock=true），所有按键事件将被禁用
4. 输入通道事件中的in_ch表示通道编号，从0开始

### 6.5. 主动上报

"硬件终端"间隔一定的时间,会往"服务器端",上报的报文
该报文是可选,可使用"参数设置"报文开启或关闭
可通过"参数设置"报文,设置上报时间间隔

| 消息类型 | JSON 格式 | 说明 |
| ---- | ------------------------------------------------------------------------------------------ | -------------------- |
| 心跳包  | `{"report":{"ping": { "device_id": "xxxx", "full_ver": "x.x.x", "rssi_abs": "-70 dBm" }}}` | 包含设备基本信息 |

### 6.6. 消息应答

终端收到服务器下发的消息后,会根据消息执行结果返回对应的应答帧。
应答帧格式如下:

| 消息类型 | JSON 格式 | 说明 |
| ------ | --------------------------- | -------------------------------------------------------------------------------------- |
| 确认应答 | `{"ask":true}` | 命令执行成功的应答 |
| 否认应答 | `{"ask":false}` | 命令执行失败的应答 |
| 获取参数应答 | {"get_param":{"name":val}} | 举例: 发送`{"get_param":{"device_id":{}}}` 返回 `{"ask_param":{"device_id":"dev001"}}` |
| 获取状态应答 | {"get_status":{"name":val}} | 举例: 发送`{"get_status":{"relays":{}}}` 返回 `{"ask_status":{"relays":[true,false,true,false]}}` 继电器组状态查询应答示例 |
| 未知命令 | `{"unknown_cmd":0}` | 收到未知命令时的应答 |

## 七、MP3音频功能说明

### 7.1. 功能概述

MP3音频功能支持音频文件的上传、管理和播放。该功能使用专用的MP3协议进行文件传输和播放控制。

**支持型号**: RD

### 7.2. 主要功能

- **文件上传**：支持分块传输大文件
- **文件管理**：支持文件列表查询和删除
- **播放控制**：支持播放、停止、暂停等操作
- **校验机制**：支持文件完整性校验

### 7.3. 相关指令

| 功能 | 指令格式 | 说明 |
|------|---------|------|
| 开始上传 | `{"ctrl_cmd":{"mp3_upload_start_cmd":{"filename":"mp3-1.mp3","file_size":1024}}}` | 开始文件上传会话 |
| 数据传输 | `{"ctrl_cmd":{"mp3_upload_data_cmd":{"session_id":"xxx","chunk_index":0,"data":"base64data"}}}` | 传输文件数据块 |
| 完成上传 | `{"ctrl_cmd":{"mp3_upload_finish_cmd":{"session_id":"xxx"}}}` | 结束上传会话 |
| 播放文件 | `{"ctrl_cmd":{"mp3_play_cmd":"mp3-1.mp3"}}` 或 `{"ctrl_cmd":{"mp3_play_cmd":{"filename":"mp3-1.mp3"}}}` | 播放指定文件，支持两种格式 |
| 停止播放 | `{"ctrl_cmd":{"mp3_stop_cmd":{}}}` | 停止当前播放 |
| 暂停播放 | `{"ctrl_cmd":{"mp3_pause_cmd":{}}}` | 暂停当前播放 |
| 恢复播放 | `{"ctrl_cmd":{"mp3_resume_cmd":{}}}` | 恢复播放 |
| 文件列表 | `{"ctrl_cmd":{"mp3_list_cmd":{}}}` | 获取文件列表 |
| 删除文件 | `{"ctrl_cmd":{"mp3_delete_cmd":{"filename":"mp3-1.mp3"}}}` | 删除指定文件 |

### 7.4. 文件上传流程

```mermaid
sequenceDiagram
    participant App as 应用终端
    participant Device as RD设备

App->>Device: 开始上传 {"ctrl_cmd":{"mp3_upload_start_cmd":{"filename":"mp3-1.mp3","file_size":1024}}}
    Device-->>App: 返回会话ID {"ask":true, "session_id":"xxx"}
    
    loop 分块传输
        App->>Device: 数据传输 {"ctrl_cmd":{"mp3_upload_data_cmd":{"session_id":"xxx","chunk_index":0,"data":"base64data"}}}
        Device-->>App: 确认接收 {"ask":true}
    end
    
    App->>Device: 完成上传 {"ctrl_cmd":{"mp3_upload_finish_cmd":{"session_id":"xxx"}}}
    Device-->>App: 确认完成 {"ask":true}
```

### 7.5. 播放控制流程

```mermaid
sequenceDiagram
    participant App as 应用终端
    participant Device as RD设备

App->>Device: 播放文件 {"ctrl_cmd":{"mp3_play_cmd":"mp3-1.mp3"}}
    Device-->>App: 开始播放 {"ask":true}
    Note over Device: 播放音频文件
    
    App->>Device: 暂停播放 {"ctrl_cmd":{"mp3_pause_cmd":{}}}
    Device-->>App: 暂停确认 {"ask":true}
    
    App->>Device: 恢复播放 {"ctrl_cmd":{"mp3_resume_cmd":{}}}
    Device-->>App: 恢复确认 {"ask":true}
    
    App->>Device: 停止播放 {"ctrl_cmd":{"mp3_stop_cmd":{}}}
    Device-->>App: 停止确认 {"ask":true}
```

## 八、倒计时功能说明

### 8.1. 功能概述

倒计时功能是RD产品的核心特性，支持倒计时设置、显示控制和时间管理。

**支持型号**: RD

### 8.2. 主要功能

- **倒计时设置**：支持按秒或分钟设置倒计时时间
- **显示控制**：支持启用/禁用数码管显示
- **时间管理**：支持启动、停止倒计时功能

### 8.3. 使用流程

```mermaid
sequenceDiagram
    participant App as 应用终端
    participant Device as RD设备

App->>Device: 设置倒计时时间 {"ctrl_cmd":{"set_countdown_s_cmd":60}}
    Device-->>App: 设置确认 {"ask":true}
    
    App->>Device: 启用显示 {"ctrl_cmd":{"countdown_display_enable_cmd":true}}
    Device-->>App: 显示启用 {"ask":true}
    
    App->>Device: 启动倒计时 {"ctrl_cmd":{"start_countdown_cmd":"start"}}
    Device-->>App: 启动确认 {"ask":true}
    Note over Device: 倒计时开始，数码管显示
    
    App->>Device: 查询显示值 {"get_status":{"countdown_display_value":{}}}
    Device-->>App: 返回当前值 {"ask_status":{"countdown_display_value":45}}
    
    App->>Device: 停止倒计时 {"ctrl_cmd":{"stop_countdown_cmd":"stop"}}
    Device-->>App: 停止确认 {"ask":true}
```

### 8.4. 相关指令说明

| 功能 | 指令格式 | 说明 |
|------|---------|------|
| 设置倒计时(秒) | `{"ctrl_cmd":{"set_countdown_s_cmd":60}}` | 设置倒计时总时间，单位：秒 |
| 设置倒计时(分钟) | `{"ctrl_cmd":{"set_countdown_cmd":10}}` | 设置倒计时总时间，单位：分钟 |
| 启动倒计时 | `{"ctrl_cmd":{"start_countdown_cmd":"start"}}` | 开始倒计时功能 |
| 停止倒计时 | `{"ctrl_cmd":{"stop_countdown_cmd":"stop"}}` | 停止倒计时功能 |
| 启用显示 | `{"ctrl_cmd":{"countdown_display_enable_cmd":true}}` | 启用数码管显示 |
| 禁用显示 | `{"ctrl_cmd":{"countdown_display_disable_cmd":true}}` | 禁用数码管显示 |
| 查询显示状态 | `{"get_status":{"countdown_display_enable":{}}}` | 查询显示是否启用 |
| 查询当前值 | `{"get_status":{"countdown_display_value":{}}}` | 查询当前倒计时显示值 |

## 九、输入通道功能说明

### 9.1. 功能概述

输入通道功能支持多种输入信号的监控和处理，包括GPIO和ADC通道。

**支持型号**: RD

### 9.2. 硬件特性

- **通道类型**：支持GPIO和ADC两种类型的输入通道
- **触发模式**：可配置触发电平和阈值
- **去抖处理**：支持可配置的去抖时间
- **有效性判断**：支持触发次数阈值判断

### 9.3. GPIO通道配置

| 参数 | 设置指令 | 获取指令 | 默认值 | 说明 |
|------|---------|---------|-------|------|
| 去抖时间 | `{"set_param":{"gpio_ch_debounce_ms":100}}` | `{"get_param":{"gpio_ch_debounce_ms":{}}}` | 100 | 单位：毫秒 |
| 触发次数阈值 | `{"set_param":{"gpio_ch_tri_cnt":3}}` | `{"get_param":{"gpio_ch_tri_cnt":{}}}` | 3 | 有效触发所需次数 |
| 触发模式 | `{"set_param":{"gpio_ch_tri_mode":0}}` | `{"get_param":{"gpio_ch_tri_mode":{}}}` | 0 | 0:低电平触发，1:高电平触发 |

### 9.4. ADC通道配置

| 参数 | 设置指令 | 获取指令 | 默认值 | 说明 |
|------|---------|---------|-------|------|
| 触发阈值 | `{"set_param":{"adc_ch_tri_th":2048}}` | `{"get_param":{"adc_ch_tri_th":{}}}` | 2048 | ADC触发阈值 |
| 去抖时间 | `{"set_param":{"adc_ch_debounce_ms":100}}` | `{"get_param":{"adc_ch_debounce_ms":{}}}` | 100 | 单位：毫秒 |
| 触发次数阈值 | `{"set_param":{"adc_ch_tri_cnt":3}}` | `{"get_param":{"adc_ch_tri_cnt":{}}}` | 3 | 有效触发所需次数 |
| 触发模式 | `{"set_param":{"adc_tri_th_mode":0}}` | `{"get_param":{"adc_tri_th_mode":{}}}` | 0 | 0:大于等于阈值触发，1:小于等于阈值触发 |

### 9.5. 事件上报

| 事件类型 | JSON 格式 | 说明 |
|---------|----------|------|
| 通道触发 | `{"event":{"in_ch":0,"triggered_evt":{}}}` | 指定通道被触发 |
| 通道释放 | `{"event":{"in_ch":0,"released_evt":{}}}` | 指定通道释放 |
| 状态变化 | `{"event":{"in_ch":0,"state_changed_evt":{}}}` | 通道状态变化 |

### 9.6. 工作原理

1. **GPIO通道工作原理**：
   - 监测数字信号的电平变化
   - 根据配置的触发模式判断有效触发
   - 通过去抖处理避免信号抖动

2. **ADC通道工作原理**：
   - 监测模拟信号的数值变化
   - 根据配置的阈值和触发模式判断有效触发
   - 通过去抖处理确保信号稳定性

3. **触发有效性判断**：
   - 只有当连续触发次数达到配置阈值时才认为有效
   - 有效触发后上报相应的事件

## 十、版本历史

### v1.5.0 (当前版本)
- 基于主协议v1.5提取RD产品专用协议
- 包含继电器控制、语音功能、倒计时显示、MP3播放等完整功能
- 支持输入通道监控功能
- 完善的参数配置和事件上报机制