An In-Depth Look at Apple’s HomeKit

I’m actually surprised there is so little additional material on the web regarding Apple’s HomeKit, so I thought I’d collect my notes and experiences with the nascent framework and post them here. If you review the HomeKit Framework Reference you’ll notice a few things. One, it’s a bit light on detail. Little more than a perfunctory introduction and class hierarchy. Second, its immediately apparent (from the class hierarchy) how Apple wants to organize your home(s) and smart controls. The rationale is obvious.; if you’re going to be talking to Siri and asking her to “turn on the lights,” you might want to be able to specify which lights.

If you poke around a little further on the HomeKit portal and iOS 8 pre-release documentation you will also realize that there are no code samples or supplementary documents (other than the WWDC workshop videos) either. Moreover there’s no OS X framework provided for HomeKit, so for the time being you can forget creating an OS X App Extension for your thermostat.

HomeKit Basics

Let’s walk through the basics of HomeKit. First, the terminology.

In HomeKit-speak, a Home can best be thought of as a standalone dwelling. An apartment would be a Home, as would your typical house on Spooner Street. If you had your own personal thermostat or lamp in your office, you might designate it as a Home (your office, not the thermostat or lamp).

With HomeKit you can have multiple homes defined and controlled through your iPhone. I only know a few people with multiple homes (I’m not one of them, but hey, I can dream), but I do know a lot of folks with grandmothers. So in our example we’ll use Grandma’s House to periodically check her thermostat. She’s always raising it to save money, but we want to make sure she stays cool in the summer.

Most homes I know of are comprised of rooms, and sure enough HomeKit provides the concept of a Room. Typical rooms might be the Master Bedroom, Utility Room, Kitchen, Garage, and so on. In HomeKit rooms are dimensionless and have no location, so it’s best to think of a Room as any label you might apply to a general area in or around the house. In our example we have Front Entry and Front Porch as rooms. Of course they aren’t rooms in the strictest sense but if you want to ask Siri to “turn on the front entry lights” she’s going to have to know about the “front entry.”

Finally, Rooms can belong a Zone. An obvious application of a zone would be the Upstairs and Downstairs. “Siri, set the upstairs thermostat to 74 degrees.” The truth is, this is about the only use I can see for zones, and how often do you want to turn on everything upstairs? You could just as easily create a Room called Upstairs and put a thermostat in it.

What you won’t find in the HomeKit Framework documentation are the details about physical accessories and how they are communicated with via iOS. These details are the purview of the HomeKit Accessory Protocol, access to which is restricted to MFi Program members.

HomeKit Accessory Protocol

I’ll take pains to point out now that there are a number of competing Home Automation protocols out there. Z-Wave, ZigBee, Insteon, X10 are just to name a few. Apple is introducing another, the HomeKit Accessory Protocol, or HAP. HAP specifies both the transport mechanism as well as the API for controlling a given accessory.

Two HAP transport mechanisms are currently defined: IP and Bluetooth low energy (BTLE) (also known as Bluetooth Smart). Again, this makes sense. IP, particularly in the form of IP over WiFi, is ubiquitous in most homes that are looking to “get smart.” As for BTLE, well, I’m no expert, but it has been pushed as an alternative to Z-Wave or Zigbee. This makes sense given that all “smartphones” already have Bluetooth radios so you can communicate directly with your device without the need of a hub. Of course, this makes less sense when you consider remote access will still require a hub of some type in your home. Z-Wave and ZigBee aren’t going to be knocked off their perch any time soon, so it remains to be seen whether there will be a significant shift in the transport mechanism for smart devices.

Sitting on top of the transport mechanism is the control API. This is where the rubber meets the road in terms of controlling your accessories. “Siri, turn on the light.” This must get translated into a command sent to the accessory, and there must be a concept of “on” that the accessory understands. “Siri, turn the thermostat to 70 degrees.” Somewhere on the wire is the value 70 (or more likely, 21.1) along with information about whether this is the cooling setpoint or the heating setpoint. Again, HAP provides the protocol and format of how to convey that information.

Services and Characteristics

