HomeKit Developer Guide

Introduction to HomeKit

这篇文档帮助你写涉及HomeKit的app。HomeKit是一个这样的框架，它用来和那些支持Apple的HomeKit Accessory Protocol的家用自动设备进行通信，并且控制这些设备。HomeKit apps使得用户能够发现这些设备和对其进行配置，用户也可以控制这些设备(例如恒温器和照明灯)，将不同的设备分类用Siri进行调控。HomeKit的对象存储在用户ios设备的数据库中，这个数据库通过iCloud与其他的ios设备同步。HomeKit支持远程接入这些设备，支持多个用户设备，也支持多个用户。HomeKit还提供隐私和安全方面的支持。

See Also

下面列出的资源为创造HomeKit的app提供了更多的信息:

• HomeKit User Interface Guidelines 提供了关于为你的app设计用户界面的指导
• App Store Review Guidelines:HomeKit 提供了关于如何加速app上架的建议
• HomeKit Framework Reference 描述了HomeKit框架中的类和方法
• Externerl Accessory Framework Reference 提供了系统自带的UI，这些UI用来发现和配置无线设备而不要求用户离开你的app。
• HomeKit Catalog 演示HomeKit特色的代码
• WWDC 2014:Introducing HomeKit 对HomeKit的介绍
• ios Security 描述了HomeKit如何应对ios上的安全和隐私

Enabling HomeKit

HomeKit是一个只能用于通过苹果商店发布的app的应用服务。HomeKit需要在你的Xcode项目中作额外的配置。你的app必须经过provision和code signing。为了避免code signing，在Xcode的Capabilities面板中启动HomeKit。你不需要在成员中心中编辑直接授权。

Setup

为了能够完成本篇文档的所有步骤，你需要

• 一台至少装有Xcode6的Mac电脑
• 为了能有最好的体验，在你的Mac上装上最新的OS X和Xcode
• 隶属于ios Developer Program
• 可以创建code signing和provisiion
  在你使用HomeKit之前核实你已经完成了这几步。你可以阅读App Distribution Quick Start来了解有关创建team provision profile。
  当你成功的完成了之前的这几步后，在General面板中Team菜单下的错误信息和Fix Issue按钮都消失了。下面是code signing成功创建后General面板的截图。
  
  如果对code signing和provision有问题，阅读App Distribution Guide中的Troubleshooting

Enable HomeKit

要使用HomeKit，你需要启用它。Xcode会增加HomeKit的授权到你的工程中的授权文件和成员中心的App ID。Xcode也会将HomeKit框架加入到你的工程中。HomeKit要求explict App ID。
启用HomeKit很简单，在Capabilities面板中。

Download HomeKit Accessory Simulator

研发你的HomeKit app不意味着你需要马上买相应的设备。你可以使用HomeKit Accessory Simulator来测试你的HomeKit app和模拟的设备之间的通信。HomeKit Accessory Simulator未随着Xcode一起发布。

To download HomeKit Accessory Simulator

1.在Capabilities面板，点击Download HomeKit Accessory Simulator
或者，选择Xcode>Open Developer Tool>More Developer Tools.
2.在浏览器中，搜索”Hardware IO Tools for Xcode”.dmg文件
3.在Finder中，双击~/Downloads中的.dmg文件
4.将HomeKit Accessory Simulator拖到/Application文件夹中
稍后，你会使用HomeKit Accessory Simulator来测试你的app。

Getting the Home Layout

HomeKit允许用户创建home的布局。home(HMHome)代表了包含有相互连接的accessories的居住环境，用户拥有home的数据，用户的任意iOS设备可以访问home的数据。用户也可以和客人共享home。一个home作为主要的home，当你输入的Siri命令中不包含home时，这个主要的home就是默认的home。
每个home可能会有多个房间，每个房间可以有多个accessories。一个room(HMRoom)代表了home中的一个房间。它具有具体的名字，例如”生活室”或者”厨房”，Siri可以用名字来访问。一个accessory(HMAccessory)是实际的房间自动设备，例如打开车库门的启动器。一个service(HMService)是accessory提供的实际服务，例如打开车库门或者关闭车库门。

