Homekit

dpearson2699/swift-ios-skills/skills/homekit

by dpearson26998d90fd121a26No license1.1K starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated 2 months ago

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.

Instructions onlySoftware Development
AI-generated overview

Guides building Apple HomeKit and MatterSupport smart-home apps for accessories, scenes, triggers and Matter commissioning.

What it does
This skill provides reference guidance and code patterns for Apple's HomeKit and MatterSupport frameworks. It covers the home/room/accessory data model, reading and writing accessory characteristics, action sets and timer or event triggers, and commissioning Matter devices into an app's ecosystem. It also lists common mistakes and a review checklist for HomeKit app configuration.
When to use it
Use it when writing or reviewing an iOS app that manages homes, rooms, accessories, scenes or triggers through HomeKit. It also applies when onboarding Matter devices via MatterSupport or building a third-party smart-home ecosystem app.
Requirements
Requires an Apple development environment with Xcode, the HomeKit capability and NSHomeKitUsageDescription in Info.plist; Matter commissioning needs a MatterSupport extension target, Bonjour service entries, and optionally the setup-payload entitlement. Instructions only; no scripts are shipped.

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

HomeKit Configuration

  1. Enable the HomeKit capability in Xcode (Signing & Capabilities)
  2. Add NSHomeKitUsageDescription to Info.plist:
xml
<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

Framework Boundary

NeedFramework
Homes, rooms, accessories, characteristics, actions, triggersHomeKit
Commission Matter into the app ecosystemMatterSupport
Select and authorize a nearby Bluetooth or Wi-Fi accessoryAccessorySetupKit
Exchange Bluetooth GATT data after selectionCoreBluetooth
Join or configure an accessory's Wi-Fi network after selectionNetworkExtension

HomeKit Data Model

HomeKit organizes home automation in a hierarchy:

text
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.

swift
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

swift
guard let home = homeManager.primaryHome else { return }
let rooms = home.roomslet kitchen = rooms.first { $0.name == "Kitchen" }
// Room for accessories not assigned to a specific roomlet defaultRoom = home.roomForEntireHome()

Managing Accessories

Discovering and Adding Accessories

Use the Framework Boundary table before adding an accessory; only HomeKit/MatterSupport work continues in this skill.

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

Listing Accessories and Services

swift
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

swift
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

swift
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

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

Observing Changes

Enable notifications for real-time updates:

swift
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:

swift
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

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

Creating a Timer Trigger

swift
var timeOfDay = DateComponents()timeOfDay.hour = 22timeOfDay.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

swift
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

swift
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

swift
// Only show devices from a specific vendorlet 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. Load the complete Advanced Matter Extension Handler [blocked] for credential validation, room selection, configuration, commissioning, and network-association overrides.

Common Mistakes

MistakeFix
Reading homes before the delegate updateCreate one manager, set its delegate, and wait for homeManagerDidUpdateHomes.
HomeKit setup is used for Matter ecosystem commissioningUse MatterAddDeviceRequest plus the configured MatterSupport extension.
Matter configuration is incompleteVerify principal handler, Bonjour services, and the setup-payload entitlement only when applicable.
Multiple HMHomeManager instances load the databaseShare one retained manager/store.
Characteristic write ignores metadataCheck 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

Source and attribution

Source:dpearson2699/swift-ios-skillsinskills/homekitat commit8d90fd1

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

More from dpearson2699/swift-ios-skills

Widgetkit

dpearson2699

Guides implementing, reviewing, and improving WidgetKit widgets and controls for iOS, iPadOS, watchOS, and CarPlay.

Software Development1.1Kupdated 2 months ago

Weatherkit

dpearson2699

Guides iOS developers in fetching WeatherKit forecasts, alerts, and attribution using WeatherService.

Software Development1.1Kupdated 2 months ago

Vision Framework

dpearson2699

Implement computer vision features including text recognition (OCR), face detection, barcode scanning, image segmentation, object tracking, and document scanning in iOS apps. Covers both the modern Swift-native Vision API (iOS 18+) and legacy VNRequest patterns, VisionKit DataScannerViewController for live camera scanning, and CoreMLRequest/VNCoreMLRequest for custom model inference. Use when adding OCR, barcode scanning, face detection, or custom Core ML model inference with Vision.

Awaiting classification1.1Kupdated 2 months ago

Tipkit

dpearson2699

Implement and review Apple TipKit feature-discovery UI for iOS 17+ apps. Use when adding or auditing in-app tips, contextual help, coach marks, Tip, TipView, popoverTip, rules, events, actions, display frequency, testing overrides, reusable tip identifiers, or iOS 18+ TipGroup and CloudKit tip sync; avoid for generic SwiftUI navigation or layout outside tip presentation.

Awaiting classification1.1Kupdated 2 months ago

Tabletopkit

dpearson2699

Guides building multiplayer spatial board games on visionOS with Apple's TabletopKit and RealityKit.

Software Development1.1Kupdated 2 months ago

Swiftui Webkit

dpearson2699

Guides embedding and controlling web content in SwiftUI apps with WebKit for SwiftUI on iOS 26 and later.

Software Development1.1Kupdated 2 months ago