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

# 项目版本: v2.1.2
***
## 一、前言

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

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

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

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

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

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

## 二、产品型号说明

本项目支持多种产品型号：

| 编号 | 名称 | 功能描述 |
| ------- | ----------- | ---------------------------------------------- |
| D2_CONV | 智能插座转换器 | 远程控制 电压检测, 电流检测, 功率检测 电压报警, 电流报警, 功率报警 |
| D2_SOC | 标准智能插座 | 远程控制 电压检测, 电流检测, 功率检测 电压报警, 电流报警, 功率报警 |
| D2_BRK | 智能电闸 | 单继电器控制 电压检测, 电流检测, 功率检测 电压报警, 电流报警, 功率报警 |
| D2_SOD | 智能云喇叭 | 语音播报 音量调节, 音调调节, 男女声切换 |
| D2_AP | 断电报警器 (喇叭新) | 断电上报 远程控制 |
| D2_CBOX | 控制盒 | 远程控制 电压检测, 电流检测, 功率检测 电压报警, 电流报警, 功率报警 |
| D2_SBOX | 迷你控制盒 | 远程控制 |

## 三、设备标识 (device_no)

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

## 四、通信协议

### 4.1 MQTT 主题说明

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

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

### 4.2 支持的命令列表

1. 控制命令 (ctrl_cmd):
	控制指令发送成功后,设备终端会返回一个"确认帧"或"否认帧"用于响应控制命令是否执行成功

| 命令     | JSON 格式                                                              | 说明         | 支持型号                  |
| ------ | -------------------------------------------------------------------- | ---------- | ----------------------- |
| OTA更新  | `{"ctrl_cmd":{"ota_cmd":{"url":"http://example.com/firmware.bin"}}}` | 固件升级       | ALL                     |
| 恢复出厂设置 | `{"ctrl_cmd":{"factory_params_cmd":{}}}`                             | 恢复出厂设置     | ALL                     |
| 重启设备   | `{"ctrl_cmd":{"restart_cmd":{}}`                                     | 重启系统       | ALL                     |
| 打开继电器  | `{"ctrl_cmd":{"open_relay_cmd":{}}`                                  | 打开继电器      | D2_CONV\|D2_SOC\|D2_BRK |
| 反转继电器  | `{"ctrl_cmd":{"toggle_relay_cmd":{}}`                                | 切换继电器状态    | D2_CONV\|D2_SOC\|D2_BRK |
| 语音播报   | `{"ctrl_cmd":{"play_voice_cmd":"要播报的文本内容"}}`                         | 播放指定文本内容   | D2_SOD                  |
| 提示音播放  | `{"ctrl_cmd":{"play_prompt_voice_cmd":1}}`                           | 播放提示音(1-5) | D2_SOD                  |
| 警示音播放  | `{"ctrl_cmd":{"play_voice_prompt_cmd":1}}`                           | 播放警示音(1-5) | D2_SOD                  |
| 铃声播放   | `{"ctrl_cmd":{"play_bell_voice_cmd":1}}`                             | 播放铃声(1-5)  | D2_SOD                  |

