Homekit

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. Targets Swift 6.3 / 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

1. Enable the HomeKit capability in Xcode (Signing & Capabilities) 2. 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:

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

Availability Check

import HomeKit

let homeManager = HMHomeManager()

// HomeKit is available on iPhone, iPad, Apple TV, Apple Watch,
// Mac Catalyst, 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

Use HomeKit and MatterSupport for home-model work: homes, rooms, HMAccessory services and characteristics, action sets, triggers and automations, HomeKit accessory setup UI, and Matter commissioning. If the same request asks about lower-level Bluetooth or Wi-Fi accessory discovery or authorization, name AccessorySetupKit as the boundary for discovery descriptors, picker authorization, ASAccessorySession events, and migration. After AccessorySetupKit setup, explicitly name both post-setup handoff targets: CoreBluetooth/GATT for Bluetooth accessories and NetworkExtension for Wi-Fi accessory network flows; neither handoff is HomeKit automation logic.

// 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 timeOfDay = DateComponents()
timeOfDay.hour = 22
timeOfDay.minute = 30

let firstFireDate = Calendar.current.nextDate(
    after: Date(),
    matching: timeOfDay,
    matchingPolicy: .nextTime
)!

let trigger = HMTimerTrigger(
    name: "Nightly",
    fireDate: firstFireDate,
    recurrence: DateComponents(day: 1)  // Repeat every day after firstFireDate
)

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 the HMHome home-automation model; it handles the Matter setup flow and calls into your MatterSupport extension.

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()
}

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

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

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

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.

import MatterSupport

final class MatterHandler: MatterAddDeviceExtensionRequestHandler {

    override func validateDeviceCredential(
        _ deviceCredential:
            MatterAddDeviceExtensionRequestHandler.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 configuration

Matter ecosystem commissioning needs the MatterSupport extension, principal handler class, and Matter Bonjour services. Add the setup-payload entitlement only when your app provides setup codes directly.

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 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
• HomeKit framework
• HMHomeManager
• HMHome
• HMAccessory
• HMRoom
• HMActionSet
• HMTrigger
• MatterSupport framework
• MatterAddDeviceRequest
• MatterAddDeviceExtensionRequestHandler
• Enabling HomeKit in your app
• Adding Matter support to your ecosystem

HomeKit + Matter Extended Patterns

Overflow reference for the homekit skill. Contains advanced patterns that exceed the main skill file's scope.

Contents

• SwiftUI HomeKit Integration
• Full Delegate Wiring
• Service Type Discovery
• Advanced Matter Extension Handler
• Testing with HomeKit Accessory Simulator

SwiftUI HomeKit Integration

HomeKit Store with @Observable

import HomeKit
import SwiftUI

@Observable
@MainActor
final class HomeStore: NSObject {
    static let shared = HomeStore()

    let homeManager = HMHomeManager()

    var homes: [HMHome] = []
    var primaryHome: HMHome?
    var isAuthorized = false

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

    var accessories: [HMAccessory] {
        primaryHome?.accessories ?? []
    }

    var rooms: [HMRoom] {
        primaryHome?.rooms ?? []
    }

    func addHome(name: String) async throws {
        try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<Void, Error>) in
            homeManager.addHome(withName: name) { home, error in
                if let error {
                    continuation.resume(throwing: error)
                } else {
                    continuation.resume()
                }
            }
        }
    }
}

extension HomeStore: HMHomeManagerDelegate {
    nonisolated func homeManagerDidUpdateHomes(_ manager: HMHomeManager) {
        Task { @MainActor in
            homes = manager.homes
            primaryHome = manager.primaryHome
        }
    }

    nonisolated func homeManager(
        _ manager: HMHomeManager,
        didUpdate status: HMHomeManagerAuthorizationStatus
    ) {
        Task { @MainActor in
            isAuthorized = status.contains(.authorized)
        }
    }

    nonisolated func homeManager(
        _ manager: HMHomeManager,
        didAdd home: HMHome
    ) {
        Task { @MainActor in
            homes = manager.homes
        }
    }

    nonisolated func homeManager(
        _ manager: HMHomeManager,
        didRemove home: HMHome
    ) {
        Task { @MainActor in
            homes = manager.homes
        }
    }
}

Accessory List View

struct AccessoryListView: View {
    @State private var homeStore = HomeStore.shared

