ios Other Core APIs Tech tutorial

HomeKit Tutorial: Getting Started

HomeKit Tutorial: Getting Started

Observe: This tutorial is updated for Swift four.2, Xcode 10 and iOS 12.

HomeKit Tutorial: Getting Started

HomeKit is a library that permits customers to make use of their Apple units to configure, monitor and management smart-home units.

The HomeKit framework permits your apps to arrange and management your HomeKit equipment. It offers a central repository for configuring these equipment in your house. Configuration is synchronized throughout all your apps and units, and it’s built-in into iOS, watchOS and tvOS. HomeKit even offers you with a option to management equipment or automation utilizing Siri voice instructions.

Earlier than you discover ways to management equipment out of your app, first check out how Apple identifies items inside HomeKit.

Getting Started

HomeKit has a well-defined construction to allow developer communications with suitable units.

On the root, HomeKit defines Houses, with one residence being designated because the “primary home.” Each residence must have a singular identify, so once you ask Siri to work together with your property, it might simply determine in case you imply your main residence within the metropolis, or your secondary residence comparable to a seashore home or mountain cabin. Distinctive names are a hard and fast requirement throughout each bit of HomeKit.

There are lots of elements to a house that HomeKit considers.

Every residence can have a number of rooms, and every room can have a number of equipment. An adjunct might be something from a ceiling fan to a toaster.

Equipment could be outfitted with a number of providers. Consider providers because the capabilities of an adjunct. For instance, a ceiling fan with lights has two providers: One for the fan and one for the sunshine.

Lastly, every service can have a number of of its personal traits. A attribute is a selected trait or worth sort related to that service. Your ceiling fan may need a velocity attribute, for instance. The sunshine within the ceiling fan may need two traits: One for depth and one other for shade.

HomeKit-compatible units can expose these traits, and builders can have granular management over how customers work together with them.

On this tutorial, you’ll go over every of those items in an app that’ll management the On/Off state of a lightbulb.

Use the Obtain Supplies button on the prime or backside of this tutorial to obtain the starter venture. Open the starter challenge in Xcode.

Notice: You could or might not have a HomeKit system out there to you. On this tutorial, nevertheless, you’ll make use of a simulator offered by Apple to create HomeKit equipment.

Getting the HomeKit Simulator

The simplest method to get the simulator is to comply with these steps:

  1. Choose the LightSwitch undertaking within the Undertaking navigator and click on the Capabilities tab.
  2. Within the record that seems, it is best to see an choice for HomeKit with a toggle button set to Off. Allow it to disclose a button labeled Obtain HomeKit Simulator.
  3. Click on the button to open a Browser window, which takes you to your Apple Developer obtain web page.
  4. Seek for Hardware IO Instruments for Xcode 7.three. When you’ve discovered it, obtain it and open it.
  5. Copy the HomeKit Accent Simulator app to your Purposes folder.

Now, launch HomeKit Accent Simulator. Within the left pane, it is best to see an empty record of equipment. Click on the + on the backside of the listing and select New Accent….

HomeKit Simulator

Give the accent the identify Lightbulb; you possibly can depart all the opposite fields clean. Then, click on End. The very first thing you’ll notice is every system is given a singular Setup Code. This code is used to pair and register the system when it’s in your community.

In the meanwhile, your accent has no service. A tragic existence for any accent, no?

Click on the Add Service button on the backside of the window. Within the dialog, click on the drop-down selector subsequent to Service. You’ll be able to see there are a selection of predefined classes of providers that HomeKit permits you to select from, together with a Customized class.

Take a minute to undergo all of them and, when prepared, choose Lightbulb. Be happy to provide this service a reputation and click on End.

HomeKit Simulator configuring a lightbulb

You possibly can see the Lightbulb service already comes with some predefined traits. You need to see On, Brightness, Hue and Saturation as traits of the service. For the needs of this demo, you possibly can take away the final three traits and simply concentrate on the On state of the attribute.

HomeKit Simulator displaying a configured lightbulb

Congratulations, you’ve simply created your first HomeKit accent!

Creating Houses, Candy Houses

Head again to the starter venture.

Since you’re working with a consumer’s personal knowledge, you’ll ask the consumer permission to learn and/or write that knowledge. Open Information.plist, and add a key named Privateness – HomeKit Utilization Description and set its worth to This app permits you to management your lightbulb.

With a view to begin interacting with HomeKit, first open HomeViewController.swift. Subsequent, add a reference to the HMHomeManager underneath the remark as proven under. This object will provide you with entry to all issues HomeKit.

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

