一、为什么要区分 BLE 直连与 BLE+Wi-Fi Combo

统一互联 3.0 的应用终端可以采用不同的网络形态，但首次配网通常都从近端 BLE 开始。BLE 的职责是让配置对端发现设备、建立安全会话、完成设备认证并下发长期配置；它并不天然等同于设备后续的运行期网络。

本文以 WS63 应用终端为例，整理两种常见形态：

两种形态不能被理解为“两套完全独立的协议”。它们的前半段应尽可能复用同一套 BLE Profile、SPEKE 安全协商、设备认证和长期凭据保存逻辑；真正的差异发生在配置完成后的网络接入与上线阶段。

图 1：两种终端共享 BLE 配网期，配网后的运行期网络不同。

二、配网角色：谁负责什么

为了便于描述，本文把手机 App 或协议网关统一称为“配网对端”。它们在终端侧使用相同的 BLE 服务；区别只在于谁发起连接、谁代办外部认证、谁保存家庭网络或中枢侧信息。

角色	主要职责	不应混淆的边界
配网对端（App / 协议网关）	扫描、连接、发起 SPEKE、请求设备信息、代办认证、下发配置	不负责终端内部持久化和底层 Wi-Fi 驱动
WS63 应用终端	广播、GATT 服务、安全处理、参数校验、凭据保存、网络接入	不实现 App 页面、云端认证业务或中枢设备管理页面
外部认证侧	基于设备认证材料完成 PSK 或证书认证	不直接操作 BLE GATT 链路
SecurityStore / 本地存储	加密持久化设备配置、长期 PSK、证书或 ACL	不参与临时 SPEKE 密钥协商
Wi-Fi 模块（Combo 可选）	扫描、关联 AP、获取网络状态	不参与 BLE PIN 协商与设备身份认证

在实际联调中，终端只需要保证：只要对端以正确的统一互联 BLE Profile 调用服务，就能按同一语义完成处理。App 直连和网关代理不应导致终端复制两套 SPEKE 或配网业务代码。

三、共同前半段：从未配网广播到安全会话

3.1 发送未配网广播

终端上电、恢复出厂或进入待配网状态后，会发送 BLE 广播。广播用于让配置对端识别“这是一个可配置的统一互联终端”，通常包含产品标识、协议版本、配网状态和能力信息。

广播阶段需要区分两件事：

• 发现成功：配置对端能够扫描到设备，且广播内容可解析；
• 配网成功：后续安全、认证、配置和网络步骤均完成。

扫描到设备只是配网入口，不代表已经建立信任关系。广播内容应避免放入 PIN、PSK、Wi-Fi 密码、证书等敏感数据。

图 2：未配网广播只提供发现与识别所需的最小信息，不承载 PIN、PSK、Wi-Fi 密码或证书。

3.2 建立 GATT 连接并准备服务

配置对端发现设备后，建立 BLE GATT 连接，协商 MTU，并发现统一互联对应的服务与特征。此时数据通道已经可用，但设备仍处于未认证、未配置状态。

对应用终端而言，GATT 层需要完成以下基础工作：

1. 接受连接并维护连接上下文；
2. 接收对端写入的协议数据，处理 MTU 限制下的分包与重组；
3. 通过通知或 Indication 返回服务响应和异步状态；
4. 在断连、超时和重复连接时释放本次会话资源。

“写特征成功”只表示数据送达 GATT 服务，不表示业务已经处理成功。后续必须以服务响应、状态回调或下一阶段日志确认。

3.3 SPEKE：建立本次配网的临时安全会话

SPEKE 是首次配网中最重要的安全边界之一。配置对端与终端使用双方一致的 PIN 等输入，完成 EC-SPEKE 消息交换并各自派生 configSessionKey。该会话密钥用于保护后续配网敏感数据，密钥本身不会通过 BLE 直接下发。

可以把 SPEKE 的作用理解为：先证明双方拥有同一个配网凭据，再获得一条临时的加密配置通道。它的成功含义仅限于“本次安全会话建立成功”，不能替代设备身份认证，也不能代表设备已联网。

