HomeKit + MatterSupport

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. Targets Swift 6.2 / iOS 26+.

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 NSHomeKitUsageDescription to Info.plist:

<key>NSHomeKitUsageDescription</key> <string>This app controls your smart home accessories.</string>

MatterSupport Configuration

For Matter commissioning into your own ecosystem:

• Enable the MatterSupport capability

• Add a MatterSupport Extension target to your project

• Add the com.apple.developer.matter.allow-setup-payload entitlement if your app provides the setup code directly

Availability Check

import HomeKit

let homeManager = HMHomeManager()

// HomeKit is available on iPhone, iPad, Apple TV, Apple Watch, Mac, and Vision Pro. // Authorization is handled through the delegate: homeManager.delegate = self

HomeKit Data Model

HomeKit organizes home automation in a hierarchy:

HMHomeManager -> HMHome (one or more) -> HMRoom (rooms in the home) -> HMAccessory (devices in a room) -> HMService (functions: light, thermostat, etc.) -> HMCharacteristic (readable/writable values) -> HMZone (groups of rooms) -> HMActionSet (grouped actions) -> HMTrigger (time or event-based triggers)

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.

import HomeKit

final class HomeStore: NSObject, HMHomeManagerDelegate { let homeManager = HMHomeManager()

override init() {
    super.init()
    homeManager.delegate = self
}

func homeManagerDidUpdateHomes(_ manager: HMHomeManager) {
    // Safe to access manager.homes now
    let homes = manager.homes
    let primaryHome = manager.primaryHome
    print("Loaded \(homes.count) homes")
}

func homeManager(
    _ manager: HMHomeManager,
    didUpdate status: HMHomeManagerAuthorizationStatus
) {
    if status.contains(.authorized) {
        print("HomeKit access granted")
    }
}

}

Accessing Rooms

guard let home = homeManager.primaryHome else { return }

let rooms = home.rooms let kitchen = rooms.first { $0.name == "Kitchen" }

// Room for accessories not assigned to a specific room let defaultRoom = home.roomForEntireHome()

Managing Accessories

Discovering and Adding Accessories

// System UI for accessory discovery home.addAndSetupAccessories { error in if let error { print("Setup failed: (error)") } }

Listing Accessories and Services

for accessory in home.accessories { print("(accessory.name) in (accessory.room?.name ?? "unassigned")")

for service in accessory.services {
    print("  Service: \(service.serviceType)")

    for characteristic in service.characteristics {
        print("    \(characteristic.characteristicType): \(characteristic.value ?? "nil")")
    }
}

}

Moving an Accessory to a Room

guard let accessory = home.accessories.first, let bedroom = home.rooms.first(where: { $0.name == "Bedroom" }) else { return }

home.assignAccessory(accessory, to: bedroom) { error in if let error { print("Failed to move accessory: (error)") } }

Reading and Writing Characteristics

Reading a Value

let characteristic: HMCharacteristic = // obtained from a service

characteristic.readValue { error in guard error == nil else { return } if let value = characteristic.value as? Bool { print("Power state: (value)") } }

Writing a Value

// Turn on a light characteristic.writeValue(true) { error in if let error { print("Write failed: (error)") } }

Observing Changes

Enable notifications for real-time updates:

characteristic.enableNotification(true) { error in guard error == nil else { return } }

// In HMAccessoryDelegate: func accessory( _ accessory: HMAccessory, service: HMService, didUpdateValueFor characteristic: HMCharacteristic ) { print("Updated: (characteristic.value ?? "nil")") }

Action Sets and Triggers

Creating an Action Set

An HMActionSet groups characteristic writes that execute together:

home.addActionSet(withName: "Good Night") { actionSet, error in guard let actionSet, error == nil else { return }

// Turn off living room light
let lightChar = livingRoomLight.powerCharacteristic
let action = HMCharacteristicWriteAction(
    characteristic: lightChar,
    targetValue: false as NSCopying
)
actionSet.addAction(action) { error in
    guard error == nil else { return }
    print("Action added to Good Night scene")
}

}

Executing an Action Set

home.executeActionSet(actionSet) { error in if let error { print("Execution failed: (error)") } }

Creating a Timer Trigger

var dateComponents = DateComponents() dateComponents.hour = 22 dateComponents.minute = 30

