234 lines
5.3 KiB
Markdown
234 lines
5.3 KiB
Markdown
# 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（命令行）
|
||
|
||
```bash
|
||
# 安装 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：确认连接成功
|
||
|
||
```bash
|
||
# 查看日志
|
||
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. 放入服务器目录：
|
||
```bash
|
||
cp ~/Downloads/xiaozhi-esp32s3-2.2.4.bin \
|
||
/Users/bigemon/WorkSpace/xiaozhi-server/data/bin/
|
||
```
|
||
3. 重启玩偶或发送唤醒词，设备自动检测并下载新固件
|
||
|
||
### 本地测试固件
|
||
|
||
如果需要测试自己编译的固件：
|
||
```bash
|
||
# 用 esptool 烧录（需 USB 连接）
|
||
esptool.py --chip esp32s3 --port /dev/tty.usbserial-* \
|
||
write_flash 0x0 your-custom-firmware.bin
|
||
```
|
||
|
||
---
|
||
|
||
## 五、测试验证
|
||
|
||
### 唤醒词
|
||
**"你好，小智"**（默认）
|
||
|
||
### 测试流程
|
||
|
||
1. **连接验证**
|
||
```bash
|
||
python3 xiaozhi_log_monitor.py -r 50
|
||
# 确认看到 "连接成功"
|
||
```
|
||
|
||
2. **语音对话测试**
|
||
```
|
||
你：你好，小智
|
||
玩偶：你好！我是小智，很高兴认识你（中文 TTS）
|
||
```
|
||
|
||
3. **心理场景测试**（模拟）
|
||
```
|
||
你：今天小朋友打我，我好害怕
|
||
玩偶：[触发心理筛查 MCP] → 回应欺凌场景
|
||
```
|
||
|
||
4. **日志过滤命令**
|
||
```bash
|
||
# 只看 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 连接）
|
||
|
||
```bash
|
||
# macOS
|
||
screen /dev/tty.usbserial-* 115200
|
||
|
||
# 退出 screen
|
||
Ctrl+A → K → Y
|
||
```
|
||
|
||
### 服务器日志
|
||
|
||
```bash
|
||
# 实时监控（彩色）
|
||
python3 xiaozhi_log_monitor.py
|
||
|
||
# 回放最近 200 条
|
||
python3 xiaozhi_log_monitor.py -r 200
|
||
|
||
# 只看错误
|
||
python3 xiaozhi_log_monitor.py -f error
|
||
```
|
||
|
||
---
|
||
|
||
## 七、服务器配置确认
|
||
|
||
确保全模块服务器的 OTA 地址配置正确：
|
||
|
||
```bash
|
||
# 检查服务器 OTA 端点
|
||
curl -I http://127.0.0.1:8002/xiaozhi/ota/ 2>&1 | head -3
|
||
|
||
# OTA 文件目录
|
||
ls /Users/bigemon/WorkSpace/xiaozhi-server/data/bin/
|
||
```
|
||
|
||
---
|
||
|
||
## 八、快速参考命令卡
|
||
|
||
```bash
|
||
# 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
|
||
```
|