HomeKit 设备配网

更新时间:2024-06-26 05:52:27下载pdf

智能生活 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 和相关对象,例如 roomaccessory 对象。

当 HomeKit 正在查询那些对象时,home managerprimaryHome 属性是 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,可以查询设备的名字和图标。