banban/docs/factory_test.md

班班硬件独立产测程序

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. 测试流程

长按电源键开机
  -> 等待音频子系统就绪
  -> 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. 音频和文件系统接口

固件只通过以下固定路径访问提示音：

U:/factory_boot_zh.mp3
U:/factory_pass_zh.mp3
U:/factory_shutdown_zh.mp3

对应资源源目录为：

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。

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 会话开始

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 节点开始

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 通过

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：

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

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"}}

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 和最终报告

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、失败码、开始时间、总耗时和全部节点状态：

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 后应立即落盘本次记录：

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 不应进入数据库。