HomeKit 设备配网

更新时间：2022-03-03 06:44:54下载pdf

TuyaSmartAppleDeviceKit

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

类名	说明
TuyaSmartHomeKitPermissionUtil	提供查询 HomeKit 权限开启状态的功能
TuyaSmartHomeKitUtil	提供查询、管理 HomeKit 本地家庭、设备的功能
TuyaSmartHomeKitConfigUtil	提供服务于 HomeKit 设备的配网功能
TuyaSmartHomeKitDeviceService	提供服务于 HomeKit 设备的云端接口功能
TuyaSmartHomeKitDevice	提供查询、更新设备涂鸦自定义 HomeKit 服务特征的功能

HomeKit 设备具有同时连接涂鸦和苹果生态的能力：

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

查询权限开启状态

接口说明

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

- (void)checkHomeKitPermissionWithCompletionHandler:(TuyaSmartHomeKitPermissionCompletionHandler)completionHandler;

参数说明

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

示例代码

Objc:

self.permissionUtil = [[TuyaSmartHomeKitPermissionUtil 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:TuyaSmartHomeKitPermissionUtil = TuyaSmartHomeKitPermissionUtil()
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(^TuyaSmartHomeKitDataCompletionHandler)(HMHomeManager * _Nullable manager);

- (void)homeKitDataCompletionHandler:(TuyaSmartHomeKitDataCompletionHandler)completionHandler;

参数说明

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

查询家庭

接口说明

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

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

查询设备

接口说明

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

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

参数说明

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

示例代码

Objc:

self.homeKitUtil = [[TuyaSmartHomeKitUtil 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:TuyaSmartHomeKitUtil = TuyaSmartHomeKitUtil()
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 = [[TuyaSmartHomeKitUtil alloc] init];
[self.homeKitUtil addAccessoryToHome:self.home completionHandler:^(NSError * _Nullable error) {
        if (!error) {
            [self reloadDevices];
        }
 }];

Swift:

let homeKitUtil:TuyaSmartHomeKitUtil = TuyaSmartHomeKitUtil()
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` 说明添加成功

示例代码

Objc:

// self.homeKitUtil = [[TuyaSmartHomeKitUtil 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:TuyaSmartHomeKitUtil = TuyaSmartHomeKitUtil()
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 配件对象，可通过 `TuyaSmartHomeKitDevice` 对象查询
home	系统的 HMHome 家庭对象
completion	移除结果回调，`error` 为 `nil` 说明移除成功

示例代码

Objc:

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

Swift:

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

监听家庭变化

接口说明

- (void)homesUpdatedHandler:(TuyaSmartHomeKitHomesUpdatedHandler)updateHandler;

参数说明

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

示例代码

Objc:

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

Swift:

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

绑定到涂鸦

接口说明

- (void)startConfigDevice:(TuyaSmartHomeKitDevice *)device
                  timeout:(NSTimeInterval)timeout
                   homeId:(long long)homeId
                  success:(void (^)(TuyaSmartDeviceModel *deviceModel))success
                  failure:(void (^)(NSError *error))failure;

参数说明

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

示例代码

Objc:

self.configUtil = [[TuyaSmartHomeKitConfigUtil alloc] init];
[self.configUtil startConfigDevice:self.device timeout:120 homeId:homeId success:^(TuyaSmartDeviceModel * _Nonnull deviceModel) {
        // bind success
        [self.device updateWithCompletionHandler:^(NSError * _Nullable error) {
            // update device info
            [self setDeviceInfo];
        }];
        } failure:^(NSError * _Nonnull error) {
        // bind fail
        }];

Swift:

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

停止绑定

接口说明

- (void)stopConfigDevice;

示例代码

Objc:

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

Swift:

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

查询设备产品信息

接口说明

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

参数说明

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

示例代码

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

}];

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

接口说明

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

参数说明

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

示例代码

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

设备信息

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

接口说明

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

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

示例代码

Objc:

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

Swift:

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

属性说明

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

特征说明

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

::info

子设备只有的 productID，子设备的绑定状态跟随桥接网关。
通过 productID characteristic 读取到的产品 ID，来查询设备的名字和图标。
:::