TalkingQ智能设备激活与使用流程文档

一、流程概述

TalkingQ智能设备的激活与使用流程主要分为四个阶段：

设备预置与准备
设备配网与连接
设备认证与激活
日常使用与管理

二、详细流程

1. 设备预置与准备阶段

设备出厂预置：
- 每台设备出厂时预置唯一的设备ID（基于MAC地址，格式："TalkingQ_MAC地址"，如"TalkingQ_AABBCCDDEEFF"）
- 预置唯一序列号（格式："批次前缀_ChipID"，批次前缀通常为8位日期格式YYYYMMDD）
- 设备信息已通过管理员API（/api/auth/register-device或/api/auth/register-devices-batch）在后端服务器预先注册
安全存储：
- 设备使用ESP32的NVS加密存储区存储凭据
- 后端在device_auth表中安全存储设备信息（包括device_id、serial_number、batch_id和is_active）

2. 设备配网与连接阶段

启动配网：
- 用户打开微信进入TalkingQ小程序
- 用户选择"设备配网"功能
WiFi信息传输：
- 小程序使用AirKiss协议进行配网
- 用户选择家庭WiFi并输入密码
- 小程序将WiFi信息通过AirKiss协议发送
设备接收配置：
- 设备使用SmartConfig技术（支持AirKiss和ESPTouch）接收配置
- 设备连接到指定WiFi网络
- 连接成功后，设备返回MAC地址给小程序

3. 设备认证与激活阶段

获取设备凭据：
- 小程序通过/api/auth/query-serial接口发送MAC地址给后端
- 请求头中携带X-Client-Key验证小程序身份
- 后端返回对应的设备ID和序列号
- 小程序安全存储设备凭据
设备WebSocket连接：
- 设备使用预置的ID和序列号向服务器发起WebSocket连接(/ws)
- 设备在10秒内发送JSON格式认证消息：
```
{
  "device_id": "TalkingQ_AABBCCDDEEFF",
  "serial_number": "20240101_12345678"
}
```
- 后端通过device_auth_manager.authenticate_device验证设备凭据
- 认证成功后，通过connection_manager.add_connection建立正式连接
- 设备播放成功提示音
激活状态确认：
- 小程序通过/api/auth/verify-device/{device_id}轮询设备状态
- 后端确认设备已激活并连接
- 小程序显示"激活成功"提示

4. 日常使用与管理阶段

设备管理：
- 用户打开小程序查看已激活设备列表
- 选择设备进入管理界面
- 小程序在API请求中使用X-Device-ID和X-Device-Serial头部传递凭据
- 后端通过api_auth依赖项验证设备身份
设备控制功能：
- 角色配置：通过/api/roles/device/{device_id}设置对话角色和首选语言
- 音量控制：通过/api/device/volume/{device_id}调整设备音量(0-100)
- 网络重置：通过/api/device/reset-network/{device_id}远程重置设备网络配置
- 对话历史：通过/api/roles/history/{device_id}和/api/roles/history-summary/{device_id}获取历史记录
实时通信：
- 设备保持WebSocket连接接收控制指令（如"VOLUME:70"、"RESET_NETWORK"等）
- 设备通过WebSocket发送语音数据（带有设备ID和会话ID的二进制数据包）
- 后端通过WebSocket发送TTS_START、TTS_END等状态通知和音频URL

三、流程图

