设备配网 (iOS)

更新时间:2024-03-21 10:06:12下载pdf

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

开发设备配网功能之前,请先了解商用照明 App SDK 基本逻辑,并已经使用商用照明 App SDK 完成登录和创建家庭等基本操作。

功能说明

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

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

名词解释

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

名词 说明
Wi-Fi 设备 采用涂鸦 Wi-Fi 模组连接路由器,和 App 以及云端进行数据交互的智能设备。
Wi-Fi 快连配网 又称快连模式。大致流程如下:
  1. App 把配网数据包打包到 802.11 数据包的指定区域中,发送到周围环境。
  2. 智能设备的 Wi-Fi 模组处于混杂模式下,监听捕获网络中的所有报文。
  3. 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

        }