HomeKit 设备配网

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

功能说明

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

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

支持的设备操作：

• 添加设备：在苹果手机本地关联。
• 绑定设备：与涂鸦 IoT 开发平台关联。
• 移除设备：在涂鸦 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，可以查询设备的名字和图标。