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

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

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

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

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

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

4. 适用的产品型号

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

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

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

## 三、设备标识 (device_id)

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

## 四、通信协议

### 4.1. MQTT 协议
#### 4.1.1. MQTT 协议概要
9. mqtt 通讯基于2个主题,device_id/device_pub_topic与device_id/device_sub_topic
10. "硬件终端"通过device_id/device_pub_topic主题发布数据,"应用终端"通过该主题接收"硬件终端"的数据
11. "硬件终端"通过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 协议概要
12. TCP Client 代表"硬件终端"作为TCP客户端与"服务器端"进行socket通讯
13. "硬件终端"上电联网完成后,会主动与"服务器端"建立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连接请求(SYN)
    TCP_Server-->>TCP_Client: 确认连接请求(SYN+ACK)
    TCP_Client->>TCP_Server: 完成连接建立(ACK)
    Note over TCP_Client,TCP_Server: TCP连接建立完成

TCP_Client->>TCP_Server: 事件上报
    Note right of TCP_Client: 事件通知(如设备状态变化)

TCP_Server->>TCP_Client: 发送控制指令
    Note right of TCP_Server: 控制命令或参数请求

TCP_Client-->>TCP_Server: 回复执行结果
    Note right of TCP_Client: 执行指令并反馈状态

Note over TCP_Client,TCP_Server: 连接保持,可继续通信
    Note over TCP_Client,TCP_Server: 任一方可主动断开连接
```
*TCP Client 采用 ascii 编码通讯内容*

### 4.3. HTTP Server 协议 
#### 4.3.1. HTTP Server 协议概要
1. 由于HTTP协议的限制,"硬件终端"无法支持"事件上报"与"消息上报"
#### 4.3.2. HTTP Server 通讯框图
	以下图表,展示了"应用终端"发送控制指令给到"硬件终端"的通讯流程图
```mermaid
sequenceDiagram
    participant App_Client
    participant HW_HTTP_Server

App_Client->>HW_HTTP_Server: 发送控制指令请求
    Note right of App_Client: 控制命令请求

HW_HTTP_Server-->>App_Client: 返回执行结果
    Note right of HW_HTTP_Server: 处理请求并反馈状态
```
* APP_Client: "应用终端"
* HW_HTTP_SERVER: "硬件终端"
#### 4.3.3. 通讯报文举例
##### HTTP 请求报文
假设我们要发送一个 POST 请求，其中包含 JSON 格式的数据：

```
POST /device_id HTTP/1.1
Host: example.com
Content-Type: application/json
Content-Length: 85

{
    "ctrl_cmd": {
        "open_relay_cmd": {}
    }
}
```

- **请求行**：`POST /device_id HTTP/1.1` 指定了请求方法为 POST，请求的资源路径为 `/device_id，使用的 HTTP 版本为 1.1。
- **头部字段**：
    - `Host: example.com` 指定了目标服务器的主机名。
    - `Content-Type: application/json` 指定了请求主体的数据格式为 JSON。
    - `Content-Length: 85` 指定了请求主体的字节长度。
- **主体**：包含了实际的数据负载，这里是一个 JSON 格式的控制命令。

##### HTTP 响应报文

假设服务器返回一个成功的响应：

```
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 17

{
    "ask": true
}
```

- **状态行**：`HTTP/1.1 200 OK` 指定了 HTTP 版本为 1.1，状态码为 200，表示请求成功。
- **头部字段**：
    - `Content-Type: application/json` 指定了响应主体的数据格式为 JSON。
    - `Content-Length: 17` 指定了响应主体的字节长度。
- **主体**：包含了实际的数据负载，这里是一个 JSON 格式的确认应答。
## 五、通讯报文
	所有协议都共用同一套通讯报文,TCP_Client,MQTT等
### 5.1. 控制命令 
	控制指令发送成功后,设备终端会返回一个"确认帧"或"否认帧"用于响应控制命令是否执行成功

| 命令 | 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":{"close_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 |
| 打开倒计时 | `{"ctrl_cmd":{"start_countdown_cmd":""}}` | 需先设置倒计时时间 | ALL |
| 关闭倒计时 | `{"ctrl_cmd":{"stop_countdown_cmd":""}}` | | ALL |
| 设置倒计时 | `{"ctrl_cmd":{"set_countdown_cmd":100}}` | 单位：分钟 | ALL |
| 灯光控制 | `{"ctrl_cmd":{"set_light_cmd":0}}` | 0:关闭灯光 1:红灯常亮 2:绿灯常亮 3:蓝灯常亮 *注意:只有light_ctrl_en==true,该指令才起作用* | ALL |
| 灯光闪烁 | `{"ctrl_cmd":{"flash_light_cmd":1}}` | 0:停止闪烁 1:红灯闪烁 2:绿灯闪烁 3:蓝灯闪烁 *注意:只有light_ctrl_en==true,该指令才起作用* | ALL |

