设备配网 UI 业务包

更新时间:2023-11-17 07:29:04下载pdf

智能生活设备配网 UI 业务包的功能涵盖了目前常见的 Wi-Fi 设备、Zigbee 设备、蓝牙设备,并且支持二维码扫码的设备,例如 GPRS 和 NB-IoT 设备。业务包主要实现不同类型的设备配网前置操作引导,和具体入网激活。

功能概述

Wi-Fi 设备配网

支持 Wi-Fi 智能设备入网连接云服务,Wi-Fi 设备配网主要有快连模式和热点模式两种,其中智能摄像机(IPC)设备支持扫二维码方式配网。

名词 说明
Wi-Fi 快连配网 又称快连模式。大致流程如下:
  1. App 把配网数据包打包到 802.11 数据包的指定区域中,发送到周围环境。
  2. 智能设备的 Wi-Fi 模组处于混杂模式下,监听捕获网络中的所有报文。
  3. Wi-Fi 模组按照约定的协议数据格式,解析出 App 发出配网信息包。
Wi-Fi 热点配网 又称热点模式,手机作为 STA(STAtion)连接智能设备的热点,双方建立一个 Socket 连接,通过约定端口交互数据。
IPC 扫码配网 IPC 设备通过扫描 App 上的二维码,来获取配网数据信息。

Zigbee 设备配网

支持 Zigbee 网关和子设备配网:

名词 说明
Zigbee 网关 融合 Zigbee 网络中协调器和 Wi-Fi 功能的设备,负责 Zigbee 网络的组建及数据信息存储。
Zigbee 子设备 Zigbee 网络中的路由或者终端设备,负责数据转发或者终端控制响应。

蓝牙设备配网

智能生活 App SDK 相关的蓝牙有以下几种技术方案:

名词 说明
蓝牙单点 蓝牙设备与手机一对一连接单点设备(蓝牙或低功耗蓝牙)。
蓝牙 Mesh 蓝牙技术联盟发布的蓝牙拓扑通信,即低功耗蓝牙 Mesh。
涂鸦 Mesh 涂鸦自研的蓝牙拓扑通信,使用场景与蓝牙 Mesh 产品相同。
双模设备 一些多协议设备也会使用到蓝牙技术,例如同时具备 Wi-Fi 能力和蓝牙能力的 双模设备

扫码配网设备

扫码配网设备上电后即连接了涂鸦的云服务,App 通过扫描设备上的二维码让设备在云端激活绑定。这个二维码必须是涂鸦支持的二维码规则,具体接入方式可咨询您的涂鸦客户经理。

名词 说明
GPRS 设备 采用 GPRS 通信技术接入网络连接云服务的智能设备。
NB-IoT 设备 采用窄带物联网(NarrowBand-Internet of Things)技术的智能设备。

自动发现配网

融合涂鸦智能通用配网技术实现,为您提供一套快捷配网的功能。

接入组件

在工程的 Podfile 文件中添加配网业务包组件,并执行 pod update 命令:

source 'https://github.com/tuya/tuya-pod-specs.git'
source 'https://cdn.cocoapods.org/'
platform :ios, '11.0'

target 'your_target_name' do
  # 添加配网业务包
  pod 'ThingSmartActivatorBizBundle'
end

Wi-Fi 设备配网过程需要获取手机当前连接 Wi-Fi 名称,需要项目开启地位权限来获取 Wi-Fi 的名称,在 info.plist 中添加如下权限声明,创建 CLLocationManager 示例,并调用 requestWhenInUseAuthorization 方法。

NSLocationAlwaysAndWhenInUseUsageDescription
NSLocationAlwaysUsageDescription
NSLocationWhenInUseUsageDescription

二维码扫码功能需要系统相机权限,需要在 info.plist 中添加以下声明:

NSCameraUsageDescription

自定义配置

蓝牙配网功能