    var body: some View {
        NavigationStack {
            Group {
                if !homeStore.isAuthorized {
                    ContentUnavailableView(
                        "HomeKit Access Required",
                        systemImage: "house.fill",
                        description: Text("Grant access in Settings to manage your home.")
                    )
                } else if homeStore.accessories.isEmpty {
                    ContentUnavailableView(
                        "No Accessories",
                        systemImage: "lightbulb",
                        description: Text("Add accessories using the Home app.")
                    )
                } else {
                    accessoryList
                }
            }
            .navigationTitle(homeStore.primaryHome?.name ?? "Home")
        }
    }

    private var accessoryList: some View {
        List {
            ForEach(homeStore.rooms, id: \.uniqueIdentifier) { room in
                Section(room.name) {
                    let roomAccessories = homeStore.accessories.filter {
                        $0.room?.uniqueIdentifier == room.uniqueIdentifier
                    }
                    ForEach(roomAccessories, id: \.uniqueIdentifier) { accessory in
                        AccessoryRow(accessory: accessory)
                    }
                }
            }
        }
    }
}

struct AccessoryRow: View {
    let accessory: HMAccessory

    var body: some View {
        HStack {
            Image(systemName: iconName)
            VStack(alignment: .leading) {
                Text(accessory.name)
                    .font(.headline)
                Text(accessory.isReachable ? "Reachable" : "Not Reachable")
                    .font(.caption)
                    .foregroundStyle(accessory.isReachable ? .green : .secondary)
            }
        }
    }

    private var iconName: String {
        switch accessory.category.categoryType {
        case HMAccessoryCategoryTypeLightbulb: return "lightbulb.fill"
        case HMAccessoryCategoryTypeThermostat: return "thermometer"
        case HMAccessoryCategoryTypeLock: return "lock.fill"
        case HMAccessoryCategoryTypeSwitch: return "light.switch.2"
        default: return "house.fill"
        }
    }
}

Light Control View

struct LightControlView: View {
    let accessory: HMAccessory

    @State private var isOn = false
    @State private var brightness: Double = 100

    private var lightbulbService: HMService? {
        accessory.services.first {
            $0.serviceType == HMServiceTypeLightbulb
        }
    }

    private var powerCharacteristic: HMCharacteristic? {
        lightbulbService?.characteristics.first {
            $0.characteristicType == HMCharacteristicTypePowerState
        }
    }

    private var brightnessCharacteristic: HMCharacteristic? {
        lightbulbService?.characteristics.first {
            $0.characteristicType == HMCharacteristicTypeBrightness
        }
    }

    var body: some View {
        VStack {
            Toggle("Power", isOn: $isOn)
                .onChange(of: isOn) { _, newValue in
                    powerCharacteristic?.writeValue(newValue) { _ in }
                }

            if isOn {
                Slider(value: $brightness, in: 0...100, step: 1)
                    .onChange(of: brightness) { _, newValue in
                        brightnessCharacteristic?.writeValue(
                            Int(newValue)
                        ) { _ in }
                    }
                Text("Brightness: \(Int(brightness))%")
            }
        }
        .padding()
        .task { await readCurrentState() }
    }

    private func readCurrentState() async {
        powerCharacteristic?.readValue { _ in
            if let value = powerCharacteristic?.value as? Bool {
                isOn = value
            }
        }
        brightnessCharacteristic?.readValue { _ in
            if let value = brightnessCharacteristic?.value as? Int {
                brightness = Double(value)
            }
        }
    }
}

Full Delegate Wiring

HMHomeDelegate

extension HomeStore: HMHomeDelegate {
    nonisolated func home(
        _ home: HMHome,
        didAdd accessory: HMAccessory
    ) {
        accessory.delegate = self
        Task { @MainActor in
            // Refresh accessory list
        }
    }

    nonisolated func home(
        _ home: HMHome,
        didRemove accessory: HMAccessory
    ) {
        Task { @MainActor in
            // Refresh accessory list
        }
    }

    nonisolated func home(
        _ home: HMHome,
        didAdd room: HMRoom
    ) {
        Task { @MainActor in
            // Refresh room list
        }
    }

    nonisolated func home(
        _ home: HMHome,
        didUpdateNameFor room: HMRoom
    ) {
        Task { @MainActor in
            // Update room name display
        }
    }
}

HMAccessoryDelegate

