唤醒词存储不足解决方案：自定义分区表实现ESP32存储容量扩展

1. 存储瓶颈诊断

1.1 现象识别

当你的ESP32设备出现以下情况时，很可能遭遇了存储容量瓶颈：

• 自定义唤醒词上传失败并提示"存储空间不足"
• 设备频繁重启或语音识别功能异常
• OTA升级过程中断并报错

1.2 容量评估方法

通过MCP协议发送存储信息查询命令，确认当前存储分配状态：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "system.storage.info",
    "arguments": {}
  },
  "id": 1
}

[!TIP] 正常响应应包含model分区信息，默认配置通常小于2MB

1.3 典型容量问题

场景	默认分区限制	实际需求	缺口
单唤醒词	1MB	512KB	充足
多唤醒词(3-5个)	1MB	3-4MB	2-3MB
带情感识别模型	1MB	6-8MB	5-7MB

2. 分区表技术原理

2.1 分区表定义

ESP32设备的分区表(Partition Table)是一种存储布局方案，通过CSV文件定义不同功能模块的存储区域分配，类似于硬盘的分区规划。

2.2 存储架构

上图展示了MCP协议下的系统架构，其中model分区专门用于存储唤醒词模型，是本次优化的核心目标。

2.3 分区表结构解析

标准分区表包含以下关键字段：

# Name,   Type, SubType, Offset,  Size, Flags
nvs,      data, nvs,     0x9000,    0x4000,  # 非易失性存储区
otadata,  data, ota,     0xd000,    0x2000,  # OTA升级信息区
phy_init, data, phy,     0xf000,    0x1000,  # 物理层初始化数据
model,    data, spiffs,  0x10000,   0x3f0000,# 唤醒词存储区(关键)
ota_0,    app,  ota_0,   0x400000,  6M,      # 应用程序区
ota_1,    app,  ota_1,   0xa00000,  6M       # 备份程序区

2.4 分区类型说明

类型	子类型	作用
data	nvs	存储系统配置和用户数据
data	ota	记录OTA升级状态
data	spiffs	用于文件系统存储(唤醒词模型)
app	ota_0/ota_1	应用程序代码存储区

3. 实施步骤

3.1 准备工作

先确认设备Flash容量→再选择对应分区模板→最后备份原始配置

[!WARNING] 错误的分区配置可能导致设备无法启动，请务必确认Flash实际容量

3.2 分区模板选择

根据设备硬件配置选择合适的分区模板：

模板文件	总容量	唤醒词分区	适用场景
partitions/v1/4m.csv	4MB	1MB	基础功能
partitions/v1/8m.csv	8MB	2MB	中等需求
partitions/v1/16m_custom_wakeword.csv	16MB	4MB	多唤醒词场景
partitions/v1/32m.csv	32MB	8MB	专业开发

3.3 修改分区配置

以16MB Flash设备为例，复制并修改分区表：

cp partitions/v1/16m_custom_wakeword.csv partitions/custom.csv

编辑自定义分区表，调整唤醒词分区大小：

# 原配置
model,    data, spiffs,  0x10000,   0x3f0000,  # 4MB

# 修改为8MB(0x7f0000)
model,    data, spiffs,  0x10000,   0x7f0000,  # 8MB

配置项说明：

• 默认值：4MB(0x3f0000)
• 推荐值：Flash总容量的1/4~1/3
• 风险提示：过大将挤占应用程序空间，过小则无法存储多个模型

3.4 生成分区二进制文件

使用项目提供的脚本工具构建资产文件：

python scripts/spiffs_assets/build_all.py --mode emoji_collections

验证输出文件是否生成：

ls -lh scripts/spiffs_assets/build/final/assets.bin

[!TIP] 成功生成的assets.bin文件大小应与分区表中model分区大小匹配

3.5 烧录分区表

idf.py -p /dev/ttyUSB0 partition-table-flash

验证分区是否生效：

idf.py monitor | grep "model partition"

预期输出应显示新的分区大小：

I (1234) partition: model partition size: 8388608 bytes

4. 场景扩展

4.1 多唤醒词配置

支持不同场景的唤醒词切换：

• 家庭场景："你好小智"
• 办公场景："小爱同学"
• 儿童模式："小机器人"

配置方法：通过MCP协议上传多个唤醒词模型到不同目录

4.2 模型动态加载

实现唤醒词模型的动态切换：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "wakeword.load",
    "arguments": {
      "model_path": "/spiffs/models/office_model"
    }
  },
  "id": 2
}

4.3 容量规划决策树

设备Flash容量 > 16MB ?
├─ 是 → 使用32m.csv模板
│  ├─ 需要存储>5个唤醒词 → 调整model分区至10MB
│  └─ 常规使用 → 保持默认8MB
└─ 否 → 使用16m_custom_wakeword.csv
   ├─ 有情感识别需求 → model分区设为6MB
   └─ 基础唤醒词功能 → 保持默认4MB

5. 常见故障排除

5.1 烧录后无法启动

症状：设备指示灯闪烁后无响应
解决方案：

1. 检查分区表中各分区总大小是否超过Flash实际容量
2. 确认ota_0和ota_1分区大小是否一致
3. 使用默认分区表恢复：idf.py -p /dev/ttyUSB0 flash

5.2 唤醒词识别率下降

症状：唤醒词响应变慢或误识别增加
解决方案：

1. 检查model分区是否分配过小(建议不小于2MB)
2. 使用system.storage.info确认模型文件完整性
3. 重新生成并烧录assets.bin：python scripts/spiffs_assets/build_all.py --clean

5.3 OTA升级失败

症状：升级到50%后失败
解决方案：

1. 检查ota_0和ota_1分区大小是否足够(建议每个不小于4MB)
2. 确认分区表中app分区起始地址是否正确
3. 调整分区配置：ota_0, app, ota_0, 0x400000, 8M

5.4 模型上传超时

症状：通过MCP上传模型超过30秒无响应
解决方案：

1. 检查网络连接稳定性
2. 将大模型拆分为多个小文件上传
3. 增加model分区大小减少碎片化

6. 进阶路径

6.1 分区优化

• 自定义分区表高级配置：partitions/v2/README.md
• 动态分区调整技术：docs/custom-board.md

6.2 唤醒词开发

• MCP协议工具注册：docs/mcp-usage.md
• 唤醒词训练指南：scripts/acoustic_check/readme.md

6.3 系统扩展

• WebSocket远程控制：docs/websocket.md
• 蓝牙配网实现：docs/blufi.md

通过合理的分区规划，你的ESP32设备将获得更强大的存储能力，为构建智能语音交互系统奠定坚实基础。