sileya-ai
/
child-psycho-companion
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
child-psycho-companion/ESP32_FLASH_GUIDE.md

5.3 KiB
Raw Permalink Blame History

ESP32 玩偶固件烧录与测试指南

目标平台： 小智 AI 玩偶（ESP32-S3/C3/P4）
固件来源： https://github.com/78/xiaozhi-esp32/releases
固件版本： v2.2.4（最新，2026-03-09）
服务器： xiaozhi-esp32-server 全模块（本地 MacBook Pro）
生成时间： 2026-04-07

一、固件获取

推荐版本

版本 固件名 状态 推荐理由
v2.2.4 xiaozhi-esp32s3-2.2.4.bin ✅ 官方最新 功能最全，但与 v1 不兼容
v1.9.2 xiaozhi-esp32s3-1.9.2.bin ✅ 稳定维护 分区表与 v2 不同，需全量烧录

下载链接： https://github.com/78/xiaozhi-esp32/releases

⚠️ v1 和 v2 分区表不同，不能从 v1 OTA 升级到 v2，必须全量烧录。

二、烧录工具选择

方案 A（推荐）：ESP Launchpad（在线，无需安装）

最适合零配置用户，无需 IDF 环境。

  1. 打开：https://espressif.github.io/esp-launchpad/
  2. 选择对应固件
  3. 连接 ESP32（USB-C 数据线）
  4. 点击 "Flash" 烧录

方案 B：esptool.py（命令行）

# 安装 esptool
pip3 install esptool

# 全量烧录（地址固定 0x0）
esptool.py --chip esp32s3 \
  --port /dev/tty.usbserial-* \
  write_flash 0x0 xiaozhi-esp32s3-2.2.4.bin

# 查找端口
ls /dev/tty.usbserial-*

方案 C：Thonny IDE（适合 Windows/Mac 入门用户）

https://thonny.org/

三、首次配置流程

固件烧录完成后，上电初始化配置：

Step 1：连接配置 WiFi

  1. 玩偶上电，等待启动
  2. 手机/电脑搜索 WiFi：Xiaozhi-XXXXXX（6位随机字符）
  3. 浏览器打开：http://192.168.4.1
  4. 填写：
    • WiFi SSID：你的 2.4GHz WiFi 名称
    • WiFi 密码：你的 WiFi 密码
    • OTA 地址：http://<MacBook-IP>:8002/xiaozhi/ota/
      • 查询本机 IP：ipconfig getifaddr en0（Mac）
      • 注意：必须是 8002（全模块），不是 8003
  5. 点击保存，设备自动重启

Step 2：确认连接成功

# 查看日志
python3 xiaozhi_log_monitor.py --filter device -r 50

# 或直接查看服务器日志
docker logs -f xiaozhi-esp32-server

成功标志：

[设备] 连接成功
Websocket地址是 ws://192.168.x.x:8000/xiaozhi/v1/
MCP接入点连接成功

四、OTA 固件升级

通过服务器 OTA（无需拆机）

  1. 下载新版本固件（如 xiaozhi-esp32s3-2.2.4.bin）
  2. 放入服务器目录： 
    cp ~/Downloads/xiaozhi-esp32s3-2.2.4.bin \
   /Users/bigemon/WorkSpace/xiaozhi-server/data/bin/
  3. 重启玩偶或发送唤醒词，设备自动检测并下载新固件

本地测试固件

如果需要测试自己编译的固件：

# 用 esptool 烧录（需 USB 连接）
esptool.py --chip esp32s3 --port /dev/tty.usbserial-* \
  write_flash 0x0 your-custom-firmware.bin

五、测试验证

唤醒词

"你好，小智"（默认）

测试流程

  1. 连接验证

    python3 xiaozhi_log_monitor.py -r 50
# 确认看到 "连接成功"

  2. 语音对话测试

    你：你好，小智
玩偶：你好！我是小智，很高兴认识你（中文 TTS）

  3. 心理场景测试（模拟）

    你：今天小朋友打我，我好害怕
玩偶：[触发心理筛查 MCP] → 回应欺凌场景

  4. 日志过滤命令

    # 只看 LLM/MCP 链路
python3 xiaozhi_log_monitor.py -f llm

# 只看 MCP 工具调用
python3 xiaozhi_log_monitor.py -f mcp

# 只看设备连接
python3 xiaozhi_log_monitor.py -f device

# 只看错误
python3 xiaozhi_log_monitor.py -f error

六、调试和问题排查

常见问题

症状 原因 解决方法
玩偶 WiFi 连接失败 输入了 5GHz WiFi 固件只支持 2.4GHz
OTA 地址填错 填了 8003 应填 8002（全模块智控台端口）
设备反复重启 WiFi 密码错误 重新进入 192.168.4.1 配置
设备不说话 TTS 未生成音频 检查 EdgeTTS 配置
MCP 工具不触发 服务器 MCP 未加载 docker logs 确认 MCP 初始化

串口日志（需要 USB 连接）

# macOS
screen /dev/tty.usbserial-* 115200

# 退出 screen
Ctrl+A → K → Y

服务器日志

# 实时监控（彩色）
python3 xiaozhi_log_monitor.py

# 回放最近 200 条
python3 xiaozhi_log_monitor.py -r 200

# 只看错误
python3 xiaozhi_log_monitor.py -f error

七、服务器配置确认

确保全模块服务器的 OTA 地址配置正确：

# 检查服务器 OTA 端点
curl -I http://127.0.0.1:8002/xiaozhi/ota/ 2>&1 | head -3

# OTA 文件目录
ls /Users/bigemon/WorkSpace/xiaozhi-server/data/bin/

八、快速参考命令卡

# 1. 启动日志监控
python3 xiaozhi_log_monitor.py

# 2. 查看设备连接日志
python3 xiaozhi_log_monitor.py -f device -r 50

# 3. 查看 MCP 工具调用
python3 xiaozhi_log_monitor.py -f mcp

# 4. 查看 LLM 调用
python3 xiaozhi_log_monitor.py -f llm

# 5. 重启服务器
docker restart xiaozhi-esp32-server

# 6. 查看容器状态
docker ps --format "{{.Names}}\t{{.Status}}"

# 7. 查询本机 IP（OTA 地址用）
ipconfig getifaddr en0