智能硬件-通讯协议说明书

# 智能硬件通信协议说明 v1
## 一、前言
本文档详细说明了智能硬件设备与服务器之间的通信协议规范。主要包含以下内容:

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

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

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

4. 通用功能支持
   - 继电器控制
   - 网络配置
   - 状态查询
   - 事件上报

本协议适用于所有支持 MQTT 通信的智能硬件设备,确保设备与服务器之间可靠、统一的数据交互。

## 二、设备标识 (device_no)

1. 用途：代表终端的唯一编号
2. 默认值：设备的 MAC 地址

## 三、命令列表

### 3.1 MQTT 主题说明

| 主题 | 用途 | 通信方向 |
|------|------|----------|
| `device_no/device_sub_topic` | 接收服务器指令和数据 | 服务器 → 设备 |
| `device_no/device_pub_topic` | 发送状态更新和事件通知 | 设备 → 服务器 |

示例:
1. 服务器通过 `device_no/device_sub_topic` 发送开继电器命令: `{"open_relay_cmd":""}`
2. 设备订阅了此主题,收到命令后执行开继电器操作
3. 操作完成后,设备通过 `device_no/device_pub_topic` 回复执行结果: `{"ask":1}`

注：`device_no` 为设备唯一标识符。

### 3.2 命令应答说明

服务器端发送给设备的每个命令都会有对应的应答数据:

1. 对于无需返回具体数据的命令:
   - 如果指令执行成功,设备会返回确认帧: `{"ask":1}`
   - 如果指令执行失败,设备会返回否认帧: `{"ask":0}`

2. 对于查询类命令:
   - 设备会返回具体的查询数据(如系统信息查询等)
   - 数据格式参见"五、消息上报"章节

3. 对于未知命令:
   - 设备会返回未知命令帧: `{"unknown_cmd":0}`

注意: 每个命令都必定会有一个对应的响应,确保通信的可靠性。

### 3.3 通用命令列表

| 命令            | JSON 格式                                            | 说明              |
| ------------- | -------------------------------------------------- | --------------- |
| 打开继电器         | `{"open_relay_cmd":""}`                            | 所有设备通用          |
| 关闭继电器         | `{"close_relay_cmd":""}`                           | 所有设备通用          |
| 设置继电器         | `{"set_relay_cmd":0}`                              | 所有设备通用          |
| 反转继电器         | `{"toggle_relay_cmd":""}`                          | 所有设备通用          |
| 修改服务器地址       | `{"set_mqtt_server_cmd":"www.example.com"}`        | 所有设备通用          |
| 修改 Wi-Fi SSID | `{"set_wifi_ssid_cmd":"xxxx"}`                     | 所有设备通用          |
| 修改 Wi-Fi 密码   | `{"set_wifi_pwd_cmd":"xxxx"}`                      | 所有设备通用          |
| 修改 MQTT 用户名   | `{"set_mqtt_username_cmd":"xxxx"}`                 | 所有设备通用          |
| 修改 MQTT 密码    | `{"set_mqtt_password_cmd":"xxxx"}`                 | 所有设备通用          |
| 设置 MQTT 端口    | `{"set_mqtt_port_cmd":1883}`                       | 所有设备通用          |
| 设置设备 ID       | `{"set_device_id_cmd":"xxxx"}`                     | 所有设备通用          |
| 获取系统信息        | `{"get_system_info_cmd":""}`                       | 所有设备通用          |
| 恢复出厂设置        | `{"factory_params_cmd":""}`                        | 所有设备通用          |
| 重启设备          | `{"restart_cmd":""}`                               | 所有设备通用          |
| 获取版本信息        | `{"get_version_cmd":""}`                           | 获取软件、硬件、协议版本等信息 |
| OTA 升级        | `{"ota_update":"http://example.com/firmware.bin"}` | 通过指定 URL 升级固件   |
|               |                                                    |                 |

### 3.4 专用命令列表

#### 3.4.1 DWY421 专用命令

| 命令 | JSON 格式 | 说明 |
|------|-----------|------|
| 语音播报 | `{"play_voice_cmd":"b4f3bcd2bac3"}` | "b4f3bcd2bac3" 为 GBK 编码的十六进制字符串 |
| 打开倒计时 | `{"start_countdown_cmd":""}` | 需先设置倒计时时间 |
| 关闭倒计时 | `{"stop_countdown_cmd":""}` | |
| 设置倒计时 | `{"set_countdown_cmd":100}` | 单位：分钟 |
| 设置开门模式 | `{"set_open_door_mode_cmd":0}` | 0: 正常模式, 1: 常开模式 |
| 设置按键控制 | `{"set_click_key_ctrl_cmd":0}` | 0: 禁用按键控制继电器, 1: 启用按键控制继电器 |

## 四、消息上报

### 4.1 消息上报说明

设备在运行过程中,会在特定事件触发时自动上报消息:
1. 设备上电时会上报一次系统信息
2. 设备状态发生变化时会实时上报
3. 设备检测到异常情况时会立即上报告警信息
4. 所有上报消息均为 JSON 格式

### 4.2 通用消息上报

| 事件 | JSON 格式 | 说明 |
|------|-----------|------|
| 系统信息上报 | `{"system_info_event":{"soft_ver":"版本号","hard_ver":"版本号","relay":"状态","wifi_ssid":"SSID","wifi_pwd":"密码","mqtt_server":"服务器地址","mqtt_port":端口号,"mqtt_username":"用户名","mqtt_password":"密码","device_id":"设备ID","device_sub_topic":"订阅主题","device_pub_topic":"发布主题"}}` | 设备上电时上报 |
| 继电器状态变化 | `{"relay_state_change_event":状态}` | 状态: 0关闭,1打开 |
| 命令确认应答 | `{"ask":1}` | 命令执行成功 |
| 命令否认应答 | `{"ask":0}` | 命令执行失败 |
| 未知命令应答 | `{"unknown_cmd":0}` | 收到未知命令时 |

### 4.3 专用消息上报

#### 4.3.1 DWY421 专用消息

| 事件 | JSON 格式 | 说明 |
|------|-----------|------|
| 倒计时完成 | `{"countdown_finish_event":1}` | 倒计时结束时上报 |
| 语音播报成功 | `{"play_voice_result_event":1}` | 语音播放完成 |
| 语音播报失败 | `{"play_voice_result_event":0}` | 语音播放失败 |

#### 4.3.2 DWY41 专用消息

| 事件 | JSON 格式 | 说明 |
|------|-----------|------|
| 过压保护触发 | `{"over_voltage_event":1}` | 电压超过阈值 |
| 欠压保护触发 | `{"under_voltage_event":1}` | 电压低于阈值 |
| 过流保护触发 | `{"over_current_event":1}` | 电流超过阈值 |
| 过温保护触发 | `{"over_temperature_event":1}` | 温度超过阈值 |
| 漏电保护触发 | `{"leakage_event":1}` | 检测到漏电 |

#### 4.3.3 DWY311 专用消息

| 事件 | JSON 格式 | 说明 |
|------|-----------|------|
| 过载保护触发 | `{"overload_event":1}` | 功率超过阈值 |
| 电量统计上报 | `{"power_statistics_event":{"voltage":电压值,"current":电流值,"power":功率值,"energy":电量值}}` | 定时上报用电数据 |