如果你的app caches home的布局信息，app需要在home布局变化时更新该信息。使用HMHomeManager对象从HomeKit的数据库中捕获HMHome和相关的对象。当用相应的api获取对象后，通过代理的callback来同步你的对象和数据库。

Getting the Home Manager Object

使用home manager即HMHomeManager对象，来访问home，room，accessory，service和其余HomeKit对象。在创建home manager后，设置其代理，以便于当获取对象后得到相应的通知。

    self.homeManager=[[HMHomeManager alloc] init];
    self.homeManager.delegate=self;

当你创建了一个home manager对象后，HomeKit开始取来homes和相关的对象－例如，room和accessory对象－从HomeKit数据库，当HomeKit在获取这些对象的时候，home manager primaryHome的值是nil，而homes property是空的数组。你的app应该应对用户还没有创建home的场景，app不应该表现为HomeKit还在原始的获取对象。当获取操作完成时，HomeKit发送homeManagerDidUpdateHomes:消息给homeManager的代理。

Getting the Primary Home and Collection of Homes

为了得到primary home，使用home manger的primaryHome property

    HMHome *home=self.homeManager.primaryHome;

使用home manager的homes property来获取用户的所有home。

    HMHome *home;
    for(home in self.homeManager.homes){
        ...
    }

Getting the Rooms in a Home

Rooms限定了accessories在一个home中的位置。枚举一个home的所有room，使用home的rooms property

    HMHome *home=self.homeManager.primaryHome;
    HMRoom *room;
    for(room in home.rooms){
        ...
    }

Getting the Accessories in a Room

Accessories属于一个home但是划分在home的room中，如果用户不将accessory划分到一个room，这个accessory将会划分到默认room中，默认room是由roomForEntireHome方法返回。

    HMAccessory *accessory;
    for(accessory in room.accessories){
        ...
    }

如果你显示关于某个accessory的信息或者允许用户控制某个accessory，设置这个accessory的代理并且实现相应的accessory代理方法。

Getting Accessories in a Home

你也可以通过home对象而不是枚举rooms来获得所有的accessories，使用HMHome的accessories方法

Creating Homes and Adding Accessories

HomeKit对象存储在HomeKit数据库中，这个共享的数据库允许多个apps通过HomeKit框架来访问。所有涉及记录的HomeKit方法都是异步执行且具有completion handler参数。如果方法调用成功，你的app应该在completion handler中更新local objects。对HomeKit对象作出变化的app不会收到代理方法，app只会收到completion handler。
观察其它apps改变HomeKit对象，阅读 Observing HomeKit Database Changes。对于异步消息的completion handler可能包含的error codes 阅读HomeKit Constants Reference。

Rules for Naming Objects

HomeKit对象的名称－例如home，room，zone－Siri可以识别。

• 名称必须唯一
• 用户的home的名字属于一个namespace
• home对象和其包含的对象属于另一个namespace
• name只能包含字母，空格，省略号
• name只能以数字或者字母开头
• 空格和省略号在比较中忽略(home1 和home 1是一样的)
• name是分大小写的

Creating Homes

添加Home，使用HomeManager的addHomeWithName:completionHandler: 方法，home name必须唯一，home name Siri可以识别

[self.homeManager addHomeWithName:@"My Home" completionHandler:^(HMHome * home,NSError *error)]{
    if(error!=nil){
    // Failed to add a home
    }else{
    // Successfully added a home
    }
}

在else从句，插入更新app view的code。

Adding a Room to a Home

添加一个room到一个home，使用addRoomWithName:completionHandler:异步方法，room name必须唯一，理由同上，Siri用其识别

    NSString *roomName=@"Living Room";
    [home addRoomWithName:roomName completionHandler:^(HMRoom *room,NSError *error){
    if(error!=nil){
    // Failed to add a home
    }else{
    // Successfully added a home
    }
}];