### 5.2. 参数设置&参数获取
	发送参数设置命令后,设备终端会返回一个"确认帧"或"否认帧"用于响应控制命令是否执行成功
	发送获取函数命令后,设备终端会根据查询的参数,返回应答帧,具体参考: [[#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 |
| 心跳包使能 | `{"set_param":{"ping_en":true}}` | `{"get_param":{"ping_en":{}}}` | 设置心跳包使能状态 | ALL |
| 心跳包周期 | `{"set_param":{"ping_interval_s":60}}` | `{"get_param":{"ping_interval_s":{}}}` | 设置心跳包上报周期,单位,秒 | 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_v_th":250}}` | `{"get_param":{"over_voltage_v_th":{}}}` | 设置过压保护阈值(单位:V) | D2_CONV\|D2_SOC\|D2_BRK\|D2_CBOX |
| 过流阈值 | `{"set_param":{"over_current_ma_th":2000}}` | `{"get_param":{"over_current_ma_th":{}}}` | 设置过流保护阈值(单位:mA) | D2_CONV\|D2_SOC\|D2_BRK\|D2_CBOX |
| 过功率阈值 | `{"set_param":{"over_power_w_th":2200}}` | `{"get_param":{"over_power_w_th":{}}}` | 设置过功率保护阈值(单位:W) | D2_CONV\|D2_SOC\|D2_BRK\|D2_CBOX |
| 过温阈值 | `{"set_param":{"over_temperature_c_th":75}}` | `{"get_param":{"over_temperature_c_th":{}}}` | 设置过温保护阈值(单位:℃) | 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":{"current_calibration":100}}` | `{"get_param":{"current_calibration":{}}}` | 用于校准BL0937测量电流的误差,正值表示增加,负值表示减少,范围: -1000~1000 | D2_CONV\|D2_SOC\|D2_BRK\|D2_CBOX |
| 电压校准参数 | `{"set_param":{"voltage_calibration":-50}}` | `{"get_param":{"voltage_calibration":{}}}` | 用于校准BL0937测量电压的误差,正值表示增加,负值表示减少,范围: -1000~1000 | 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 |
| 灯光闪烁频率 | `{"set_param":{"light_hz_ms":100}}` | `{"get_param":{"voice_speed_cmd":{}}}` | 设置灯光闪烁频率,单位:ms | |
| 灯控使能 | `{"set_param":{"light_ctrl_en":true}}` | `{"get_param":{"light_ctrl_en":{}}}` | 灯控使能,只有参数打开时,才允许进行灯光控制,同时也以为着,灯光将不在指示硬件状态,例如在联网过程中,灯光将不在闪烁提示,完全交由用户控制 | |

### 5.3. 事件上报

| 事件类型       | 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                 |
| 电流过流事件     | `{"event":{"current_over_evt":当前电流}}`     | 当检测到电流超过阈值时上报     | D2_CONV\|D2_SOC\|D2_BRK |
| 过流恢复事件     | `{"event":{"current_recovery_evt":当前电流}}` | 电流恢复正常后上报         | D2_CONV\|D2_SOC\|D2_BRK |
| 电压过压事件     | `{"event":{"voltage_over_evt":当前电压}}`     | 当检测到电压超过阈值时上报     | D2_CONV\|D2_SOC\|D2_BRK |
| 过压恢复事件     | `{"event":{"voltage_recovery_evt":当前电压}}` | 电压恢复正常后上报         | D2_CONV\|D2_SOC\|D2_BRK |
| 功率过载事件     | `{"event":{"power_over_evt":当前功率}}`       | 当检测到功率超过阈值时上报     | D2_CONV\|D2_SOC\|D2_BRK |
| 功率恢复事件     | `{"event":{"power_recovery_evt":当前功率}}`   | 功率恢复正常后上报         | D2_CONV\|D2_SOC\|D2_BRK |
| 倒计时完成      | `{"event":{"countdown_finish_event":{}}}` | 倒计时结束时上报          | ALL                     |
| 输入通道       | `{"event":{"in_ch_evt":1}}`               | 输入通道触发,表示输入通道1被触发 |                         |
| 按键短按       | `{"event":{"short_click_evt":""}}`        | 按键被短按时触发          | ALL                     |
| 按键长按       | `{"event":{"long_click_evt":""}}`         | 按键被长按时触发          | ALL                     |
| 按键超长按      | `{"event":{"extra_long_click_evt":""}}`   | 按键被超长按时触发         | ALL                     |
| 按键双击       | `{"event":{"double_click_evt":""}}`       | 按键被双击时触发          | ALL                     |
| 按键三级       | `{"event":{"triple_click_evt":""}}`       | 按键被三级时触发          | ALL                     |
|            |                                           |                   |                         |

### 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 |
| | | | |
| | | | |
### 5.5. 主动上报
	"硬件终端"间隔一定的时间,会往"服务器端",上报的报文
	该报文是可选,可使用"参数设置"报文开启或关闭
	可通过"参数设置"报文,设置上报时间间隔

| 消息类型 | JSON 格式                                                                                    | 说明                   | 支持型号 |
| ---- | ------------------------------------------------------------------------------------------ | -------------------- | ---- |
| 心跳包  | `{"report":{"ping": { "device_id": "xxxx", "full_ver": "x.x.x", "rssi_abs": "-70 dBm" }}}` | 包含设备ID、版本号和信号强度的状态信息 | ALL  |
|      |                                                                                            |                      |      |

***