配网业务包支持 Wi-Fi、蓝牙等类型的设备配网,其中蓝牙配网为可选项。

  • 如果当前 App 不需要蓝牙配网功能,只需要将自定义 thing_custom_config.json 中的 needBle 属性设置为 false 即可。

  • 如果当前 App 需要蓝牙配网功能,首先您需要在项目的 info.plist 文件中添加蓝牙权限的声明,设置 thing_custom_config.json 中的 needBle 属性设置为 true,然后需要在项目中添加以下依赖:

    系统权限

    NSBluetoothAlwaysUsageDescription
    NSBluetoothPeripheralUsageDescription
    

    配置项

    {
        "config": {
            "appId": 123,
            "thingAppKey": "xxxxxxxxxxxx",
            "appScheme": "tuyaSmart",
            "hotspotPrefixs": ["SmartLife"],
            "needBle": true, // 设置为 true 则表示支持蓝牙设备的配网
            "needQRCode": true // 设置为 true 则表示支持扫一扫配网
        },
    "colors":{
            "themeColor": "#FF5A28",
        }
    }
    

    依赖

    pod 'ThingBLEInterfaceImpl'
    pod 'ThingBLEMeshInterfaceImpl'
    pod 'ThingSmartBLEKit'
    pod 'ThingSmartBLEMeshKit'
    

热点名称设置

  • 涂鸦设备热点前缀默认为 SmartLife

  • 若当前设备的热点前缀名称已修改,则需要在 thing_custom_config.json 文件中设置 hotspotPrefixs 属性,设置为当前设备的热点前缀。

    {
        "config": {
            "appId": 123,
            "thingAppKey": "xxxxxxxxxxxx",
            "appScheme": "tuyaSmart",
            "hotspotPrefixs": ["SL"], // 表示修改支持的设备热点前缀为 SL
            "needBle": true
        },
    "colors":{
            "themeColor": "#FF5A28",
        }
    }
    

自发现开关配置

如果需要控制自发现支持设备类型,需要在 thing_custom_config.json 文件中设置 activator_auto_serach_capacity 属性。

```json
{
    "config": {
        "appId": 123,
        "thingAppKey": "xxxxxxxxxxxx",
        "appScheme": "tuyaSmart",
        "hotspotPrefixs": ["SL"], // 表示修改支持的设备热点前缀为 SL
        "needBle": true,           
        "activator_auto_serach_capacity": {
                "searchTypeBle": true,
                "searchTypeEZ": false,
                "searchTypePegasus": true,
                "searchTypeWired": true,
                "searchTypeZigbee": true,
                "searchTypeMatter": true
        },
    },
"colors":{
        "themeColor": "#FF5A28",
    }
}
```

Matter 设备配网

