跳到主要内容

常见问答 30 题

阅读说明书过程中最可能遇到的 30 个高频问题，每题给一个简短回答 + 对应的深入阅读位置。

A. 项目定位类​

Q1. 这个项目跟商业语音助手（如小爱同学、天猫精灵）有什么不一样？​

A. 那些是端到端的成品，云端 + App + 设备一条龙、技术栈封闭。这个项目是开源的语音前端固件——只管"在 ESP32 上把语音收上来 + 把回复播下去"这件事，云端的 LLM/ASR/TTS 你自己接。优势是完全可控、可定制、可商用。

Q2. 这个项目是谁做的？​

A. 由社区主导维护的开源项目，主仓库在 GitHub xinnan-tech/xiaozhi-esp32。Espressif（乐鑫）官方也支持，提供了 esp-sr 等关键组件。

Q3. 能不能商用？​

A. 看 LICENSE。代码本身基本是宽松开源协议，但用到的某些第三方组件（如 esp-sr 的语音模型）有自己的授权条款，商用前需要逐个确认。

Q4. 这里的 MCP 协议是行业标准吗？​

A. 是的，2024 年起业界推广的开放规范（基于 JSON-RPC 2.0，定义了工具发现/调用/通知的格式）。本项目只实现了设备端的 MCP Server 部分，云端的 MCP Client 由服务器侧实现，主流大模型客户端已经普遍支持。

B. 硬件类​

Q5. 最低硬件配置是什么？​

A. ESP32-S3（双核 + 8MB PSRAM）+ I²S 麦克风（如 INMP441）+ I²S 喇叭（如 MAX98357）+ 4MB Flash 起。4MB 不能 OTA（用 factory only），常规推荐 16MB。

Q6. 支持普通 ESP32（非 S3）吗？​

A. 支持，但内存压力大，AFE 高级算法跑不了——只能用单麦克风简单唤醒词方案。建议 S3 起步。

Q7. 必须有屏幕吗？​

A. 不必须。NoDisplay 是个空实现，没屏的板子（如 atom-echo）跑得很好。

Q8. 4G 板和 Wi-Fi 板能切换吗？​

A. DualNetworkBoard 设计就是给双栈板用的——内置 Wi-Fi + ML307 模块，用户可以切换，切换走重启（4 秒）。

Q9. 支持电池供电吗？​

A. 支持。Board::GetBatteryLevel() 接口可重写，结合 PowerSaveTimer + SleepTimer 进 light_sleep 大幅省电。某些板子（如 atom-echo-s3r）就是电池供电的。

Q10. ESP32-P4 这种新芯片支持吗？​

A. 支持。P4 性能强（双核 RISC-V 400MHz + 32MB PSRAM），但没内置 Wi-Fi，要靠 SDIO 外挂 ESP32-C6。代码里专门处理了这种"主控+协处理器"组合的 MAC 地址读取等问题。

C. 软件/架构类​

Q11. 改一行代码要重新刷整个 16MB Flash 吗？​

A. 不需要。idf.py build flash monitor 只会刷修改过的分区（通常是 xiaozhi.bin），几十秒完成。

Q12. assets.bin 怎么更新，每次都要 USB 刷吗？​

A. OTA 服务器可以下发 assets_url，设备会在线下载资源包并直接写入 assets 分区——升级语音模型、字体、emoji 都不需要 USB。

Q13. 状态机里的 11 个状态太多了，能不能精简？​

A. 可以，但不建议。每个状态都对应明确的语义（待机/听话/说话/升级等），UI 反馈（灯/屏/提示音）都依赖这些状态。精简后可能要重写大量逻辑。

Q14. 为什么音频用 5 个队列？不能少一些吗？​

A. 因为 3 个 FreeRTOS 任务之间速度不一致——麦克风固定 16 kHz，AFE 处理速度波动，Opus 编码更慢，网络发包更不确定。每两个速度不同的环节之间放一个队列吸收抖动。少了某个队列会出现"前面卡住后面所有"。

Q15. WebSocket 和 MQTT+UDP 同时用一个能跑不？​

A. 不能同时用两个 Protocol 实例。Application::InitializeProtocol() 二选一，由 NVS 配置决定。但切换协议不用改业务代码——这是这套设计的核心优势。

Q16. 怎么加自己的 MCP 工具？​

A. 在板子代码里：

auto& mcp = McpServer::GetInstance();
mcp.AddTool("my.weather", "查询天气",
    PropertyList({Property("city", kPropertyTypeString)}),
    [](const PropertyList& props) -> ReturnValue {
        auto city = props["city"].value<std::string>();
        // ... 真的查天气
        return "上海今天小雨，18 度";
    });

调用 Initialize*Tools() 函数里加进去即可。

Q17. McpTool 的回调在哪个线程跑？​

A. 主循环线程——这是为了保证硬件操作（GPIO/I²C）的线程安全。McpServer::DoToolCall() 不会直接调回调，而是 Schedule() 到主循环。

Q18. 改唤醒词怎么改？​

