OpenHarmony 局域网设备控制架构解析：从设备发现到业务控制

摘要

在局域网 IoT 场景中，设备连上 Wi-Fi 并不等于控制端已经能够安全控制设备。一个完整的本地控制系统还需要解决设备发现、网络可达、身份建立、安全会话、业务控制和状态同步等问题。

本文以 OpenHarmony iot_management 组件为背景，分析 BLE、Wi-Fi、CoAP、SPEKE 和本地控制 Session 的职责边界，并给出设备从首次发现到稳定控制的完整生命周期模型。

关键字

OpenHarmony、iot_management、BLE、Wi-Fi、CoAP、SPEKE、本地控制

1. 为什么“设备有 IP”还不够

在最简单的网络程序中，只要知道对端 IP 和端口就可以发送 UDP 数据。但在真实 IoT 产品中，还必须回答以下问题：

1. 控制端如何确认网络中的响应来自目标设备？
2. 新设备尚未配置身份时，如何安全地完成首次接入？
3. 设备身份已经建立后，是否还需要每次重新执行高成本认证？
4. 设备重启、IP 变化或 Session 丢失后，双方如何恢复一致状态？
5. 如何防止旧数据包、重复请求和非法控制命令被再次执行？

因此，一个可用的设备控制系统至少需要五层能力：

这五层是逐级依赖关系。网络不可达时无法认证；身份未建立时不能直接进入长期本地控制；Session 不一致时，即使数据包到达设备也无法正确解密。

2. iot_management 的分层架构

iot_management 将应用接口、IPC 服务、设备编排、协议实现和平台能力分开组织。

这种分层有三个直接收益：

• 应用不需要理解 BLE、CoAP 的底层报文格式；
• 服务层只负责 IPC 生命周期，不直接实现协议状态机；
• BLE、Wi-Fi、CoAP、密码和 KV 后端可以分别适配和测试。

3. BLE、Wi-Fi 与 CoAP 的职责

3.1 BLE：首次发现与近场接入

BLE 适合设备尚未入网的阶段。控制端可以通过广播发现设备，通过近场连接完成身份信息或 Wi-Fi 参数的下发。

BLE 的优势是设备不依赖现有局域网即可被发现，但它不适合作为所有业务控制的唯一通道：连接范围、吞吐量和并发能力都受到限制。

3.2 Wi-Fi：提供网络可达性

Wi-Fi 解决的是链路与 IP 层可达问题。设备和控制端进入同一可达网络后，才能使用 CoAP 进行发现和控制。

Wi-Fi 本身不证明设备身份。控制端看到某个 IP 在线，只能说明网络上存在一个节点，不能据此直接执行敏感操作。

3.3 CoAP：局域网发现与本地控制

CoAP 基于 UDP，适合资源受限设备。当前链路主要划分为两个端口：

端口	能力范围
5683	CloudSetup 发现、SPEKE、CloudSetup、设备主动事件
5686	本地控制发现、Session 管理、加密控制

5683 更接近“接入与配置平面”，5686 更接近“认证后的控制平面”。这种端口分工使首次接入和长期控制可以采用不同的安全策略。

4. 设备生命周期

设备状态不是简单的“在线/离线”，而是一个逐步收敛的状态机。

状态不同，允许执行的操作也不同：

状态	允许的主要操作
已发现未入网	BLE 连接、网络配置
已入网未身份化	CoAP 发现、PIN/SPEKE、CloudSetup
已身份化	AuthCode 校验、创建本地控制 Session
本地控制可用	加密命令、事件订阅、状态同步
会话失效	清理旧状态、重新发现和建会话

5. 一次完整控制的数据流

对于已经完成身份配置的设备，一次典型控制过程如下：

其中 DeviceInfo 不只是展示信息，还承担了网络地址、逻辑身份、认证标识和远端 Session 状态之间的关联作用。

6. 架构设计中的关键原则

6.1 发现不等于认证

发现只证明设备能够响应网络请求。只有完成身份校验和 Session 建立后，设备才进入可控状态。

6.2 临时安全通道不等于长期控制会话

PIN/SPEKE 用于首次身份配置，AuthCode Session 用于后续稳定控制。两者的生命周期和安全目标不同。

