banban/factory_host/docs/USAGE.md

EG800 产测上位机使用说明

1. 发布目录

现场使用时至少保留以下内容，并保持相对目录不变：

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。推荐配置：

{
  "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. 测试结果与日志

默认自动保存位置：

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. 替换固件包

方法一：修改配置文件

把新固件复制到稳定目录，然后修改：

"firmwares": {
  "production": "新产测固件.zip",
  "official": "新正式固件-fac.zip"
}

推荐每次替换后记录文件名、版本、文件大小和 SHA-256，避免现场混用旧包。

方法二：在界面选择

选择“产测固件”或“正式固件”类型，再使用界面的固件选择按钮指定对应 ZIP。选择后检查界面顶部显示的完整路径。

正式固件通常不包含 FT1 产测协议。换烧正式固件后，上位机不能再自动识别为 FT1 产测工位，这是正常现象。

7. 更新产测音频并生成固件

音频源目录：

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

文件必须保持脚本要求的名称和音频格式。更新后在项目根目录执行：

python -B .\factory_host\scripts\build_factory_audio_package.py
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\factory_host\scripts\build_factory_firmware.ps1

生成物：

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。

开发环境先安装依赖：

python -m pip install -r .\factory_host\requirements.txt
python -m pip install pyinstaller

运行测试并打包：

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 保存，以及正式固件换烧。