Framework

HomeKit

Communicate with and control configured accessories in the user’s home. Discover accessories, add them to a persistent database, and edit the database.

Overview

HomeKit allows seamless integration between iOS devices and home automation accessories, by promoting a common protocol and providing a public API for configuring and communicating with accessories. HomeKit enables a single app to coordinate and control a range of accessories from multiple vendors. Multiple accessories can act as a single coherent whole, without requiring vendors to coordinate directly with each other.

Working with Home Accessories

HomeKit allows third-party apps to perform three major functions:

  1. Discover 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 not only available to third-party apps, it’s also available to Siri. This allows users to give commands like “Siri, turn on the lights in the living room.” If a user creates a home configuration with logical groupings of accessories, services, and commands, Siri can make it very easy to accomplish sophisticated operations with 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.”

Symbols

Classes

HMAccessory

An HMAccessory object represents a home automation accessory in the home, such as a garage door opener or a thermostat. Each physical accessory in the home is represented by one and only one accessory object. A single accessory provides one or more services, represented by instances of HMService.

HMAccessoryBrowser

An HMAccessoryBrowser object is a network browser used to discover new accessories.

HMAccessoryCategory

An HMAccessoryCategory object specifies the primary category for a HomeKit accessory.

HMAccessoryProfile
HMAction

HMAction is an abstract base class for actions in HomeKit.

HMActionSet

An HMActionSet object represents a set of actions (instances of HMAction) to be applied as a single set.

HMCameraAudioControlHMCameraControlHMCameraProfileHMCameraSettingsControlHMCameraSnapshotHMCameraSnapshotControlHMCameraSourceHMCameraStreamHMCameraStreamControlHMCameraView
HMCharacteristic

An HMCharacteristic object represents a specific characteristic of a service—for example, if a light is on or off, or what temperature a thermostat is set to.

HMCharacteristicEvent
HMCharacteristicMetadata

An HMCharacteristicMetadata object represents metadata for a characteristic. Characteristic metadata is information that further specifies a characteristic’s value and that may be useful for presentation purposes.

HMCharacteristicWriteAction

An HMCharacteristicWriteAction object is used to represent an action in an action set that writes a value to a characteristic.

HMEvent
HMEventTrigger

An HMEventTrigger object represents a trigger for executing a scene that is based on a set of events and optional conditions.

HMHome

An HMHome object allows you to communicate with and configure the different accessories in a home. Homes are the central organizing object for HomeKit.

HMHomeAccessControl
HMHomeManager

A home manager object manages a collection of one or more homes. Use the home manager to add homes, get the list of homes, and track changes to homes with the home manager’s delegate.

HMLocationEvent
HMRoom

An HMRoom object is used to represent a room in a home. Accessories can be assigned to rooms.

HMService

An HMService object represents a service provided by an accessory.

HMServiceGroup

An HMServiceGroup object represents a collection of accessory services, making it easier to address the services as a single entity. For example, a user might choose to group a set of lights together as “Desk Lamps”, and have another set of lights grouped as “Ceiling Lights”.

HMTimerTrigger

An HMTimerTrigger object represents a trigger based on periodic timers.

HMTrigger

An HMTrigger object represents a trigger event, used to trigger one or more action sets (instances of HMActionSet) when the conditions of the trigger are satisfied.

HMUser

An HMUser object represents a person in the home who may have access to control accessories and services in the home.

HMZone

An HMZone object represents a collection of rooms that the user thinks of as a single area or zone—for example, “Living Room” and “Kitchen” might be grouped into a zone called “Downstairs”. A single room can be in multiple zones—for example, “Kitchen” might be in both “Downstairs” and “Entertainment Area”.

Protocols

HMAccessoryBrowserDelegate

HMAccessoryBrowserDelegate defines the interface for an HMAccessoryBrowser object to notify its delegate of new accessories.

HMAccessoryDelegate

The HMAccessoryDelegate protocol defines the communication method for state updates from accessories to their delegates.

HMCameraSnapshotControlDelegateHMCameraStreamControlDelegate
HMHomeDelegate

The HMHomeDelegate protocol define the communication method for configuration changes to a home and for the state of executing action sets in the home.

HMHomeManagerDelegate

The HMHomeManagerDelegate protocol defines how home manager objects communicate changes to their delegate. Implement this protocol and set your object as the delegate of a HMHomeManager object if you want to track changes to a collection of homes.

Structures

Extended Types

See Also

Related Documentation