A HAP accessory need not be something as simple as a lightbulb or even a thermostat. Imagine a ceiling fan (they are popular in Texas) that has both a fan motor and a lightbulb. Although it’s one accessory (“the ceiling fan”) it provides two services: a fan and a light. The fan can be on or off, and likewise, the light can be on or off. But, wait, there’s more. Not only can the light be on or off, but it could dim or bright. Yet another adjustable attribute.

Each of these adjustable attributes are characteristics. Whether or not you can physically adjust the attribute is irrelevant. You can’t adjust how hot the thermostat thinks it actually is, but its an attribute that adjusts. It becomes readily apparent that like HomeKit, HAP has a structured hierarchy. Accessories have services which in turn have characteristics.

Hands On With HomeKit

As I have found little in the way of hands-on examples using HomeKit, I’ve put together this basic walkthrough. Disclaimer: Like you, I’m still learning the nuances of HomeKit and coding with the API. There are likely bugs in the code to be shared, and as you find them I’d love your feedback and comments.

Starting with iOS Beta 1 and XCode 6 Beta 1 Apple began delivering to developers the HomeKit framework and the HomeKit Accessory Simulator since folks couldn’t go down to Home Depot in early June and purchase a HAP-enabled switch. My goal here is to provide a walkthrough of HomeKit using the accessory simulator with an aim at interacting with Siri. To me that’s the selling point of HomeKit. I already own a Z-Wave hub (three of them actually) and thermostat I can control through the web. We’ve been doing that since 2010. What’s new and powerful here is Siri integration, followed by integration with other iDevices.

To follow along at home you are going to need Xcode 6 (preferably the latest beta, which as of this writing was Beta 7) and an iPhone running iOS Beta 5. Download our Home Wizard and start the HomeKit Accessory Simulator (which has moved as of Xcode 6 Beta 6 to the Hardware IO Tools for Xcode).

We’re going to create the following “home control ecosystem”. Our primary home will be named ‘Spooner Street’ and it will have:

• a front entry “room” with a light
• a living room with a ceiling fan, the ceiling fan having an on/off switch and a light
• a thermostat

Our secondary home will be named ‘Grandmas’ and will have:

• a single porch light
• a front entry door with a lock
• a thermostat

Once we’ve created the accessories in the HomeKit Accessory Simulator we will build our ecosystem with our Home Wizard and we should be able to start talking to Siri with some natural language phrases like:

• Lock the door at Grandma’s
• What is the thermostat set to at Spooner Street?
• Turn the living room fan on
• Turn off the front entry light
• Set Grandma’s thermostat to 76 degrees
• Turn on all the living room lights
• How many lights are there?
• Is the front entry light turned on?

And so on.

Okay, let’s get started. Start the HomeKit Accessory Simulator and in the lower left click on the + button to add an accessory. Start with an accessory light by choosing New Accessory and then populate the Name and Manufacturer. We’ll purchase all of our HAP gear from Acme (they’re into everything); the AcmeLight, AcmeThermostat, you get the idea. For the Name type AcmeLight, for the Manufacturer type Acme.

What one notices right away with the simulator is that each accessory can be populated with an array of services. The light itself isn’t the accessory, it’s a service that the accessory provides. So add a Lightbulb service. Click Add Service and Add LightBulb to see:

The ceiling fan will be an AcmeFan, and it will have both a lightbulb service and it’s own intrinsic characteristic of On. To create the AcmeFan go back to the + in the lower-left corner and select New Accessory and give it a name of AcmeFan with a manufacturer of Acme. Rather than adding a service first, notice the Add Characteristic under the Name, Manufacturer, etc. Click it and for the Characteristic Type choose On. You can leave the defaults as is and simply click Finish. Then add a Light Bulb service. Your completed AcmeFan should look something like this:

Finally add a thermostat by adding the accessory AcmeThermostat, then adding the Thermostat service to it.

Once done your HomeKit Accessory Simulator should look something like this:

Now, let’s add Grandma’s accessories. Here’s where you can speed things up by going to Bitbucket and checking out the homekitaccessories repository. You will find .hak files to import into the simulator. Simply download and then in the Homekit Accessory Simulator choose Import Accessory from the File menu. You can import as many lights, thermostats, etc. as you like.