+-------------+            +----------------+            +---------------+            +----------------+
|    用户     |            |   微信小程序   |            |   TalkingQ设备 |            |    后端服务    |
+-------------+            +----------------+            +---------------+            +----------------+
      |                           |                             |                           |
      |                           |                             |         【设备预置阶段】   |
      |                           |                             | 出厂预置设备ID和序列号    |
      |                           |                             |------------------------   |
      |                           |                             |                           | 管理员API预注册设备信息
      |                           |                             |                           | (/api/auth/register-device)
      |                           |                             |                           |------------------------
      |                           |                             |                           |
      |                           |                             |                           |
      |         【设备配网阶段】                                 |                           |
      | 打开微信小程序            |                             |                           |
      |-------------------------->|                             |                           |
      | 选择"设备配网"            |                             |                           |
      |-------------------------->|                             |                           |
      | 选择WiFi并输入密码        |                             |                           |
      |-------------------------->|                             |                           |
      |                           | 使用AirKiss协议发送WiFi信息 |                           |
      |                           |---------------------------->|                           |
      |                           |                             | 通过SmartConfig接收配置   |
      |                           |                             |------------------------   |
      |                           |                             | 连接到指定WiFi网络        |
      |                           |                             |------------------------   |
      |                           |                             | 连接成功返回MAC地址       |
      |                           |<----------------------------|                           |
      |                           |                             |                           |
      |         【设备认证与激活阶段】                           |                           |
      |                           | /api/auth/query-serial      |                           |
      |                           | (含MAC地址+X-Client-Key)    |                           |
      |                           |----------------------------------------------------------->|
      |                           |                             |                           | 验证小程序身份
      |                           |                             |                           | 查询对应设备信息
      |                           |            返回设备ID和序列号|                           |
      |                           |<-----------------------------------------------------------|
      |                           | 本地安全存储设备凭据        |                           |
      |                           |------------------------     |                           |
      |                           |                             | 发起WebSocket连接(/ws)    |
      |                           |                             |---------------------------->|
      |                           |                             | 发送JSON认证消息           |
      |                           |                             |---------------------------->|
      |                           |                             |                           | authenticate_device验证
      |                           |                             |                           | connection_manager注册
      |                           |                             | 认证成功确认               |
      |                           |                             |<----------------------------|
      |                           |                             | 播放welcome提示音         |
      |                           |                             |------------------------   |
      |                           | /api/auth/verify-device     |                           |
      |                           |----------------------------------------------------------->|
      |                           |                设备已激活状态|                           |
      |                           |<-----------------------------------------------------------|
      | 显示"激活成功"提示        |                             |                           |
      |<--------------------------|                             |                           |
      |                           |                             |                           |
      |         【日常使用与管理阶段】                          |                           |
      | 打开小程序查看设备列表    |                             |                           |
      |-------------------------->|                             |                           |
      | 选择并进入设备管理        |                             |                           |
      |-------------------------->|                             |                           |
      |                           | 请求设备信息                |                           |
      |                           | (含X-Device-ID和X-Device-Serial)                       |
      |                           |----------------------------------------------------------->|
      |                           |               设备详细信息  |                           |
      |                           |<-----------------------------------------------------------|
      | 执行设备管理操作          |                             |                           |
      | (角色/音量/网络设置)      |                             |                           |
      |-------------------------->|                             |                           |
      |                           | 发送管理请求                |                           |
      |                           | (含设备凭据头部)            |                           |
      |                           |----------------------------------------------------------->|
      |                           |                  处理结果   |                           |
      |                           |<-----------------------------------------------------------|
      |                           |                             | 实时WebSocket控制指令     |
      |                           |                             |<----------------------------|
      |                           |                             | 执行指令并提供服务        |
      |                           |                             |------------------------   |

四、安全特性

整个流程具有以下安全特性：

一物一密：
- 每台设备使用唯一ID（格式："TalkingQ_MAC地址"）和序列号（格式："批次前缀_ChipID"）
- 设备认证需同时验证设备ID和序列号
- 通过device_auth_manager.authenticate_device方法严格验证设备凭据
安全存储：
- 设备使用ESP32的NVS加密存储区保护凭据
- 后端在MySQL数据库的device_auth表中安全存储设备信息
- 实现安全启动和Flash加密保护敏感信息
分层认证：
- 小程序使用X-Client-Key认证身份（由settings.client_api_key提供）
- 设备管理API使用X-Device-ID和X-Device-Serial认证（api_auth依赖项）
- 管理员API使用X-Admin-API-Key认证（admin_auth依赖项）
- WebSocket连接通过JSON格式认证消息验证，认证超时时间为10秒
权限隔离：
- 只有管理员API密钥才能注册设备（admin_auth依赖项）
- 用户只能管理自己配网过的设备（使用admin_or_api_auth依赖项验证权限）
- 设备配置修改需通过api_auth认证，防止未授权访问
通信加密：
- 所有API通过HTTPS传输
- WebSocket连接安全验证
- 敏感信息不明文传输
设备状态跟踪：
- 通过connection_manager跟踪所有活跃的设备连接
- 通过device_auth_manager支持设备禁用功能（设置is_active=False）
- 提供设备状态验证接口（/api/auth/verify-device/{device_id}）

五、开发关键点

ESP32端：
- 实现SmartConfig配网（同时支持AirKiss和ESPTouch）
- 在NVS加密区域安全存储设备凭据
- 实现WebSocket认证流程和10秒内发送认证消息
- 处理来自后端的实时控制指令（VOLUME、RESET_NETWORK等）
- 实现二进制音频数据包发送格式，包含设备ID和会话ID
微信小程序：
- 实现AirKiss配网协议
- 通过/api/auth/query-serial获取设备凭据
- 在HTTP请求头中添加X-Client-Key或者X-Device-ID和X-Device-Serial组合
- 使用/api/roles/device/{device_id}管理设备角色和语言设置
- 使用/api/device/volume/{device_id}管理设备音量
后端服务：
- 通过device_auth_manager.authenticate_device验证设备身份
- 使用connection_manager管理WebSocket连接
- 实现多种语音识别、语言模型和语音合成服务对接
- 提供丰富的API接口：
  - /api/roles/device/{device_id} - 角色配置
  - /api/device/volume/{device_id} - 音量控制
  - /api/device/reset-network/{device_id} - 网络重置
  - /api/roles/history/{device_id} - 对话历史
  - /api/auth/verify-device/{device_id} - 设备验证

此流程设计确保非技术用户也能轻松完成设备激活和管理，同时在背后实现了高级别的安全保障。整个激活过程只需要几分钟，用户只需要提供WiFi信息，其他都由系统自动完成。

14 KiB Raw Permalink Blame History Unescape Escape

TalkingQ智能设备激活与使用流程文档

一、流程概述

二、详细流程

1. 设备预置与准备阶段

2. 设备配网与连接阶段

3. 设备认证与激活阶段

4. 日常使用与管理阶段

三、流程图

四、安全特性

五、开发关键点

14 KiB

Raw Permalink Blame History