要让设备和 App 支持 Matter 配网,您需要:

  • 添加 iOS 系统权限 matter.allow-setup-payload

  • info.plist 中添加 iOS Bonjour 服务相关配置。

  • 通过设置 thing_custom_config.json 中的 is_matter_support 属性设置为 true,开启 Matter 设备配网功能,否则会保持默认的关闭状态。

  • 在项目中添加 Matter Extension Target,主工程与 Matter Extension Target 需要设置在相同的 App Groups。

    系统权限

    com.apple.developer.matter.allow-setup-payload
    

    info.plist 配置

        <key>NSBonjourServices</key>
         <array>
        <string>_meshcop._udp</string>
        <string>_matterd._udp</string>
        <string>_matter._tcp</string>
        <string>_matterc._udp</string>
         </array>
    

    配置项

    {
        "config": {
            "appId": 123,
            "thingAppKey": "xxxxxxxxxxxx",
            "appScheme": "tuyaSmart",
            "hotspotPrefixs": ["SmartLife"],
            "needBle": true, // 设置为 true 则表示支持蓝牙设备的配网
            "is_matter_support":true,
        },
    "colors":{
            "themeColor": "#FF5A28",
        }
    }
    

    依赖

    
    target 'your_target_name' do
       pod 'ThingSmartMatterInterface'  
    end
    
    target 'MatterExtension' do
       pod 'ThingSmartMatterExtensionKit'
    end
    
    

    Matter Extension 实现如下

    //
    // RequestHandler.swift
    // ThingMatterExtension
    //
    
    import MatterSupport
    import ThingSmartMatterExtensionKit
    
    // The extension is launched in response to `MatterAddDeviceRequest.perform()` and this class is the entry point
    // for the extension operations.
    class RequestHandler: MatterAddDeviceExtensionRequestHandler {
    
        override init() {
            super.init()
            ThingMatterExtensionSupport.shared.setMatterConfigKey(configKey: "your app group")
        }
    
        override func validateDeviceCredential(_ deviceCredential: MatterAddDeviceExtensionRequestHandler.DeviceCredential) async throws {
            ThingMatterExtensionSupport.shared.validateDeviceCredential(deviceCredential)
        }
    
        override func selectWi-FiNetwork(from wifiScanResults: [MatterAddDeviceExtensionRequestHandler.Wi-FiScanResult]) async throws -> MatterAddDeviceExtensionRequestHandler.Wi-FiNetworkAssociation {
            // Use this function to select a Wi-Fi network for the device if your ecosystem has special requirements.
            // Or, return `.defaultSystemNetwork` to use the iOS device's current network.
    //        return .defaultSystemNetwork
    
            return ThingMatterExtensionSupport.shared.selectWi-FiNetwork(from: wifiScanResults)
        }
    
        override func selectThreadNetwork(from threadScanResults: [MatterAddDeviceExtensionRequestHandler.ThreadScanResult]) async throws -> MatterAddDeviceExtensionRequestHandler.ThreadNetworkAssociation {
            // Use this function to select a Thread network for the device if your ecosystem has special requirements.
            // Or, return `.defaultSystemNetwork` to use the default Thread network.
            return ThingMatterExtensionSupport.shared.selectThreadNetwork(from: threadScanResults)
    //        return .defaultSystemNetwork
        }
    
        override func commissionDevice(in home: MatterAddDeviceRequest.Home?, onboardingPayload: String, commissioningID: UUID) async throws {
            // Use this function to commission the device with your Matter stack.
            ThingMatterExtensionSupport.shared.commissionDevice(in: home, onboardingPayload: onboardingPayload, commissioningID: commissioningID)
        }
    
        override func rooms(in home: MatterAddDeviceRequest.Home?) async -> [MatterAddDeviceRequest.Room] {
            // Use this function to return the rooms your ecosystem manages.
            // If your ecosystem manages multiple homes, ensure you are returning rooms that belong to the provided home.
            return [MatterAddDeviceRequest.Room(displayName: "room")]
        }
    
        override func configureDevice(named name: String, in room: MatterAddDeviceRequest.Room?) async {
            // Use this function to configure the (now) commissioned device with the given name and room.
            ThingMatterExtensionSupport.shared.configureDevice(named: name, in: room)
        }
    }
    

服务协议

提供服务

配网业务包实现 ThingActivatorProtocol 协议以提供服务,在 ThingModuleServices 组件中查看 ThingActivatorProtocol.h,协议文件内容为:

#ifndef ThingActivatorProtocol_h
#define ThingActivatorProtocol_h

typedef NS_ENUM(NSUInteger, ThingActivatorCompletionNode) {
    ThingActivatorCompletionNodeNormal
};

@class ThingSmartHome;

@protocol ThingActivatorProtocol <NSObject>

/**
 * Start config
 * Goto device config list view
 */
- (void)gotoCategoryViewController;

/**
 *  Obtain device information after each device connection
 *  @param node completion node, default ThingActivatorCompletionNodeNormal
 *  @param custionJump default false, set true for process not need to jump to de device panel
 */
- (void)activatorCompletion:(ThingActivatorCompletionNode)node customJump:(BOOL)customJump completionBlock:(void (^)(NSArray * _Nullable deviceList))callback;

/**
 *  Open qrcode view
 *  @param userInfo reserved parameter
 */
- (void)gotoQRCodeViewControllerWithUserInfo:(nullable NSDictionary *)userInfo;

@end
#endif /* ThingActivatorProtocol_h */

若您需要自定义配网品类或产品列表返回,则需要实现 ThingActivatorExternalExtensionProtocol 提供的协议方法。

ThingActivatorExternalExtensionProtocol

/**
 *  Back action form category View Controller
 *  Need to implement when additional operations are needed
 */
- (BOOL)categoryViewControllerCustomBackAction;

依赖服务

配网业务包正常运行需要依赖 ThingSmartHomeDataProtocol 这个协议提供的方法,以提供配网所需当前家庭信息。调用业务包之前需要实现该依赖协议。

/**
 获取当前的家庭,当前没有家庭的时候,返回 nil。

 @return ThingSmartHome
 */
- (ThingSmartHome *)getCurrentHome;