在else从句，插入更新app view的code。

Discovering Accessories

Accessories封装了accessory的状态所以不能由用户创造。为了允许用户添加新的accessories，使用HMAccessoryBrowser对象来发现还没有和home关联的新accessories。这个HMAccessoryBrowser在后台搜索accessories且使用代理来通知你的app新的accessories。HMAccessoryBrowserDelegate消息只有在startSearchingForNewAccessories方法调用之后且在stopSearchingForNewAccessories方法被调用之前发送到代理处。

To discover accessories in a home

1.添加accessory browser代理协议，在你类接口添加accessory browser property

@interface EditHomeViewController () <HMAccessoryBrowserDelegate>
@property HMAccessoryBrowser *accessoryBrowser;
@end

2.生成accessory browser，设置代理

self.accessoryBrowser = [[HMAccessoryBrowser alloc] init];
self.accessoryBrowser.delegate = self;

3.开始搜索

[self.accessoryBrowser startSearchingForNewAccessories];

4.代理消息实现

- (void)accessoryBrowser:(HMAccessoryBrowser *)browser didFindNewAccessory:(HMAccessory *)accessory {
    // Update the UI per the new accessory; for example, reload a picker view.
    [self.accessoryPicker reloadAllComponents];
}

上面的代码可以由你自己的代码实现，同时实accessoryBrowser:didRemoveNewAccessory方法。
5.停止搜索accessories
如果一个视图控制器在搜索accessories

- (void)viewWillDisappear:(BOOL)animated {
    [self.accessoryBrowser stopSearchingForNewAccessories];
}

Adding Accessories to Homes and Rooms

Accessories属于home，也可以加在home的一个room中。将accessory添加到home可以使用addAccessory:completionHandler:异步方法。将accessory添加到room可以使用
assignAccessory:toRoom:completionHandler: 异步方法。默认的room是由roomForEntireHome方法返回的room。

// Add an accesory to a home and a room
// 1. Get the home and room objects for the completion handlers.
    __block HMHome *home=self.home;
    __block HMRoom *room=roomInHome;
// 2. Add the accessory to the home
[home addAccessory:accessory completionHandler:^(NEError *error){
    if(error){
    // Failed to add accessory to home
    }
    else{
        if(accessory.room!=room){
        // 3. If successfully, add the accessory to the room
        [home assignAccessory:accessory toRoom:room completionHandler:^(NSError *error){
            if(error){
            // Failed to add accessory to room
            }
            }]
        }
    }
}]

Accessories可以有服务，服务具有制造商定义的特性。为了得到accessory的服务和特性对象，阅读Accessory Services and Characteristics

Changing Names of Accessories

调用updateName:completionHandler:方法来改变accessory的name

[accessory updateName:@"Kid's Night Light" completionHandler:^(NSError *error){
    if (error) {
        // Failed to change the name
    } else {
        // Successfully changed the name
    }
}];

Adding Bridges to Homes and Rooms

bridge是一个特殊类型的accessory，它允许你同那些无法和HomeKit直接通信的accessories进行通信。例如，bridge可以是多盏灯的集线器，它们不使用HomeKit Accessory Protocol。添加bridge到home，参照Adding Accessories to Homes and Rooms中提及的步骤。当你添加bridge到home时，bridge”后面”的accessories也添加到了home。home的代理不会收到bridge对应的home:didAddAccessory代理消息，而是收到bridge后面各个accessory对应的home:didAddAccessory:代理消息。
不同的是，当你将bridge添加到room时，bridge后面的accessories不会自动的添加到room中，因为bridge和它的accessories可能位于不同的room

Creating Zones

zone(HMZone)是room的组合，例如，楼上，楼下。rooms可以被添加到一个或者多个zone。

调用addZoneWithName:CompletionHandler:方法来创建一个zone。

