跳到主要内容

进阶学习路径

这份文档是一份"系统学习计划"。不要一口气把 9500 行说明书全啃下来——按这个 5 阶段路径循序渐进，每阶段大约花 1-3 天。

阶段 0：跑通设备（半天）​

目标：先让一块开发板真的能"喊小智回应"，建立直观感受。

步骤：

  1. 弄到一块 ESP32-S3 开发板（推荐 ESP32-S3-Box-3 或自己搭面包板）
  2. 装好 ESP-IDF（按官方 Get Started 文档）
  3. clone xiaozhi-esp32 仓库
  4. idf.py set-target esp32s3 → idf.py menuconfig 选板子型号 → idf.py build flash monitor
  5. 设备启动后扫码绑定到云端账号
  6. 喊"你好小智"听到回应——跑通

成功标志：能完成至少 3 轮人机对话。

学习产出：知道整个流程能跑通，对项目有信心。

阶段 1：理解整体架构（1 天）​

目标：搞清楚"整个项目大概有什么、怎么组织"，不深入代码细节。

阅读顺序（按从大到小推进）：

  1. 看 /diagrams/01-architecture（含 [图 1]）—— 整体一张图
  2. 看 /diagrams/02-startup-sequence（含 [图 2]）—— 启动顺序
  3. 看 /diagrams/11-file-dependency（含 [图 11]）—— 文件相互依赖
  4. 看主说明书 /01-overview—— 完整的文件分级总览表
  5. 看主说明书 /02-main-application §2.1-2.2—— Application 单例和事件组的设计

学习产出：

  • 能画出项目大致架构图
  • 知道每个目录大致是干嘛的
  • 知道 application.cc 是中枢

阶段 2：搞懂数据流（1-2 天）​

目标：搞清楚"声音怎么进去、回复怎么出来、数据走了哪些路径"。

阅读顺序：

  1. 看 /diagrams/03-audio-pipeline（[图 3]）—— 上行下行链路
  2. 看 /diagrams/05-wake-to-reply（[图 5]）—— 完整对话过程
  3. 看主说明书 /04-audio（整章）—— 5 个队列 + 3 任务 + AFE + 唤醒词
  4. 看 /diagrams/04-state-machine（[图 4]）+ 主说明书 /03-state-machine—— 状态机
  5. 看 /diagrams/06-protocol-comparison（[图 6]）+ 主说明书 /05-protocols §5.1-5.3—— WebSocket 协议

学习产出：

  • 能讲清"用户喊'你好小智'之后到喇叭出声中间发生了什么"
  • 知道 AFE 干嘛、Opus 编码用在哪里、状态机怎么切
  • 知道协议层只是一层"传输管子"，可以替换

练习题（自测）：

  • 用户说话期间设备屏幕显示什么？
  • 如果 Wi-Fi 突然断开，状态机会怎么走？
  • Opus 编码每帧多少毫秒？为什么是这个值？

阶段 3：深入子系统（2-3 天）​

目标：把每个核心子系统的内部实现摸透。

挑你最感兴趣的 1-2 个子系统深入：

选项 A：网络协议（适合做服务器对接）​

阅读：

  • 主说明书 /05-protocols（整章）
  • /diagrams/06-protocol-comparison
  • 项目自带文档 docs/websocket.md、docs/mqtt-udp.md

练习：用 Python 写一个最小的 echo 服务器，让设备能连上并回放对方的音频。

选项 B：MCP 工具（适合做应用层扩展）​

阅读：

  • 主说明书 /06-mcp-server（整章）
  • /diagrams/07-mcp-tool-call
  • 项目自带文档 docs/mcp-protocol.md、docs/mcp-usage.md

练习：写一个 MCP 工具让 LLM 能查询设备 IP，并测试调用。

选项 C：OTA / 系统服务（适合做产品化）​

阅读：

  • 主说明书 /07-system-services（整章）
  • /diagrams/08-ota-flow

练习：搭一个最小的 OTA 服务器，能让设备从你的服务器拉取新固件并升级。

选项 D：板级抽象（适合做硬件适配）​

阅读：

  • 主说明书 /09-boards（整章）
  • /diagrams/10-board-hierarchy
  • 项目自带文档 docs/custom-board.md

练习：自己设计一块板子（GPIO 不同），改一份 config.h 和 <your>_board.cc 让项目编译过。

阶段 4：构建与发布（1 天）​

目标：搞清楚怎么改代码、怎么发布、怎么管理多板子多版本。

阅读顺序：

  1. 主说明书 /10-build-and-tools（整章）
  2. 玩一下 scripts/release.py 看怎么批量编译
  3. 看 partitions/v2/ 下不同 Flash 容量的分区表
  4. 用 idf.py menuconfig 玩一遍所有选项

学习产出：

  • 能从头建一个属于自己的板子配置
  • 能跑发布脚本生成 zip 给别人烧录
  • 知道 sdkconfig.defaults / Kconfig / CMakeLists 的关系

阶段 5：实战与扩展（持续）​

目标：把项目按自己业务定制化。

按业务方向选其一：

方向 A：智能音箱产品化​

  • 自己设计板子（外壳/塑胶/批量生产）
  • 自家 LLM 后端
  • 自家激活/付费体系（替换 OTA 服务器的激活流程）
  • 远程管理后台

方向 B：物联网控制中心​

  • 加大量 MCP 工具（控空调/灯/窗帘等）
  • 接入 Home Assistant 或自家 IoT 平台
  • 用语音控制全屋设备

方向 C：教育/玩具​

  • 训练自定义唤醒词（Sherpa-ONNX）
  • 自定义角色 / 性格 / 表情
  • 接入儿童故事 / 英语教学等垂直内容

方向 D：行业终端​

  • 客服机器人
  • 工业巡检助手
  • 医疗陪护

学习路径地图​

阶段 0 (跑通)
   ↓
阶段 1 (架构) → 第 1, 2, 11 图 + Chapter 1, 2
   ↓
阶段 2 (数据流) → 第 3, 4, 5, 6 图 + Chapter 3, 4, 5
   ↓
阶段 3 (深入) → 任选 A/B/C/D + 对应 Chapter
   ↓
阶段 4 (构建) → Chapter 10 + scripts/
   ↓
阶段 5 (实战) → 任选方向

推荐辅助资源​

必看的官方文档​

推荐的视频/课程​

  • B 站搜"ESP-IDF 入门"基础教程
  • B 站搜"FreeRTOS 教程"
  • 关于 MCP 协议：去 modelcontextprotocol.io 看官方规范

如果卡在某一步​

  1. 先看说明书对应章节的"看完本章你应该掌握的"清单——是否真的掌握了？
  2. 把那段代码拷出来在 VSCode / CLion 里跟着读，对照说明书
  3. 跑 idf.py monitor 看日志，活的项目比死的代码好懂得多
  4. 找我（Jason）问

时间估算（保守）​

学习者类型阶段 0-2阶段 3-4阶段 5
嵌入式工程师有经验2-3 天3-5 天看业务
后端/移动开发转入3-5 天5-7 天看业务
学生/初学者1-2 周1-2 周看业务
想"看懂"不动手3-4 天看选项—

核心建议：每阶段都要动手——跑一下、改一下、加一个 print 看一下。光看说明书学的是"概念"，跑通了项目学的是"能力"。