SuperAPI AI Directory

homekit

General & other

View repository

Updated 10-16 05:52

About this skill

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