使用指南

注意事项

  • 任何接口调用之前,务必确认用户已登录。

  • 调用配网业务包逻辑前,要先实现 ThingSmartHomeDataProtocol 中的协议方法getCurrentHome

    Objective-C 示例

    #import <ThingSmartBizCore/ThingSmartBizCore.h>
    #import <ThingModuleServices/ThingSmartHomeDataProtocol.h>
    
    - (void)initCurrentHome {
        // 注册要实现的协议
        [[ThingSmartBizCore sharedInstance] registerService:@protocol(ThingSmartHomeDataProtocol) withInstance:self];
    }
    
    // 实现对应的协议方法
    - (ThingSmartHome *)getCurrentHome {
        ThingSmartHome *home = [ThingSmartHome homeWithHomeId:@"当前家庭 id"];
        return home;
    }
    

    Swift 示例

    import ThingSmartDeviceKit
    
    class ThingActivatorTest: NSObject,ThingSmartHomeDataProtocol{
    
        func test() {
            ThingSmartBizCore.sharedInstance().registerService(ThingSmartHomeDataProtocol.self, withInstance: self)
        }
    
        func getCurrentHome() -> ThingSmartHome! {
            let home = ThingSmartHome.init(homeId: 111)
            return home
        }
    
    }
    

进入配网

Objective-C 示例

#import <ThingSmartBizCore/ThingSmartBizCore.h>
#import <ThingModuleServices/ThingActivatorProtocol.h>

- (void)gotoDeviceConfig {
    id<ThingActivatorProtocol> impl = [[ThingSmartBizCore sharedInstance] serviceOfProtocol:@protocol(ThingActivatorProtocol)];
    [impl gotoCategoryViewController];

    // 获取配网结果
    [impl activatorCompletion:ThingActivatorCompletionNodeNormal customJump:NO completionBlock:^(NSArray * _Nullable deviceList) {
        NSLog(@"deviceList: %@",deviceList);
    }];
}

Swift 示例

let impl = ThingSmartBizCore.sharedInstance().service(of: ThingActivatorProtocol.self) as? ThingActivatorProtocol
impl?.gotoCategoryViewController()

impl?.activatorCompletion(ThingActivatorCompletionNodeNormal, customJump: false, completionBlock: { (evIdList:[Any]?) in
            print(devIdList ?? [])
        })

返回自定义配网品类

Objective-C 示例

#import <ThingSmartBizCore/ThingSmartBizCore.h>
#import <ThingModuleServices/ThingActivatorExternalExtensionProtocol.h>

- (void)initCurrentHome {
    // 注册要实现的协议
    [[ThingSmartBizCore sharedInstance] registerService:@protocol(ThingActivatorExternalExtensionProtocol) withInstance:self];
}

// 实现对应的协议方法
- (BOOL)categoryViewControllerCustomBackAction {
    [self.navigationController popToRootViewControllerAnimated:YES];
    return YES;
}

Swift 示例

class ThingActivatorTest: NSObject,ThingActivatorExternalExtensionProtocol{

    func test() {
 ThingSmartBizCore.sharedInstance().registerService(ThingActivatorExternalExtensionProtocol.self, withInstance: self)
    }

    func categoryViewControllerCustomBackAction() -> Bool {
        self.navigationController?.popToRootViewController(animated: true)
        return true;
    }

}

扫码功能

Objective-C 示例

#import <ThingSmartBizCore/ThingSmartBizCore.h>
#import <ThingModuleServices/ThingActivatorProtocol.h>

- (void)gotoQRCodeViewController {
    // 注册要实现的协议
      id<ThingActivatorProtocol> impl = [[ThingSmartBizCore sharedInstance] serviceOfProtocol:@protocol(ThingActivatorProtocol)];
      if ([impl respondsToSelector:@selector(gotoQRCodeViewControllerWithUserInfo:)]) {
        [impl gotoQRCodeViewControllerWithUserInfo:nil];
    }
}

Swift 示例

if let impl = ThingSmartBizCore.sharedInstance.service(of: ThingActivatorProtocol.self),
   impl.responds(to: #selector(impl.gotoQRCodeViewController(withUserInfo:))) {
    impl.gotoQRCodeViewController(withUserInfo: nil)
}