feat: add standalone factory test firmware

2026-09-23 17:12:54 +08:00
parent 1f55943c29
commit 3e86e6cd66
14 changed files with 1349 additions and 2 deletions
@@ -0,0 +1,213 @@
+# 班班硬件独立产测程序
+
+## 1. 目标和边界
+
+本分支提供独立于主业务程序的硬件产测固件。`ql-application/threadx/Makefile`
+只编译 `interface/factory_test`，不会启动原 `custom_app`、MQTT、WSS、FOTA、
+业务按键或业务 NFC 线程。
+
+产测固件复用 SDK 底层接口、ES8311 配置、DP1312EA 驱动和 Type A 读卡实现。
+测试结果通过 USB CDC 和调试串口输出。上位机只需解析以 `FT1 ` 开头的行，
+其他 SDK 调试信息可以忽略。
+
+默认通信参数：
+
+- USB CDC，115200 8N1；
+- 同一条协议也通过 `printf` 输出到调试日志；
+- 每条协议消息为一行 UTF-8/ASCII JSON，以 `\r\n` 结束；
+- 协议前缀固定为 `FT1 `，协议版本为 `1`。
+
+## 2. 测试流程
+
+```text
+长按电源键开机
+  -> 等待音频子系统就绪
+  -> ES8311 ID/初始化，设置所有播放音量为 100%
+  -> 播放开机提示音
+  -> 电源 ADC
+  -> 按住对话键录音，松开后回放，最多录 5 秒
+  -> 工人判断音质
+       正常：按另一个按键三次
+       异常：不再操作，60 秒后 KEY_TRIPLE 失败
+  -> eSIM READY 和 ICCID
+  -> 4G 注册、PDP 激活、获取 IPv4
+  -> Ping 业务域名
+  -> 前面全部通过后启用 NFC 测试
+  -> 读取 NTAG213 UID
+  -> 播放“全部测试通过”
+  -> 播放关机提示音
+  -> 输出最终报告
+  -> 正常关机
+```
+
+任何节点失败后立即输出 `node_result=FAIL` 和 `session_result=FAIL`，随后停留在
+当前失败状态，不继续后续测试、不开放 NFC、也不自动关机。重新测试需要重新开机。
+
+## 3. 节点定义
+
+| ID | 名称 | 测试方法 | 通过条件 | 超时 |
+|---:|---|---|---|---:|
+| 0 | `BOOT_AUDIO` | 读取 ES8311 ID，初始化外置 Codec，播放 `U:/factory_boot_zh.mp3` | Codec ID 为 `0x83`，文件存在且播放结束 | 15 秒播放超时 |
+| 1 | `POWER_ADC` | 读取 6 次 VBAT，去掉最大值和最小值后平均 | `3500mV <= 平均值 <= 4200mV` | - |
+| 2 | `AUDIO_LOOPBACK` | 按住电源/对话键录音，松开后按原音量回放 | 录音和回放 API 成功且至少有一帧 PCM | 等待按键 60 秒，录音最长 5 秒 |
+| 3 | `KEY_TRIPLE` | GPIO84 按下并释放三次，每次输出进度 PASS | 60 秒内累计三次有效按键 | 60 秒 |
+| 4 | `ESIM` | 查询 SIM 状态并读取 ICCID | `READY`，ICCID 为 18-22 位十进制数字 | 30 秒 |
+| 5 | `DATA_CALL` | 等待注册、激活 CID 1 IPv4 PDP | 返回非 `0.0.0.0` 的 IPv4 | 注册等待 120 秒 |
+| 6 | `PING` | Ping `banban.api.talkingq.com` 3 次 | 至少收到 2 次回复 | 单包 4 秒，总等待 20 秒 |
+| 7 | `NFC` | 检查 DP1312EA 版本并轮询 NTAG213 | 版本 `0x82`，成功读取 UID | 60 秒 |
+
+说明：`AUDIO_LOOPBACK` 的软件通过仅代表数据链路完成。最终声学判断由工人完成；
+如果声音异常，工人不按三击键，随后 `KEY_TRIPLE` 超时，整机产测失败。这避免了
+上位机额外的人工确认按钮。
+
+## 4. 音频和文件系统接口
+
+固件只通过以下固定路径访问提示音：
+
+```text
+U:/factory_boot_zh.mp3
+U:/factory_pass_zh.mp3
+U:/factory_shutdown_zh.mp3
+```
+
+对应资源源目录为：
+
+```text
+audio_prompts/factory_test/customer_fs/
+```
+
+资源为 16kHz、单声道、48kbps MP3。代码不会下载提示音，也不会在运行时回退到
+业务网络资源。缺少开机提示音会返回 `1002`；最终提示音缺失或播放失败会返回
+`1801`，并禁止自动关机。
+
+本分支不生成、不覆盖 `ql-config/config/EG800AKCN_11LG/customer_fs.bin`。
+Windows 打包方法见 [factory_test_windows_fs.md](factory_test_windows_fs.md)。
+
+## 5. 上位机协议
+
+### 5.1 公共字段
+
+| 字段 | 说明 |
+|---|---|
+| `v` | 协议版本，当前为 1 |
+| `type` | `session_start`、`node_start`、`node_progress`、`node_result`、`session_result` 或 `power_off` |
+| `seq` | 本次开机内单调递增的消息序号 |
+| `session` | RTC 有效时使用时间生成，否则为 `BOOT-<uptime>` |
+| `uptime_ms` | 开机后的毫秒数，不依赖网络校时 |
+| `imei` | 模组 IMEI；读取失败时为空字符串 |
+| `iccid` | eSIM 节点通过后填写，此前为空字符串 |
+| `nfc_uid` | NFC 节点通过后填写，此前为空字符串 |
+| `code` / `fail_code` | 0 表示成功，非零值见失败码表 |
+| `elapsed_ms` | 单个节点耗时 |
+| `duration_ms` | 整次产测耗时 |
+
+### 5.2 会话开始
+
+```text
+FT1 {"v":1,"type":"session_start","seq":1,"session":"20260923-163010","uptime_ms":2050,"imei":"860123456789012","iccid":"","nfc_uid":"","fw":"FACTORY_TEST_1.0.0","ping_host":"banban.api.talkingq.com","start_time":"2026-09-23T16:30:10"}
+```
+
+RTC 无效时 `start_time` 为 `null`。RTC 无效不会导致产测失败；测试耗时始终以
+`uptime_ms` 为准。
+
+### 5.3 节点开始
+
+```text
+FT1 {"v":1,"type":"node_start","seq":2,"session":"20260923-163010","uptime_ms":2100,"imei":"860123456789012","iccid":"","nfc_uid":"","node":1,"name":"POWER_ADC"}
+```
+
+### 5.4 ADC 通过
+
+```text
+FT1 {"v":1,"type":"node_result","seq":3,"session":"20260923-163010","uptime_ms":2450,"imei":"860123456789012","iccid":"","nfc_uid":"","node":1,"name":"POWER_ADC","result":"PASS","code":0,"elapsed_ms":350,"data":{"voltage_mv":3865,"sample_min_mv":3858,"sample_max_mv":3873,"limit_min_mv":3500,"limit_max_mv":4200}}
+```
+
+### 5.5 三击按键进度
+
+每次完整按下并释放都输出一条 `node_progress`：
+
+```text
+FT1 {"v":1,"type":"node_progress","seq":8,"session":"20260923-163010","uptime_ms":12300,"imei":"860123456789012","iccid":"","nfc_uid":"","node":3,"name":"KEY_TRIPLE","result":"PASS","data":{"current":1,"required":3}}
+```
+
+第三次松开后再输出正式的 `node_result=PASS`。
+
+### 5.6 网络和 Ping
+
+```text
+FT1 {"v":1,"type":"node_result","seq":14,"session":"20260923-163010","uptime_ms":28000,"imei":"860123456789012","iccid":"89860xxxxxxxxxxxxxxx","nfc_uid":"","node":5,"name":"DATA_CALL","result":"PASS","code":0,"elapsed_ms":8200,"data":{"ip":"10.23.45.67","ip_type":"IPv4"}}
+```
+
+```text
+FT1 {"v":1,"type":"node_result","seq":16,"session":"20260923-163010","uptime_ms":31500,"imei":"860123456789012","iccid":"89860xxxxxxxxxxxxxxx","nfc_uid":"","node":6,"name":"PING","result":"PASS","code":0,"elapsed_ms":3400,"data":{"host":"banban.api.talkingq.com","sent":3,"received":3,"lost":0,"avg_rtt_ms":86}}
+```
+
+### 5.7 NFC 和最终报告
+
+```text
+FT1 {"v":1,"type":"node_result","seq":18,"session":"20260923-163010","uptime_ms":34000,"imei":"860123456789012","iccid":"89860xxxxxxxxxxxxxxx","nfc_uid":"04A1B2C3D4E5F6","node":7,"name":"NFC","result":"PASS","code":0,"elapsed_ms":1900,"data":{"chip_version":"0x82","uid":"04A1B2C3D4E5F6"}}
+```
+
+最终报告包含 IMEI、ICCID、NFC UID、失败码、开始时间、总耗时和全部节点状态：
+
+```text
+FT1 {"v":1,"type":"session_result","seq":19,"session":"20260923-163010","uptime_ms":40120,"result":"PASS","fail_code":0,"imei":"860123456789012","iccid":"89860xxxxxxxxxxxxxxx","nfc_uid":"04A1B2C3D4E5F6","start_time":"2026-09-23T16:30:10","duration_ms":38070,"nodes":{"BOOT_AUDIO":"PASS","POWER_ADC":"PASS","AUDIO_LOOPBACK":"PASS","KEY_TRIPLE":"PASS","ESIM":"PASS","DATA_CALL":"PASS","PING":"PASS","NFC":"PASS"}}
+```
+
+上位机收到 `power_off` 后应立即落盘本次记录：
+
+```text
+FT1 {"v":1,"type":"power_off","seq":20,"session":"20260923-163010","uptime_ms":40150,"imei":"860123456789012","iccid":"89860xxxxxxxxxxxxxxx","nfc_uid":"04A1B2C3D4E5F6","code":0}
+```
+
+## 6. 失败码
+
+| 失败码 | 含义 |
+|---:|---|
+| 0 | 成功 |
+| 1001 | ES8311 初始化或设备 ID 检查失败 |
+| 1002 | 开机提示音文件不存在 |
+| 1003 | 开机提示音播放失败或超时 |
+| 1101 | ADC 初始化或读取失败 |
+| 1102 | 电压低于 3500mV |
+| 1103 | 电压高于 4200mV |
+| 1201 | 录音句柄或 160KB 缓冲区创建失败 |
+| 1202 | 没有录到一帧有效 PCM |
+| 1203 | PCM 回放失败 |
+| 1204 | 60 秒内未按下对话键 |
+| 1301 | 音质异常未继续，或 60 秒内未完成三击 |
+| 1401 | eSIM 未进入 READY |
+| 1402 | ICCID 读取失败 |
+| 1403 | ICCID 长度或字符格式错误 |
+| 1501 | 4G 网络注册超时 |
+| 1502 | IPv4 PDP 激活失败 |
+| 1503 | 未获取有效 IPv4 地址 |
+| 1601 | Ping 上下文或同步对象创建失败 |
+| 1602 | Ping 启动或等待回调失败 |
+| 1603 | 3 包中收到少于 2 包 |
+| 1701 | 前置节点未全部通过，NFC 锁定 |
+| 1702 | DP1312EA 版本寄存器不是 `0x82` |
+| 1703 | 60 秒内没有成功刷卡 |
+| 1704 | NFC UID 无效（预留） |
+| 1801 | 最终通过/关机提示音播放失败 |
+| 1802 | 正常关机接口返回（理论上不应返回） |
+
+## 7. 代码位置和可调参数
+
+- `interface/factory_test/factory_test.c`：顺序状态机和具体测试；
+- `interface/factory_test/factory_audio.c`：ES8311、100% 音量、MP3、录音回放；
+- `interface/factory_test/factory_protocol.c`：FT1 JSON 日志；
+- `interface/factory_test/factory_test.h`：阈值、超时、业务域名、GPIO 和文件路径；
+- `interface/factory_test/Makefile`：独立产测编译单元。
+
+修改 Ping 地址时只需修改 `FT_PING_HOST`。ADC 阈值、按键超时和 NFC 超时也集中在
+`factory_test.h`。GPIO84 是第二个按键，GPIO68 是功放控制；产测代码不会把 GPIO68
+当作 LED，也不会把 GPIO86 当作红色 LED，避免和 NFC 复位冲突。
+
+## 8. 上板前检查
+
+1. 确认 PCB 上对话键确实连接模组 PWRKEY，第二按键连接 GPIO84。
+2. 确认 GPIO68 为 NS4150B `PA_CTL`，GPIO86 为 NFC Reset。
+3. 将三段 MP3 打入 U 盘文件系统，不能只更新 APP。
+4. 首板先观察 ES8311 ID、ADC 原始值、IP 和 DP1312EA 版本日志。
+5. 上位机只把 `FT1 ` 行作为协议消息，SDK 的普通 `printf` 不应进入数据库。
@@ -0,0 +1,136 @@
+# Windows 生成产测 customer_fs.bin
+
+## 1. 说明
+
+产测固件从 U 盘文件系统根目录读取以下三个文件：
+
+```text
+factory_boot_zh.mp3
+factory_pass_zh.mp3
+factory_shutdown_zh.mp3
+```
+
+仓库中的待打包目录是：
+
+```text
+audio_prompts\factory_test\customer_fs
+```
+
+SDK 自带的 Windows 工具是：
+
+```text
+ql-cross-tool\win32\mklfs-v2.exe
+```
+
+工具的命令格式为：
+
+```text
+mklfs-v2.exe -c <待打包目录> -s <文件系统字节数> -i <输出镜像>
+```
+
+当前 `EG800AKCN_11LG/customer_fs.bin` 的大小是 262144 字节，因此产测镜像也使用
+262144。不要改变该容量，除非同时确认分区表允许更大的 customer_fs。
+
+## 2. 检查资源
+
+在 Windows `cmd.exe` 中进入仓库根目录：
+
+```bat
+cd /d D:\你的路径\banban
+dir audio_prompts\factory_test\customer_fs
+```
+
+应看到且只需要打包以下文件：
+
+```text
+factory_boot_zh.mp3
+factory_pass_zh.mp3
+factory_shutdown_zh.mp3
+```
+
+代码访问的是文件系统根目录，所以不要在 `customer_fs` 目录里面再创建一层同名目录。
+
+## 3. 备份现有镜像
+
+现有镜像属于原业务固件。先备份，避免之后无法恢复：
+
+```bat
+copy /Y ql-config\config\EG800AKCN_11LG\customer_fs.bin ^
+  ql-config\config\EG800AKCN_11LG\customer_fs.bin.before-factory-test
+```
+
+本仓库提交不会替你执行此覆盖操作。
+
+## 4. 生成到临时输出目录
+
+先生成到独立目录，不要让打包工具直接覆盖配置目录：
+
+```bat
+if not exist output\factory-test mkdir output\factory-test
+
+ql-cross-tool\win32\mklfs-v2.exe ^
+  -c audio_prompts\factory_test\customer_fs ^
+  -s 262144 ^
+  -i output\factory-test\customer_fs.bin
+```
+
+工具应正常退出，并生成：
+
+```text
+output\factory-test\customer_fs.bin
+```
+
+检查镜像大小：
+
+```bat
+for %I in (output\factory-test\customer_fs.bin) do @echo %~zI bytes
+```
+
+结果必须是：
+
+```text
+262144 bytes
+```
+
+如果把命令写进 `.bat` 文件，`%I` 要写成 `%%I`。
+
+## 5. 放入项目配置目录
+
+确认临时镜像大小正确后再复制：
+
+```bat
+copy /Y output\factory-test\customer_fs.bin ^
+  ql-config\config\EG800AKCN_11LG\customer_fs.bin
+```
+
+此时再执行产测 APP 和整包构建：
+
+```bat
+build.bat app
+build.bat firmware
+```
+
+`build_package.bat` 会从下面的位置取 customer_fs：
+
+```text
+ql-config\config\EG800AKCN_11LG\customer_fs.bin
+```
+
+## 6. 烧录后验证
+
+1. 长按开机后应听到“设备已开机，开始硬件测试啦”。
+2. 串口应出现 `BOOT_AUDIO` 的 `node_result=PASS`。
+3. 如果返回 `1002`，说明 APP 已更新但 customer_fs 没有更新，或文件名/层级错误。
+4. 如果返回 `1003`，文件存在但无法解码或播放超时；检查 MP3 是否为完整文件。
+5. 通过 USB CDC 抓取 `FT1 ` 开头的完整日志，确认 IMEI、ICCID、NFC UID 和耗时均出现。
+
+## 7. 恢复业务文件系统
+
+需要恢复原业务固件时：
+
+```bat
+copy /Y ql-config\config\EG800AKCN_11LG\customer_fs.bin.before-factory-test ^
+  ql-config\config\EG800AKCN_11LG\customer_fs.bin
+```
+
+然后重新执行 `build.bat firmware`。不要把产测 customer_fs 和正式业务 APP 混合发布。