Once everything is configured we can start testing things out to see if Siri understands what we’re talking about.

Using Home Wizard

Disclaimer! Home Wizard is more like Home Wizard’s Apprentice, or Home Wizard’s Chambermaid. The code is very immature but should get you creating a few homes and rooms and putting accessories in them. As HomeKit itself matures we’ll be working on the code to make it more robust, easier to use to manipulate your “ecosystem,” and of course, polish the UI. Again, you can get the code from Bitbucket.

If you have played with HomeKit before, go ahead and go to iOS Settings > Privacy > HomeKit and Reset HomeKit Configuration. This will give us a nice clean slate to work from.

NB: If you haven’t worked with HomeKit before you will need also need to iOS Settings > iCloud > Keychain and enable iCloud Keychain. Failure to do so will result in the annoying Error Domain=HMErrorDomain Code=78 error when trying to add a home.

Build and launch the Home Wizard.

Spooner Street

The first screen you see will have a text dialog under the phrase Home Name. Type in Spooner Street and press Add Home. If adding the home was successful you should see a dialog indicating so. Enter another home named Grandmas. Then press Continue.

The next screen will allow you to create rooms and assign them to a Home. Remember, we’re going to create a front entry and living room for Spooner Street, and since we’re going to add a “house-wide” thermostat we’ll add one called House. So three rooms for Spooner Street: Front Entry, Living Room, and House.

Side Note:HomeKit does provide for accessories to be added to a “house-wide” room, a pointer to which can be obtained by calling HMHomeManager.roomForEntireHome(). For our purposes it was easier to create a “House” room in the UI. Future versions of Home Wizard will have the option to use the roomForEntireHome feature.

Grandma’s House

At Grandma’s we’ll have her front entry, front porch, and a “house” room (for the thermostat).

After you are done adding rooms, press Continue and you will get to the Place your Accessory page. On this page you will see accessories populated in the picker view. If you don’t there may not be any accessories enabled in the HomeKit Accessory Simulator, or if your Wifi isn’t enabled on your iPhone you won’t see them. For IP, accessories actually present themselves as Bonjour services that your iPhone discovers. If you are going to find yourself working a lot with the HomeKit Accessory Simulator, or perhaps are writing your own accessory, you might want to check out the Bonjour Browser application for the Mac. It’s very handy and will show you when accessories come and go in the Bonjour services list, simply look under _hap._tcp.

Note: If you are a member of the MFi Program and have access to the HomeKit Accessory Protocol for IP, the details of the Bonjour TXT records for the accessories is documented there.

Now, let’s add our accessories to the Spooner Street house. If you’ve already added Grandma’s accessories to the simulator you’ll probably notice that there are entries in the accessory list marked with (2). That’s annoying, but if there are two accessories with the same name on the network, they have to be noted as being different somehow. We’ll add the AcmeFan to the Spooner Street Living Room first. Select AcmeFan in the first wheel, and then select Spooner Street on the left and Living Room on the right:

Press Add Accessory. At this point you will get a dialog initiated by iOS requesting the setup code for the AcmeFan. This is the code you see listed in the HomeKit Accessory Simulator. In our case its 721-47-549. The dashes are for show, you don’t actually enter them. If the code is accepted you should see a dialog box indicating that “AcmeFan has been added to Spooner Street Living Room”.

Finish out Spooner Street by adding the thermostat to the House room, and the light to the Front Entry.

Once Spooner Street is complete you can add Grandma’s accessories. I won’t go through the nitty gritty steps here, it should be obvious. Just recall at Grandma’s we’ll add

• a single porch light
• a front entry door with a lock
• a thermostat

Talk to me Siri!

Now that we have our accessories added, let’s start trying to control them through Siri. If your iPhone is connected to power you don’t even have to press the Home button, just say, “Hey Siri.”

Okay, let’s see how she does. We’ll start off with a straightforward question, “How many thermostats are there?” We have two thermostats, one in the house at Spooner Street and one at Grandmas, so we would expect her to say “two”. When asked though she says one. It turns out when you don’t specify which home you are referring to Siri will default to the primary home you have configured. In Home Wizard the first home you add is defaulted to the primary, so, since there is one thermostat in the Spooner Street, she replies “one”. You can ask the questions How many thermostats are there at Spooner Street? and How many thermostats are there at Grandmas? and she responds correctly.

