banban/docs/new_board_wss.md

新板 main 分支 WSS 迁移说明

最新上板反馈（2026-09-16）：用户确认将 MQTT 改为 banban.api.talkingq.com:1883 后已连接成功。该反馈支持域名访问方式适配新板受限 eSIM 的判断；未提供本次成功日志，本文不据此宣称 GNSS、全部业务及 WSS 性能均已验收。

更新日期：2026-09-16。适用工作区：D:\banban\project\nfc_gnss，分支：main。

1. 迁移范围

以原主分支 2746cc3d4ebbd90f8fa0c1e68db93b199b297714 的新板代码为基础，迁入旧板已经完成联调的 WSS 实现、故障修复、完整握手优化与测试工具。新板仍使用自身的 GNSS 检测和定位任务。

旧板来源提交	迁入内容
3e463f5	WSS 地址解析、可信根 CA、服务器证书及域名验证、WebSocket Upgrade 校验
5c3e7ee	内核 ECDSA/GCM 能力、APP 与内核共享配置、RTC 证书日期校验、TLS 接收重试修复
3a0714c	NIST 曲线模约减加速、握手阶段计时、连接循环日志修正
551a7bb	完整握手优先协商 X25519，保留原有其他曲线作为回退
54bf67c	旧板联调过程、算法说明与实测总结，作为历史资料保留

这些提交的修改迁入工作区，不直接合并旧板分支。旧板关闭 GNSS 的提交 f283223 和音量改为 100 的提交 4b56595 未迁入。

2. 新板硬件与业务行为

• 内核 quec_get_gnssid_task() 仍创建 GNSS 型号识别任务 quec_get_ocname_by_gnss_task。
• APP app_gnss_init() 仍创建定位任务 quec_gnss_test，set_gnss_mode() 仍更新定位模式。
• audio.c 与原主分支一致：音量优先读取设备保存值，读取失败时回退至 70。
• 设备身份仍沿用 device_id / serial_number，不改后台鉴权格式。
• 按键触发连接；每次新连接仍执行完整 TLS 握手，没有提前建连或新增会话恢复逻辑。

3. WSS 与密码算法

默认地址：wss://banban.api.talkingq.com:443/ws。

使用 TLS 1.2，配置 ISRG Root X2 公共根 CA，验证服务器证书链、有效期和主机名。单向 TLS 不需要设备客户端证书，但服务器证书校验仍必须通过。WebSocket 层继续验证 HTTP 101 与 Sec-WebSocket-Accept。

内核提供 ECDSA 签名验证、ECDHE 密钥交换及 AES-GCM 等能力。APP 和内核共用 talkingq_mbedtls_config.h，避免跨边界使用 mbedTLS 结构体时因宏配置不同导致布局不一致。证书时间检查使用真实 RTC 和 UTC 转换，不再依赖原空时间实现。

ECDHE 优先使用 X25519；证书签名算法不因此改变。NIST 优化针对证书链和回退曲线的有限域计算，X25519 优化针对临时密钥交换，二者可同时受益。服务器最终选择的曲线以设备协商日志为准。

TLS 非阻塞读写返回 WANT_READ / WANT_WRITE 时继续等待或重试，不把暂时没有数据误判为连接断开。工作线程使用 16 KiB 栈，并保留完整握手总耗时、各阶段耗时及协商信息日志。

更多算法和问题根因见 旧板完整总结。其中的默认音量、关闭 GNSS 和实测性能均属于旧板历史。

4. 构建与切分支缓存

从原新板 main 升级至此版本，需要同时更新内核和 APP，因为原内核没有本次补齐的完整 TLS 算法与配置。不能只编译 APP 并沿用原 main 内核。

在仓库根目录执行：

build.bat kernel
build.bat app
build.bat firmware

首次切换发现旧 GNSS .d 文件仍引用旧板专用 board_features.h，导致内核构建提示依赖不存在。这是跨分支残留编译缓存，不是新板缺失硬件配置。处理方法为备份并移走内核 gps_app 和 APP gnss 的旧 .o、.d 文件，再重新构建；没有添加旧板配置头或跳过 GNSS 编译。

本次缓存备份和构建日志位于 artifacts/wss/new-board/。SDK 生成的诊断对象和链接反馈文件另行备份，包生成后恢复其原始受版本控制的内容，避免把构建副产物混入源码修改。

build.bat firmware 生成完整多分区固件包。提供的下载包来自 target/EG800AKCN_11LG/EG800AKCN_11LG.zip 内层 ZIP；它不是仅含 APP 的更新包。

5. 产物与验证

新板包：EG800AKCN_11LG-new-board-wss-x25519.zip。

本地验证报告：verification.json。该报告记录包 SHA-256、镜像大小和哈希、下载清单及检查结果。

验证覆盖：

• WSS URL、HTTP Upgrade、TLS 读写及接收回归测试。
• APP/内核 mbedTLS ABI、实际 SDK 证书链验证及 ECDH 运算测试。
• ZIP CRC，以及包内 cp.bin、customer_app.bin 与本次构建输出逐字节一致性。
• 最终 ELF 中 ECDSA、GCM、NIST 优化、RTC 时间转换和 WSS 关键符号。
• 反汇编确认 GNSS 识别及定位入口仍创建任务，且对应 worker 存在；新板镜像不包含旧板跳过 GNSS 的日志标记。

