# 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 块约束；
- 修改、删除或重命名业务音频前，必须同步检查代码中的文件名引用。