HomeKit 设备配网

更新时间：2024-06-05 09:06:16下载pdf

Cube App SDK 能让 HomeKit 设备具有同时连接涂鸦和苹果生态的能力。用户通过在苹果家庭（Home）App 中本地添加设备，能实现同时绑定到涂鸦开发者平台。

功能说明

ThingSmartAppleDeviceKit 模块主要包括管理苹果家庭（Home）App 的 HomeKit 数据，和直接将苹果设备连接到涂鸦开发者平台的功能。优点是更加快速地集成苹果 HomeKit 框架，并且可以通过简单的接口绑定涂鸦设备、查询设备信息等。

类名	说明
ThingSmartHomeKitPermissionUtil	查询 HomeKit 权限开启状态
ThingSmartHomeKitUtil	查询、管理 HomeKit 本地家庭和设备
ThingSmartHomeKitConfigUtil	服务于 HomeKit 设备的配网
ThingSmartHomeKitDeviceService	服务于 HomeKit 设备的云端接口
ThingSmartHomeKitDevice	查询、更新设备的涂鸦自定义 HomeKit 服务特征

支持的设备操作：

添加设备：在苹果手机本地关联。
绑定设备：与涂鸦开发者平台关联。
移除设备：在涂鸦 App 或苹果 Home App 中移除设备，只会移除各自的绑定状态。
重置设备：手动重置（一般为插座按键长按或连续开灯 3 次）会移除两端的绑定状态。

查询权限开启状态

接口说明

typedef void(^ThingSmartHomeKitPermissionCompletionHandler)(BOOL granted, HMHomeManager * _Nullable manager);

- (void)checkHomeKitPermissionWithCompletionHandler:(ThingSmartHomeKitPermissionCompletionHandler)completionHandler;

参数说明

参数	说明
completionHandler	结果回调，返回权限开启状态和当前 `homeManager`

示例代码

Objective C：

self.permissionUtil = [[ThingSmartHomeKitPermissionUtil alloc] init];
[self.permissionUtil checkHomeKitPermissionWithCompletionHandler:^(BOOL granted, HMHomeManager * _Nullable manager) {
        if (granted) {
            NSLog(@"HomeKit Permission is on");
        } else {
            NSLog(@"HomeKit Permission is off");
        }
    }];

Swift：

let permissionUtil:ThingSmartHomeKitPermissionUtil = ThingSmartHomeKitPermissionUtil()
permissionUtil.checkHomeKitPermission(completionHandler: { granted, manager in
        if granted {
            print("HomeKit Permission is on")
        } else {
            print("HomeKit Permission is off")
        }
    })

完成加载 HomeKit 数据

接口说明

当您创建一个 home manager 对象时，HomeKit 就开始从 HomeKit 数据库查询这些 homes 和相关对象，例如 room 和 accessory 对象。

当 HomeKit 正在查询那些对象时，home manager 的 primaryHome 属性是 nil，并且 homes 属性是个空数组。您的 App 应该处理用户还没有完成创建 home 的情况，App 也需要等待直到 HomeKit 完成初始化。

typedef void(^ThingSmartHomeKitDataCompletionHandler)(HMHomeManager * _Nullable manager);

- (void)homeKitDataCompletionHandler:(ThingSmartHomeKitDataCompletionHandler)completionHandler;

参数说明

参数	说明
completionHandler	数据加载完成回调

查询家庭

接口说明

/// The primary home in HomeKit.
- (HMHome *)primaryHome;

/// Enumerate all homes in HomeKit.
- (NSArray<HMHome *> *)homes;

查询设备

接口说明

/// Enumerate all Tuya device in HomeKit.
- (NSArray<ThingSmartHomeKitDevice *> *)devices;

/// Enumerate single Home's devices in HomeKit.
- (NSArray<ThingSmartHomeKitDevice *> *)devicesForHome:(HMHome *)home;

参数说明

参数	说明
home	苹果系统的家庭对象

示例代码

Objective C：

self.homeKitUtil = [[ThingSmartHomeKitUtil alloc] init];
[self.homeKitUtil homeKitDataCompletionHandler:^(HMHomeManager * _Nullable manager) {
        // data loaded
  self.primaryHome = [self.homeKitUtil primaryHome];
  self.homes = [self.homeKitUtil homes];
  self.devices = [self.homeKitUtil devices];
  self.devicesForHome = [self.homeKitUtil devicesForHome:currentHome];
 }];

Swift：

let homeKitUtil:ThingSmartHomeKitUtil = ThingSmartHomeKitUtil()
homeKitUtil.homeKitDataCompletionHandler { (manager) in
    // data loaded
    primaryHome = homeKitUtil.primaryHome
    homes = homeKitUtil.homes()
    devices = homeKitUtil.devices()
    devicesForHome = homeKitUtil.devices(forHome: currentHome)
}

添加设备

接口说明

