HomeKit

HomeKit lets people securely control connected accessories in their homes using Siri or the Home app on iPhone, iPad, and Apple Watch. In iOS, the Home app also lets users manage and configure accessories. Your iOS, tvOS, or watchOS app can also integrate with HomeKit to provide a custom or branded home automation experience.

An image showing an iPad, an iPhone, and an Apple Watch. Each device's screen shows the Home app with HomeKit scenes and accessories.

HomeKit Terminology

Home automation can be intimidating. To help make it approachable, all HomeKit apps should use a friendly, conversational language that people understand.

Homes

In HomeKit, a home represents a physical home, office, or other location of relevance to the user. People might have multiple homes that are far apart, such as a main home and a vacation home. Or, they may have homes that are close together, but considered separate, such as a main home and a guest cottage.

Primary home

Vacation home

Rooms

A room represents a physical room in a home. Rooms don’t have specific characteristics such as size or location. They’re simply meaningful names, such as Bedroom or Office. Rooms allow accessories to be organized and controlled based on their actual location within a home. Rooms also enable voice commands like “Siri, turn on the bedroom lights.”

Zones

A zone represents a specific area in a home, such as Upstairs or Downstairs. Zones allow rooms, typically in close proximity to one another, to be grouped, organized, and controlled. Zones also enable voice commands like “Siri, turn on all of the lights upstairs.”

Accessories, Services, Characteristics, and Actions

An accessory is a physical, connected HomeKit accessory, like a ceiling fan, light, or camera. People add accessories to rooms in their homes. Accessories communicate with iCloud or a server to receive instructions, respond to those instructions, and provide status updates. This communication takes place directly or through an iOS device such as Apple TV or iPad in the home that is operating as a hub.

A controllable feature of an accessory, such as the light on a connected lamp, is known as a service. Some accessories offer multiple services. For example, a connected garage door might let you individually control both the light and the door, or a connected outlet might let you control the top outlet and the bottom outlet separately. Apps don't actually use the word service. Instead, they use terms that describe the service, such as Kitchen Light and Kitchen Fan.

A characteristic is a controllable attribute of a service. For example, on a ceiling fan, the fan service might have a speed (off, low, medium, high) characteristic and the light service might have a brightness characteristic. Apps don't actually use the word characteristic. Instead, they use terms that describe the service, such as speed and brightness.

An action is the act of changing a characteristic of a service. For example, adjusting the speed of a fan or the brightness of a light. Actions are initiated by users and through automation.

Scenes

A scene is a group of actions for controlling one or more services on one or more accessories. Someone might, for example, create a Movie Time scene that lowers the shades and dims the lights in the living room, or a Good Morning scene that turns on the lights, raises the shades, and starts the coffee maker in the kitchen.

Automations

Automations cause accessories to react to certain situations, such as when your location changes, a particular time of day occurs, another accessory turns on or off, or a sensor detects something. An automation could be used, for example, to turn your house lights on at sunset or when you pull up the driveway.

Provide a Great Experience

Through HomeKit, your app can help people:

  • Set up and manage homes, rooms, zones, and scenes

  • Find, add, remove, and interact with accessories

  • Give trusted family and friends access to control accessories

  • Use Siri to control accessories with voice commands

  • Check the status of accessories

  • Automate common accessory behaviors and settings

Simplify Accessory Setup and Interaction

Make accessory setup quick, intuitive, and automatic whenever possible. Ideally, your app automatically detects new accessories and presents them prominently. Don’t force people to create an account before they can add an accessory.

Prompt users to assign accessories to rooms after setup. After configuring a new accessory, immediately suggest adding the accessory to a room. If a home or room doesn't exist yet, provide a way to create one. If only one room exists, suggest adding the accessory to that room but also provide a way to add another room.

Make sure accessories are easy to identify. Accessories should be recognizable when users interact with them, during the setup process, and when adjusting settings later. If a living room contains multiple lights, for example, provide a way to differentiate each one. In this scenario, you might provide a control that physically flashes a light to identify it and let people give each light’s service a unique name, such as desk lamp or chandelier.

Provide multiple ways to locate accessories. People want to interact with accessories quickly, such as unlocking the door while walking up to the house. Implement ways to filter and search for accessories by name, type, or location in the home. Consider providing a dashboard of favorite accessory services.

Report accessory statuses accurately and help the user resolve problems. If an accessory can’t be reached, don’t assume its status. For instance, if a lock is unreachable, don’t say it’s locked or unlocked based on the last known status. Instead, explain that the lock is currently unreachable, suggest possible reasons why, and offer suggestions for fixing the problem.

Enable Hands-Free Interaction

Voice-driven and automatic interactions make it easy to control accessories.

During setup, teach people the commands Siri understands. Siri makes it easy to perform sophisticated operations with a single statement. Siri automatically recognizes the names of homes, rooms, zones, services, and scenes in HomeKit. When appropriate throughout your app, show examples of phrases that work with Siri, such as “You can say ‘Siri, set the house to movie mode.’ to activate this configuration.”

When there are multiple homes, set a primary home. Siri needs to know which home to target when saying something like “Turn on my living room lights.” If there’s only one home, that home is targeted for all commands. If the person has multiple homes and no primary home is configured, the current home—the one the person is in at the moment—is targeted.

Make the configuration of automations intuitive. HomeKit accessories can be controlled automatically, based on conditional relationships such as time, location, and the behavior of other accessories. For example, the kitchen lights could be set to come on when the garage door opens and it’s after sunset. Setting up conditional relationships like this can be confusing, so make this process as simple as possible. Design clear interfaces and use verbiage that mirrors the way people speak.

Make Your App Approachable

Use friendly, conversational terminology throughout your app. Avoid using acronyms and technical jargon that might cause confusion or frustration. Use standard HomeKit terms (home, room, zone, accessory, automation) to provide a consistent and approachable experience.

Use everyday language when referring to services and characteristics. For services, use terms like Kitchen Light and Kitchen Fan. For characteristics, use terms like brightness and speed.

Correct

Kitchen Light

Incorrect

Kitchen Fan

Incorrect

Fan 2 - Ceiling
Light Service

Incorrect

Fan 2 - Ceiling
Fan Service

Use appropriate controls to let people change characteristics. For example, use a switch to let people toggle a service on and off.

Provide good defaults. Every user's home setup is different. During home configuration, offer generic defaults that are widely applicable. For example, your app might assume that all users have a primary home they want to name Home. Default names should be concise, well-known words or phrases.

Allow customization. Make sure home, room, zone, accessory, service, and automation names are customizable. For example, someone might want to rename a connected outlet or switch to desk lamp if that’s what the outlet or switch controls. Never use company names or model numbers for service names.

Assist with name conflicts. Siri requires that home, room, zone, service, and scene names be unique. When name conflicts arise, explain the problem clearly and offer alternatives that make sense and are easy to remember.

Accessory Considerations

As you design your HomeKit app, consider the user experience of specific accessories.

HomeKit Cameras

HomeKit apps can display still images or streaming video from a connected HomeKit IP camera.

Don't block camera imagery. It's fine to supplement the camera's content with useful features, such as an alert calling attention to potentially interesting activity. However, avoid covering portions of the camera's imagery with other content.

Show a microphone button only if the camera supports bidirectional audio. A microphone button that can't be used is a waste of space and confusing to the user.

Learn More

For developer guidance, see HomeKit Developer Guide and HomeKit. If you’re an MFi licensee, visit the MFi portal for guidance on naming and messaging for accessory packaging.