主机算法测试仅证明算法与配置可用，不能代替设备端速度测量。构建和静态校验也不代表已经完成新板上电、定位或语音业务测试。

6. 上板验收与影响

新板仍需验证正常启动、GNSS 识别、定位任务和语音业务。WSS 日志应出现证书/域名验证成功、HTTP 101，以及原有设备身份发送流程。关注 RTC 是否有效、网络信号、完整握手协商曲线与各阶段耗时。

旧板实测从最初约 9.6 秒 TLS 握手，经 NIST 优化降至 1820 ms，再经 X25519 优化降至 1455 ms。上述数据不能直接标注为新板测试结果；新板 GNSS 等任务可能影响调度和 CPU 负载，需要采集新日志比较。

证书校验继续要求正确时间、匹配域名和受信任证书链；未来后台更换证书链或根 CA 时需要复核。共享 TLS 配置改变了内核密码能力，其他使用相同内核接口的模块也需在新板回归时观察。

旧板分支和历史包保留，供旧板使用与回溯。新板使用本说明中的独立包目录，避免与 artifacts/wss/full-handshake/ 的旧板包混淆。

7. MQTT 连接诊断版本（2026-09-16）

新板 16:43 日志确认拨号获得 IP，但 MQTTConnect 返回 -1。语音键被识别后，因现有入口要求“拨号在线且 MQTT 在线”，播放网络检查提示，尚未发起 WSS。本轮增加连接诊断，GNSS 及网络准入、鉴权、重连策略保持原逻辑。

诊断包：EG800AKCN_11LG-new-board-wss-mqtt-diag.zip。这是完整多分区包；内核与上一新板 WSS 包逐字节相同，APP 增加日志。已刷入上一新板 WSS 内核时，本轮只需 build.bat app 和 build.bat firmware，无需重编内核。报告和构建日志位于包的同一目录。

日志	含义
[MQTT-DIAG] TCP begin/end	MQTT 服务地址、端口、拨号状态、连接返回值与耗时
CONNECT begin	协议版本、会话选项、超时及 SDK 客户端状态
write request / rc	SDK 写回调请求及返回字节数；负值表示失败
read request / rc	SDK 读回调返回值及耗时；0 或负值不等于鉴权拒绝
CONNECT end	MQTT 最终返回值、总耗时、读写次数及字节数
CONNACK code=0	服务端接受连接
CONNACK code=1/2/3/4/5	协议版本不支持 / Client ID 被拒绝 / 服务不可用 / 用户名或密码错误 / 未授权
no response bytes returned by SDK read	SDK 读回调未返回有效字节，不能单凭此项断定服务端原因
no valid initial CONNACK	已收到数据，但开头不构成完整合法 CONNACK
failed before transport write	尚未调用发送回调，优先检查客户端状态或 CONNECT 序列化
[NET-GATE] blocked_mqtt_offline	按键已识别，但 MQTT 未在线，因此未尝试 WSS
[NET-GATE] start_voice	通过网络准入，进入原语音流程

SDK 读回调把 EOF 和部分 socket 错误统一映射为 -1。errno_snapshot 是即时读取的错误快照，可能残留旧值，不能单凭它断言服务端拒绝或关闭。只有完整合法 CONNACK 中的拒绝码才作为服务端拒绝证据。诊断只观察原回调，不替换底层 socket 实现。

诊断仅在同步 MQTT CONNECT 期间挂接原有读写回调，结束即恢复，随后才启动 MQTT 后台线程。代码不打印 CONNECT 原文、账号、密码或业务报文，仅暂存接收开头四字节用于识别 CONNACK。诊断状态按现有单一 MQTT 连接工作线程的串行使用约束实现。

在 Visual Studio 开发命令行运行 tools/test_mqtt_diag.py，可测试参数和返回值透传、成功与失败后回调恢复、分片 CONNACK、服务端拒绝、无效响应、读写错误、无发送提前返回、时钟回绕，以及凭据测试标记不出现在日志中。

APP 构建、诊断测试和固件镜像校验已通过。SDK 原有隐式声明等编译警告仍存在，本轮没有修改这些接口。具体 MQTT 根因仍需新板运行诊断包后取得日志。

8. MQTT 域名试验版本（2026-09-16）

根据新板使用受限 eSIM 的情况，将 mqtt.c 中 DEFAULT_SERVER_DOMAIN 从 101.35.224.118 改为 banban.api.talkingq.com，端口仍为 1883，沿用明文 MQTT 和原有鉴权、注册流程。保留 MQTT-DIAG 与 NET-GATE 日志。

电脑侧已验证该域名解析到 101.35.224.118，使用固件现有账号、临时 Client ID 可收到 CONNACK=0。该结果不能代替新板 eSIM 白名单验证：若卡商还限制端口或协议，仅改域名可能仍无法通过。

本次包：EG800AKCN_11LG-new-board-wss-mqtt-domain.zip。内核与上一诊断包相同，APP 编译、固件打包和镜像校验通过；用户随后确认改域名后已连接成功。已使用本轮新板 WSS 内核时，只需 build.bat app 和 build.bat firmware。本包仍是完整多分区包。

开机应看到 [MQTT-DIAG] TCP begin host=banban.api.talkingq.com port=1883。随后观察 CONNACK、设备注册和按语音键后的 WSS 连接结果。本轮不更改提示音下载地址。