As soon as it’s been added, you’ll be able to entry all of the houses recognized to HomeKit by accessing the houses property on the homeManager. Subsequent, add the next inside viewDidLoad() under the remark.

// 2. Add houses from homeManager

Since modifications to houses can occur on any gadget synchronized together with your account, you’ll add a delegate to homeManager to get notifications of modifications to any houses. First, add the next inside init(coder:) under the remark to assign your self because the delegate object:

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

Don’t panic concerning the error this line of code simply generated. It’s as a result of HomeViewController doesn’t conform to HMHomeManagerDelegate but. You’ll repair that by implementing the optionally available delegate strategies. Add the next extension on the backside of HomeViewController.swift:

// four. Implement HMHomeManagerDelegate as extension on HomeViewController
extension HomeViewController: HMHomeManagerDelegate
func homeManagerDidUpdateHomes(_ supervisor: HMHomeManager)

Right here’s what this does. First, you conform HomeViewController to HMHomeManagerDelegate. Then, you implement homeManagerDidUpdateHomes(_:) so as to add all the houses from HMHomeManager into your houses array through the use of the helper addHomes(_:).

Not everybody will have already got a House outlined in HomeKit, so when you’re right here you’ll add the power to create your personal residence and provides it a Room. Find newHome(sender:) and add the next code inside under the remark:

// 5. Add new Residence + Room

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

// 2
if let error = error
print(“Failed to add home: (error.localizedDescription)”)

// three
if let discoveredHome = house
discoveredHome.addRoom(withName: roomName) _, error in

// four
if let error = error
print(“Failed to add room: (error.localizedDescription)”)

Right here’s what this code does:

  1. Name addHome(withName:completionHandler:) passing within the identify of the house.
  2. Confirm there was no error whereas including the house. If there was an error, merely print it out.
  3. When you efficiently created an HMHome, add a room to it utilizing the identify entered within the dialog.
  4. Should you efficiently added a room, add the newly created house to the houses array and refresh the gathering view.

Construct and run the app. After granting the required permissions, create a brand new House and Room.

Including Equipment

Including equipment is a bit totally different from the best way you added houses. Equipment have to be found earlier than they are often added to a given House and Room. In order that’s what you’re going to do subsequent: Dealing with accent discovery.

First, open AccessoryViewController.swift and add the next properties to the category declaration on the prime:

// 1. For locating new equipment
let browser = HMAccessoryBrowser()
var discoveredAccessories: [HMAccessory] = []

Right here, you added an occasion of HMAccessoryBrowser as a property to the category to assist uncover equipment, together with an array of HMAccessory objects, which you’ll use to maintain monitor of all the found equipment.

The AccessoryViewController has a button on the top-right you’ll be able to faucet to start out the invention of latest equipment. This button calls again to discoverAccessories(sender:) in your code. Add the next inside discoverAccessories(sender:):

