test: verify NTP reachability and APP clock on device

2026-10-26 15:24:13 +08:00
parent c53a117368
commit 03627a26fa
6 changed files with 500 additions and 1 deletions
@@ -0,0 +1,44 @@
+# 纯 APP 的设备侧 NTP 测试
+
+本次测试只新增 APP 代码，不需要编译、修改或更新内核。测试使用设备自己的 PDP 1 和 SIM 网络，不使用电脑网络来判断白名单是否放行。
+
+## 编译与运行
+
+在现有 Windows 构建环境执行 `build.bat app`，按现有 APP OTA 流程生成、校验和更新 APP 镜像，核对分区容量。保留目标设备原内核和 RTC/NVM 状态。不要为了运行这个测试执行 `build.bat kernel` 或烧录全分区包；分支之前的内核诊断改动不是本测试的依赖。
+
+每次启动后，PDP 首次成功激活会自动启动独立测试任务，不阻塞 MQTT 联网流程。每次启动只测试一次，不依赖串口命令。默认服务器为现有 GNSS 配置所用的 `ntp.aliyun.com`，端口为 UDP 123；可在编译时用 `APP_NTP_TEST_SERVER` 替换为白名单中的服务器。
+
+测试会实际调用现有 SDK NTP 接口，可能校正 APP RTC。这是连通性与校时效果的测试版本，不包含正式修复所需的周期校时、退避重试和 WSS 等待策略。
+
+## 判定流程
+
+1. 在设备 PDP 上解析目标域名，输出解析到的 IP。`dns_ok` 不表示 NTP 可用。
+2. 向解析到的第一个 IPv4 地址发送 NTP 请求，接收窗口为 5 秒。使用连接的 UDP socket，并检查响应模式、版本、闰秒状态、层级、请求时间戳回显及时间范围。合法响应输出 `UDP_RESPONSE_VERIFIED` 和服务器 UTC 秒数。支持 2036 年 NTP era 翻转，范围限定在 2024 年至目标 signed 32 位时间上限。
+3. 检查原内核是否导出已有的 `ql_ntp_set_server`、`ql_ntp_set_cid`、`ql_ntp_sync_ex`。缺少接口时明确失败，不把动态转发接口静默返回当成成功。
+4. 通过公开 SDK 接口向同一域名发起 APP 校时，等待回调最多 25 秒。超时后不启动第二个请求；信号量保留到本次启动结束，以便迟到回调安全返回。
+5. 读取 `time(NULL)` 的返回值和 RTC 日历。要求回调成功、RTC 读取成功、APP UTC 有效，且 APP UTC 与第一次独立响应按运行计时外推后的时间相差不超过 6 秒，才输出 `PASS`。该容差涵盖首次响应最多 5 秒的传输窗口及秒级取整；不是精密授时指标。
+
+网络超时只能说明这次没有取得响应，不能单凭超时确定是白名单拦截，也可能是服务器、DNS、路由或临时网络故障。该 NTP 测试不提供服务器身份认证。
+
+## 日志示例
+
+以下是格式示例，不是本次设备实测结果：
+
+```text
+[APP-NTP-TEST] begin server=ntp.aliyun.com port=123 protocol=UDP pdp=1
+[APP-NTP-TEST] dns_ok ip=... response_not_yet_verified=1
+[APP-NTP-TEST] UDP_RESPONSE_VERIFIED ip=... epoch=... rtt_ms=...
+[APP-NTP-TEST] sdk_sync_begin app_before=...
+[APP-NTP-TEST] sdk_result callback=0 app_before=... app_after=... expected=... delta_s=0 rtc_rc=0
+[APP-NTP-TEST] PASS udp_response=verified app_utc=verified wss_still_requires_separate_handshake_check=1
+```
+
+`FAIL stage=dns`、`receive_wait`、`sdk_api_unavailable`、`sdk_callback_timeout`、`app_clock_verification` 分别定位到解析、接收、内核接口兼容、SDK 回调和 APP 时间结果。
+
+设备上出现 `PASS` 证明该次网络响应及 APP 校时读回通过，WSS 实际握手仍需另行核对。发布前还需验证原内核、故障现场 NVM、重启、断网恢复等场景。
+
+## 本机检查与当前状态
+
+`python3 tools/test_app_ntp_test.py` 编译实际测试模块，使用模拟网络和 SDK 验证响应校验、成功与失败路径、SDK 缺失、时区偏差、迟到回调及资源释放。这些模拟测试不向设备或公网发包。
+
+当前 macOS 环境无法运行仓库的 Windows 完整固件构建工具链。设备串口已有程序占用，且当前 APP 没有 NTP 测试指令，因此尚未执行本测试固件的设备侧验证，不能宣称白名单已经放行。