/// Adding accessory to primary home.
- (void)addAccessoryToPrimaryHomeCompletionHandler:(void (^)(NSError * __nullable error))completion;

/// Adding accessory to designated home.
- (void)addAccessoryToHome:(HMHome *)home completionHandler:(void (^)(NSError * __nullable error))completion;

参数说明

参数	说明
completion	设备添加结果回调，error 为 nil 则说明添加成功
home	家庭对象

示例代码

self.homeKitUtil = [[ThingSmartHomeKitUtil alloc] init];
[self.homeKitUtil addAccessoryToHome:self.home completionHandler:^(NSError * _Nullable error) {
        if (!error) {
            [self reloadDevices];
        }
 }];

Swift：

let homeKitUtil:ThingSmartHomeKitUtil = ThingSmartHomeKitUtil()
homeKitUtil.addAccessory(to: home) { (error) in
    if error == nil {
        reloadDevices()
    }
}

添加设备和提供加载完成时机

接口说明

调用苹果系统的添加设备方法无法查询系统 HomeKit 设置控制器的加载完成回调，使用以下方法可解决问题。

/// @param viewControllerDidLoad HomeKit Accessory setup view controller did load.
- (void)addAccessoryToPrimaryHomeWithSetupViewControllerDidLoadHandler:(void (^)(void))viewControllerDidLoad completionHandler:(void (^)(NSError * __nullable error))completion;

/// @param viewControllerDidLoad HomeKit Accessory setup view controller did load.
- (void)addAccessoryToHome:(HMHome *)home setUpViewControllerDidLoadHandler:(void (^)(void))viewControllerDidLoad completionHandler:(void (^)(NSError * __nullable error))completion;

参数说明

参数	说明
viewControllerDidLoad	系统 HomeKit 设置控制器加载完成回调
completion	设备添加结果回调，error 为 nil 则说明添加成功

示例代码

Objective C：

// self.homeKitUtil = [[ThingSmartHomeKitUtil alloc] init];
[self.homeKitUtil addAccessoryToPrimaryHomeWithSetupViewControllerDidLoadHandler:^{
            // do something when setup view controller did load
        } completionHandler:^(NSError * _Nullable error) {
            if (!error) {
                // accessory add successed.
            }
 }];

Swift：

// let homeKitUtil:ThingSmartHomeKitUtil = ThingSmartHomeKitUtil()
homeKitUtil.addAccessoryToPrimaryHome {
        // do something when setup view controller did load
    } completionHandler: { (error) in
        if error == nil {
            // accessory add successed.
        }
    }

移除设备

接口说明

- (void)removeAccessory:(HMAccessory *)accessory fromHome:(HMHome *)home completionHandler:(void (^)(NSError * __nullable error))completion;

参数说明

参数	说明
accessory	系统的 `HMAccessory` 配件对象，可通过 `ThingSmartHomeKitDevice` 对象查询
home	系统的 `HMHome` 家庭对象
completion	移除结果回调，error 为 nil 则说明移除成功

示例代码

Objective C：

// self.homeKitUtil = [[ThingSmartHomeKitUtil alloc] init];
[self.homeKitUtil removeAccessory:device.accessory fromHome:self.home completionHandler:^(NSError * _Nullable error) {
            if (!error) {
                // remove success
            }
        }];

Swift：

// let homeKitUtil:ThingSmartHomeKitUtil = ThingSmartHomeKitUtil()
homeKitUtil.remove(accessory, from: home) { (error) in
        if error == nil {
            // remove success
        }
    }

监听家庭变化

接口说明

- (void)homesUpdatedHandler:(ThingSmartHomeKitHomesUpdatedHandler)updateHandler;

参数说明

参数	说明
updateHandler	系统家庭发送变化回调，例如主家庭变化、添加移除家庭等

示例代码

Objective C：

// self.homeKitUtil = [[ThingSmartHomeKitUtil alloc] init];
[self.homeKitUtil homesUpdatedHandler:^(HMHomeManager * _Nullable manager) {
        self.homes = [self.homeKitUtil homes];
        [self.tableView reloadData];
    }];

Swift：

// let homeKitUtil:ThingSmartHomeKitUtil = ThingSmartHomeKitUtil()
homeKitUtil.homesUpdatedHandler { (manager) in
      homes = homeKitUtil.homes()
      tableView.reloadData()
   }

绑定到涂鸦

接口说明

- (void)startConfigDevice:(ThingSmartHomeKitDevice *)device
                  bleAdv:(NSData *)bleAdv
                  timeout:(NSTimeInterval)timeout
                   homeId:(long long)homeId
                  success:(void (^)(ThingSmartDeviceModel *deviceModel))success
                  failure:(void (^)(NSError *error))failure;

参数说明

参数	说明
device	可绑定的 `ThingSmartHomeKitDevice` 设备对象
timeout	绑定超时时间，一般为 90~120 秒
homeId	要绑定到涂鸦的家庭 ID
success	绑定成功
failure	绑定失败