Let’s adjust each thermostat independently. “Hey Siri, set the thermostat to 74 degrees cooling.” Siri responds back “I set the thermostat to 73.9.” Okay, a tenth of degree off is fine. But unfortunately she didn’t turn it to Cool, and moreover, no plain English phrases I tried could get her to change the thermostat mode.

If you are familiar with Z-Wave thermostat command classes you are used to ThermostatMode and ThermostatOperatingState. In the screen shot above the target mode corresponds to Z-Wave’s ThermostatMode where as current mode corresponds to the operating state (that is, what is the HVAC system doing right now? Cooling? Heating? Off?).

For setting the thermostat at Grandma’s, all of the following questions and commands were accepted.

• What’s the thermostat set to at Grandma’s?
• Set Grandma’s thermostat to 74 degrees.
• Set the thermostat at Grandma’s to 74 degrees.
• What’s the temperature at Grandma’s?

Enough with thermostats. From my perspective they are broken with Siri integration. Let’s move on to the fan at Spooner Street. Here we have even less luck. No matter how hard I try I can’t get to the intrinsic “on” characteristic of the fan. For example, Turn the AcmeFan on is met with Hmm… I don’t see any HomeKit accessories. But once you’ve set some up, together we could rule… your home.. Well, Siri is certainly optimistic about the future of home automation.

Update: I was quick to come to the conclusion that there is such as a thing as intrinsic characteristics for an accessory, that is characteristics that weren’t tied to a service. Wrong! There is no such thing!. See below for more details.

What we can do is address the light that is a part of the fan, but only in the context of it being in a certain room. Turn off the fan light results in all lights at Spooner Street being turned off! Sacrebleu! A quick table outlining the results of each command to Siri, and remember, without a specifier, Siri operates on the primary home only:

Even more interesting are questions such as Are the lights on? In my tests Siri only considered the light in the living room. If it was turned on Siri would respond “The light is turned on.”

Finally, let’s take a look at Grandma’s door lock. The door lock accessory responded nicely to my commands, but only if I specified that the lock was at Grandma’s. Failure to specify the location defaulted to the primary home, which in our case is Spooner Street. But all of the following responded correctly:

• “Is Grandma’s door locked?” resulted in “The door lock is unlocked.”
• “Lock Grandma’s door.” resulted in “The door lock is locked.”
• “Unlock Grandma’s door.” resulted in “The door lock is unlocked.”

Siri Conclusions

Most folks don’t have two homes, so they don’t need to worry about being that specific with Siri. However, homes with multiple lights and switches will have challenges. Grouping the lights into rooms or zones will certainly help, but even then I was frequently met with I don’t see any HomeKit accessories. For example, the Front Entry room would have its accessories occasionally “disappear” in the sense Siri wouldn’t recognize the room name. In one case I said, “Is the front entry light on?” and Siri caught “Is the front entryway turtle?” Charming. Perhaps like other Siri encounters you find yourself having to ar-tic-u-late slowly and with em-pha-sis.

Siri seems to have a few canned responses to when it thinks you are talking about an accessory and it can’t find it in the hierarchy. I’ve been met with Hmm… I’m not seeing any HomeKit accessories. But if you set some up, I think I’d enjoy the company. along with But once you’ve set some up, together we could rule… your home. and But I can help you once you’ve set some up.

Notable Bugs and Issues

Before wrapping up I’d thought I’d share some additional learnings I’ve discovered working with HomeKit.

I’ve noticed that if you are on a screen and initiate browsing for accessories (the screen where you place your accessories into homes and rooms) and you add a device to the HomeKit Accessory Simulator, you frequently get duplicate accessory notifications from HomeKit. For example, here’s how to start browsing for accessories:

[objc]
self.accessoryBrowser = HMAccessoryBrowser()
self.accessoryBrowser!.delegate = self
self.accessoryBrowser!.startSearchingForNewAccessories()
[/objc]