3. 参数设置&参数获取:
	发送参数设置命令后,设备终端会返回一个"确认帧"或"否认帧"用于响应控制命令是否执行成功
	发送获取函数命令后,设备终端会根据查询的参数,返回应答帧,具体参考: [[#5.4 消息应答]]

| 命令 | 设置参数 | 获取参数 | 说明 | 支持型号 |
| --------- | ----------------------------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| 设备ID | `{"set_param":{"device_id":"dev001"}}` | `{"get_param":{"device_id":{}}}` | 设置设备ID后会自动更新: device_sub_topic为"{device_id}/device_sub_topic"、 2. device_pub_topic为"{device_id}/device_pub_topic"、 3. ap_ssid为"esp_{device_id}" | ALL |
| MQTT服务器 | `{"set_param":{"mqtt_server":"xxx.xxx.xxx"}}` | `{"get_param":{"mqtt_server":{}}}` | | ALL |
| MQTT端口 | `{"set_param":{"mqtt_port":1883}}` | `{"get_param":{"mqtt_port":{}}}` | | ALL |
| MQTT用户名 | `{"set_param":{"mqtt_username":"xxxx"}}` | `{"get_param":{"mqtt_username":{}}}` | | ALL |
| MQTT密码 | `{"set_param":{"mqtt_password":"xxxx"}}` | `{"get_param":{"mqtt_password":{}}}` | | ALL |
| AP密码 | `{"set_param":{"ap_pwd":"xxxx"}}` | `{"get_param":{"ap_pwd":{}}}` | | ALL |
| 网络调试状态 | `{"set_param":{"net_console_en":true}}` | `{"get_param":{"net_console_en":{}}}` | | ALL |
| 串口调试状态 | `{"set_param":{"com_console_en":true}}` | `{"get_param":{"com_console_en":{}}}` | | ALL |
| 网络调试主题 | `{"set_param":{"device_net_console_topic":"xxxx"}}` | `{"get_param":{"device_net_console_topic":{}}}` | | ALL |
| 软件版本号 | - | `{"get_param":{"soft_ver":{}}}` | 只读参数 | ALL |
| 硬件版本号 | - | `{"get_param":{"hard_ver":{}}}` | 只读参数 | ALL |
| 协议版本号 | - | `{"get_param":{"protocol_ver":{}}}` | 只读参数 | ALL |
| 编译时间 | - | `{"get_param":{"build_datetime":{}}}` | 只读参数 | ALL |
| 参数版本号 | - | `{"get_param":{"param_ver":{}}}` | 只读参数 | ALL |
| 完整版本号 | - | `{"get_param":{"full_ver":{}}}` | 只读参数 | ALL |
| WiFi信号强度 | - | `{"get_param":{"rssi_abs":{}}}` | 只读参数,单位:dBm | ALL |
| 全局发布主题 | `{"set_param":{"device_global_pub_topic":"device_global_pub_topic"}}` | `{"get_param":{"device_global_pub_topic":{}}}` | 设置全局发布主题 | ALL |
| 全局订阅主题 | `{"set_param":{"device_global_sub_topic":"device_global_sub_topic"}}` | `{"get_param":{"device_global_sub_topic":{}}}` | 设置全局订阅主题 | ALL |
| 设备订阅主题 | `{"set_param":{"device_sub_topic":"device_sub_topic"}}` | `{"get_param":{"device_sub_topic":{}}}` | 设置设备订阅主题 | ALL |
| 设备发布主题 | `{"set_param":{"device_pub_topic":"device_pub_topic"}}` | `{"get_param":{"device_pub_topic":{}}}` | 设置设备发布主题 | ALL |
| 网络调试主题 | `{"set_param":{"device_net_console_topic":"device_net_console_topic"}}` | `{"get_param":{"device_net_console_topic":{}}}` | 设置网络调试主题 | ALL |
| 网络调试使能 | `{"set_param":{"net_console_en":true}}` | `{"get_param":{"net_console_en":{}}}` | 设置网络调试使能状态 | ALL |
| 串口调试使能 | `{"set_param":{"com_console_en":true}}` | `{"get_param":{"com_console_en":{}}}` | 设置串口调试使能状态 | ALL |
| WiFi SSID | `{"set_param":{"wifi_ssid":"xxxx"}}` | `{"get_param":{"wifi_ssid":{}}}` | | D2_CONV\|D2_SOC\|D2_BRK\|D2_CBOX\|D2_SBOX |
| WiFi密码 | `{"set_param":{"wifi_pwd":"xxxx"}}` | `{"get_param":{"wifi_pwd":{}}}` | | D2_CONV\|D2_SOC\|D2_BRK\|D2_CBOX\|D2_SBOX |
| 继电器状态 | `{"set_param":{"relay":true}}` | `{"get_param":{"relay":{}}}` | | D2_CONV\|D2_SOC\|D2_BRK\|D2_CBOX\|D2_SBOX |
| 过压阈值 | `{"set_param":{"over_voltage_threshold":250}}` | `{"get_param":{"over_voltage_threshold":{}}}` | 设置过压保护阈值(单位:V) | D2_CONV\|D2_SOC\|D2_BRK\|D2_CBOX |
| 过流阈值 | `{"set_param":{"over_current_threshold":2000}}` | `{"get_param":{"over_current_threshold":{}}}` | 设置过流保护阈值(单位:mA) | D2_CONV\|D2_SOC\|D2_BRK\|D2_CBOX |
| 过功率阈值 | `{"set_param":{"over_power_threshold":2200}}` | `{"get_param":{"over_power_threshold":{}}}` | 设置过功率保护阈值(单位:W) | D2_CONV\|D2_SOC\|D2_BRK\|D2_CBOX |
| 过温阈值 | `{"set_param":{"over_temperature_threshold":75}}` | `{"get_param":{"over_temperature_threshold":{}}}` | 设置过温保护阈值(单位:℃) | D2_CONV\|D2_SOC\|D2_BRK\|D2_CBOX |
| 电压值 | - | `{"get_param":{"voltage_v":{}}}` | 只读参数,单位:V | D2_CONV\|D2_SOC\|D2_BRK\|D2_CBOX |
| 电流值 | - | `{"get_param":{"current_ma":{}}}` | 只读参数,单位:mA | D2_CONV\|D2_SOC\|D2_BRK\|D2_CBOX |
| 功率值 | - | `{"get_param":{"power_w":{}}}` | 只读参数,单位:W | D2_CONV\|D2_SOC\|D2_BRK\|D2_CBOX |
| 温度值 | - | `{"get_param":{"temperature_c":{}}}` | 只读参数,单位:℃ | D2_CONV\|D2_SOC\|D2_BRK\|D2_CBOX |
| 语音播报开关 | `{"set_param":{"voice_enable_cmd":true}}` | `{"get_param":{"voice_enable_cmd":{}}}` | 开启/关闭语音播报功能 | D2_SOD |
| 语调 | `{"set_param":{"set_voice_tone_cmd":5}}` | `{"get_param":{"set_voice_tone_cmd":{}}}` | 设置语音音调(0-9) | D2_SOD |
| 音量 | `{"set_param":{"set_voice_volume_cmd":5}}` | `{"get_param":{"set_voice_volume_cmd":{}}}` | 设置语音音量(0-9) | D2_SOD\|D2_AP |
| 灯光使能 | `{"set_param":{"light_enable_cmd":true}}` | `{"get_param":{"light_enable_cmd":{}}}` | 开启/关闭灯光功能 | D2_SOD\|D2_AP |
| 灯光模式 | `{"set_param":{"light_mode_cmd":0}}` | `{"get_param":{"light_mode_cmd":{}}}` | 设置灯光模式(0:常亮 1:呼吸 2:闪烁) | D2_SOD\|D2_AP |
| 人声模式 | `{"set_param":{"voice_mode_cmd":0}}` | `{"get_param":{"voice_mode_cmd":{}}}` | 设置人声模式(0:标准男声 1:标准女声) | D2_SOD |
| 语速 | `{"set_param":{"voice_speed_cmd":5}}` | `{"get_param":{"voice_speed_cmd":{}}}` | 设置语音速度(0-9) | D2_SOD |

#### 5.3 消息上报

终端运行过程中，在运行至特殊的状态时，会主动往 device_no/device_pub_topic 上报数据，上报格式为 JSON 格式。

| 事件类型       | 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":状态}}` | 继电器状态发生改变时上报  | D2_CONV\|D2_SOC\|D2_BRK |
| 断电事件       | `{"event":{"powerdown_evt":""}}`          | 设备断电时上报       | D2_ARMS                 |

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

| 消息类型 | JSON 格式 | 说明 | 支持型号 |
| ------ | -------------------------------------- | -------------------------------------------------------------------------------------- | ---- |
| 确认应答 | `{"ask":true}` | 命令执行成功的应答 | ALL |
| 否认应答 | `{"ask":false}` | 命令执行失败的应答 | ALL |
| 获取参数应答 | {"ask_param":{"param_name":param_val}} | 举例: 发送`{"get_param":{"device_id":{}}}` 返回 `{"get_param":{"device_id":"dev001"}}` | ALL |
| 未知命令 | `{"unknown_cmd":0}` | 收到未知命令时的应答 | ALL |
| | | | |

注意：所有这些消息都会同时发送到 device_no/device_pub_topic 主题。
***