终端侧应记录协议阶段、数据长度、返回码和会话清理结果；不应打印 PIN、原始密钥材料、临时私钥、完整安全报文或会话密钥。

图 3：SPEKE 消息交互与临时配置会话建立。

四、共同中段：设备信息、认证与长期配置

4.1 deviceInfo：确认设备身份和能力

SPEKE 成功后，配网对端通常先读取 deviceInfo。该接口用于获取终端的基础身份、产品信息和配网所需能力描述，使对端知道后续应如何认证和配置。

deviceInfo 返回成功通常代表设备侧查询服务正常，不代表认证或绑定已经完成。处理该请求时应注意字段完整性、版本兼容和敏感字段最小暴露原则。

4.2 getProvisionRequest：获取认证初始化材料

配置对端随后通过 getProvisionRequest 请求设备认证初始化数据。按照 BLE 业务操作语义，该请求是查询操作，应以 GET（op=1）发起；终端侧将其注册为 GET 服务并返回认证材料。

这里容易混淆“GATT 写入”和“协议操作类型”：即使请求最终经由某个 BLE 写特征送达，业务层仍需要依据协议头中的 op 选择 GET 或 PUT 服务回调。把 getProvisionRequest 误当作 PUT，会使终端进入错误分发路径，无法得到预期的认证请求数据。

4.3 配网对端代办外部认证

终端返回认证材料后，由配网对端与外部认证侧交互，代办 PSK 或证书认证。终端的职责是提供必要材料、等待认证后的配置下发，并验证返回配置是否处于正确的安全会话中。

这一步体现了“近端传输”和“身份认证”的分层：BLE 负责把材料安全地传给配网对端，认证服务负责确认设备合法性。终端无需把云端或中枢认证逻辑复制到固件中。

4.4 hubCfg 与 provisionPSK：保存长期运行配置

认证通过后，配网对端会向终端下发中枢绑定信息和长期管理凭据。常见的配置包括：

• hubCfg：如 domainId、code、devId 等中枢或管理域信息；对于 Combo 终端，也可包含 SSID、密码、BSSID、信道等 Wi-Fi 接入参数；
• provisionPSK：终端后续管理会话所需的长期 PSK 及关联信息；
• 证书或 ACL：按产品安全模型可选下发的身份与权限配置。

设备端在持久化前至少应校验消息处于合法 SPEKE 会话、关键字段格式正确、参数长度合理，并在失败时避免把半成品状态误标记为“已配网”。长期 PSK、证书、Wi-Fi 密码等应使用安全存储或加密存储，不能通过普通调试日志输出。

图 4：设备信息查询、认证初始化与长期配置下发。

五、两种形态从哪里开始分叉

完成长期配置保存后，BLE 直连型终端与 BLE+Wi-Fi Combo 终端会走向不同的运行期网络。

5.1 BLE 直连型终端：继续依赖 BLE 接入中枢

BLE 直连型终端不需要自行接入家庭 Wi-Fi。配网后，它继续以 BLE 为终端侧通信介质，由协议网关或本地中枢负责发现、转发、管理和向更上层系统接入。

终端侧的后续重点包括：

1. 持久化管理域、设备标识和长期凭据；
2. 从待配网广播切换为已配网运行状态；
3. 根据产品策略提供可被网关发现、连接和控制的 BLE 服务；
4. 建立配网后的管理会话，例如按需创建 PSK 会话；
5. 正确处理网关重连、控制命令、状态查询、状态上报与恢复出厂。

