HomeKit
Control home automation accessories and commission Matter devices. HomeKit manages the home/room/accessory model, action sets, and triggers. MatterSupport handles device commissioning into your ecosystem.
Contents
- Setup
- HomeKit Data Model
- Managing Accessories
- Reading and Writing Characteristics
- Action Sets and Triggers
- Matter Commissioning
- MatterAddDeviceExtensionRequestHandler
- Common Mistakes
- Review Checklist
- References
Setup
HomeKit Configuration
- Enable the HomeKit capability in Xcode (Signing & Capabilities)
- Add
NSHomeKitUsageDescriptionto Info.plist:
MatterSupport Configuration
For Matter commissioning into your own ecosystem:
- Add a MatterSupport Extension target and set its principal class to a
MatterAddDeviceExtensionRequestHandlersubclass - Add
NSBonjourServicesentries for_matter._tcp,_matterc._udp, and_matterd._udp - Add
com.apple.developer.matter.allow-setup-payloadonly if the caller supplies a Matter setup payload programmatically
Framework Boundary
HomeKit Data Model
HomeKit organizes home automation in a hierarchy:
Initializing the Home Manager
Create a single HMHomeManager and implement the delegate to know when
data is loaded. HomeKit loads asynchronously -- do not access homes until
the delegate fires.
Accessing Rooms
Managing Accessories
Discovering and Adding Accessories
Use the Framework Boundary table before adding an accessory; only HomeKit/MatterSupport work continues in this skill.
Listing Accessories and Services
Moving an Accessory to a Room
Reading and Writing Characteristics
Reading a Value
Writing a Value
Observing Changes
Enable notifications for real-time updates:
Action Sets and Triggers
Creating an Action Set
An HMActionSet groups characteristic writes that execute together:
Executing an Action Set
Creating a Timer Trigger
Creating an Event Trigger
Matter Commissioning
Use MatterAddDeviceRequest to commission a Matter device into your ecosystem.
This is separate from the HMHome home-automation model; it handles the
Matter setup flow and calls into your MatterSupport extension.
Basic Commissioning
When providing a setup code directly, import Matter and pass an
MTRSetupPayload as setupPayload; this is the case that requires the
setup-payload entitlement.
Filtering Devices
Combine criteria with .all([.vendorID(...), .not(.productID(...))]) or use
.any(...) when any one criterion is enough.
MatterAddDeviceExtensionRequestHandler
For full ecosystem support, create a MatterSupport Extension. The extension
handles commissioning callbacks. Override the needed methods, but do not call
super from those overrides.
Load the complete Advanced Matter Extension Handler [blocked]
for credential validation, room selection, configuration, commissioning, and
network-association overrides.
Common Mistakes
Review Checklist
- HomeKit capability enabled in Xcode
-
NSHomeKitUsageDescriptionpresent in Info.plist - Single
HMHomeManagerinstance shared across the app -
HMHomeManagerDelegateimplemented; homes not accessed beforehomeManagerDidUpdateHomes -
HMHomeDelegateset on homes to receive accessory and room changes -
HMAccessoryDelegateset on accessories to receive characteristic updates - Characteristic metadata checked before writing values
- Error handling in all completion handlers
- MatterSupport extension target and principal handler configured
- Matter discovery
NSBonjourServicesentries added -
com.apple.developer.matter.allow-setup-payloadused only when providing setup codes -
MatterAddDeviceRequest.isSupportedchecked before performing requests - Matter extension handler implements
commissionDevice(in:onboardingPayload:commissioningID:) - Action sets tested with the HomeKit Accessory Simulator before shipping
- Triggers enabled after creation (
trigger.enable(true))
References
- Extended patterns (Matter extension, delegate wiring, SwiftUI): references/matter-commissioning.md [blocked]
- HomeKit framework
- HMHomeManager
- HMHome
- HMAccessory
- HMRoom
- HMActionSet
- HMTrigger
- MatterSupport framework
- MatterAddDeviceRequest
- MatterAddDeviceExtensionRequestHandler
- Enabling HomeKit in your app
- Adding Matter support to your ecosystem