6.3 设备状态必须能够重新收敛

控制端和设备分别维护状态，设备重启后可能丢失内存 Session。控制端必须依据新的发现结果重新判断，而不能永久相信本地缓存。

6.4 Demo 不是业务架构

测试程序中的固定 PIN、Wi-Fi 参数或认证材料只用于联调。生产系统应由安全存储、用户输入或可信服务提供这些信息。

7. 源码模块映射

能力	主要目录
Native API	interfaces/inner_kits/native_cpp
IPC 服务	services/client、services/service
扫描与控制编排	core/connect_adapter
BLE/CoAP 扫描	core/device_add
设备连接与命令	core/device_mgr
CoAP/SPEKE/DB	core/home_base
Wi-Fi、CoAP、密码、KV 适配	core/adapter

7.1 扫描调用链

设备扫描不是由应用直接调用 BLE 或 CoAP 接口，而是经过统一入口进行协议分发：

统一入口的价值在于，应用可以请求扫描全部协议，但不同协议的回调到达顺序不需要一致。缓存层负责将多来源数据转换成相对稳定的设备视图。

7.2 连接和控制调用链

连接阶段由设备的 scannedProtocol 决定具体管理器：

这里有一个重要约束：应用连接时通常只提交 UDID 和连接参数，服务端会根据 UDID 从扫描缓存中恢复完整设备信息。如果扫描列表与核心缓存使用了不同 UDID，即使界面中能看到设备，连接仍可能报“device info is null”。

7.3 异步回调模型

扫描、连接和命令都不是简单同步函数。接口立即返回通常只说明请求已提交，最终结果需要通过回调或 Observer 获取。

操作	提交结果	最终结果
扫描	StartScanDevice 被接受	OnDeviceDiscovered / OnDeviceDiscoveryFinished
连接	ConnectDevice 请求进入服务	DeviceConnectCallback
命令	SendCommand 返回提交状态	BaseCallback 或 EventObserver
主动事件	SubscribeEvent 注册成功	EventObserver::OnEvent

如果只检查同步返回值，很容易把“进入发送队列”误判为“设备已经执行”。

8. 配置平面与控制平面

从系统设计角度看，5683 和 5686 可以理解为两个逻辑平面：

8.1 配置平面

配置平面负责让设备从不可管理状态进入可管理状态，包含：

• 设备能力发现；
• PIN/SPEKE 临时认证；
• CloudSetup 身份写入；
• 网络和身份状态迁移。

配置平面的操作频率较低，但安全影响较大。身份写入失败时，应保持设备仍处于未身份化状态，避免写入一半的数据。

8.2 控制平面

控制平面面向日常业务，包含：

• 本地控制身份发现；
• Session 创建与复用；
• AES-GCM 加密命令；
• sequence 重放保护；
• 设备主动事件上报。

控制平面的重点是低开销、可恢复和状态一致。设备重启后允许 Session 失效，但必须能够通过重新发现和重新协商恢复。

9. 构建特性与运行能力

组件使用 GN feature 控制协议能力。概念上，Wi-Fi 或 Ethernet 可以启用 CoAP 核心，但当前工程中的 CoAP 扫描、本地接口 IP 获取和事件监听仍依赖 Wi-Fi 适配。因此“编译了 CoAP”与“具备完整 CoAP 运行能力”不能画等号。

系统集成时需要同时验证：

• IOTC_COAP_SUPPORT 是否进入编译；
• third_party/libcoap 是否链接；
• Wi-Fi 服务和 DHCP 是否正常；
• KV 根目录是否可写；
• SAMGR 是否能发布和查询服务；
• Demo 或业务进程是否链接 Native API。

10. 总结

iot_management 的核心不是把几种协议简单组合，而是把设备生命周期拆成发现、入网、身份建立、安全会话和业务控制五个阶段。BLE 负责近场接入，Wi-Fi 提供网络可达性，CoAP 承载局域网配置与控制，SPEKE 和 AuthCode 分别服务于首次身份建立和长期本地控制。

理解这套分层后，很多“已经连上 Wi-Fi 为什么仍不能控制”的问题就有了明确答案：网络只是基础条件，身份和会话才决定设备是否真正可控。