banban/docs/factory_test.md

班班硬件独立产测程序

1. 目标和边界

本分支提供独立于主业务程序的硬件产测固件。ql-application/threadx/Makefile 只编译 interface/factory_test，不会启动原 custom_app、MQTT、WSS、FOTA、 业务按键或业务 NFC 线程。

产测固件复用 SDK 底层接口、ES8311 配置、DP1312EA 驱动和 Type A 读卡实现。 测试结果通过 DBG UART 输出。上位机只需解析以 FT1 开头的行， 其他 SDK 调试信息可以忽略。

默认通信参数：

• DBG UART（GPIO29/30），115200 8N1；
• 协议与 SDK 调试日志共用 printf 输出；
• 每条协议消息为一行 UTF-8/ASCII JSON，以 \r\n 结束；
• 协议前缀固定为 FT1 ，协议版本为 2。

2. 测试流程

长按电源键开机
  -> 立即在后台打开 GNSS，持续累计 NMEA、卫星数和定位状态
  -> 等待音频子系统就绪
  -> ES8311 ID/初始化，设置所有播放音量为 100%
  -> 播放开机提示音
  -> 电源 ADC
  -> 按住 GPIO84（原三击测试按键）录音，松开后回放，最多录 5 秒
  -> 工人判断音质
  -> eSIM READY 和 ICCID
  -> 4G 注册、PDP 激活、获取 IPv4
  -> 前面全部通过后启用 NFC 测试
  -> 读取 NTAG213 UID
  -> 播放一次 GNSS 测试提示音并读取后台累计结果
  -> 未达到门槛时保持呼吸灯并持续等待
  -> GNSS 通过后结束搜索
  -> 播放关机提示音
  -> 输出最终报告
  -> 正常关机

任何节点失败后立即输出 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	按住 GPIO84 录音，松开后按原音量回放	录音和回放 API 成功且至少有一帧 PCM	等待按键 60 秒，录音最长 5 秒
3	ESIM	查询 SIM 状态并读取 ICCID	READY，且能读到 18-22 位 ICCID	30 秒
4	DATA_CALL	等待注册、激活 CID 1 IPv4 PDP	返回非 0.0.0.0 的 IPv4	注册等待 120 秒
5	NFC	检查 DP1312EA 版本并轮询 NTAG213	版本 0x82，成功读取 UID	60 秒
6	GNSS	开机后后台搜索，到节点后循环读取累计值	open_ret=0 且 nmea_count>=5；卫星数和定位状态只记录	无限等待直到通过；打开失败时每 2 秒重试

说明：AUDIO_LOOPBACK 使用 GPIO84 按键，软件通过仅代表录放数据链路完成。 最终声学判断由工人完成。

GPIO70 蓝色状态灯在普通流程中长亮，Loopback 使用 250ms 慢闪，NFC 使用 100ms 快闪，GNSS 使用 PWM1 做约 1.4 秒一轮的呼吸效果。如果 PWM 配置或使能失败， GNSS 会自动降级为两次 80ms 短闪后熄灭 520ms，不影响测试判定。GNSS 未达到 基础硬件门槛时不会报失败或退出节点，指示灯持续呼吸；通过后才恢复常亮并进入关机流程。

4. 音频和文件系统接口

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

U:/factory_boot_zh.mp3
U:/factory_audio_loopback_zh.mp3
U:/factory_nfc_test_zh.mp3
U:/factory_gnss_test_zh.mp3
U:/factory_shutdown_zh.mp3

对应资源源目录为：

audio_prompts/factory_test/customer_fs/

资源为 16kHz、单声道、48kbps MP3。代码不会下载提示音，也不会在运行时回退到 业务网络资源。节点提示音缺失或播放失败会返回 1002/1003；关机提示音播放 失败会返回 1801，并禁止自动关机。本固件没有“全部测试通过”音频。

本分支不生成、不覆盖 ql-config/config/EG800AKCN_11LG/customer_fs.bin。 Windows 打包方法见 factory_test_windows_fs.md。

5. 上位机协议

5.1 公共字段

字段	说明
v	协议版本，当前为 2
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":2,"type":"session_start","seq":1,"session":"20260923-163010","uptime_ms":2050,"imei":"860123456789012","iccid":"","nfc_uid":"","fw":"FACTORY_TEST_1.1.1","start_time":"2026-09-23T16:30:10"}

RTC 无效时 start_time 为 null。RTC 无效不会导致产测失败；测试耗时始终以 uptime_ms 为准。

5.3 节点开始

FT1 {"v":2,"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":2,"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 数据连接

FT1 {"v":2,"type":"node_result","seq":14,"session":"20260923-163010","uptime_ms":28000,"imei":"860123456789012","iccid":"89860xxxxxxxxxxxxxxx","nfc_uid":"","node":4,"name":"DATA_CALL","result":"PASS","code":0,"elapsed_ms":8200,"data":{"ip":"10.23.45.67","ip_type":"IPv4"}}

5.6 NFC、GNSS 和最终报告

FT1 {"v":2,"type":"node_result","seq":18,"session":"20260923-163010","uptime_ms":34000,"imei":"860123456789012","iccid":"89860xxxxxxxxxxxxxxx","nfc_uid":"04A1B2C3D4E5F6","node":5,"name":"NFC","result":"PASS","code":0,"elapsed_ms":1900,"data":{"chip_version":"0x82","uid":"04A1B2C3D4E5F6"}}
FT1 {"v":2,"type":"node_result","seq":20,"session":"20260923-163010","uptime_ms":35200,"imei":"860123456789012","iccid":"89860xxxxxxxxxxxxxxx","nfc_uid":"04A1B2C3D4E5F6","node":6,"name":"GNSS","result":"PASS","code":0,"elapsed_ms":950,"data":{"open_ret":0,"nmea_count":65,"sat_count":0,"fix_status":0,"search_ms":35100,"required_nmea_count":5,"required_sat_count":0}}

最终报告包含 IMEI、ICCID、NFC UID、失败码、开始时间、总耗时和全部节点状态：

FT1 {"v":2,"type":"session_result","seq":21,"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","ESIM":"PASS","DATA_CALL":"PASS","NFC":"PASS","GNSS":"PASS"}}

上位机收到 power_off 后应立即落盘本次记录：

FT1 {"v":2,"type":"power_off","seq":22,"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 秒内未按下 Loopback 按键
1401	eSIM 未进入 READY
1402	ICCID 读取失败
1403	ICCID 长度不在 18-22 位范围内
1501	4G 网络注册超时
1502	IPv4 PDP 激活失败
1503	未获取有效 IPv4 地址
1601	GNSS 打开失败
1602	GNSS 打开成功但未收到 NMEA
1603	GNSS 已收到 NMEA，但未发现卫星且没有有效定位
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_gnss.c：开机后台搜星、NMEA/GSV/GGA 累计；
• interface/factory_test/factory_protocol.c：FT1 JSON 日志；
• interface/factory_test/factory_test.h：阈值、超时、业务域名、GPIO 和文件路径；
• interface/factory_test/Makefile：独立产测编译单元。

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 版本和 GNSS 累计值。
5. 上位机只把 FT1 行作为协议消息，SDK 的普通 printf 不应进入数据库。