🎙️ 小智语音机器人开源项目分析报告

xiaozhi-esp32 整体业务逻辑 · 完整工作流 · 数据链条
出品：Phys🐷 + Asst🌸 + Math🐱 三人组联合分析 | 源码版本：main bb9122a

一、项目定位

开源 AI 语音助手 + 大模型与真实硬件的连接器：基于 ESP32 系列芯片，语音唤醒 → 全双工对话，通过 MCP 协议把大模型能力接到真实硬件（灯光/舵机/智能家居）。MIT 开源，138 个板卡目录、171 个固件变体，硬件门槛低到面包板手搓。

二、整体架构（三层）

┌─ 硬件层 ──────────────────────────────┐
│  ESP32-S3 为主（C3/C5/C6/P4 也可）      │
│  音频 codec：ES8311/8374/8388/8389     │
│  外设：LVGL 屏(10+驱动)、LED、摄像头、   │
│  BMI270、BQ27220 电量计、旋钮、USB      │
├─ 系统层 ──────────────────────────────┤
│  Application 事件主循环                 │
│  → DeviceStateMachine 状态机(12态)     │
│  → protocols：WebSocket / MQTT+UDP    │
│  → audio_service：采集/编解码/播放3任务  │
│  → 60+ managed 组件(esp-sr/lvgl...)   │
├─ 云侧 ────────────────────────────────┤
│  xiaozhi.me 官方 or 自建服务器          │
│  ASR → LLM(Qwen免费) → TTS 实时流      │
└───────────────────────────────────────┘

三、完整工作流（用户视角 → 状态机）

12 个状态：Unknown → Starting → WifiConfiguring → Activating → Idle ⇄ Connecting → Listening ⇄ Speaking，另有 Notifying / Upgrading / AudioTesting / FatalError，所有迁移有严格校验表（防死锁）。

配网：首次启动热点配网（或 BluFi 蓝牙配网）→ 存 NVS
激活：连服务器，Device-Id(MAC) + Client-Id(UUID) 鉴权，自动查 OTA
空闲 → 喊唤醒词（如"你好小智"）→ 本地 esp-sr 检测（不耗云端）
连接：开 WebSocket，hello 握手（Opus/16kHz/单声道/60ms 帧），服务器回 session_id + 下行 24kHz
听：麦克风 48kHz PCM → 重采样 16kHz → Opus 编码(VBR+DTX) → 60ms/帧上行；VAD 检测静音
说：服务器 TTS 流 Opus 帧下行 → 解码 → 重采样 → 喇叭播放；屏幕同步字幕
结束：tts,stop → auto 回 Listening（连续对话）/ manual 回 Idle

打断：播放中说唤醒词 → abort(wake_word_detected) → 清空队列 → 立即回听，全双工无感知切换。

四、数据链条（端到端）

🎤 MEMS麦克风 → PCM 48k → 重采样 16k → VAD/降噪
   → Opus编码(60ms/帧=960样本) → [v2头12B / v3头4B]+payload
   → WebSocket 二进制帧（或 MQTT信令 + UDP音频 AES-128-CTR 加密）
   → 云端 ASR → LLM → TTS
   → 下行 Opus(24k) → 解码 → 重采样 → DAC → 🔊 喇叭

消息类型	方向	用途
hello / listen / abort	上行	握手 / 开始停止监听 / 打断
stt / llm / tts	下行	识别文本 / 情绪表情 / 语音流+字幕
mcp	双向	JSON-RPC 2.0 工具调用（控制硬件）
system / alert / notify	下行	远程重启 / 告警 / 被动通知播报

可靠性：WS 靠 TCP keepalive；MQTT keepalive 240s + 120s 无数据判死 + 60s 自动重连；MQTT 音频通道 AES-128-CTR + 序列号防重放。

五、显示 / LED 生态（三层）

① LCD/OLED 屏：lvgl_display 完整实现（GIF 动图、emoji、字体、主题）；OLED 支持 SSD1306/SH1106 类 I2C 屏；屏幕显示对话字幕与 UI
② 表情系统 esp_emote：乐鑫官方组件（gfx 轻量 UI 库 + expression + 多分辨率资源包 320×240/360×360/1024×600）。表情由 AI 驱动：LLM 回复发 {"type":"llm","emotion":"happy"} → 设备 SetEmotion 立刻换表情，对话中显示思考中/说话中/开心等动态表情
③ LED 灯：single_led/gpio_led 状态灯 + circular_strip 环形 RGB 灯带（WS2812 表情环）

闭环：收音 → 屏显"正在听" → LLM 情绪 → 表情切换 → TTS 说话+字幕+LED 呼吸，全程可视化。

六、MCP 设备工具库（灵魂功能）

设备端运行 MCP Server，大模型通过对话直接调用：

工具	作用
self.audio_speaker.set_volume	调音量
self.screen.set_brightness / set_theme	屏幕亮度 / 主题
self.camera.take_photo	拍照
self.screen.snapshot / preview_image	截屏上传 / 屏显图片
self.get_device_status / get_system_info	查设备状态 / 系统信息
self.reboot	远程重启
self.upgrade_firmware	对话里直接命令设备升级固件
self.assets.set_download_url	更换资源包（表情/字体）
板卡自定义工具	各家板子注册自己的（灯带 RGB、舵机、GPIO…）

这就是"动口控制万物"的实现：AI 说"把灯调暗点"，工具调用直接落硬件。

七、部署 / 烧录

编译：idf.py set-target esp32s3 && idf.py build（xiaozhi.bin 2.6M 实测编译通过 ✅）
分区：双 OTA 分区（ota_0/ota_1 各 4MB）+ assets SPIFFS 8MB → 支持远程滚动升级
OTA 机制：esp_ota_ops 双分区交替 + 启动自校验回滚（新固件起不来自动回退）
烧录：idf.py -p /dev/ttyUSB0 flash（16MB flash，80MHz）
自定义：menuconfig（唤醒词/OTA_URL/界面语言 38 种）；自定义资源用 assets 生成器
自建服务器：改 OTA_URL + WS/MQTT 地址即可，协议全开放

八、补充亮点

Realtime 全双工：开 AEC 后边听边说，不用等 TTS 播完就能插话
网络形态多样：WiFi / 蓝牙 / 4G 蜂窝(ML307) / USB 网卡 / 以太网
视觉能力：esp32-camera + SSCMA AI 视觉推理（目标检测），拍照给大模型看
电源管理：ADC 估电 / BQ27220 库仑计 / AXP2101 PMIC 三种方案
音频后处理：esp_audio_effects 音效 + esp-dsp + FFT 频谱 + AEC 回声消除标配
服务器端开源：xiaozhi-server(Python) ASR/LLM/TTS 全插件化，可自由换服务商

⚠️ 待核实：声纹识别（3D-Speaker 说话人区分）在 README 有提及，设备端代码未直接检索到，可能在服务器端或 esp-sr 组件中。

九、三人组共识结论

设计亮点：状态机严格化（防死锁）、本地唤醒（低功耗省流量）、全双工+打断、MCP 万物互联、双协议自适应（有公网 IP 用 MQTT+UDP 低延迟）
技术栈门槛：改固件需 ESP-IDF；只想玩可刷预编译固件连官方服务器
生态价值：免费 Qwen 模型引流 + 硬件厂商入驻 + MCP 协议 = AI 语音硬件底座