A. 三选一：

  1. 用 ESP-SR 自带的几个预训练唤醒词（"你好小智"/"嗨小智"等），改 sdkconfig 切；
  2. 让 Espressif 帮训新唤醒词（要付费，但效果好）；
  3. 用 Sherpa-ONNX 自己训（免费但要会调参）—— custom_wake_word.cc 已支持。

Q19. Opus 帧大小为什么是 60ms？​

A. Opus 标准支持 2.5/5/10/20/40/60ms 多种帧长。60ms 压缩率最高（相同 bitrate 下音质最好），适合语音场景。代价是延迟稍高 60ms——对话场景能接受。

Q20. 一秒能传多少数据？​

A. 16 kbps Opus = 2 KB/s。一分钟对话 120 KB。每月 100 小时使用 = 720 MB——4G 套餐扛得住。

D. 安全/运维类​

Q21. eFuse 是什么？为什么用它存设备序列号？​

A. eFuse 是 ESP32 芯片内的一次性可编程存储（OTP），出厂烧入后无法修改，连软件读也只能在合法场景下读。安全性高于 Flash 里的 NVS——攻击者就算把 Flash dump 出来分析，eFuse 的密钥也拿不到。

Q22. UDP 加密用 AES-128-CTR，AES key 怎么传输的？​

A. 通过 MQTTS（TLS over MQTT）安全通道传输。设备和云端用 MQTT 握手时，云端临时生成一个 AES key 发给设备，仅在当次音频会话中有效。下次会话换新 key——一次一密。

Q23. OTA 失败设备会变砖吗？​

A. 不会。两道保险：

  1. 下载验证：HTTP 拉完做 SHA-256 校验，校验不通过不切分区；
  2. 运行时回滚：新分区启动后 1 秒内不调 MarkCurrentVersionValid()，Bootloader 下次启动自动回滚到旧分区。

Q24. 怎么防止山寨设备绕过激活？​

A. 激活流程用 HMAC-SHA256 质询/应答，签名密钥是 eFuse 内的 32 字节序列号。山寨设备没有真实的 eFuse 密钥，签出来的应答服务器一对就不对。

Q25. 设备弱网时怎么表现？​

A.

  • WebSocket：TCP 重传机制保送达，但弱网会卡顿、断开重连；
  • MQTT+UDP：UDP 丢包不重传，用 forward error correction 不如简单丢弃——音质会"嘶嘶"几声但不会卡死。

项目实现里有完整的自动重连 + 序列号检查 + 超时检测机制。

E. 性能/优化类​

Q26. AFE 跑起来 CPU 占用多少？​

A. ESP32-S3 240MHz 下，AFE 单麦克风方案占用约 20-30% 一个核（核 0）；多麦克风 BSS（盲源分离）方案占用 40-60%。所以 ESP32-S3 是建议起点——单核 ESP32 跑不动。

Q27. RAM 占用情况？​

A. 典型 8MB PSRAM 板子：

  • 固件代码段（在 Flash 不占 RAM）：~1.5MB
  • 静态数据段：~50KB
  • FreeRTOS heap：~200KB（任务栈 + 队列）
  • LVGL 缓冲区：~150KB
  • 网络栈：~80KB
  • AFE 工作内存：~300KB（PSRAM）
  • 音频队列 + 编解码 buffer：~100KB

合计 SRAM ~700KB / PSRAM ~500KB。剩余够跑其它业务。

Q28. 怎么进一步降功耗？​

A. 三个开关：

  1. PowerSaveTimer：Idle 一段时间后降 CPU 频率（240MHz → 80MHz）
  2. SleepTimer：再 Idle 一段时间进 light_sleep（CPU 完全停，GPIO 中断/RTC 唤醒）
  3. Wi-Fi PowerSave：BSS PS 模式，平均 mA 降一半

电池板（atom-echo）综合做下来续航能从几小时拉到几十小时。

Q29. 启动到能用要 8 秒，能不能更快？​

A. 几个优化点：

  • 把 Wi-Fi 凭证缓存好 → 省配网时间
  • 跳过 OTA 检查（设置短超时）→ 省 1-2 秒
  • 不用 LVGL 直接画屏 → 省渲染时间
  • 预先验证激活 → 省激活流程

实测可以从 8 秒压到 3 秒左右。

F. 商业/合规类​

Q30. 上市要做哪些合规认证？​

A. 主要是：

  • CCC（中国 3C 强制认证）
  • SRRC（中国无线电型号核准——Wi-Fi/蓝牙模块需要）
  • CE（欧盟，对应 RED 指令）
  • FCC（美国，Part 15.247）
  • PSE（日本）

ESP32 模组本身通常已经拿过这些认证（用 Espressif 模组而非裸芯片），整机层面再走一遍即可。

没问到的问题怎么办​

按主题去查对应章节：

问题方向去看
文件层面主说明书 /01-overview 的全文件分级表
主调度逻辑/02-main-application
状态切换/03-state-machine + 图 4
音频处理/04-audio + 图 3
网络通信/05-protocols + 图 6
工具协议/06-mcp-server + 图 7
系统服务/07-system-services
UI / LED/08-display-led
板级抽象/09-boards + 图 10
编译 / 工具/10-build-and-tools

实在找不到答案，可以联系（Jason）补一份增量章节。