__block HMHome *home=self.home;
NSString *zoneName=@"Upstairs";
[home addZoneWithName:zoneName completionHandler:^(HMZone *zone,NSError *error){
    if (error) {
        // Failed to create zone
    } else {
        // Successfully created zone, now add the rooms
    }
}]

调用addRoom:completionHandler异步方法来将一个room添加到一个zone中

__block HMRoom *room=roomInHome;
[zone addRoom:room completionHandler:^(NSError *erro){
    if (error) {
        // Failed to add room to zone
    } else {
        // Successfully added room to zone
    }
}]

Observing HomeKit Database Changes

每一个home都有一个HomeKit的数据库。如下图所示，这个数据库和用户的iOS设备保持同步并且可以授予guest user的设备以访问该数据库的权利。为了向用户显示当前的数据，你的app需要观察数据库的变化。

About HomeKit Delegation Methods

HomeKit使用代理的设计模式来通知你的app有关HomeKit对象的变化。总的来说，如果你的app调用HomeKit带有completion handler参数的方法并且这个方法调用成功，相关的代理消息会被传递到其它运行在该设备或者其它远程iOS的HomeKit apps。apps甚至可以是guest users的apps。如果你的app发动了变化，代理消息不会发送到你的app。因此，将代码添加到completion handler和相关的代理方法来reload data和更新views。如果home的布局变化很大，reload所有关于home的信息。如果是completion handler的情形，更新app前首先check方法是不是成功。HomeKit同样调用代理方法来通知你有关home network的状态变化。
举个例子，如果1相应用户的行为，2你的app调用了addRoomWithName:completionHandler:并且调用成功。3completion handler需要更新home 的views。如果成功，HomeKit5发送home:didAddRoome:消息给其它app中该home的代理。因此你home:didAddRoom方法的实现也应该更新home的views。

apps需要运行在前台才能接收到这些代理信息。当你的app在后台运行的时候，变化不累积，如果有个app成功的往home中添加了一个room，而此时你的app运行在后台。你的app不会收到home:didAddRoom:消息，当你的app回到前台运行时，你的app收到homeManagerDidUpdateHomes:消息，这个消息指示你的app应该reload所有的data。

Observing Changes to the Collection of Homes

为了接收主要home或者home集合变化的代理消息，设置home mamager的代理并实现HMHomeManagerDelegate协议。
所有的apps需要实现homeManagerDidUpdateHomes:方法，当HomeKit完成最初的获取homes操作后会调用该方法。这个方法调用的时候，对于新构建的home manager的primaryHome property是nil，homes property是个空的数组。如果app运行在后台的时候，数据有变化，当app返回到前台的时候，homeManagerDidUpdateHomes:同样会被调用。这个方法应该重载所有跟homes相关的数据。

To observe changes to homes

1.添加home manager代理协议，并且在你的类的接口添加home manager property

@interface AppDelegate () <HMHomeManagerDelegate>
@property (strong, nonatomic) HMHomeManager *homeManager;
@end

2.创建home manager对象 设置其代理

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    self.homeManager = [[HMHomeManager alloc] init];
    self.homeManager.delegate = self;
    return YES;

3实现相应的代理方法 例如，如果多个视图控制器显示有关homes的信息，你可以post通知来更新所有的views

- (void)homeManagerDidUpdateHomes:(HMHomeManager *)manager {
    // Send a notification to the other objects
    [[NSNotificationCenter defaultCenter] postNotificationName:@"UpdateHomesNotification" object:self];
}
- (void)homeManagerDidUpdatePrimaryHome:(HMHomeManager *)manager {
    // Send a notification to the other objects
    [[NSNotificationCenter defaultCenter] postNotificationName:@"UpdatePrimaryHomeNotification" object:self];
}

视图控制器注册观察的通知并且实现相应的action

Observing Changes to Individual Homes

显示某个home的信息的视图控制器应该设置为该home的代理并且当home变化时更新views

To observe changes to a specific home

1.添加home代理协议

@interface HomeViewController () <HMHomeDelegate>
@end

