HomeKit Tutorial: Getting Started

HomeKit is a library that allows users to use their Apple devices to configure, monitor and control smart-home devices.

The HomeKit framework allows your apps to set up and control your HomeKit accessories. It provides a central repository for configuring these accessories in your home. Configuration is synchronized across all of your apps and devices, and it’s integrated into iOS, watchOS and tvOS. HomeKit even provides you with a way to control accessories or automation using Siri voice commands.

Before you learn how to control accessories from your app, first take a look at how Apple identifies pieces inside HomeKit.

Getting Started

HomeKit has a well-defined structure to enable developer communications with compatible devices.

At the root, HomeKit defines Homes, with one home being designated as the “primary home.” Every home needs to have a unique name, so when you ask Siri to interact with your home, it can easily identify if you mean your primary residence in the city, or your secondary residence such as a beach house or mountain cabin. Unique names are a fixed requirement across each piece of HomeKit.

There are many aspects to a home that HomeKit considers.

Each home can have one or more rooms, and each room can have one or more accessories. An accessory could be anything from a ceiling fan to a toaster.

Accessories can be equipped with one or more services. Think of services as the capabilities of an accessory. For example, a ceiling fan with lights has two services: One for the fan and one for the light.

Finally, each service can have one or more of its own characteristics. A characteristic is a specific trait or value type associated with that service. Your ceiling fan might have a speed characteristic, for example. The light in the ceiling fan might have two characteristics: One for intensity and another for color.

HomeKit-compatible devices can expose these characteristics, and developers can have granular control over how users interact with them.

In this tutorial, you’ll go over each of these pieces in an app that’ll control the On/Off state of a lightbulb.

Use the Download Materials button at the top or bottom of this tutorial to download the starter project. Open the starter project in Xcode.

Getting the HomeKit Simulator

The easiest way to get the simulator is to follow these steps:

1. Select the LightSwitch project in the Project navigator and click the Capabilities tab.
2. In the list that appears, you should see an option for HomeKit with a toggle button set to Off. Enable it to reveal a button labeled Download HomeKit Simulator.
3. Click the button to open a Browser window, which takes you to your Apple Developer download page.
4. Search for Hardware IO Tools for Xcode 7.3. Once you’ve found it, download it and open it.
5. Copy the HomeKit Accessory Simulator app to your Applications folder.

Now, launch HomeKit Accessory Simulator. In the left pane, you should see an empty list of accessories. Click the + at the bottom of the list and choose New Accessory….

Give the accessory the name Lightbulb; you can leave all the other fields blank. Then, click Finish. The first thing you’ll note is each device is given a unique Setup Code. This code is used to pair and register the device when it’s on your network.

At the moment, your accessory has no service. A sad existence for any accessory, no?

Click the Add Service button at the bottom of the window. In the dialog, click the drop-down selector next to Service. You can see there are a number of predefined categories of services that HomeKit lets you choose from, including a Custom category.

Take a minute to go through them all and, when ready, select Lightbulb. Feel free to give this service a name and click Finish.

You can see the Lightbulb service already comes with some predefined characteristics. You should see On, Brightness, Hue and Saturation as characteristics of the service. For the purposes of this demo, you can remove the last three characteristics and just focus on the On state of the characteristic.

Congratulations, you’ve just created your first HomeKit accessory!

Creating Homes, Sweet Homes

Head back to the starter project.

Because you’re working with a user’s private data, you’ll ask the user permission to read and/or write that data. Open Info.plist, and add a key named Privacy – HomeKit Usage Description and set its value to This app lets you control your lightbulb.

In order to start interacting with HomeKit, first open HomeViewController.swift. Next, add a reference to the HMHomeManager under the comment as shown below. This object will give you access to all things HomeKit.

// 1. Add the homeManager
let homeManager = HMHomeManager()

Once it’s been added, you can access all the homes known to HomeKit by accessing the homes property on the homeManager. Next, add the following inside viewDidLoad() below the comment.

// 2. Add homes from homeManager
addHomes(homeManager.homes)

Since changes to homes can happen on any device synchronized with your account, you’ll add a delegate to homeManager to get notifications of changes to any homes. First, add the following inside init(coder:) below the comment to assign yourself as the delegate object:

// 3. Add HomeViewController as delegate to homeManager
homeManager.delegate = self

Don’t panic about the error this line of code just generated. It’s because HomeViewController doesn’t conform to HMHomeManagerDelegate yet. You’ll fix that by implementing the optional delegate methods. Add the following extension at the bottom of HomeViewController.swift:

// 4. Implement HMHomeManagerDelegate as extension on HomeViewController
extension HomeViewController: HMHomeManagerDelegate {
  func homeManagerDidUpdateHomes(_ manager: HMHomeManager) {
    addHomes(manager.homes)
  }
}

Here’s what this does. First, you conform HomeViewController to HMHomeManagerDelegate. Then, you implement homeManagerDidUpdateHomes(_:) to add all of the homes from HMHomeManager into your homes array by using the helper addHomes(_:).

Not everyone will already have a Home defined in HomeKit, so while you’re here you’ll add the ability to create your own home and give it a Room. Locate newHome(sender:) and add the following code inside below the comment:

// 5. Add new Home + Room

// 1
self.homeManager.addHome(withName: homeName) { [weak self] home, error in
  guard let self = self else {
    return
  }

  // 2
  if let error = error {
    print("Failed to add home: \(error.localizedDescription)")
  }

  // 3
  if let discoveredHome = home {
    discoveredHome.addRoom(withName: roomName) { _, error  in

      // 4
      if let error = error {
        print("Failed to add room: \(error.localizedDescription)")
      } else {
        self.homes.append(discoveredHome)
        self.collectionView?.reloadData()
      }
    }
  }
}

Here’s what this code does:

1. Call addHome(withName:completionHandler:) passing in the name of the home.
2. Verify there was no error while adding the home. If there was an error, simply print it out.
3. If you successfully created an HMHome, add a room to it using the name entered in the dialog.
4. If you successfully added a room, add the newly created home to the homes array and refresh the collection view.

Build and run the app. After granting the necessary permissions, create a new Home and Room.