HomeKit

Control home automation accessories and commission Matter devices into an app ecosystem. HomeKit manages the home/room/accessory hierarchy, characteristics, and automation triggers; MatterSupport handles ecosystem device commissioning.

Contents

• Setup & Framework Boundaries
• HomeKit Data Model
• Accessories & Characteristics
• Action Sets & Triggers
• Matter Device Commissioning
• Common Mistakes
• Review Checklist
• References

Setup & Framework Boundaries

Entitlements & Info.plist

1. Enable the HomeKit capability in Xcode.
2. Add NSHomeKitUsageDescription to Info.plist.
3. For MatterSupport commissioning: add a MatterSupport Extension target, declare Bonjour services (_matter._tcp, _matterc._udp, _matterd._udp), and set the extension's principal class to MatterAddDeviceExtensionRequestHandler.

Boundary Division

• HomeKit: Homes, rooms, accessory control, characteristics, scenes, triggers.
• MatterSupport: Commissioning Matter hardware into a third-party ecosystem.
• AccessorySetupKit: Selecting/pairing nearby Bluetooth/Wi-Fi devices without broad permissions.
• CoreBluetooth / NetworkExtension: Raw data transport after device authorization.

HomeKit Data Model

HomeKit loads asynchronously. Maintain a single HMHomeManager instance and await the homeManagerDidUpdateHomes(_:) delegate callback before accessing homes or primaryHome.

HMHomeManager -> HMHome -> HMRoom -> HMAccessory -> HMService -> HMCharacteristic

import HomeKit

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

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

    func homeManagerDidUpdateHomes(_ manager: HMHomeManager) {
        // Safe to read homes and accessories
        let primary = manager.primaryHome
    }
}

Accessories & Characteristics

Interact with accessory services (e.g. lights, thermostats) via HMCharacteristic:

func setLightPower(_ characteristic: HMCharacteristic, isOn: Bool) async throws {
    guard characteristic.characteristicType == HMCharacteristicTypePowerState else { return }
    try await characteristic.writeValue(isOn)
}

func readTemperature(_ characteristic: HMCharacteristic) async throws -> Double? {
    try await characteristic.readValue()
    return characteristic.value as? Double
}

Action Sets & Triggers

Group changes into scenes and automate execution:

// Create an action set (scene)
func createNightScene(home: HMHome, lightAction: HMCharacteristicWriteAction<Bool>) async throws {
    let actionSet = try await home.addActionSet(withName: "Good Night")
    try await actionSet.addAction(lightAction)
}

// Event-based automation
func addTrigger(home: HMHome, trigger: HMEventTrigger) async throws {
    try await home.addTrigger(trigger)
    try await trigger.enable(true)
}

Matter Device Commissioning

Use MatterSupport to onboard Matter devices into your ecosystem:

import MatterSupport

let topology = MatterAddDeviceRequest.Topology(ecosystemName: "MyHome", homes: [home])
let request = MatterAddDeviceRequest(topology: topology)
try await request.perform()

The system invokes your MatterAddDeviceExtensionRequestHandler subclass in the extension target to complete pairing.

Common Mistakes

• Accessing homes synchronously at launch: manager.homes is empty until homeManagerDidUpdateHomes fires.
• Missing Bonjour services for Matter: Commissioning fails silently without _matter._tcp, _matterc._udp, and _matterd._udp in NSBonjourServices.
• Directly modifying characteristic values: Always call asynchronous characteristic.writeValue(_:) rather than mutating state locally.
• Creating multiple HMHomeManager instances: Instantiate one shared manager to prevent duplicate notifications and sync conflicts.
• Confusing HomeKit with AccessorySetupKit: Use HomeKit for smart-home accessories; use AccessorySetupKit for proprietary BLE/Wi-Fi peripherals.

Review Checklist

• NSHomeKitUsageDescription present in target Info.plist
• HMHomeManager instantiated once and guarded until homeManagerDidUpdateHomes fires
• Characteristic mutations performed via writeValue(_:) with error handling
• MatterSupport extension target configured with Bonjour service declarations
• Triggers explicitly enabled via trigger.enable(true) after creation

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