Control smart-home accessories and commission Matter devices using HomeKit and MatterSupport. Use when managing homes/rooms/accessories, creating action sets or triggers, reading accessory characteristics, onboarding Matter devices, or building a third-party smart-home ecosystem app.

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]( setup) [HomeKit Data Model]( homekit data model) [Managing Accessories]( managing accessories) [Reading and Writing Characteristics]( reading and writing characteristics) [Action Sets and Triggers]( action sets and triggers) [Matter Commissioning]( matter commissioning) [MatterAddDeviceExtensionRequestHandler]( matteradddeviceextensionrequesthandler) [Common Mistakes]( common mistakes) [Review Checklist]( review checklist) [References]( references) Setup HomeKit Configuration 1. Enable the HomeKit capability in Xcode (Signing & Capabilities) 2. Add NSHomeKitUsageDescription to Info.plist: MatterSupport Configuration For Matter commissioning into your own ecosystem: 1. Add a MatterSupport Extension target and set its principal class to a MatterAddDeviceExtensionRequestHandler subclass 2. Add NSBonjourServices entries for matter. tcp , matterc. udp , and matterd. udp 3. Add com.apple.developer.matter.allow setup payload only if the caller supplies a Matter setup payload programmatically Framework Boundary Need Framework Homes, rooms, accessories, characteristics, actions, triggers HomeKit Commission Matter into the app ecosystem MatterSupport Select and authorize a nearby Bluetooth or Wi Fi accessory AccessorySetupKit Exchange Bluetooth GATT data after selection CoreBluetooth Join or configure an accessory's Wi Fi network after selection NetworkExtension 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]( 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](references/matter commissioning.md advanced matter extension handler) for credential validation, room selection, configuration, commissioning, and network association overrides. Common Mistakes Mistake Fix Reading homes before the delegate update Create one manager, set its delegate, and wait for homeManagerDidUpdateHomes . HomeKit setup is used for Matter ecosystem commissioning Use MatterAddDeviceRequest plus the configured MatterSupport extension. Matter configuration is incomplete Verify principal handler, Bonjour services, and the setup payload entitlement only when applicable. Multiple HMHomeManager instances load the database Share one retained manager/store. Characteristic write ignores metadata Check permissions, format, min/max/step, and allowed values before writing. Review Checklist [ ] HomeKit capability enabled in Xcode [ ] NSHomeKitUsageDescription present in Info.plist [ ] Single HMHomeManager instance shared across the app [ ] HMHomeManagerDelegate implemented; homes not accessed before homeManagerDidUpdateHomes [ ] HMHomeDelegate set on homes to receive accessory and room changes [ ] HMAccessoryDelegate set 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 NSBonjourServices entries added [ ] com.apple.developer.matter.allow setup payload used only when providing setup codes [ ] MatterAddDeviceRequest.isSupported checked 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](references/matter commissioning.md) [HomeKit framework](https://sosumi.ai/documentation/homekit) [HMHomeManager](https://sosumi.ai/documentation/homekit/hmhomemanager) [HMHome](https://sosumi.ai/documentation/homekit/hmhome) [HMAccessory](https://sosumi.ai/documentation/homekit/hmaccessory) [HMRoom](https://sosumi.ai/documentation/homekit/hmroom) [HMActionSet](https://sosumi.ai/documentation/homekit/hmactionset) [HMTrigger](https://sosumi.ai/documentation/homekit/hmtrigger) [MatterSupport framework](https://sosumi.ai/documentation/mattersupport) [MatterAddDeviceRequest](https://sosumi.ai/documentation/mattersupport/matteradddevicerequest) [MatterAddDeviceExtensionRequestHandler](https://sosumi.ai/documentation/mattersupport/matteradddeviceextensionrequesthandler) [Enabling HomeKit in your app](https://sosumi.ai/documentation/homekit/enabling homekit in your app) [Adding Matter support to your ecosystem](https://sosumi.ai/documentation/mattersupport/adding matter support to your ecosystem)