2.设置代理

home.delegate = self;

3.实现HMHomeDelegate协议，例如，实现home:didAddAccessory:,home:didRemoveAccessory方法来更新显示accessories的views。可以用HMAccessory类的room property来得到该accessory所属的home。

Bridge Note:当你将一个bridge添加到home时，bridge后面的accessories自动的添加到home，你会收到对应各个accessory的home:didAddAccessory:消息，但是你的代理不会收到对应bridige的home:didAddAccessory:消息

Observing Changes to Accessories

accessory的状态任何时候都能变化，accessory可能处于无法联络的状态，可能处于关掉的状态。更新用户界面来反应accessory的当前状态，特别是你的app允许用户控制一个accessory。
在下面的步骤中含有你已经从HomeKit database中获取accessory对象的前提，正如 Getting the Accessories in a Room所提及的。

To observe changes to a specific accessory

1.将accessory代理协议添加到你的类接口

@interface AccessoryViewController () <HMAccessoryDelegate>
@end

2.设置代理

accessory.delegate = self;

3实现HMAccessoryDelegate协议，例如实现accessoryDidUpdateReachability:方法来启用或者禁止accessory。

- (void)accessoryDidUpdateReachability:(HMAccessory *)accessory {
    if (accessory.reachable == YES) {
       // Can communicate with the accessory
    } else {
       // The accessory is out of range, turned off, etc
    }
}

如果你显示services的状态和它们的特征，实现下列的代理方法来更新views:
accessoryDidUpdateServices: accessory:service:didupdateValueForCharacteristic: 为了访问accessory的services，阅读Accessing Services and Their Characteristics.

Accessing Services and Characteristics

service(HMService)代表了accessory的一个功能并且封装了该accessory的characteristics(HMCharacteristic)。一个accessory可以有多个services，一个service可以有多个characteristics。例如车库开启accessory可以有light和switch服务。light service可以有关闭开启和亮度的characteristics。用户不创造accessories和它们的services－制造商定义accessory的功能－但是用户可以改变service的characteristics的值。某些characteristics代表的可以读写的物理状态－例如，恒温器的当前温度是只读的，但是目标温度是读写的。苹果预先定义了service和characteristics的名字，这些名字Siri可以识别。

Getting Services and Their Properties

当你获得一个accessory对象后，正如Getting the Accessories in a Room所描述的，你可以获取它的services和characteristics。你也可以从home直接得到其services。
你通过访问HMAccessory的services property来得到accessory的services。

NSArray *services = accessory.services;

也可以通过home来直接获取services，但是需要制定types

// Get all lights and thermostats in a home
NSArray *lightServices = [home servicesWithTypes:[HMServiceTypeLightbulb]];
NSArray *thermostatServices = [home servicesWithTypes:[HMServiceTypeThermostat]];

用name property获取service的name

NSString *name = service.name;

用characteristics来获取service的characteristics

NSArray *characteristics = service.characteristics;

用serviceType来获取service的type

NSString *serviceType = service.serviceType;

苹果定义了Siri能够识别的服务类型

• Door locks
• Garage door openers
• Lights
• Outlets
• Thermostats

Changing Name of Services

可以用updateName:completionHandler:异步方法来改变service的名字。

[service updateName:@"Garage 1 Opener" completionHandler:^(NSError *error) {
    if (error) {
        // Failed to change the name
    } else {
        // Successfully changed the name
    }
}];

Accessing Values of Characteristics

characteristic代表了service的一个参数，可以只读，可以读写，要么只写。它提供了参数可能取值的信息。例如，一个布尔值或者范围。恒温器的温度是只读的，但是目标温度是读写的。
苹果定义的characteristic types Siri可以识别

• Brightness
• Current temperature
• Lock state
• Power state
• Target state
• Target temperature

例如车库门开启器的target state是open或者closed。门锁的target state是已锁或者解锁。当你得到一个HMService对象后，正如Getting Services and Their Properties所描述的，你可以访问service 各个characteritic的取值。由于这些值是从实际的accessory获得的，这些读写的方法都是异步的。

