Framework

HomeKit

Communicate with, configure, and control home automation accessories, including complex camera-type accessories.

Overview

HomeKit integrates iOS, tvOS, and watchOS devices with home automation accessories, using a device-independent protocol. HomeKit enables your app to coordinate and control accessories from multiple vendors, presenting a coherent, user-focused interface.

Working with Home Automation Accessories

HomeKit allows your app to perform three major functions:

  1. Discover HomeKit-compatible automation accessories and add them to a persistent, cross-device home configuration database.

  2. Display, edit, and act upon the data in the home configuration database.

  3. Communicate with configured accessories and services to get them to perform actions, such as turning on the lights in the living room.

The home configuration database is available not only to third-party apps, but also to Siri. This allows users to speak commands such as “Siri, turn on the lights in the living room.” A user can configure a home with logical groupings of accessories, services, and commands, and then use Siri to invoke sophisticated operations with simple voice control.

Home Configuration

HomeKit views a home as a collection of home automation accessories. The purpose of having a home configuration is to allow the end user to provide meaningful labels and groupings to the home automation accessories they have purchased and installed. Apps can provide suggestions to help the user create useful labels and groupings, but should not impose their own preferences on the users—the user’s wishes are most important.

The basic data containment hierarchy looks like this:

  • Homes (HMHome) are the top level container, and represent a structure that a user would generally consider to be a single home. Users might have multiple homes that are far apart, such as a primary home and a vacation home. Or they might have two homes that are close together, but that they consider different homes—for example, a main home and a guest cottage on the same property.

  • Rooms (HMRoom) are optional parts of homes, and represent individual rooms in the home. Rooms don’t have any physical characteristics—size, location, etc. They’re simply names that are meaningful to the user, such as “living room” or “kitchen”. Meaningful room names enable commands like, “Siri, turn on the kitchen lights.”

  • Accessories (HMAccessory) are installed into homes and assigned to rooms. These are the actual physical home automation devices, such as a garage door opener. If the user doesn’t configure any rooms, HomeKit assigns accessories to a special default room for the home.

  • Services (HMService) are the actual services provided by an accessory. Accessories have both user-controllable services, like a light, and services that are for their own use, like a firmware update service. HomeKit is most concerned with user-controllable services.

    A single accessory may have more than one user-controllable service. For example, most garage door openers have a service for opening and closing the door, and another service for the light on the garage door opener.

  • Zones (HMZone) are optional groupings of rooms in a home; for example, “upstairs” and “downstairs” would be represented by zones. Zones are completely optional—rooms don’t need to be in a zone. By adding rooms to a zone, the user is able to give commands to Siri such as, “Siri, turn on all of the lights downstairs.”

Topics

Home Setup

Define and configure homes and home users, and set up user permissions for controlling a home.

class HMHome

A home and its accessories.

class HMHomeManager

The manager for a collection of one or more homes.

class HMUser

A person in the home who may have access to control accessories and services in the home.

class HMHomeAccessControl

The access privileges of a user associated with a home.

Home Layout

class HMZone

A collection of rooms that users generally think of as a single area.

class HMRoom

A room in a home.

Home Automation Accessories

Accessory Configuration

Discover and configure nearby home automation accessories. Set up accessory triggers, actions, and events.

Light and Power

Work with natural and artificial light sources. Monitor and control power outlets, switches, and batteries.

Air, Temperature, Humidity, and Water

Monitor and control ventilation, air conditioning, smoke detection, and air quality accessories. Work with water supply and filtration accessories.

Locks, Safety, and Security

Monitor, configure, and use doorbells, garage door openers, and locks. Work with home security systems.

Cameras, Video Cameras, and Sound

Connect with, configure, and use camera-type accessories, including video cameras, and configure and use audio accessories.

Events and Event Triggers

Define and respond to events, such as a user arriving home or a specific time of day, and set up scene automations.

Location Events

Specify events that represent the user's movement among regions.

Time Events

Specify events based on time, significant occurrences, and time durations.

Characteristic Events

Specify events based on the capabilities or characteristics of accessories.

Presence Events

Specify events based on the user's presence in a home.

class HMEventTrigger

A trigger for executing a HomeKit automation scene based on a set of events and optional conditions.

class HMEvent

A nonspecific HomeKit event.

See Also

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software