refactor: organize factory host release layout
This commit is contained in:
chenjintao
@@ -0,0 +1,146 @@
|
||||
# EG800 产测上位机开发与发布
|
||||
|
||||
## 1. 目录职责
|
||||
|
||||
| 目录 | 用途 | 是否提交 |
|
||||
| --- | --- | --- |
|
||||
| `src/` | 上位机与 FT1 协议源码 | 是 |
|
||||
| `config/` | 默认发布配置 | 是 |
|
||||
| `scripts/` | 音频、固件、上位机发布脚本 | 是 |
|
||||
| `tests/` | 单元测试 | 是 |
|
||||
| `docs/` | 工厂与开发文档 | 是 |
|
||||
| `firmware/` | 默认产测与正式固件 | 是，二进制由 Git LFS 管理 |
|
||||
| `vendor/` | 完整 Aboot 厂商工具 | 否，本地依赖 |
|
||||
| `build/` | 中间产物、备份和开发日志 | 否 |
|
||||
| `dist/` | 最终 release 目录和 ZIP | 否 |
|
||||
|
||||
不要在 `dist/` 保存需要长期保留的文件。`build_release.ps1` 每次发布前都会校验目标位于
|
||||
`factory_host` 内，然后清空并重建目标目录。
|
||||
|
||||
## 2. 环境准备
|
||||
|
||||
在项目根目录执行：
|
||||
|
||||
```powershell
|
||||
python -m pip install -r .\factory_host\requirements.txt
|
||||
python -m pip install pyinstaller
|
||||
```
|
||||
|
||||
完整固件构建还需要当前 EG800 SDK 的编译环境能够正常执行 `build.bat app` 和
|
||||
`build.bat firmware`。
|
||||
|
||||
发布还要求本机存在完整厂商工具目录：
|
||||
|
||||
```text
|
||||
factory_host/vendor/aboot-tools-2024.08.08-win-x64/
|
||||
```
|
||||
|
||||
`vendor/` 被 Git 忽略，不能只放一个 `adownload.exe`；请保留原工具的 DLL、配置、驱动和
|
||||
平台文件。发布脚本缺少该目录时会直接报错，不会生成残缺包。
|
||||
|
||||
## 3. 开发与测试
|
||||
|
||||
运行源码：
|
||||
|
||||
```powershell
|
||||
python -B .\factory_host\src\factory_host.py
|
||||
```
|
||||
|
||||
运行全部测试：
|
||||
|
||||
```powershell
|
||||
python -B -m unittest discover -s .\factory_host\tests -p "test_*.py" -v
|
||||
```
|
||||
|
||||
源码模式读取 `factory_host/config/factory_host_config.json`，日志写入
|
||||
`factory_host/build/logs/`。默认相对固件路径会解析到 `factory_host/dist/firmware/`。
|
||||
|
||||
## 4. 更新产测音频和固件
|
||||
|
||||
音频源位于：
|
||||
|
||||
```text
|
||||
audio_prompts/factory_test/customer_fs/
|
||||
```
|
||||
|
||||
生成并验证音频文件系统：
|
||||
|
||||
```powershell
|
||||
python -B .\factory_host\scripts\build_factory_audio_package.py
|
||||
```
|
||||
|
||||
输出位于 `factory_host/build/audio/`。脚本会检查五个固定 MP3 的名称与格式，生成
|
||||
262144 字节 `customer_fs.bin`，反向解包并逐文件核对 SHA-256。
|
||||
|
||||
生成产测完整固件：
|
||||
|
||||
```powershell
|
||||
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\factory_host\scripts\build_factory_firmware.ps1
|
||||
```
|
||||
|
||||
输出位于 `factory_host/build/firmware/`。脚本会临时替换 SDK 的业务
|
||||
`customer_fs.bin`，完成后恢复原文件并核对哈希。恢复失败时不得继续发布。
|
||||
|
||||
确认新固件后，将其更新为默认产测固件：
|
||||
|
||||
```text
|
||||
factory_host/firmware/test/EG800AKCN_11LG-FT1-factory-test.zip
|
||||
```
|
||||
|
||||
也可以不覆盖默认文件，在发布时通过 `-FactoryFirmware` 显式选择。
|
||||
|
||||
## 5. 生成交付包
|
||||
|
||||
使用默认两份固件：
|
||||
|
||||
```powershell
|
||||
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\factory_host\scripts\build_release.ps1
|
||||
```
|
||||
|
||||
使用指定固件，路径相对于项目根目录，也支持绝对路径：
|
||||
|
||||
```powershell
|
||||
powershell.exe -NoProfile -ExecutionPolicy Bypass `
|
||||
-File .\factory_host\scripts\build_release.ps1 `
|
||||
-FactoryFirmware "factory_host\build\firmware\EG800AKCN_11LG-FT1-factory-test.zip" `
|
||||
-OfficialFirmware "factory_host\firmware\official\EG800AKCN_11LG-official-fac.zip"
|
||||
```
|
||||
|
||||
发布脚本会：
|
||||
|
||||
1. 清空并重建 `factory_host/dist/`。
|
||||
2. 从 `src/` 生成无控制台窗口的单文件 EXE。
|
||||
3. 复制完整 Aboot 工具目录，不能只复制 `adownload.exe`。
|
||||
4. 复制产测与正式固件到 `dist/firmware/`。
|
||||
5. 把配置、使用说明、下载器和日志目录放入 `.runtime/`。
|
||||
6. 生成包含 Git revision、文件大小和 SHA-256 的 `release_manifest.json`。
|
||||
7. 生成 `EG800-Factory-Tool-Full-Package.zip`。
|
||||
|
||||
## 6. 发布检查
|
||||
|
||||
发布前至少执行：
|
||||
|
||||
```powershell
|
||||
python -B -m unittest discover -s .\factory_host\tests -p "test_*.py" -v
|
||||
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\factory_host\scripts\build_release.ps1
|
||||
tar.exe -tf .\factory_host\dist\EG800-Factory-Tool-Full-Package.zip
|
||||
```
|
||||
|
||||
ZIP 顶层只能包含：
|
||||
|
||||
```text
|
||||
START-EG800-FACTORY-TOOL.exe
|
||||
firmware/
|
||||
.runtime/
|
||||
```
|
||||
|
||||
还应在一台真实设备上验证：自动等待上电烧录、断开后才允许下一台、DBG UART 自动识别、
|
||||
六项 FT1 状态、JSON/CSV 保存，以及产测固件和正式固件切换。
|
||||
|
||||
## 7. 固件替换规则
|
||||
|
||||
- 产测与正式固件都必须是 Aboot 可直接烧录的内层 ZIP，不要选择外层 `*-target.zip`。
|
||||
- 默认文件名保持不变时无需修改配置。
|
||||
- 修改文件名时同步更新 `config/factory_host_config.json`。
|
||||
- 每次发布核对 `.runtime/release_manifest.json` 中的大小和 SHA-256。
|
||||
- 不要把源码、`build/`、SDK 编译目录或历史日志交付给工厂。
|
||||
@@ -0,0 +1,181 @@
|
||||
# EG800 产测上位机使用说明
|
||||
|
||||
## 1. 发布目录
|
||||
|
||||
现场使用时至少保留以下内容，并保持相对目录不变：
|
||||
|
||||
```text
|
||||
factory_host/dist/
|
||||
├─ START-EG800-FACTORY-TOOL.exe
|
||||
├─ firmware/
|
||||
│ ├─ EG800AKCN_11LG-FT1-factory-test.zip
|
||||
│ └─ EG800AKCN_11LG-official-fac.zip
|
||||
└─ .runtime/
|
||||
├─ factory_host_config.json
|
||||
├─ burn_tool/
|
||||
│ └─ aboot-tools-2024.08.08-win-x64/
|
||||
│ ├─ adownload.exe
|
||||
│ └─ 其他随工具提供的 DLL、配置和驱动文件
|
||||
├─ docs/USAGE.md
|
||||
├─ release_manifest.json
|
||||
└─ logs/
|
||||
```
|
||||
|
||||
`adownload.exe` 不能脱离原来的工具目录单独复制，否则可能缺少 DLL、配置或驱动。
|
||||
|
||||
工厂现场只需接收并解压 `EG800-Factory-Tool-Full-Package.zip`，然后双击根目录的
|
||||
`START-EG800-FACTORY-TOOL.exe`。不要把 `factory_host` 源码目录交付给现场；`.runtime`
|
||||
用于保存下载器、配置和日志，程序启动时会自动将其设为 Windows 隐藏目录，不应移动或删除。
|
||||
|
||||
## 2. 首次配置
|
||||
|
||||
上位机读取 `.runtime/factory_host_config.json`。推荐配置：
|
||||
|
||||
```json
|
||||
{
|
||||
"flash": {
|
||||
"downloader_path": ".runtime/burn_tool/aboot-tools-2024.08.08-win-x64/adownload.exe",
|
||||
"args": ["-u", "-a", "-s", "{baudrate}", "-q", "{firmware}"],
|
||||
"timeout_seconds": 900,
|
||||
"workers": 2
|
||||
},
|
||||
"firmwares": {
|
||||
"production": "firmware/EG800AKCN_11LG-FT1-factory-test.zip",
|
||||
"official": "firmware/EG800AKCN_11LG-official-fac.zip"
|
||||
},
|
||||
"serial": {
|
||||
"baudrate": 115200,
|
||||
"encoding": "utf-8",
|
||||
"line_ending": "\\r\\n"
|
||||
},
|
||||
"protocol": {
|
||||
"prefix": "FT1 ",
|
||||
"version": 1,
|
||||
"auto_save": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `production`：产测固件，包含 FT1 测试程序、开机/Loopback/NFC/关机音频，以及暂不参与流程的 GNSS 音频。
|
||||
- `official`：正式业务固件，供产测完成后换烧。
|
||||
- 固件路径可以使用相对于 EXE 所在发布目录的路径，也可以填写绝对路径。
|
||||
- 必须选择可直接烧录的内层 FT1 ZIP 或 `*-fac.zip`，不要选择外层 `*-target.zip` 归档。
|
||||
- 修改配置后重新启动上位机，或使用界面中的重新加载配置功能。
|
||||
|
||||
## 3. 烧录产测固件
|
||||
|
||||
1. 启动 `START-EG800-FACTORY-TOOL.exe`，固件类型选择“产测固件”或“正式固件”，确认顶部完整路径。
|
||||
2. 连接一个或多个烧录器，设备保持关机。
|
||||
3. 点击醒目的“启动自动烧录”，工具每 0.5 秒持续检测烧录串口，并为每个串口建立工位。
|
||||
4. 工位显示“烧录中·等待上电”后给对应设备开机，设备进入 AROM 后自动开始烧录。
|
||||
5. 工位显示“烧录成功”后先断开当前设备；工具检测到端口消失后才会允许下一次烧录，避免同一设备反复烧录。
|
||||
6. 换上下一台关机设备并上电，端口重新出现后自动开始下一次烧录。
|
||||
7. 全部生产完成后点击“停止烧录”；不要在实际写入过程中拔线或关闭程序。
|
||||
|
||||
默认参数使用 `adownload.exe -u -a` 自动等待 AROM 下载设备，因此烧录口和产测 UART 是两个不同角色。
|
||||
|
||||
## 4. 自动识别并开始产测
|
||||
|
||||
烧录完成、设备正常启动并连接调试 UART 后：
|
||||
|
||||
1. 点击“扫描串口”可只识别设备并查看工位；直接点击“开始产测”也会先自动扫描。
|
||||
2. 上位机被动监听所有候选 COM 口，不向设备发送 `IDENTIFY` 或 `START` 命令。
|
||||
3. 只有能持续返回合法 FT1 状态广播的 UART 才会自动添加为工位。当前固件使用 `QL_DEBUG_UART_PORT`（GPIO29/30），不使用 USB CDC；AROM、主 UART、DIAG 和 AT 口不会被添加。
|
||||
4. 每发现一台设备，上位机自动创建或复用一个空工位，并在工位表显示对应 COM 口。
|
||||
5. 设备上电后自动开始测试；上位机只接收并解析每 500ms 一次的完整状态广播，不需要发送启动命令。
|
||||
6. 未手工选中工位时，“开始产测”会启动所有已识别工位；选中工位时只启动选中的设备。
|
||||
|
||||
每个工位会实时显示：
|
||||
|
||||
- 当前测试节点和通过数量；
|
||||
- 整机通过或失败状态；
|
||||
- IMEI、ICCID、NFC UID；
|
||||
- 失败码、结构化测试数据和实时串口日志。
|
||||
|
||||
产测固件当前依次执行：开机音频、电源 ADC、音频 Loopback、eSIM、数据连接和 NFC。
|
||||
|
||||
## 5. 测试结果与日志
|
||||
|
||||
默认自动保存位置：
|
||||
|
||||
```text
|
||||
factory_host/dist/.runtime/logs/factory_results.csv
|
||||
factory_host/dist/.runtime/logs/sessions/*.json
|
||||
```
|
||||
|
||||
- `factory_results.csv`：每台设备一行，适合生产汇总。
|
||||
- `sessions/*.json`：保存完整协议消息、节点耗时、失败码和各节点数据，适合追查单台设备。
|
||||
- 普通 SDK 日志会显示在实时日志区，但只有 `FT1 ` 开头的合法协议消息会参与结果判定。
|
||||
- 最终判定以设备发送的 `session_result` 为准，上位机不会根据普通文本日志猜测通过或失败。
|
||||
|
||||
## 6. 替换固件包
|
||||
|
||||
### 方法一：修改配置文件
|
||||
|
||||
把新固件复制到稳定目录，然后修改：
|
||||
|
||||
```json
|
||||
"firmwares": {
|
||||
"production": "新产测固件.zip",
|
||||
"official": "新正式固件-fac.zip"
|
||||
}
|
||||
```
|
||||
|
||||
推荐每次替换后记录文件名、版本、文件大小和 SHA-256，避免现场混用旧包。
|
||||
|
||||
### 方法二：在界面选择
|
||||
|
||||
选择“产测固件”或“正式固件”类型，再使用界面的固件选择按钮指定对应 ZIP。选择后检查界面顶部显示的完整路径。
|
||||
|
||||
正式固件通常不包含 FT1 产测协议。换烧正式固件后，上位机不能再自动识别为 FT1 产测工位，这是正常现象。
|
||||
|
||||
## 7. 更新产测音频并生成固件
|
||||
|
||||
音频源目录：
|
||||
|
||||
```text
|
||||
audio_prompts/factory_test/customer_fs/
|
||||
├─ factory_boot_zh.mp3
|
||||
├─ factory_audio_loopback_zh.mp3
|
||||
├─ factory_nfc_test_zh.mp3
|
||||
├─ factory_gnss_test_zh.mp3
|
||||
└─ factory_shutdown_zh.mp3
|
||||
```
|
||||
|
||||
文件必须保持脚本要求的名称和音频格式。更新后在项目根目录执行：
|
||||
|
||||
```powershell
|
||||
python -B .\factory_host\scripts\build_factory_audio_package.py
|
||||
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\factory_host\scripts\build_factory_firmware.ps1
|
||||
```
|
||||
|
||||
生成物：
|
||||
|
||||
```text
|
||||
factory_host/build/audio/customer_fs.bin
|
||||
factory_host/build/audio/EG800AKCN_11LG-FT1-factory-audio.zip
|
||||
factory_host/build/firmware/EG800AKCN_11LG-FT1-factory-test.zip
|
||||
factory_host/build/firmware/firmware_manifest.json
|
||||
```
|
||||
|
||||
固件脚本会临时替换构建目录中的 `customer_fs.bin`，完成后自动恢复业务镜像并核对哈希。若脚本报告恢复失败，不要继续发布固件，应先检查备份和当前业务镜像。
|
||||
|
||||
## 8. 重新打包上位机
|
||||
|
||||
完整的工程结构、固件更新和发布参数见 `factory_host/docs/DEVELOPMENT.md`。
|
||||
|
||||
开发环境先安装依赖：
|
||||
|
||||
```powershell
|
||||
python -m pip install -r .\factory_host\requirements.txt
|
||||
python -m pip install pyinstaller
|
||||
```
|
||||
|
||||
运行测试并打包：
|
||||
|
||||
```powershell
|
||||
python -B -m unittest discover -s .\factory_host\tests -p "test_*.py" -v
|
||||
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\factory_host\scripts\build_release.ps1
|
||||
```
|
||||
|
||||
发布前至少使用一台设备验证：产测固件烧录、调试 UART 自动识别、START 握手、六项测试结果、JSON/CSV 保存，以及正式固件换烧。
|
||||
Reference in New Issue
Block a user