let trigger = HMTimerTrigger( name: "Nightly", fireDate: Calendar.current.nextDate( after: Date(), matching: dateComponents, matchingPolicy: .nextTime )!, timeZone: .current, recurrence: dateComponents, // Repeats daily at 22:30 recurrenceCalendar: .current )

home.addTrigger(trigger) { error in guard error == nil else { return }

// Attach the action set to the trigger
trigger.addActionSet(goodNightActionSet) { error in
    guard error == nil else { return }

    trigger.enable(true) { error in
        print("Trigger enabled: \(error == nil)")
    }
}

}

Creating an Event Trigger

let motionDetected = HMCharacteristicEvent( characteristic: motionSensorCharacteristic, triggerValue: true as NSCopying )

let eventTrigger = HMEventTrigger( name: "Motion Lights", events: [motionDetected], predicate: nil )

home.addTrigger(eventTrigger) { error in // Add action sets as above }

Matter Commissioning

Use MatterAddDeviceRequest to commission a Matter device into your ecosystem. This is separate from HomeKit -- it handles the pairing flow.

Basic Commissioning

import MatterSupport

func addMatterDevice() async throws { guard MatterAddDeviceRequest.isSupported else { print("Matter not supported on this device") return }

let topology = MatterAddDeviceRequest.Topology(
    ecosystemName: "My Smart Home",
    homes: [
        MatterAddDeviceRequest.Home(displayName: "Main House")
    ]
)

let request = MatterAddDeviceRequest(
    topology: topology,
    setupPayload: nil,
    showing: .allDevices
)

// Presents system UI for device pairing
try await request.perform()

}

Filtering Devices

// Only show devices from a specific vendor let criteria = MatterAddDeviceRequest.DeviceCriteria.vendorID(0x1234)

let request = MatterAddDeviceRequest( topology: topology, setupPayload: nil, showing: criteria )

Combining Device Criteria

let criteria = MatterAddDeviceRequest.DeviceCriteria.all([ .vendorID(0x1234), .not(.productID(0x0001)) // Exclude a specific product ])

MatterAddDeviceExtensionRequestHandler

For full ecosystem support, create a MatterSupport Extension. The extension handles commissioning callbacks:

import MatterSupport

final class MatterHandler: MatterAddDeviceExtensionRequestHandler {

override func validateDeviceCredential(
    _ deviceCredential: DeviceCredential
) async throws {
    // Validate the device attestation certificate
    // Throw to reject the device
}

override func rooms(
    in home: MatterAddDeviceRequest.Home?
) async -> [MatterAddDeviceRequest.Room] {
    // Return rooms in the selected home
    return [
        MatterAddDeviceRequest.Room(displayName: "Living Room"),
        MatterAddDeviceRequest.Room(displayName: "Kitchen")
    ]
}

override func configureDevice(
    named name: String,
    in room: MatterAddDeviceRequest.Room?
) async {
    // Save the device configuration to your backend
    print("Configuring \(name) in \(room?.displayName ?? "no room")")
}

override func commissionDevice(
    in home: MatterAddDeviceRequest.Home?,
    onboardingPayload: String,
    commissioningID: UUID
) async throws {
    // Use the onboarding payload to commission the device
    // into your fabric using the Matter framework
}

}

Common Mistakes

DON'T: Access homes before the delegate fires

// WRONG -- homes array is empty until delegate is called let manager = HMHomeManager() let homes = manager.homes // Always empty here

// CORRECT -- wait for delegate func homeManagerDidUpdateHomes(_ manager: HMHomeManager) { let homes = manager.homes // Now populated }

DON'T: Confuse HomeKit setup with Matter commissioning

// WRONG -- using HomeKit accessory setup for a Matter ecosystem app home.addAndSetupAccessories { error in }

// CORRECT -- use MatterAddDeviceRequest for Matter ecosystem commissioning let request = MatterAddDeviceRequest( topology: topology, setupPayload: nil, showing: .allDevices ) try await request.perform()

DON'T: Forget required entitlements

// WRONG -- calling Matter APIs without the MatterSupport entitlement // Results in runtime error

// CORRECT -- ensure these are set up: // 1. HomeKit capability for HMHomeManager access // 2. MatterSupport Extension target for ecosystem commissioning // 3. com.apple.developer.matter.allow-setup-payload if providing setup codes

DON'T: Create multiple HMHomeManager instances

// WRONG -- each instance loads the full database independently class ScreenA { let manager = HMHomeManager() } class ScreenB { let manager = HMHomeManager() }

// CORRECT -- single shared instance @Observable final class HomeStore { static let shared = HomeStore() let homeManager = HMHomeManager() }

DON'T: Write characteristics without checking metadata

// WRONG -- writing a value outside the valid range characteristic.writeValue(500) { _ in }

// CORRECT -- check metadata first if let metadata = characteristic.metadata, let maxValue = metadata.maximumValue?.intValue { let safeValue = min(brightness, maxValue) characteristic.writeValue(safeValue) { _ in } }

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 capability and extension target added for Matter commissioning

• 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

• HomeKit framework

• HMHomeManager

• HMHome

• HMAccessory

• HMRoom

• HMActionSet

• HMTrigger

• MatterSupport framework

• MatterAddDeviceRequest

• MatterAddDeviceExtensionRequestHandler

• Enabling HomeKit in your app

• Adding Matter support to your ecosystem