[characteristic readValueWithCompletionHandler:^(NSError *error) {
    if (error == nil) {
       // Successfully read the value
       id value = characteristic.value;
    }
    else {
       // Unable to read the value
    }
}];
[self.characteristic writeValue:@42 withCompletionHandler:^(NSError *error) {
    if (error == nil) {
       // Successfully wrote the value
    }
    else {
       // Unable to write the value
    }
}];

Creating Service Groups

service group(HMServiceGroup)提供了一个控制任意service的简便方法，这些service可以隶属于不同的accessories。例如，当用户离开的时候，控制home的照明灯。

当你获得HMHome对象后，你可以在home中创建一个service group。你可以调用HMHome类的addServiceGroupWithName:completionHandler:方法来创建一个service group。

[self.home addServiceGroupWithName:@"Away Lights" completionHandler:^(HMServiceGroup *serviceGroup, NSError *error) {
    if (error == nil) {
       // Successfully created the service group
    }
    else {
       // Unable to create the service group
    }];

当service添加到service group中，使用HMServiceGroup的addService:completionHandler:方法。一个service可以隶属于多个service group。

[serviceGroup addService:service completionHandler:^(NSError *error) {
    if (error == nil) {
       // Successfully added service to service group
    }
       // Unable to add the service to the service group
    }];

得到home的service groups，可以使用HMHome的servicesGroups property

NSArray *serviceGroups = self.home.serviceGroups;

类似accessories，如果别的apps改变了service groups，会调用代理方法。如果你的app使用service groups，阅读HMHomeDelegate Protocol Reference。

Testing Your HomeKit App

如果你没有现实中的accessories，使用HomeKit Accessory Simulator来仿真home中的accessory。每一个仿真accessory都有带characteristics的services。你的app创建对象和关系，将它们都存储在HomeKit数据库中。建立home的布局，在仿真环境中将accessories添加到home中，将accessories添加到home的room中。然后你的app可以控制这些accessories。将你的app运行在ios Simulator或者真机上来测试HomeKit Accessory Simulator。
HomeKit Accessory Simulator是另外的开发者工具，并没有跟Xcode一起安装，你需要先安装。

Adding Accessories

使用HomeKit Accessory Simulator将accessories添加到仿真的网络中。

To add an accessory to the network

1.在HomeKit Accessory Simulator中，点击左边底部增加的按钮
2.选择Add Accessory
3.添加accessory名字和制造商
4.点击Finish

Adding Services to Accessories

accessory需要有service让你能够从app中控制改accessory。你从预先定义的列表中选择service，并且自定制characteristics.

To add a service to an accessory

1.从HomeKit Accessory Simulator中，选择accessory，该accessory的services出现在detail view中

2.选择Add Service，从弹出的菜单中选择service type，新的service出现在detail view中。HomeKit Accessory Simulator生成该service的常用characteristics，例如，a Light Bulb service的默认characteristic是hue，saturation，brightness，on。有些characteristics是强制的，有些是可选的。例如，on characteristic是强制的，hue，saturation，brightness是可选的。

Adding Characteristics to Services

你可以通过列表向service添加characteristics，或者你可以构造自定制的characteristic。

To add a characteristic to a service

1.在HomeKit Accessory Simulator，点击Add Characteristic
2.从Characteristic Type菜单中，选择type或者custom

3.在fields中添加有关characteristic其它信息，点击Finish

Adding Accessories to a Home in Your App

在HomeKit Accessory Simulator中生成accessory后，运行你的app，将这个new accessory添加到home中。

To pair an accessory with a home

1.在Xcode中，点击运行并且执行会调用addAccessory:completionHandler:方法的代码
2.如果Add HomeKit Accessory对话框出现，点击Add Anyway。

3.在接下来的Add HomeKit Accesory对话框中，输入accessory的setup code并点击Add。