216 lines
5.8 KiB
Markdown
216 lines
5.8 KiB
Markdown
# customer_fs.bin 双系统生成工具
|
||
|
||
本目录提供 `EG800AKCN_11LG` 项目的 `customer_fs.bin` 自动生成和校验工具，支持
|
||
Windows 与 macOS。
|
||
|
||
当前 `customer_fs` 分区大小为 576 KiB，设备 kernel 只支持 LittleFS 磁盘格式
|
||
`0x00020000`（disk 2.0）。所有生成入口都会在输出前执行兼容性检查，避免再次生成
|
||
kernel 无法挂载的 disk 2.1 镜像。
|
||
|
||
## 1. 源文件目录
|
||
|
||
文件系统的源文件统一存放在：
|
||
|
||
```text
|
||
audio_prompts/customer_fs/
|
||
```
|
||
|
||
当前目录中的 14 个音频文件，全部从已经过实机验证、能够正常挂载的 Windows
|
||
`customer_fs.bin` 中提取，并经过重新打包和逐文件回读验证。
|
||
|
||
设备代码从 `U:/` 根目录访问文件，因此所有文件必须直接放在上述目录中。例如：
|
||
|
||
```text
|
||
正确：audio_prompts/customer_fs/network_connect_zh.mp3
|
||
错误：audio_prompts/customer_fs/subdir/network_connect_zh.mp3
|
||
```
|
||
|
||
生成工具会拒绝隐藏文件和子目录，避免把 `.DS_Store` 等无关文件打进正式镜像。
|
||
|
||
## 2. 如何增删改文件
|
||
|
||
生成工具采用“根据源目录全量重建”的方式，不是在旧 bin 上追加内容。
|
||
|
||
- 添加：把新文件直接放进 `audio_prompts/customer_fs/`；
|
||
- 替换：用新文件覆盖同名文件；
|
||
- 编辑：使用音频工具修改原文件并保存到原位置；
|
||
- 删除：从源目录删除文件，下一次生成的 bin 中将不再包含该文件；
|
||
- 改名：直接修改源文件名，但必须同步确认业务代码使用的新文件名。
|
||
|
||
部分音频文件名已经写入业务代码。删除或改名后，如果代码仍然播放原文件，串口会打印：
|
||
|
||
```text
|
||
tips file missing
|
||
```
|
||
|
||
因此，生成工具允许删减文件，但删减前仍需确认业务代码不再使用它。
|
||
|
||
## 3. Windows 一键生成
|
||
|
||
在项目根目录执行：
|
||
|
||
```bat
|
||
tools\customer_fs\build_windows.bat
|
||
```
|
||
|
||
Windows 版本使用项目自带并已通过实机验证的工具：
|
||
|
||
```text
|
||
ql-cross-tool\win32\mklfs-v2.exe
|
||
```
|
||
|
||
同时使用 SDK 自带的 Python 执行兼容性校验，不需要另外安装 Python 依赖。
|
||
|
||
也可以指定自定义源目录和输出文件：
|
||
|
||
```bat
|
||
tools\customer_fs\build_windows.bat 源目录 输出文件
|
||
```
|
||
|
||
例如：
|
||
|
||
```bat
|
||
tools\customer_fs\build_windows.bat ^
|
||
audio_prompts\customer_fs ^
|
||
output\customer_fs\customer_fs.bin
|
||
```
|
||
|
||
## 4. macOS 一键生成
|
||
|
||
在项目根目录执行：
|
||
|
||
```bash
|
||
./tools/customer_fs/build_macos.sh
|
||
```
|
||
|
||
首次运行时，脚本会自动创建：
|
||
|
||
```text
|
||
.venv-customer-fs
|
||
```
|
||
|
||
并安装项目固定的依赖版本：
|
||
|
||
```text
|
||
littlefs-python==0.19.0
|
||
```
|
||
|
||
新版 `littlefs-python` 默认会生成 disk 2.1 镜像，不能直接使用它自带的命令行生成。
|
||
本项目的 `generate_macos.py` 会显式设置：
|
||
|
||
```text
|
||
disk_version = 0x00020000
|
||
```
|
||
|
||
从而生成当前设备 kernel 可以识别的 disk 2.0 镜像。
|
||
|
||
也可以指定自定义源目录和输出文件：
|
||
|
||
```bash
|
||
./tools/customer_fs/build_macos.sh 源目录 输出文件
|
||
```
|
||
|
||
例如：
|
||
|
||
```bash
|
||
./tools/customer_fs/build_macos.sh \
|
||
audio_prompts/customer_fs \
|
||
output/customer_fs/customer_fs.bin
|
||
```
|
||
|
||
## 5. 默认输出位置
|
||
|
||
Windows 和 macOS 默认都输出到：
|
||
|
||
```text
|
||
output/customer_fs/customer_fs.bin
|
||
```
|
||
|
||
生成时会先写入临时文件：
|
||
|
||
```text
|
||
customer_fs.bin.tmp
|
||
```
|
||
|
||
只有生成和全部校验成功后，临时文件才会替换正式输出。生成或校验失败时，已有正式输出
|
||
不会被覆盖。
|
||
|
||
## 6. 自动门禁检查
|
||
|
||
每次生成都会检查：
|
||
|
||
| 检查项 | 要求 |
|
||
| --- | ---: |
|
||
| 镜像大小 | 589824 字节 |
|
||
| LittleFS 磁盘格式 | `0x00020000` |
|
||
| Block Size | 4096 字节 |
|
||
| Block Count | 144 |
|
||
| 第一个 superblock | 必须存在且参数正确 |
|
||
| 第二个 superblock | 必须存在且参数正确 |
|
||
| 源目录 | 不能为空 |
|
||
| 源文件层级 | 只能是根目录文件 |
|
||
| 隐藏文件 | 不允许 |
|
||
| 文件名 | 必须能在生成镜像中找到 |
|
||
|
||
也可以单独校验一个镜像：
|
||
|
||
```bash
|
||
python3 tools/customer_fs/verify_customer_fs.py \
|
||
--image output/customer_fs/customer_fs.bin \
|
||
--source audio_prompts/customer_fs
|
||
```
|
||
|
||
校验成功会输出镜像大小、LittleFS 版本、块参数、源文件数量和 SHA-256。
|
||
|
||
## 7. 放入正式固件工程
|
||
|
||
生成并校验成功后，需要显式复制到 SDK 打包位置。
|
||
|
||
macOS：
|
||
|
||
```bash
|
||
cp output/customer_fs/customer_fs.bin \
|
||
ql-config/config/EG800AKCN_11LG/customer_fs.bin
|
||
```
|
||
|
||
Windows：
|
||
|
||
```bat
|
||
copy /Y output\customer_fs\customer_fs.bin ^
|
||
ql-config\config\EG800AKCN_11LG\customer_fs.bin
|
||
```
|
||
|
||
替换前建议备份原文件并记录新镜像的 SHA-256。
|
||
|
||
`customer_fs.bin` 不是当前 APP-only OTA 的升级内容。修改该镜像后，需要重新生成并烧录
|
||
包含分区表、kernel、customer_app 和 customer_fs 的完整工厂包，不能只下发 APP OTA。
|
||
|
||
## 8. 实机验收
|
||
|
||
Windows 生成工具已经过实机验证。macOS 工具已经通过结构校验、重新挂载和逐文件回读，
|
||
首次用于正式版本前仍应至少烧录一台设备验收。
|
||
|
||
启动日志应直接出现：
|
||
|
||
```text
|
||
[U] mount successfully
|
||
```
|
||
|
||
不能出现：
|
||
|
||
```text
|
||
[U] mount failed (-22), will format fs partition
|
||
```
|
||
|
||
还需要逐一验证镜像中的音频能够通过 `U:/文件名` 正常读取和播放，并记录本次发布使用的
|
||
`customer_fs.bin` SHA-256。
|
||
|
||
## 9. 注意事项
|
||
|
||
- 不要用十六进制工具把 disk 2.1 镜像的版本字段直接改成 disk 2.0；
|
||
- 不要直接使用 `python -m littlefs create`，它当前默认生成 disk 2.1；
|
||
- 不要把 `.venv-customer-fs`、`output` 或 `.DS_Store` 提交到仓库；
|
||
- Windows 和 macOS 生成镜像的整体 SHA-256 可能不同，这是块分配顺序不同造成的；
|
||
- 两个平台产物必须满足相同的 disk 2.0、4096 字节块和 144 块约束；
|
||
- 修改、删除或重命名业务音频前，必须同步检查代码中的文件名引用。
|