// 2. Begin discovery
browser.delegate = self
carry out(#selector(stopDiscoveringAccessories), with: nil, afterDelay: 10)

Right here, you reset the record of found equipment and assign AccessoryViewController as a delegate to the HMAccessoryBrowser. Subsequent, you might have the browser begin the invention and set a timer to cease looking after 10 seconds.

Now, keep in mind, as a delegate of HMAccessoryBrowser, you’re required to evolve to HMAccessoryBrowserDelegate so HomeKit can notify your app when it discovers a brand new accent in the course of the search. Repair this concern by including the next extension to the underside of AccessoryViewController.swift:

// three. Have AccessoryViewController implement HMAccessoryBrowserDelegate
extension AccessoryViewController: HMAccessoryBrowserDelegate
func accessoryBrowser(_ browser: HMAccessoryBrowser, didFindNewAccessory accent: HMAccessory)

On this app, you’ll simply document when a brand new accent has been discovered, and also you’ll analyze the outcomes after the timer completes.

After 10 seconds, the timer will name stopDiscoveringAccessories(). That is your probability to see if any equipment have been found. Add the next code inside stopDiscoveringAccessories() proper earlier than the closing bracket:

// four. Cease discovering
if discoveredAccessories.isEmpty
let alert = UIAlertController(
title: “No Accessories Found”,
message: “No Accessories were found. Make sure your accessory is nearby and on the same network.”,
preferredStyle: .alert)
alert.addAction(UIAlertAction(title: “Dismiss”, fashion: .default))
current(alert, animated: true)
let homeName = residence?.identify
let message = “””
Discovered a complete of (discoveredAccessories.rely) equipment.
Add them to your own home (homeName ?? “”)?

let alert = UIAlertController(
title: “Accessories Found”,
message: message,
preferredStyle: .alert)
alert.addAction(UIAlertAction(title: “Cancel”, type: .default))
alert.addAction(UIAlertAction(title: “OK”, fashion: .default) _ in
current(alert, animated: true)

On this code, you first examine if the listing of found equipment is empty. Whether it is, then you definitely let the consumer know that no equipment have been discovered. In any other case, you notify the consumer what number of equipment you need to add to their house and immediate for affirmation. Discover the way you name addAccessories(_:) with the found equipment as a part of the OK button motion name.

Notice: You’ll simply add the accent to the house. Usually you’d need to add it to a sure HMRoom for higher administration, however within the curiosity of time, you’ll simply add it to the house.

So now that you simply’ve added equipment to the Residence, it’s essential to add the power to regulate the On/Off state of the lightbulb.

Begin by displaying all recognized equipment. In loadAccessories(), add the next code earlier than the decision to reload the info:

// 5. Load equipment
guard let homeAccessories = residence?.equipment else

for accent in homeAccessories
if let attribute = HMServiceTypeLightbulb,
characteristicType: HMCharacteristicMetadataFormatBool)
accent.delegate = self
attribute.enableNotification(true) error in
if error != nil
print(“Something went wrong when enabling notification for a characteristic.”)

Right here’s what you’re doing on this code:

  • First you type by means of all of a house’s equipment to attempt to discover an adjunct with a service that matches the HMServiceTypeLightbulb sort and has a Boolean (on/off) attribute format.
  • Within the case you discovered one, you append it to the listing of equipment, set AccessoryViewController because the delegate for the accent and allow notification on that attribute. That method, you’ll obtain a callback when the worth of the attribute modifications.

Subsequent, add the next extension on the backside of AccessoryViewController to implement the HMAccessoryDelegate protocol:

// 6. Have AccessoryViewController implement HMAccessoryDelegate to detect modifications in accent
extension AccessoryViewController: HMAccessoryDelegate
func accent(_ accent: HMAccessory, service: HMService,
didUpdateValueFor attribute: HMCharacteristic)

Right here, you reload all the knowledge on the Assortment view to mirror the brand new modifications.

Lastly, in collectionView(_:didSelectItemAt:), you need to toggle the worth of the On/Off state within the lightbulb. The simplest means to do that is to make use of the asynchronous technique writeValue(_:completionHandler:) on the attribute whose worth must be modified. Find collectionView(_:didSelectItemAt:) and add the next code proper earlier than the closing bracket:

// 7. Deal with touches which toggle the state of the lightbulb
let accent = equipment[indexPath.row]
let attribute = HMServiceTypeLightbulb,
characteristicType: HMCharacteristicMetadataFormatBool) else

let toggleState = (attribute.worth as! Bool) ? false : true
attribute.writeValue(NSNumber(worth: toggleState)) error in
if error != nil
print(“Something went wrong when attempting to update the service characteristic.”)


On this code, you ensure that the merchandise is a lightbulb and has a Bool knowledge format. You then toggle its state and reload all the info on the Assortment view.

Construct and run the app. Faucet on the Residence you added, then choose the magnifying glass button. This can begin looking for any equipment on the community.

It can discover the accent you created earlier; go forward and full the setup course of for this.

Toggling the LightBulb accent On/Off will even toggle the standing contained in the HomeKit simulator. Give it a attempt!

And that’s it!

The place to Go From Right here?

You’ll be able to obtain the finished model of the venture utilizing the Obtain Supplies button on the prime or backside of this tutorial.

HomeKit is a superb library that will help you work together with all of your HomeKit enabled units. Though you didn’t cowl it on this tutorial, HomeKit provides you the power to arrange scenes and automation, that are teams of actions that have an effect on the equipment in your sensible house.

HomeKit additionally permits you to create motion triggers based mostly on calendar values or geolocation. You’ll be able to view the 2017 WWDC video, “What’s New in Homekit”, displaying the easiest of HomeKit.

I hope you loved this HomeKit tutorial and really feel empowered to start out constructing HomeKit into your personal apps! Please be a part of the dialogue under about how one can make the most of the HomeKit framework.

Obtain Supplies

(perform(d, s, id)
var js, fjs = d.getElementsByTagName(s)[0];
if (d.getElementById(id)) return;
js = d.createElement(s); = id;
js.src = “//”;
fjs.parentNode.insertBefore(js, fjs);
(doc, ‘script’, ‘facebook-jssdk’));