Skip to content

Commit 252a7cc

Browse files
flyingcysflyingcys
committed
add docs
1 parent 1fb5ea0 commit 252a7cc

47 files changed

Lines changed: 4220 additions & 257 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎1.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
apps/xiaozhi 项目当前可以通过mqtt和 websocket连接服务器，但是需要验证，你先帮我获取到验证码，然后我加入服务器。可以正常连接服务器后，你需要帮我打通语音上行和下行通道，语音之前使用 alsa效果不好，我现在想使用 portaudio,然后唤醒使用 snowboy，这2个可以参考 /home/share/samba/Demo4Echo 下的适配，可以使用 c/C++ 混合编程
2+
3+
要求，可以正常 在当前 ubuntu上编译运行。
4+
5+
在 /home/share/samba/tuyaopen/apps/xiaozhi 目录下运行 tos.py build 编译
6+

‎apps/xiaozhi/CMakeLists.txt‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,10 @@ set(APP_SRCS
2323
${APP_PATH}/../../src/peripherals/audio_codecs/tdl_audio/src/tdl_audio_manage.c
2424
${APP_PATH}/src/xiaozhi_ws.c
2525
${APP_PATH}/src/xiaozhi_ws_handshake.c
26+
${APP_PATH}/src/audio/xz_portaudio_device.c
27+
${APP_PATH}/src/audio/xz_audio_opus_bridge.c
28+
${APP_PATH}/src/wakeword/xz_snowboy_runner.cc
29+
${APP_PATH}/src/third_party/snowboy_wrapper/snowboy-detect-c-wrapper.cc
2630
${APP_PATH}/src/xiaozhi_audio_linux.c
2731
${APP_PATH}/src/xiaozhi_state.c
2832
${APP_PATH}/src/xiaozhi_mqtt_udp.c
@@ -33,6 +37,8 @@ set(APP_SRCS
3337
set(APP_INC
3438
${APP_PATH}/src
3539
${APP_PATH}/../../src/peripherals/audio_codecs/tdl_audio/include
40+
${APP_PATH}/src/third_party/snowboy_wrapper
41+
${APP_PATH}/src/third_party/snowboy_wrapper/include
3642
)
3743

3844
########################################
@@ -51,5 +57,20 @@ target_include_directories(${EXAMPLE_LIB}
5157
)
5258

5359
if(TOS_PROJECT_PLATFORM STREQUAL "LINUX")
54-
set(PLATFORM_NEED_LIBS "${PLATFORM_NEED_LIBS} opus")
60+
find_package(PkgConfig REQUIRED)
61+
pkg_check_modules(PORTAUDIO REQUIRED portaudio-2.0)
62+
find_package(BLAS REQUIRED)
63+
find_package(LAPACK REQUIRED)
64+
65+
target_include_directories(${EXAMPLE_LIB}
66+
PRIVATE
67+
${PORTAUDIO_INCLUDE_DIRS}
68+
)
69+
target_compile_definitions(${EXAMPLE_LIB}
70+
PRIVATE
71+
_GLIBCXX_USE_CXX11_ABI=0
72+
)
73+
74+
set(SNOWBOY_STATIC_LIB ${APP_PATH}/src/third_party/snowboy_wrapper/lib/ubuntu64/libsnowboy-detect.a)
75+
set(PLATFORM_NEED_LIBS "${PLATFORM_NEED_LIBS} opus portaudio blas lapack ${SNOWBOY_STATIC_LIB}")
5576
endif()

‎apps/xiaozhi/docs/README.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# apps/xiaozhi 文档中心
2+
3+
本文档目录用于管理 `apps/xiaozhi` 的版本化说明文档。
4+
5+
## 文档组织规则
6+
7+
- 顶层 `README.md` 作为总入口，只负责版本导航。
8+
- 每个版本使用一个独立目录管理模块化文档。
9+
- 版本目录内的 `README.md` 负责该版本的总览与模块索引。
10+
11+
## 版本列表
12+
13+
- [v1.0.0](./v1.0.0/README.md)
14+
15+
## 补充资料
16+
17+
以下文档用于补充协议对齐与审计背景：
18+
19+
- [功能对齐审计](./compatibility-audit.md)
20+
- [协议 JSON 字段检查清单](./protocol-json-field-checklist.md)

‎apps/xiaozhi/docs/v1.0.0/01-overview.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# v1.0.0 概览
2+
3+
## 1. 应用定位
4+
5+
`apps/xiaozhi` 是 TuyaOpen 版本的小智应用实现，协议行为对齐 `xiaozhi-esp32`，支持两类通信方式：
6+
7+
- `WebSocket`：控制消息和音频可共用同一条 WebSocket 连接。
8+
- `MQTT + UDP`：MQTT 负责控制消息，UDP 负责实时音频数据。
9+
10+
## 2. 当前能力
11+
12+
`v1.0.0` 已覆盖以下模块：
13+
14+
- 设备身份初始化：`device_id`、`client_id`
15+
- OTA 配置拉取
16+
- 激活码展示与挑战应答激活
17+
- WebSocket 握手与消息收发
18+
- MQTT 建链、订阅、控制消息交换
19+
- UDP 音频通道建立与 AES-CTR 加密传输
20+
- `listen`、`abort`、`mcp`、`goodbye`、`tts`、`stt`、`llm` 等消息处理
21+
- Linux 目标的音频采集、播放和手工验证
22+
23+
## 3. 代码目录
24+
25+
核心代码主要位于：
26+
27+
- `apps/xiaozhi/src/xiaozhi_app.c`
28+
- `apps/xiaozhi/src/xiaozhi_ota.c`
29+
- `apps/xiaozhi/src/xiaozhi_ws.c`
30+
- `apps/xiaozhi/src/xiaozhi_mqtt_udp.c`
31+
- `apps/xiaozhi/src/xiaozhi_protocol.c`
32+
- `apps/xiaozhi/src/xiaozhi_mcp.c`
33+
- `apps/xiaozhi/src/cli_cmd.c`
34+
35+
## 4. 关键概念
36+
37+
### 4.1 设备身份
38+
39+
- `device_id`：设备物理身份，通常来源于 MAC 或硬件标识。
40+
- `client_id`：软件实例身份，通常为本地生成并持久化的 UUID。
41+
- `serial_number`：可选，用于激活 v2 语义。
42+
- `activation_secret`：可选，用于基于 challenge 生成 HMAC。
43+
44+
### 4.2 OTA 引导
45+
46+
应用启动后可先访问 OTA 配置服务，服务端可下发：
47+
48+
- `mqtt` 配置
49+
- `websocket` 配置
50+
- 激活码或激活挑战
51+
- 固件升级地址和版本信息
52+
53+
### 4.3 会话与状态
54+
55+
小智的语音会话围绕 `session_id` 展开，典型状态流转是：
56+
57+
`空闲 -> 连接 -> 收到 server hello -> 开始 listen -> 上传音频 -> 接收 TTS/STT/MCP -> 结束会话 -> 回到空闲`
58+
59+
## 5. 协议版本要点
60+
61+
- WebSocket `hello.version` 在 CLI 中可配置，默认值为 `1`。
62+
- MQTT+UDP `hello.version` 在当前实现中固定使用 `3`。
63+
- OTA check payload 顶层 `version` 为 `2`。
64+
65+
## 6. 平台说明
66+
67+
### 6.1 Linux
68+
69+
- 支持原生构建和运行。
70+
- 当前 Linux 语音链路重点支持 WebSocket。
71+
- 音频设备依赖 ALSA `default`。
72+
73+
### 6.2 T5AI / ESP 类平台
74+
75+
- 支持通过 TuyaOpen 构建配置编译。
76+
- OTA 逻辑中补齐了 ESP 侧运行时字段和激活相关信息。
77+
78+
## 7. 建议阅读路径
79+
80+
- 想看注册和初始化：先读 [设备注册与激活](./02-device-registration-and-activation.md)
81+
- 想看 WebSocket：读 [WebSocket 通道](./03-websocket.md)
82+
- 想看 MQTT 音频链路：读 [MQTT + UDP 通道](./04-mqtt-udp.md)
83+
- 想看整体时序：读 [完整流程总览](./09-full-process.md)

‎apps/xiaozhi/docs/v1.0.0/02-device-registration-and-activation.md‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
# v1.0.0 设备注册与激活
2+
3+
## 1. 目标
4+
5+
本章节说明 `apps/xiaozhi` 如何完成以下工作：
6+
7+
- 生成或读取设备身份
8+
- 向 OTA 服务发起配置检查
9+
- 根据服务端返回内容执行激活
10+
- 将返回的 WebSocket 或 MQTT 配置落地到本地设置
11+
12+
## 2. 设备注册所需身份字段
13+
14+
代码位置：`apps/xiaozhi/src/xiaozhi_ota.c`、`apps/xiaozhi/src/cli_cmd.c`
15+
16+
主要字段如下：
17+
18+
- `Device-Id`
19+
- 设备标识
20+
- 会放在 OTA 请求头中
21+
- 也可通过 `xz_sys device_id <value>` 手动写入
22+
- `Client-Id`
23+
- 客户端实例标识
24+
- 会放在 OTA 请求头中
25+
- 也可通过 `xz_sys client_id <value>` 手动写入
26+
- `Serial-Number`
27+
- 可选
28+
- 用于切换到激活 v2 逻辑
29+
- 可通过 `xz_sys serial_number <value>` 写入
30+
- `activation_secret`
31+
- 可选
32+
- 在服务端下发 `challenge` 时用来计算 HMAC
33+
- 可通过 `xz_sys activation_secret <value>` 写入
34+
35+
查看当前身份配置：
36+
37+
```bash
38+
xz_sys show
39+
```
40+
41+
## 3. OTA 配置检查流程
42+
43+
代码位置：`apps/xiaozhi/src/xiaozhi_ota.c`
44+
45+
默认 OTA 地址：
46+
47+
```text
48+
https://api.tenclass.net/xiaozhi/ota/
49+
```
50+
51+
也可以通过以下方式覆盖：
52+
53+
```bash
54+
xz_ota url https://your.server/xiaozhi/ota/
55+
```
56+
57+
或使用环境变量：
58+
59+
```bash
60+
XZ_OTA_URL=https://your.server/xiaozhi/ota/
61+
```
62+
63+
触发配置检查：
64+
65+
```bash
66+
xz_ota check
67+
```
68+
69+
## 4. OTA check 请求内容
70+
71+
### 4.1 HTTP 头
72+
73+
当前实现会发送以下关键请求头：
74+
75+
- `Activation-Version`
76+
- `Device-Id`
77+
- `Client-Id`
78+
- `Serial-Number`
79+
- `User-Agent`
80+
- `Accept-Language`
81+
- `Content-Type`
82+
83+
其中 `Activation-Version` 的判断规则是：
84+
85+
- 有 `serial_number` 时，使用 `2`
86+
- 没有 `serial_number` 时，使用 `1`
87+
88+
### 4.2 请求体
89+
90+
请求体为 JSON，主要包含：
91+
92+
- 顶层基础字段：
93+
- `version`
94+
- `language`
95+
- `flash_size`
96+
- `minimum_free_heap_size`
97+
- `mac_address`
98+
- `uuid`
99+
- `chip_model_name`
100+
- 子对象：
101+
- `chip_info`
102+
- `application`
103+
- `partition_table`
104+
- `ota`
105+
- `display`
106+
- `board`
107+
108+
这些字段用于让 OTA 服务判断：
109+
110+
- 设备型号和板型
111+
- 当前运行版本
112+
- 是否需要升级
113+
- 是否应该下发 MQTT 或 WebSocket 配置
114+
- 是否需要激活
115+
116+
## 5. OTA 返回内容与本地落地
117+
118+
服务端可能返回以下对象：
119+
120+
- `mqtt`
121+
- `websocket`
122+
- `activation`
123+
- `firmware`
124+
125+
应用会根据返回内容写入本地设置空间：
126+
127+
- `mqtt` 写入 `XZ_NS_MQTT`
128+
- `websocket` 写入 `XZ_NS_WS`
129+
- 选中的协议写入协议设置
130+
131+
协议选择规则：
132+
133+
- 如果返回 `mqtt`，优先使用 `mqtt-udp`
134+
- 否则如果返回 `websocket`，使用 `websocket`
135+
136+
## 6. 激活流程
137+
138+
### 6.1 两种激活模式
139+
140+
服务端可返回 `activation` 对象，其中可能包括：
141+
142+
- `message`
143+
- `code`
144+
- `challenge`
145+
- `timeout_ms`
146+
147+
当前支持两种激活方式：
148+
149+
1. 激活码展示
150+
- 服务端下发 `code`
151+
- 设备向用户展示激活码
152+
- 用户在配套平台完成绑定
153+
154+
2. challenge 应答激活
155+
- 服务端下发 `challenge`
156+
- 设备使用 `activation_secret` 计算 HMAC
157+
- 再向 OTA 服务发起 activate 请求
158+
159+
### 6.2 激活 v1 与 v2
160+
161+
- v1：没有 `serial_number`
162+
- 激活请求体通常为空对象 `{}`
163+
- v2：有 `serial_number`
164+
- 激活请求体包含：
165+
- `algorithm`
166+
- `serial_number`
167+
- `challenge`
168+
- `hmac`
169+
170+
## 7. 典型注册与激活操作步骤
171+
172+
### 7.1 手动注入身份并发起检查
173+
174+
```bash
175+
xz_sys device_id your_device_id
176+
xz_sys client_id your_client_id
177+
xz_sys serial_number your_serial
178+
xz_sys activation_secret your_secret
179+
xz_ota check
180+
```
181+
182+
### 7.2 仅依赖 OTA 自动下发协议配置
183+
184+
```bash
185+
xz_ota check
186+
xz_status
187+
```
188+
189+
如果 OTA 已返回 MQTT 或 WebSocket 配置，本地就会得到对应参数。
190+
191+
## 8. 注册成功后会发生什么
192+
193+
完成 OTA 检查和激活后，应用进入可连接状态，后续通常会：
194+
195+
1. 依据协议设置选择 `websocket` 或 `mqtt-udp`
196+
2. 创建控制通道
197+
3. 发起 `hello`
198+
4. 收到服务端 `hello`
199+
5. 进入 listen / tts / mcp 正常交互
200+
201+
## 9. 常见注意事项
202+
203+
- 没有 `serial_number` 时，不会走激活 v2。
204+
- 没有 `activation_secret` 时，challenge 激活无法完成。
205+
- OTA 只负责下发配置和升级信息，不等于语音会话已建立。
206+
- OTA 成功后仍需执行协议连接流程。

0 commit comments

Comments
 (0)