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](#setup)
- [HomeKit Data Model](#homekit-data-model)
- [Managing Accessories](#managing-accessories)
- [Reading and Writing Characteristics](#reading-and-writing-characteristics)
- [Action Sets and Triggers](#action-sets-and-triggers)
- [Matter Commissioning](#matter-commissioning)
- [MatterAddDeviceExtensionRequestHandler](#matteradddeviceextensionrequesthandler)
- [Common Mistakes](#common-mistakes)
- [Review Checklist](#review-checklist)
- [References](#references)

## 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

### Availability Check

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

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

```swift
// System UI for accessory discovery
home.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 light
characteristic.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