That seems simple enough. Declare my view controller as an HMAccessoryBrowserDelegate, set the delegate reference, and start searching for new accessories. The delegate function

[objc]
func accessoryBrowser(
browser: HMAccessoryBrowser!,
didFindNewAccessory accessory: HMAccessory!)
[/objc]

gets called. Unfortunately it gets called, and called, and called when adding a single accessory to the simulator:

No, I didn’t add two AcmeThermostats, so why are they there! They even have separate identifiers. This only seems to happen if the startSearchingForNewAccessories() routine is active when I add an accessory to the simulator, so the workaround is either don’t do that or go back to a previous page.

While the previous issue I consider to be a downright bug, the delay between executing a HomeKit routine and when you can actually make use of the outcome is irritating. Consider the following:

[objc]
func addHome(homeName:String!) {

self.homeManager.addHomeWithName(homeName, {
(home: HMHome?, error: NSError?) -> Void in
if let addHomeError = error {
NSLog("Error: \(addHomeError.localizedDescription)")
} else {
NSLog("Added home: \(home)")
}
})
}
[/objc]

Now, you would think that if the completion handler of addHomeWithName was called you would be able to begin working with the home object. You would be wrong. You must wait until the homeManagerDidUpdateHomes delegate method is called before you can assume that the home is actually available.

This bit me a number of times, and continues to do so. Another example is when presenting, say, a list of homes and you allow the user to delete one of them. This routine looks straightforward enough:

[objc]
alert.addAction(UIAlertAction(title: "OK", style: UIAlertActionStyle.Default, handler: {
(action:UIAlertAction!) -> Void in
let hm = HomeManagerControllerSharedInstanced
let index = indexPath.row
hm.homeManager.removeHome(self.homes[index] as HMHome, completionHandler: { (e:NSError!) -> Void in
NSLog("Home removed")

// Update our data
self.homes = hm.myHomes

// Remove the row
self.homeKitTableView.deleteRowsAtIndexPaths([indexPath as AnyObject], withRowAnimation:UITableViewRowAnimation.Automatic)
self.homeKitTableView.reloadData()
}
)

}))
[/objc]

Our action when trying to delete a table entry that is a home is to ask our HMHomeManager to remove the home, and we provide a completion handler. Again, you would think that once the completion handler was called, our home would be gone, and we can refresh our datasource (self.homes = hm.myHomes), but you would be wrong again. You must wait until the homeManagerDidUpdateHomes delegate function is called. This can make for some, well, interesting code like this:

[objc]
hm.homeManager.removeHome(self.homes[index] as HMHome, completionHandler: { (e:NSError!) -> Void in
NSLog("Home removed")

// Register for a HomesUpdated notification and then delete
NSNotificationCenter.defaultCenter().addObserverForName(kHomesUpdated, object:nil, queue: nil,
usingBlock: { (notification:NSNotification!) -> Void in
// Update our data
self.homes = hm.myHomes

// Remove the row
self.homeKitTableView.deleteRowsAtIndexPaths([indexPath as AnyObject], withRowAnimation:UITableViewRowAnimation.Automatic)
self.homeKitTableView.reloadData()
})

}
)

[/objc]

The obvious question is, “Hey, why all the delay?” We’re just building a simple data structure of has-a relationships between Homes, Rooms, and Accessories, right? Well, yes, conceptually the data structure is simple. But remember when we said that you had to have iCloud Keychain enabled to even work with HomeKit? That’s right. Every action and operation taken to our home ecosystem is being pushed to iCloud. The iOS completion handler feedback is instant: the synchronization with iCloud is far from it. Of course this raises the question as to how to handle this in the UI. If I want to allow you to add Rooms to your newly created Home, but I can’t until I’ve received a notification that the homes have been updated then I need to prevent it somehow or make you wait. Of course that means progress HUDs. Our reworked function to handle removing a home is as follows:

[objc]
var alert = UIAlertController(title: kAppName, message: "Are you sure? Deleting a home will remove all rooms and accessories in that home.", preferredStyle: UIAlertControllerStyle.Alert)
alert.addAction(UIAlertAction(title: "OK", style: UIAlertActionStyle.Default, handler: {
(action:UIAlertAction!) -> Void in
let hm = HomeManagerControllerSharedInstanced
let index = indexPath.row
var hud = JGProgressHUD(style:JGProgressHUDStyle.Dark)
hud.textLabel.text = "Removing Home";
hud.showInView(self.view)
hm.homeManager.removeHome(self.homes[index] as HMHome, completionHandler: { (e:NSError!) -> Void in
// Register for a HomesUpdated notification and then delete
var tmpObserver:AnyObject? = nil
tmpObserver = NSNotificationCenter.defaultCenter().addObserverForName(kHomesUpdated, object:nil, queue: nil,
usingBlock: { (notification:NSNotification!) -> Void in
// Update our data
self.homes = hm.myHomes

// Remove the row
self.homeKitTableView.deleteRowsAtIndexPaths([indexPath as AnyObject], withRowAnimation:UITableViewRowAnimation.Automatic)
self.homeKitTableView.reloadData()

hud.dismiss()

// Remove our temporary observer, otherwise this block will fire
// again when homes are updated
NSNotificationCenter.defaultCenter().removeObserver(tmpObserver!)
})

}
)

}))
[/objc]

Even more troublesome is being in the middle of an action such as adding an accessory and having the HomeKit data change while it is in progress. On numerous occasions I’ve seen callbacks (completion handlers) simply fail to be called if homeManagerDidUpdateHomes is called after you’ve called HMHome.addAccessory(HMAccessory!, ((NSError!) -> Void)!)). It’s not that you get an error, you simply don’t get called at all (likely because the HMHome reference you started with has changed underneath you). At the moment I haven’t found how to get around this issue.

Intrinsic Characteristics

After rereading the documentation, both the HomeKit Framework and HomeKit Accessory Protocol for IP, I’ve come to the conclusion that intrinsic characteristics are not supported. It appears that is supported in the simulator, but that is misleading. Adding a characteristic of on to the accessory only adds an entry in the Accessory Information service. As a “work-around” for our AcmeFan, you could add a Switch service to the accessory, but even this is less than satisfactory.

HomeKit Remote Access

I’m going to save the HomeKit Remote Access topic for another article. It’s already confirmed that the AppleTV will be used to facilitate remote access to HomeKit accessories, and iOS 8 Family Sharing will likely be used to share the HomeKit configuration with other iPhones in the family (how else would it work? It’s doubtful everyone in the house would have to go around pairing their phone with accessories).

Conclusion

I have high hopes for Apple’s HomeKit. To reiterate, there’s already a plethora of home automation solutions on the market. Mi Casa Verde, Wink, HomeSeer are to name but a few, and startups such as Prodea Systems and open source projects like The Thing System continue to pop up all over the landscape. What I see that sets Apple apart is number one, it’s Apple. Number two, the use of Siri for voice control is powerful. It will become even more so when you no longer have to be tethered to your phone but have mic pickups in the house that are listening for your commands. There’s still be a place for a user interface and application extensions (let’s face it, if you are at your Mac its going to be quicker to access the “widgets” pane and adjust the thermostat than it is to start talking to Siri), but voice control will be the future of home automation.
Finally, an AppleTV as a remote access point is also powerful. The device is already in your home, and if it isn’t for $99 you get not only remote access to your accessories, but a beautiful media renderer to boot.

Even with those high hopes I have to come to the conclusion that HomeKit is not ready for prime time, at least in its current iOS 8 Beta 5 incarnation. Completion handlers firing before the HomeKit database is really updated, multiple accessories appearing when there is only one, Siri unable to adjust even the most basic thermostat controls, and oh, yes, remote access through the AppleTV doesn’t work with Siri either (it times out essentially); these are just a few of the issues I’ve encountered. I was hopeful that mid-August would bring an update to iOS 8 that would resolve these issues, but was left disappointed. It remains to be seen whether they will be addressed when iOS goes GA.

PostScript

Are you working with HomeKit or other automation protocols? I’d love to hear from you! I’ve been working on a Z-Wave bridging accessory and if you are a member of the MFi Program would enjoy the opportunity to share experiences. Drop me a line at joe@iachieved.it.