云喇叭-通讯协议说明书-v1

# 云喇叭通讯协议说明书
版本: v1.0.0

## 一、前言

本文档详细说明了云喇叭设备与服务器或应用终端之间的通信协议规范，主要聚焦于语音播报和灯光控制功能。本协议基于智能硬件通用通讯协议，采用JSON格式进行数据交换。

### 适用产品
- D2_SOD (智能云喇叭)

## 二、控制命令

### 2.1 语音播报命令

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

### 2.2 灯光控制命令

| 命令 | JSON 格式 | 说明 |
| ---- | -------- | ---- |
| 灯光控制 | `{"ctrl_cmd":{"set_light_cmd":0}}` | 0:关闭灯光 1:红灯常亮 2:绿灯常亮 3:蓝灯常亮 *注意:只有light_ctrl_en==true,该指令才起作用* |
| 灯光闪烁 | `{"ctrl_cmd":{"flash_light_cmd":1}}` | 0:停止闪烁 1:红灯闪烁 2:绿灯闪烁 3:蓝灯闪烁 *注意:只有light_ctrl_en==true,该指令才起作用* |

### 2.3 系统控制命令

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

## 三、参数设置与获取

### 3.1 语音参数

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

### 3.2 灯光参数

| 参数 | 设置格式 | 获取格式 | 说明 |
| ---- | -------- | ---- | ---- |
| 灯光闪烁频率 | `{"set_param":{"light_hz_ms":100}}` | `{"get_param":{"light_hz_ms":{}}}` | 设置灯光闪烁频率,单位:ms |
| 灯控使能 | `{"set_param":{"light_ctrl_en":true}}` | `{"get_param":{"light_ctrl_en":{}}}` | 灯控使能,只有参数打开时,才允许进行灯光控制,同时也意味着灯光将不再指示硬件状态 |

## 四、事件上报

| 事件类型 | JSON 格式 | 说明 |
| -------- | -------- | ---- |
| OTA更新完成 | `{"event":{"ota_end_evt":true}}` | OTA升级完成后上报结果 |
| 上电事件 | `{"event":{"powerup_evt":""}}` | 设备上电时上报 |
| 重启事件 | `{"event":{"reboot_evt":""}}` | 设备重启时上报 |
| 恢复出厂设置 | `{"event":{"factory_params_evt":""}}` | 恢复出厂设置时上报 |

## 五、灯光控制流程说明

### 5.1 灯光控制状态机

```mermaid
stateDiagram-v2
    [*] --> 系统控制
    系统控制 --> 用户控制: 设置light_ctrl_en=true
    用户控制 --> 系统控制: 设置light_ctrl_en=false
    
    state 系统控制 {
        [*] --> 网络连接中
        网络连接中 --> 网络连接成功: 连接成功
        网络连接中 --> AP配网模式: 进入配网
        
        网络连接中: LED每500ms闪烁
        网络连接成功: LED常亮
        AP配网模式: LED快速闪烁(100ms)
    }
    
    state 用户控制 {
        [*] --> 常亮模式
        常亮模式 --> 闪烁模式: flash_light_cmd
        闪烁模式 --> 常亮模式: set_light_cmd
        闪烁模式 --> 关闭状态: flash_light_cmd=0
        常亮模式 --> 关闭状态: set_light_cmd=0
        关闭状态 --> 常亮模式: set_light_cmd
        关闭状态 --> 闪烁模式: flash_light_cmd
    }
```

### 5.2 灯光控制使用流程

```mermaid
sequenceDiagram
 participant App as 应用终端
 participant Device as 云喇叭设备
 
 Note over Device: 默认状态：系统控制LED 用于指示网络状态
 
 App->>Device: {"set_param":{"light_ctrl_en":true}}
 Device-->>App: {"ask":true}
 Note over Device: 切换到用户控制模式 系统不再控制LED
 
 App->>Device: {"ctrl_cmd":{"set_light_cmd":1}}
 Device-->>App: {"ask":true}
 Note over Device: 设置红灯常亮
 
 App->>Device: {"ctrl_cmd":{"flash_light_cmd":2}}
 Device-->>App: {"ask":true}
 Note over Device: 设置绿灯闪烁 使用light_hz_ms设定的频率
 
 App->>Device: {"set_param":{"light_hz_ms":200}}
 Device-->>App: {"ask":true}
 Note over Device: 更新闪烁频率为200ms
 
 App->>Device: {"set_param":{"light_ctrl_en":false}}
 Device-->>App: {"ask":true}
 Note over Device: 恢复系统控制模式 LED重新指示系统状态
```

### 5.3 注意事项

1. **灯光控制权限**
   - 默认情况下，`light_ctrl_en=false`，LED由系统控制用于指示网络状态
   - 设置`light_ctrl_en=true`后，系统让出LED控制权，完全由用户控制
   - 用户控制模式下，系统状态变化不会影响LED状态

2. **命令优先级**
   - `light_ctrl_en=false`时，`set_light_cmd`和`flash_light_cmd`命令会被忽略
   - `flash_light_cmd`命令会覆盖`set_light_cmd`的设置
   - `set_light_cmd`命令会停止当前的闪烁效果

3. **闪烁控制**
   - 闪烁频率由`light_hz_ms`参数控制，单位为毫秒
   - 设置`flash_light_cmd=0`或执行任何`set_light_cmd`都会停止闪烁
   - 修改`light_hz_ms`会实时影响当前闪烁效果

4. **系统状态指示**
   - 网络连接中：LED每500ms闪烁
   - 网络连接成功：LED常亮
   - AP配网模式：LED快速闪烁(100ms)
   - 进入用户控制模式后，以上状态指示失效

5. **掉电保存**
   - `light_ctrl_en`和`light_hz_ms`参数掉电保存
   - 设备重启后会恢复保存的设置
   - 恢复出厂设置会将这些参数恢复默认值

6. **常见错误避免**
   - 不要在`light_ctrl_en=false`时尝试控制LED
   - 切换到用户控制模式前先规划好LED使用方式
   - 在不需要用户控制时及时释放LED控制权给系统