extension HomeStore: HMAccessoryDelegate {
    nonisolated func accessory(
        _ accessory: HMAccessory,
        service: HMService,
        didUpdateValueFor characteristic: HMCharacteristic
    ) {
        Task { @MainActor in
            // Update UI for the changed characteristic
            let newValue = characteristic.value
            print("\(accessory.name).\(characteristic.characteristicType) = \(newValue ?? "nil")")
        }
    }

    nonisolated func accessoryDidUpdateReachability(
        _ accessory: HMAccessory
    ) {
        Task { @MainActor in
            print("\(accessory.name) reachable: \(accessory.isReachable)")
        }
    }

    nonisolated func accessoryDidUpdateName(
        _ accessory: HMAccessory
    ) {
        Task { @MainActor in
            // Refresh name display
        }
    }
}

Service Type Discovery

Finding Specific Service Types

// Find all thermostats in the home
let thermostats = home.servicesWithTypes([HMServiceTypeThermostat]) ?? []

for service in thermostats {
    let currentTemp = service.characteristics.first {
        $0.characteristicType == HMCharacteristicTypeCurrentTemperature
    }
    let targetTemp = service.characteristics.first {
        $0.characteristicType == HMCharacteristicTypeTargetTemperature
    }

    currentTemp?.readValue { _ in
        print("Current: \(currentTemp?.value ?? "?")")
    }
}

Common Service Types

Common Characteristic Types

Advanced Matter Extension Handler

Full Handler with Network Selection

import MatterSupport

final class MyMatterHandler: MatterAddDeviceExtensionRequestHandler {

    override func validateDeviceCredential(
        _ deviceCredential:
            MatterAddDeviceExtensionRequestHandler.DeviceCredential
    ) async throws {
        // Validate the Device Attestation Certificate (DAC) against
        // your Product Attestation Authority (PAA) root certificates.
        let dac = deviceCredential.deviceAttestationCertificate
        let pai = deviceCredential.productAttestationIntermediateCertificate
        let cd = deviceCredential.certificationDeclaration

        // If validation fails, throw an error to reject the device
        guard isValidCertificateChain(dac: dac, pai: pai, cd: cd) else {
            throw MatterCommissioningError.invalidCredential
        }
    }

    override func rooms(
        in home: MatterAddDeviceRequest.Home?
    ) async -> [MatterAddDeviceRequest.Room] {
        // Fetch rooms from your backend for the given home
        guard let home else { return [] }

        let roomNames = await fetchRoomsFromBackend(homeName: home.displayName)
        return roomNames.map { MatterAddDeviceRequest.Room(displayName: $0) }
    }

    override func configureDevice(
        named name: String,
        in room: MatterAddDeviceRequest.Room?
    ) async {
        // Save device configuration to your ecosystem backend
        await saveDeviceToBackend(
            deviceName: name,
            roomName: room?.displayName
        )
    }

    override func commissionDevice(
        in home: MatterAddDeviceRequest.Home?,
        onboardingPayload: String,
        commissioningID: UUID
    ) async throws {
        // Commission the device into your Matter fabric
        // using the Matter framework (MTRDeviceController)
        try await commissionToFabric(
            payload: onboardingPayload,
            commissioningID: commissioningID
        )
    }

    override func selectWiFiNetwork(
        from networks:
            [MatterAddDeviceExtensionRequestHandler.WiFiScanResult]
    ) async throws
        -> MatterAddDeviceExtensionRequestHandler.WiFiNetworkAssociation {
        // Use the system default network or specify one
        return .defaultSystemNetwork
    }

    override func selectThreadNetwork(
        from networks:
            [MatterAddDeviceExtensionRequestHandler.ThreadScanResult]
    ) async throws
        -> MatterAddDeviceExtensionRequestHandler.ThreadNetworkAssociation {
        return .defaultSystemNetwork
    }
}

Testing with HomeKit Accessory Simulator

1. Download Additional Tools for Xcode from Apple's developer downloads page 2. Launch HomeKit Accessory Simulator 3. Create simulated accessories (lights, locks, sensors) 4. Pair them with your app running in Simulator or on device

// Enable verbose logging during development
#if DEBUG
import os
let homeKitLog = Logger(subsystem: "com.example.app", category: "HomeKit")

func logAccessories() {
    guard let home = homeManager.primaryHome else { return }
    for accessory in home.accessories {
        homeKitLog.debug("Accessory: \(accessory.name), reachable: \(accessory.isReachable)")
        for service in accessory.services {
            homeKitLog.debug("  Service: \(service.localizedDescription ?? service.serviceType)")
        }
    }
}
#endif