lucky-cat/docs/embedded-assets-and-flash-layout.md

应用内嵌素材与 Flash 布局

LCD PNG 和 Opus 提示音随应用固件一起发布。ota_0、ota_1 各为 4.5 MiB；每个槽位包含代码和同版本素材。语音识别模型仍单独使用 model 分区，NVS、OTA 数据和 coredump 维持各自用途。分区的实际偏移以 16m.csv 和每次构建生成的空间报告为准。

构建流程

1. tools/optimize_lcd_assets.py check-current 核对已提交的优化 PNG 与原图、manifest 一致。
2. components/platform/CMakeLists.txt 将明确列出的 PNG 和 assets/audio_prompts/ 中的 Opus 复制到构建暂存目录。
3. tools/pack_embedded_assets.py 按名称排序，生成 platform_assets.pack。包内每项包含名称、长度及原始文件字节；程序通过名称查找，不需要 LittleFS 挂载。未列入 PNG 清单的原图不会进入固件。
4. 构建系统将整个包嵌入 TQ_Cat_Code.bin。OTA 对应用镜像执行原有长度、SHA-256 和镜像校验，素材随固件一起切换或回滚。
5. 每次 idf.py build 结束后，tools/report_flash_usage.py 输出完整分区地址、应用槽位占用、素材包大小、模型镜像占用和 Flash 未分配尾部；超出分区容量时构建失败。

idf.py flash 首次烧录 bootloader、分区表、OTA 数据、应用和模型。不再生成或烧录 gifpack.bin。旧分区布局的开发板需先整片擦除，再烧录新布局；只执行应用 OTA 不会改写分区表或模型分区。

运行时读取

platform 内部的 platform_asset_find() 返回只读地址和长度。调用方必须使用完整包内名称：LCD 使用 lcd/<名称>.png，提示音使用 audio_prompts/<名称>.opus。PNG 解码器直接读取应用镜像内的字节，不复制整张 PNG 到 PSRAM；解码后的 RGB565 缓存仍保留。Opus 按原有四字节大端长度头逐帧送入音频管线，并逐帧检查边界。

素材只随应用固件发布。仅修改某张图或提示音，也需要发布新的应用 OTA 镜像。model 分区仍通过 ESP-SR 独立加载，不属于应用 OTA。

验证边界

本地构建和素材包校验可证明文件被打包且镜像装入分区；LCD 显示、提示音播放、双槽 OTA、回滚及模型加载仍须在开发板上验证。