需要注意的是，应用终端不直接实现中枢与协议网关之间的 /bridge/* 管理接口。那些接口属于中枢或网关侧；终端只需维持统一的终端 BLE Profile 和已配网状态。

5.2 BLE+Wi-Fi Combo：从 hubCfg 获取参数并接入 Wi-Fi

Combo 终端仍然先使用 BLE 完成安全配网，但在 hubCfg 保存成功后，会读取其中的 Wi-Fi 参数，启动 STA 扫描、关联目标 AP，并等待网络可用。

典型步骤如下：

1. 校验 hubCfg 中的 SSID、密码、BSSID、信道等网络参数；
2. 将必要配置加密持久化，避免断电或重启后丢失；
3. 启动 Wi-Fi STA，按产品策略扫描并关联目标 AP；
4. 获取网络状态与 IP 地址，确认设备具备局域网通信条件；
5. 启动运行期的本地网络服务，与中枢或局域网服务建立后续通信。

这里的一个关键约定是：Wi-Fi 参数由 hubCfg 承载时，netCfg 用于上报网络连接状态，而不是再重复下发一份 SSID 和密码。 这样可以避免两套网络配置来源互相覆盖，也使配网对端能根据状态区分“开始连接、已连接、连接失败或超时”。

图 5：BLE+Wi-Fi Combo 终端从 hubCfg 到 Wi-Fi STA 入网的处理链路。

六、统一视角下的完整流程图

下面的时序图将共同链路与两种分叉链路放在一起。配网对端可以是 App，也可以是协议网关；终端侧的主服务处理逻辑应保持一致。

图 6：共同配网主线及 BLE 直连、BLE+Wi-Fi Combo 的分叉收尾。

图 7：共同配网主线及 BLE 直连、BLE+Wi-Fi Combo 的时序图。
上图以状态流转展示流程分支；下图以参与方交互顺序展示相同过程。

七、联调时应如何判断每一阶段完成

1. 广播发现：观察扫描记录和广播原始数据；设备应可发现、可解析且状态正确。不要把“扫描到设备”当作“配网成功”。
2. GATT 建连：观察连接状态、服务发现和特征是否可用；服务收发通道建立后才能进入下一步。不要把“写入成功”当作“业务成功”。
3. SPEKE：观察阶段推进、返回码和会话清理；双方完成临时安全会话才算通过。SPEKE 成功不等于设备认证成功。
4. 设备认证：观察 deviceInfo、getProvisionRequest 与认证结果；终端应返回正确材料，认证结果才能用于下发配置。deviceInfo 成功不等于设备已经绑定。
5. 长期配置：观察 hubCfg、PSK/证书/ACL 的保存结果；应完成安全校验和持久化，失败不得污染配网状态。参数被接收不等于已经保存。
6. BLE 直连后段：观察网关发现、连接、控制和状态上报；终端应按已配网 Profile 工作。终端不需要实现网关的 /bridge/* 接口。
7. Combo 后段：观察 STA 关联、网络状态、IP 与本地服务；Wi-Fi 可用并进入运行期网络才算通过。Wi-Fi 初始化成功不等于已经入网。

建议将“最后一个确定成功阶段”和“第一个异常阶段”写入每轮联调记录。即使串口日志存在多线程交错，也可以借助时间戳、连接标识、服务名和请求标识恢复主要时序。

八、安全与可靠性注意事项

1. 不记录 PIN、PSK、sessionKey、私钥、证书正文、Wi-Fi 密码或原始认证报文；
2. getProvisionRequest 作为查询服务，应按协议使用 GET 语义，避免 GET/PUT 分发混淆；
3. 只在安全会话合法、配置字段完整时持久化长期配置；
4. 配置保存、Wi-Fi 入网或后续网络初始化失败时，不能错误切换为已配网状态；
5. 断连、超时、恢复出厂和重复配网时，应清理临时 SPEKE 会话与半成品资源；
6. Combo 终端的 Wi-Fi 密码应只进入受保护存储和驱动配置接口，不进入普通日志或状态上报。

九、总结

BLE 直连型终端与 BLE+Wi-Fi Combo 终端的配网核心相同：先通过 BLE 发现和 GATT 建连，再完成 SPEKE、安全认证、hubCfg 与长期凭据下发。区别在于配网后的运行期网络：BLE 直连型终端继续由协议网关或中枢通过 BLE 接入；Combo 终端则从 hubCfg 获取网络参数，自行接入 Wi-Fi 并启动局域网运行期服务。

将共同主线和网络分叉拆开理解，可以减少重复实现，也能让联调人员快速判断问题属于 BLE 传输、安全认证、配置持久化，还是后续网络接入阶段。