示例代码

Objective C：

self.configUtil = [[ThingSmartHomeKitConfigWifiUtil alloc] init]; // 蓝牙使用 ThingSmartHomeKitConfigBleUtil 
[self.configUtil startConfigDevice:self.device timeout:120 homeId:homeId success:^(ThingSmartDeviceModel * _Nonnull deviceModel) {
        // bind success
        [self.device updateWithCompletionHandler:^(NSError * _Nullable error) {
            // update device info
            [self setDeviceInfo];
        }];
        } failure:^(NSError * _Nonnull error) {
        // bind fail
        }];

Swift：

let configUtil:ThingSmartHomeKitConfigUtil = ThingSmartHomeKitConfigUtil()
configUtil.startConfigDevice(device, timeout: 120, homeId: 68) { (device) in
        // bind success
        device.update { (error) in
            // update device info
            setDeviceInfo()
        }
    } failure: { (error) in
        // bind fail
    }

停止绑定

接口说明

- (void)stopConfigDevice;

示例代码

Objective C：

// self.configUtil = [[ThingSmartHomeKitConfigWifiUtil alloc] init];
[configUtil stopConfigDevice];

Swift：

// let configUtil:ThingSmartHomeKitConfigUtil = ThingSmartHomeKitConfigUtil()
configUtil.stopConfigDevice()

查询设备产品信息

接口说明

+ (void)requestProductInfoWithProductId:(NSString *)productId
                                   uuid:(NSString *)uuid
                                   success:(void (^)(ThingSmartHomeKitProductInfo *info))success
                                failure:(void(^)(NSError *error))failure;

参数说明

参数	说明
productId	设备产品 ID
uuid	设备唯一 ID
success	成功回调，返回 `ThingSmartHomeKitProductInfo` 信息
failure	失败回调

示例代码

// ThingSmartHomeKitDevice *homekitDevice
NSString *productID = homekitDevice.productID.value;
NSString *uuid = homekitDevice.UUID.value;
[ThingSmartHomeKitDeviceService requestProductInfoWithProductId:productID uuid:uuid success:^(ThingSmartHomeKitProductInfo * _Nonnull info) {
    [cell.imageView sd_setImageWithURL:[NSURL URLWithString:info.iconURL] placeholderImage:[UIImage imageNamed:@"thing_device_empty"]];
} failure:^(NSError * _Nonnull error) {

}];

查询已绑定云设备的 HomeKit 设置代码

接口说明

+ (void)requestDeviceHomeKitSetupCodeWithDeviceId:(NSString *)deviceId
                                          success:(void (^)(ThingSmartHomeKitSetupCodeInfo *info))success
                                          failure:(void(^)(NSError *error))failure;

参数说明

参数	说明
deviceId	已绑定云的设备 ID
success	成功回调，返回 `ThingSmartHomeKitSetupCodeInfo` 信息
failure	失败回调

示例代码

[ThingSmartHomeKitDeviceService requestDeviceHomeKitSetupCodeWithDeviceId:deviceId success:^(ThingSmartHomeKitSetupCodeInfo * _Nonnull info) {
        self.homeKitCodeLabel.text = info.homeKitSetupCode;
        [self.tableView reloadData];
    } failure:^(NSError * _Nonnull error) {
        [self.tableView reloadData];
    }];

设备信息

ThingSmartHomeKitDevice 封装了苹果配件对象的涂鸦设备模型，提供了创建设备、查询设备状态、查询和更新设备涂鸦自定义服务特征的功能。

接口说明

- (instancetype)initWithAccessory:(HMAccessory *)accessory;

参数	说明
accessory	系统的配件对象

示例代码

Objective C：

#pragma mark - HMHomeDelegate
- (void)home:(HMHome *)home didAddAccessory:(HMAccessory *)accessory {
  ThingSmartHomeKitDevice *deviceNew = [[ThingSmartHomeKitDevice alloc] initWithAccessory:accessory];
}

Swift：

func home(_ home: HMHome, didAdd accessory: HMAccessory) {
    let deviceNew = ThingSmartHomeKitDevice(accessory: accessory)
}

属性说明

属性	说明
reachable	设备是否可连接
bridged	设备是否被桥接
isThingDevice	是否为涂鸦设备
accessory	持有的系统配件对象

特征说明

参数	说明
devId	设备 ID，仅已绑定的设备才有
productID	设备的产品 ID
UUID	设备唯一标识
token	配网 Token
active	涂鸦的云端激活（绑定）状态： 0 未激活 1 已激活

子设备只有 productID，子设备的绑定状态跟随桥接网关。

通过 productID 特征（characteristic）读取到的产品 ID，可以查询设备的名字和图标。

上一篇NB-IoT 设备配网

下一篇闪电配网