设备配网 (iOS)

商用照明 App SDK 提供了把智能设备配置上路由器或网关的能力。以常见的 Wi-Fi 快连为例，SDK 从云端获取配网 Token，再经由 App 来广播配网信息（路由 ID、密码和配网 Token）。智能设备接收到后，开始快速激活，同时连接到 App 和云端，开启设备上云的第一步。

功能说明

设备配网支撑的具体能力包括：

• Wi-Fi 设备配网
  • Wi-Fi 快连模式（又称 EZ 模式）
  • 热点模式（又称 AP 模式）
• 有线设备配网
• 子设备配网

名词解释

本文介绍设备配网过程中涉及到的部分名词。有关更多名词的说明，参考 名词解释。

名词	说明
Wi-Fi 设备	采用涂鸦 Wi-Fi 模组连接路由器，和 App 以及云端进行数据交互的智能设备。
Wi-Fi 快连配网	又称快连模式。大致流程如下： App 把配网数据包打包到 802.11 数据包的指定区域中，发送到周围环境。 智能设备的 Wi-Fi 模组处于混杂模式下，监听捕获网络中的所有报文。 Wi-Fi 模组按照约定的协议数据格式，解析出 App 发出配网信息包。
热点配网	又称热点模式，手机作为 STA（Station）连接智能设备的热点，双方建立一个 Socket 连接，通过约定端口交互数据。
有线设备	通过有线网络连接路由器的设备，例如 Zigbee 有线网关、有线摄像头等。
子设备	通过网关，与 App 以及云端数据交互的设备，例如 Zigbee 子设备。
Zigbee	Zigbee 技术是一种近距离、低复杂度、低功耗、低速率、低成本的双向无线通讯技术。 主要用于距离短、功耗低且传输速率不高的各种电子设备之间进行数据传输，以及典型的有周期性数据、间歇性数据和低反应时间数据传输的应用。
Zigbee 网关	融合 Zigbee 网络中协调器和 Wi-Fi 功能的设备，负责 Zigbee 网络的组建及数据信息存储。
Zigbee 子设备	Zigbee 网络中的路由或者终端设备，负责数据转发或者终端控制响应。

功能说明

类名	说明	场景
ThingSmartActivator	提供快连模式、热点模式、有线设备激活、子设备激活等配网能力	需要在主线程中调用该类

版本适配

iOS 14 版本适配

从 iOS 14 版本开始，在设备配网、局域网本地控制时会触发 本地网络 权限弹窗。

• 如果用户单击了允许，App 才能够向本地局域网发送数据。
• 如果用户单击了拒绝，将无法使用相关功能。

目前苹果没有提供任何 API 对此权限进行判断，建议您在相关功能无法正常使用时提示、引导用户检查 系统设置 中的 app设置，确认是否开启了 本地网络 权限。

iOS 13 版本适配

从 iOS 13 版本开始，如果用户没有开启地理位置权限，在已开启 Wi-Fi 权限的前提下，[ThingSmartActivator currentWifiSSID] 将无法获取有效的 Wi-Fi SSID 或 BSSID。在此情况下，iOS 会返回下列默认值：

• SSID：WLAN 或 Wi-Fi，针对中国大陆地区则是 WLAN
• BSSID："00:00:00:00:00:00"

建议您在 Wi-Fi 功能无法正常使用时，进行以下排查：

1. 确认 App 已开启地理位置权限。
2. 如果您通过系统方法获取的 BSSID 为 00:00:00:00:00:00，则可以判断为系统的默认返回。此时，您可以引导用户，例如手动输入 Wi-Fi 名称。

获取手机当前连接 SSID

接口说明

/// Get the SSID of the current Wi-Fi asynchronously.
/// @see ThingSmartActivator::currentWifiSSID
/// @param success Called when the task finishes successfully. ThingSuccessString will be returned.
/// @param failure Called when the task is interrupted by an error.
+ (void)getSSID:(ThingSuccessString)success
        failure:(ThingFailureError)failure;

示例代码

Objective-C：

[ThingSmartActivator getSSID:^(NSString *result) {

    } failure:^(NSError *error) {

    }];

Swift：

ThingSmartActivator.getSSID { (_: String?) in

        } failure: { (Error) in

        }