toy-hardware/自定义唤醒词配置使用手册.md

# AI小智自定义唤醒词配置使用手册

## 🚀 快速开始

### 1. 配置项目

在项目根目录执行配置命令：
```bash
idf.py menuconfig
```

### 2. 导航到配置选项

在menuconfig界面中：
```
顶级菜单 → Xiaozhi Assistant → 唤醒词配置
```

### 3. 选择唤醒词模式

**方案A：使用自定义唤醒词（推荐）**
```
[ ] 启用唤醒词检测                    # 关闭传统模式
[*] 启用自定义唤醒词检测              # 开启自定义模式
    自定义唤醒词 (ni hao xiao zhi)   # 拼音配置
    自定义唤醒词显示文本 (你好小智)   # 显示文本
```

**方案B：使用传统固定唤醒词**
```
[*] 启用唤醒词检测                    # 开启传统模式
[ ] 启用自定义唤醒词检测              # 关闭自定义模式
```

## 🎨 自定义唤醒词配置示例

### 配置"小爱同学"
```
[*] 启用自定义唤醒词检测
    自定义唤醒词 (xiao ai tong xue)
    自定义唤醒词显示文本 (小爱同学)
```

### 配置"天猫精灵"
```
[*] 启用自定义唤醒词检测
    自定义唤醒词 (tian mao jing ling)
    自定义唤醒词显示文本 (天猫精灵)
```

### 配置"小度小度"
```
[*] 启用自定义唤醒词检测
    自定义唤醒词 (xiao du xiao du)
    自定义唤醒词显示文本 (小度小度)
```

### 配置"嘿Siri"
```
[*] 启用自定义唤醒词检测
    自定义唤醒词 (hei siri)
    自定义唤醒词显示文本 (嘿Siri)
```

## 📋 拼音输入规则

### 基本规则
- **格式**：汉语拼音，单词间用空格分隔
- **声调**：不需要标注声调
- **大小写**：建议使用小写
- **长度**：建议2-5个字，效果最佳

### 拼音对照表
| 汉字 | 拼音 | 汉字 | 拼音 |
|------|------|------|------|
| 小 | xiao | 智 | zhi |
| 爱 | ai | 助 | zhu |
| 你 | ni | 手 | shou |
| 好 | hao | 机 | ji |
| 天 | tian | 器 | qi |
| 猫 | mao | 人 | ren |

### 常见错误
❌ `xiaozhi`（连写）  
✅ `xiao zhi`（分开）

❌ `ni-hao`（用连字符）  
✅ `ni hao`（用空格）

## 🔧 编译和部署

### 1. 编译项目
```bash
idf.py build
```

**预期输出**：
```
...
[100%] Built target ai-xiaozhi.elf
Project build complete.
```

### 2. 烧录固件
```bash
idf.py flash
```

### 3. 查看运行日志
```bash
idf.py monitor
```

**成功日志示例**：
```
I (12345) CustomWakeWord: multinet:mn5_cn
I (12346) CustomWakeWord: Custom wake word: ni hao xiao zhi
I (12347) CustomWakeWord: Audio detection task started
...
I (15000) CustomWakeWord: Custom wake word 'ni hao xiao zhi' detected successfully!
```

## 🧪 功能测试

### 1. 基础测试
- **开机自检**：查看日志确认唤醒词模式
- **唤醒测试**：说出配置的唤醒词
- **响应测试**：确认设备正确响应

### 2. 对比测试
- **灵敏度**：与传统模式对比响应速度
- **准确率**：测试误唤醒和漏检情况
- **稳定性**：长时间运行测试

### 3. 环境测试
- **安静环境**：测试最低音量阈值
- **噪音环境**：测试抗干扰能力
- **距离测试**：测试有效识别距离

## ⚙️ 高级配置

### 调整检测阈值
如果唤醒词过于敏感或不够敏感，可以修改代码：

**文件**：`main/audio_processing/custom_wake_word.cc`
**位置**：第67行
```cpp
multinet_->set_det_threshold(multinet_model_data_, 0.5);  // 默认0.5，范围0.1-0.9
```

- **降低值**（如0.3）：更容易唤醒，但可能误触发
- **提高值**（如0.7）：减少误触发，但需要更清晰发音

### 调整超时时间
**位置**：第66行
```cpp
multinet_model_data_ = multinet_->create(mn_name_, 2000);  // 2秒超时
```

### 调试模式启用
在menuconfig中启用：
```
Component config → Log output → Default log verbosity → Debug
```

## 🐛 故障排除

### 编译错误

**错误1**：`undefined reference to CONFIG_CUSTOM_WAKE_WORD`
```
解决：确保在menuconfig中启用了自定义唤醒词
```

**错误2**：`esp_mn_commands_* not found`
```
解决：确认ESP-SR组件版本 >= 2.0.3
```

### 运行错误

**错误1**：初始化失败
```
日志：Failed to initialize multinet
解决：检查PSRAM配置，确保ESP32-S3芯片
```

**错误2**：唤醒词不响应
```
检查：1. 麦克风硬件  2. 拼音配置  3. 音量大小
```

**错误3**：频繁误触发
```
解决：提高检测阈值或更换唤醒词
```

## 📈 性能优化

### 内存优化
- 确保PSRAM启用
- 监控堆内存使用
- 定期检查内存泄漏

### CPU优化
- 合理设置任务优先级
- 避免在音频任务中执行重操作
- 使用合适的CPU核心分配

## 🔄 版本兼容性

| ESP-IDF版本 | 支持状态 | 备注 |
|-------------|----------|------|
| 5.3+ | ✅ 完全支持 | 推荐版本 |
| 5.2 | ⚠️ 部分支持 | 需要更新ESP-SR |
| 5.1 | ❌ 不支持 | 缺少必要组件 |

## 📞 技术支持

如遇到问题，请检查：
1. 硬件是否符合要求（ESP32-S3 + PSRAM）
2. ESP-SR组件版本是否正确
3. 拼音配置是否准确
4. 系统日志中的错误信息

---

**祝您使用愉快！** 🎉