设备配网

智能生活 App SDK 提供了将智能设备配置到路由器或网关的能力。以常见的 Wi-Fi 快连为例，SDK 从云端获取配网 Token，再通过 App 广播配网信息，包括路由 ID、密码和配网 Token。智能设备接收到这些信息后，开始快速激活，并连接到 App 和云端，从而完成设备上云的第一步。

为了简化配网流程，提高代码复用率和开发效率，智能生活 App SDK 还封装和拓展了 设备配网 业务。通过使用该 SDK，您可以大大简化配网流程，并享受丰富的配网状态回调和错误码支持，以帮助您实时监控配网状态和处理异常情况。

功能说明

配网基座提供统一的可并行的搜索服务和激活服务，支持配网能力如下：

• Wi-Fi 快连模式（又称 EZ 模式）
• Wi-Fi 热点模式（又称 AP 模式）
• 智能摄像头扫码配网
• Zigbee 有线网关配网
• Zigbee 子设备配网
• App 扫智能设备二维码配网
  • 直连类设备
  • 蓝牙扫码设备
• 闪电搜索配网
• NB-IoT 设备配网
• 蓝牙设备配网
  • 蓝牙单点配网
  • 蓝牙 Mesh 配网
  • 蓝牙 LE + Wi-Fi 双模配网
  • Beacon 配网
• TuyaLink 设备绑定
• Matter 设备配网
• 复合扫描功能

接入扩展 SDK

组件接入

1. 在 Podfile 文件中添加依赖，如下所示：

   source 'https://github.com/tuya/tuya-pod-specs.git'
   platform :ios, '11.0'
   
   target 'Your_Project_Name' do
       # 从涂鸦开发者平台（https://platform.tuya.com）构建和获取 ThingSmartCryption
       # 购买正式版后，需重新在涂鸦开发者平台构建 SDK 并重新集成
       # ./ 代表将 ios_core_sdk.tar.gz 解压之后所在目录与 podfile 同级
       # 若自定义存放目录，可以修改 path 为自定义目录层级
       pod 'ThingSmartCryption', :path =>'./'
       pod 'ThingSmartHomeKit'
       pod 'ThingSmartBusinessExtensionKit'
   
       # 蓝牙实现层（可裁剪）
       pod 'ThingSmartBusinessExtensionKitBLEExtra'
   
       # Matter
       pod 'ThingSmartBusinessExtensionKitMatterExtra'
   
   end
   

2. 在项目根目录下，执行 pod update 命令。

使用说明

配网提供方法主要在 ThingSmartActivatorActiveProtocol、ThingSmartActivatorSearchProtocol 和 ThingSmartActivatorConfigProtocol 协议中。

初始化方法可在 ThingSmartActivatorConfigProtocol 中查看，提供配网类型的注册和代理的设置。

@protocol ThingSmartActivatorConfigProtocol <NSObject>

@required

/// Start the basic configuration, this method needs to be called after the App starts.
- (void)loadConfig;

/// Initialize network configuration types
/// @param typeList Network configuration types
- (void)registerWithActivatorList:(NSArray<ThingSmartActivatorTypeModel *>*)typeList;

/// Configure delegate object
/// @param delegate Delegate
- (void)setupDelegate:(nullable id)delegate;

/// Remove delegate object
/// @param delegate Delegate
- (void)removeDelegate:(nullable id)delegate;
@end

设备搜索服务可在 ThingSmartActivatorSearchProtocol 中查看，提供统一的可并行的设备搜索服务。

@protocol ThingSmartActivatorSearchProtocol <NSObject>

/// Start searching
/// @param typeList Network configuration types
- (void)startSearch:(NSArray <ThingSmartActivatorTypeModel *>*)typeList;

/// Stop searching
/// @param typeList Network configuration types
/// @param clearCache Whether to clear the cache
- (void)stopSearch:(NSArray <ThingSmartActivatorTypeModel *>*)typeList clearCache:(BOOL)clearCache;

@end

设备激活服务可在 ThingSmartActivatorActiveProtocol 中查看，提供统一的设备激活回调服务。

@protocol ThingSmartActivatorActiveProtocol <NSObject>

/// Activate devices with a single network configuration type
/// @param type Network configuration type
/// @param deviceList Devices to be activated
- (void)startActive:(ThingSmartActivatorTypeModel *)type deviceList:(NSArray<ThingSmartActivatorDeviceModel *>*)deviceList;

/// Stop activating devices
/// @param typeList Array of network configuration types
/// @param clearCache Whether to clear the cache
- (void)stopActive:(NSArray <ThingSmartActivatorTypeModel *>*)typeList clearCache:(BOOL)clearCache;

@end

支持配网方式，可以在 ThingSmartActivatorType 中进行查询。

typedef NS_OPTIONS(NSInteger, ThingSmartActivatorType) {
    ThingSmartActivatorTypeDefault =     0,       // Default
    ThingSmartActivatorTypeWired =       1 << 0, // 有线设备配网（例如有线 Zigbee 网关，有线摄像头）
    ThingSmartActivatorTypeBle =         1 << 1, // 蓝牙单点设备、蓝牙 Wi-Fi 双模设备配网
    ThingSmartActivatorTypeBleMesh =     1 << 2, // 涂鸦 Mesh 配网
    ThingSmartActivatorTypeSigMesh =     1 << 3, // 蓝牙 Mesh 配网
    ThingSmartActivatorTypeSubDevice =   1 << 4, // Zigbee 配网
    ThingSmartActivatorTypeEZSearch =    1 << 5, // Wi-Fi 快连
    ThingSmartActivatorTypeAuto =        1 << 6, // 免密
    ThingSmartActivatorTypeHomeKit =     1 << 7, // HomeKit 配网（后续版本支持）
    ThingSmartActivatorTypeRouter =      1 << 8, // 融合路由配网
    ThingSmartActivatorTypePegasus =     1 << 9, // 闪电配网
    ThingSmartActivatorTypeAP =          1 << 10, // 热点配网
    ThingSmartActivatorTypeQRCode =      1 << 11, // 摄像头扫描二维码配网
    ThingSmartActivatorTypeBroadband =   1 << 12, // 宽带配网
    ThingSmartActivatorTypeMatter =      1 << 13, // Matter 配网
    ThingSmartActivatorTypeNB =          1 << 14, // NB-IoT 配网
    ThingSmartActivatorTypeApDirectly = 1 << 15, // AP 直连配网（局域网可用摄像头，行车记录仪等）
    ThingSmartActivatorTypeThingLink =   1 << 16, // TuyaLink 配网
    ThingSmartActivatorTypeVirtual =     1 << 17, // 虚拟设备配网
    ThingSmartActivatorTypeMQTTDirectly = 1 << 18, // MQTT 直连设备配网 （GPRS/Cat1 等）
    ThingSmartActivatorTypeInstallCode = 1 << 19, // Zigbee install code 配网
    ThingSmartActivatorTypeBeacon =      1 << 20, // Beacon 配网
    ThingSmartActivatorTypeEnd =         1 << 21,
};

版本适配

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 名称。