@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/homekit-matter/references/matter-commissioning.md

@@ -1,275 +1,213 @@
-# HomeKit + Matter Extended Patterns
+# Matter commissioning and HomeKit UI recipes
 
-Overflow reference for the `homekit` skill. Contains advanced patterns
-that exceed the main skill file's scope.
+Extended material for the `homekit-matter` skill ([../SKILL.md](../SKILL.md)):
+a SwiftUI store, accessory screens, complete delegate wiring, service and
+characteristic tables, a fuller MatterSupport handler, and simulator testing.
 
 ## Contents
 
-- [SwiftUI HomeKit Integration](#swiftui-homekit-integration)
-- [Full Delegate Wiring](#full-delegate-wiring)
-- [Service Type Discovery](#service-type-discovery)
-- [Advanced Matter Extension Handler](#advanced-matter-extension-handler)
-- [Testing with HomeKit Accessory Simulator](#testing-with-homekit-accessory-simulator)
+- [SwiftUI integration](#swiftui-integration)
+- [Delegate wiring](#delegate-wiring)
+- [Finding services by type](#finding-services-by-type)
+- [A fuller MatterSupport handler](#a-fuller-mattersupport-handler)
+- [Simulated accessories for testing](#simulated-accessories-for-testing)
 
-## SwiftUI HomeKit Integration
+## SwiftUI integration
 
-### HomeKit Store with `@Observable`
+### An observable store
+
+One store owns the single `HMHomeManager`. HomeKit calls its delegates off the
+main actor, so the callbacks are `nonisolated` and hop back before touching
+state.
 
 ```swift
 import HomeKit
-import SwiftUI
+import Observation
 
 @Observable
 @MainActor
-final class HomeStore: NSObject {
-    static let shared = HomeStore()
+final class HouseStore: NSObject {
+    static let shared = HouseStore()
 
-    let homeManager = HMHomeManager()
+    @ObservationIgnored private let manager = HMHomeManager()
+    private(set) var houses: [HMHome] = []
+    private(set) var mainHouse: HMHome?
+    private(set) var hasAccess = false
 
-    var homes: [HMHome] = []
-    var primaryHome: HMHome?
-    var isAuthorized = false
+    var devices: [HMAccessory] { mainHouse?.accessories ?? [] }
+    var spaces: [HMRoom] { mainHouse?.rooms ?? [] }
 
-    override init() {
+    private override init() {
         super.init()
-        homeManager.delegate = self
+        manager.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)
+    func createHouse(named name: String) async throws -> HMHome {
+        try await withCheckedThrowingContinuation { continuation in
+            manager.addHome(withName: name) { created, failure in
+                if let created {
+                    continuation.resume(returning: created)
                 } else {
-                    continuation.resume()
+                    continuation.resume(throwing: failure ?? HMError(.genericError))
                 }
             }
         }
     }
+
+    private func reload() {
+        houses = manager.homes
+        // primaryHome is deprecated since iOS 16.1; keep the user's own choice.
+        mainHouse = houses.first { $0 == mainHouse } ?? houses.first
+    }
 }
 
-extension HomeStore: HMHomeManagerDelegate {
-    nonisolated func homeManagerDidUpdateHomes(_ manager: HMHomeManager) {
-        Task { @MainActor in
-            homes = manager.homes
-            primaryHome = manager.primaryHome
-        }
+extension HouseStore: HMHomeManagerDelegate {
+    nonisolated func homeManagerDidUpdateHomes(_ source: HMHomeManager) {
+        Task { @MainActor in reload() }
     }
 
-    nonisolated func homeManager(
-        _ manager: HMHomeManager,
-        didUpdate status: HMHomeManagerAuthorizationStatus
-    ) {
-        Task { @MainActor in
-            isAuthorized = status.contains(.authorized)
-        }
+    nonisolated func homeManager(_ source: HMHomeManager,
+                                 didUpdate status: HMHomeManagerAuthorizationStatus) {
+        let granted = status.contains(.authorized)
+        Task { @MainActor in hasAccess = granted }
     }
 
-    nonisolated func homeManager(
-        _ manager: HMHomeManager,
-        didAdd home: HMHome
-    ) {
-        Task { @MainActor in
-            homes = manager.homes
-        }
+    nonisolated func homeManager(_ source: HMHomeManager, didAdd home: HMHome) {
+        Task { @MainActor in reload() }
     }
 
-    nonisolated func homeManager(
-        _ manager: HMHomeManager,
-        didRemove home: HMHome
-    ) {
-        Task { @MainActor in
-            homes = manager.homes
-        }
+    nonisolated func homeManager(_ source: HMHomeManager, didRemove home: HMHome) {
+        Task { @MainActor in reload() }
     }
 }
 ```
 
-### Accessory List View
+### Accessories grouped by room
 
 ```swift
-struct AccessoryListView: View {
-    @State private var homeStore = HomeStore.shared
+import SwiftUI
+import HomeKit
+
+struct DeviceBrowser: View {
+    let store = HouseStore.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.")
-                    )
+                if !store.hasAccess {
+                    ContentUnavailableView("Home access is off",
+                                           systemImage: "house.slash",
+                                           description: Text("Allow access in Settings."))
+                } else if store.devices.isEmpty {
+                    ContentUnavailableView("No devices yet", systemImage: "lightbulb.slash")
                 } else {
-                    accessoryList
+                    List(store.spaces, id: \.uniqueIdentifier) { space in
+                        Section(space.name) {
+                            ForEach(devices(in: space), id: \.uniqueIdentifier) { device in
+                                DeviceRow(device: device)
+                            }
+                        }
+                    }
                 }
             }
-            .navigationTitle(homeStore.primaryHome?.name ?? "Home")
+            .navigationTitle("Devices")
         }
     }
 
-    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)
-                    }
-                }
-            }
-        }
+    private func devices(in space: HMRoom) -> [HMAccessory] {
+        store.devices.filter { $0.room?.uniqueIdentifier == space.uniqueIdentifier }
     }
 }
 
-struct AccessoryRow: View {
-    let accessory: HMAccessory
+struct DeviceRow: View {
+    let device: HMAccessory
 
     var body: some View {
-        HStack {
-            Image(systemName: iconName)
+        Label {
             VStack(alignment: .leading) {
-                Text(accessory.name)
-                    .font(.headline)
-                Text(accessory.isReachable ? "Reachable" : "Not Reachable")
+                Text(device.name)
+                Text(device.isReachable ? "Online" : "Offline")
                     .font(.caption)
-                    .foregroundStyle(accessory.isReachable ? .green : .secondary)
+                    .foregroundStyle(.secondary)
             }
+        } icon: {
+            Image(systemName: glyph)
         }
     }
 
-    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"
+    private var glyph: String {
+        switch device.category.categoryType {
+        case HMAccessoryCategoryTypeLightbulb: "lightbulb"
+        case HMAccessoryCategoryTypeThermostat: "thermometer"
+        case HMAccessoryCategoryTypeDoorLock: "lock"
+        case HMAccessoryCategoryTypeSwitch: "switch.2"
+        default: "questionmark.square"
         }
     }
 }
 ```
 
-### Light Control View
+### A lamp control screen
 
 ```swift
-struct LightControlView: View {
-    let accessory: HMAccessory
+struct LampPanel: View {
+    let lamp: HMAccessory
+    @State private var isLit = false
+    @State private var level = 50.0
 
-    @State private var isOn = false
-    @State private var brightness: Double = 100
-
-    private var lightbulbService: HMService? {
-        accessory.services.first {
-            $0.serviceType == HMServiceTypeLightbulb
-        }
+    private var bulb: HMService? {
+        lamp.services.first { $0.serviceType == HMServiceTypeLightbulb }
     }
-
-    private var powerCharacteristic: HMCharacteristic? {
-        lightbulbService?.characteristics.first {
-            $0.characteristicType == HMCharacteristicTypePowerState
-        }
+    private var power: HMCharacteristic? {
+        bulb?.characteristics.first { $0.characteristicType == HMCharacteristicTypePowerState }
     }
-
-    private var brightnessCharacteristic: HMCharacteristic? {
-        lightbulbService?.characteristics.first {
-            $0.characteristicType == HMCharacteristicTypeBrightness
-        }
+    private var dimmer: HMCharacteristic? {
+        bulb?.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
-            }
+        Form {
+            Toggle("Lit", isOn: $isLit)
+                .onChange(of: isLit) { _, lit in power?.writeValue(lit) { _ in } }
+            Slider(value: $level, in: 0...100, step: 1)
+                .onChange(of: level) { _, value in dimmer?.writeValue(Int(value)) { _ in } }
         }
-        brightnessCharacteristic?.readValue { _ in
-            if let value = brightnessCharacteristic?.value as? Int {
-                brightness = Double(value)
-            }
+        .task {
+            try? await power?.readValue()
+            try? await dimmer?.readValue()
+            isLit = power?.value as? Bool ?? false
+            level = Double(dimmer?.value as? Int ?? 0)
         }
     }
 }
 ```
 
-## Full Delegate Wiring
+## Delegate wiring
 
 ### HMHomeDelegate
 
+Set the accessory's delegate as soon as it appears so value pushes are not
+lost.
+
 ```swift
-extension HomeStore: HMHomeDelegate {
-    nonisolated func home(
-        _ home: HMHome,
-        didAdd accessory: HMAccessory
-    ) {
-        accessory.delegate = self
+extension HouseStore: HMHomeDelegate {
+    nonisolated func home(_ house: HMHome, didAdd device: HMAccessory) {
         Task { @MainActor in
-            // Refresh accessory list
+            device.delegate = self
+            reload()
         }
     }
 
-    nonisolated func home(
-        _ home: HMHome,
-        didRemove accessory: HMAccessory
-    ) {
-        Task { @MainActor in
-            // Refresh accessory list
-        }
+    nonisolated func home(_ house: HMHome, didRemove device: HMAccessory) {
+        Task { @MainActor in reload() }
     }
 
-    nonisolated func home(
-        _ home: HMHome,
-        didAdd room: HMRoom
-    ) {
-        Task { @MainActor in
-            // Refresh room list
-        }
+    nonisolated func home(_ house: HMHome, didAdd space: HMRoom) {
+        Task { @MainActor in reload() }
     }
 
-    nonisolated func home(
-        _ home: HMHome,
-        didUpdateNameFor room: HMRoom
-    ) {
-        Task { @MainActor in
-            // Update room name display
-        }
+    nonisolated func home(_ house: HMHome, didUpdateNameFor space: HMRoom) {
+        Task { @MainActor in reload() }
     }
 }
 ```
@@ -277,129 +215,83 @@ extension HomeStore: HMHomeDelegate {
 ### HMAccessoryDelegate
 
 ```swift
-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")")
-        }
+extension HouseStore: HMAccessoryDelegate {
+    nonisolated func accessory(_ device: HMAccessory,
+                               service: HMService,
+                               didUpdateValueFor trait: HMCharacteristic) {
+        Task { @MainActor in reload() }
     }
 
-    nonisolated func accessoryDidUpdateReachability(
-        _ accessory: HMAccessory
-    ) {
-        Task { @MainActor in
-            print("\(accessory.name) reachable: \(accessory.isReachable)")
-        }
+    nonisolated func accessoryDidUpdateReachability(_ device: HMAccessory) {
+        Task { @MainActor in reload() }
     }
 
-    nonisolated func accessoryDidUpdateName(
-        _ accessory: HMAccessory
-    ) {
-        Task { @MainActor in
-            // Refresh name display
-        }
+    nonisolated func accessoryDidUpdateName(_ device: HMAccessory) {
+        Task { @MainActor in reload() }
     }
 }
 ```
 
-## Service Type Discovery
-
-### Finding Specific Service Types
+## Finding services by type
 
 ```swift
-// 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 ?? "?")")
-    }
+let climate = house.servicesWithTypes([HMServiceTypeThermostat]) ?? []
+for unit in climate {
+    let now = unit.characteristics.first { $0.characteristicType == HMCharacteristicTypeCurrentTemperature }
+    let goal = unit.characteristics.first { $0.characteristicType == HMCharacteristicTypeTargetTemperature }
+    print(now?.value ?? "?", "->", goal?.value ?? "?")
 }
 ```
 
-### Common Service Types
+### Frequently used service types
 
-| Constant | Description |
+| Constant | Typical device |
 |---|---|
-| `HMServiceTypeLightbulb` | Light control (on/off, brightness, color) |
-| `HMServiceTypeThermostat` | Temperature control |
+| `HMServiceTypeLightbulb` | Light with power, brightness, colour |
+| `HMServiceTypeThermostat` | Heating and cooling control |
 | `HMServiceTypeLockMechanism` | Door lock |
 | `HMServiceTypeGarageDoorOpener` | Garage door |
-| `HMServiceTypeSwitch` | Generic on/off switch |
-| `HMServiceTypeMotionSensor` | Motion detection |
-| `HMServiceTypeTemperatureSensor` | Temperature reading |
-| `HMServiceTypeContactSensor` | Door/window open/close |
+| `HMServiceTypeSwitch` | Plain on/off switch |
+| `HMServiceTypeMotionSensor` | Motion detector |
+| `HMServiceTypeTemperatureSensor` | Temperature probe |
+| `HMServiceTypeContactSensor` | Door or window open/closed sensor |
 
-### Common Characteristic Types
+### Frequently used characteristic types
 
-| Constant | Value Type | Description |
+| Constant | Swift value | Notes |
 |---|---|---|
-| `HMCharacteristicTypePowerState` | Bool | On/off |
-| `HMCharacteristicTypeBrightness` | Int (0-100) | Light brightness |
-| `HMCharacteristicTypeHue` | Float (0-360) | Light hue |
-| `HMCharacteristicTypeSaturation` | Float (0-100) | Light saturation |
-| `HMCharacteristicTypeCurrentTemperature` | Float | Celsius reading |
-| `HMCharacteristicTypeTargetTemperature` | Float | Celsius target |
-| `HMCharacteristicTypeLockCurrentState` | Int | Lock state (0=unsecured) |
-| `HMCharacteristicTypeLockTargetState` | Int | Lock target state |
+| `HMCharacteristicTypePowerState` | `Bool` | on or off |
+| `HMCharacteristicTypeBrightness` | `Int` | 0 to 100 percent |
+| `HMCharacteristicTypeHue` | `Float` | 0 to 360 degrees |
+| `HMCharacteristicTypeSaturation` | `Float` | 0 to 100 percent |
+| `HMCharacteristicTypeCurrentTemperature` | `Float` | Celsius |
+| `HMCharacteristicTypeTargetTemperature` | `Float` | Celsius |
+| `HMCharacteristicTypeLockCurrentState` | `Int` | 0 means unsecured |
+| `HMCharacteristicTypeLockTargetState` | `Int` | desired lock state |
 
-## Advanced Matter Extension Handler
-
-### Full Handler with Network Selection
+## A fuller MatterSupport handler
 
 ```swift
 import MatterSupport
 
-final class MyMatterHandler: MatterAddDeviceExtensionRequestHandler {
-
+final class CabinPairingHandler: MatterAddDeviceExtensionRequestHandler {
     override func validateDeviceCredential(
-        _ deviceCredential:
-            MatterAddDeviceExtensionRequestHandler.DeviceCredential
+        _ credential: 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
-        }
+        let dac = credential.deviceAttestationCertificate
+        let pai = credential.productAttestationIntermediateCertificate
+        let declaration = credential.certificationDeclaration
+        // Verify DAC -> PAI -> one of your trusted PAA roots, and check the
+        // certification declaration. Throw to stop pairing.
+        try AttestationChecker.verify(dac: dac, pai: pai, declaration: declaration)
     }
 
     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
-        )
+        let names = await CabinBackend.roomNames(forHome: home.displayName)
+        return names.map { MatterAddDeviceRequest.Room(displayName: $0) }
     }
 
     override func commissionDevice(
@@ -407,52 +299,54 @@ final class MyMatterHandler: MatterAddDeviceExtensionRequestHandler {
         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
-        )
+        // Use MTRDeviceController from the Matter framework to add the
+        // device to your fabric with this onboarding payload.
+        try await CabinFabric.commission(payload: onboardingPayload, id: commissioningID)
     }
 
     override func selectWiFiNetwork(
-        from networks:
-            [MatterAddDeviceExtensionRequestHandler.WiFiScanResult]
-    ) async throws
-        -> MatterAddDeviceExtensionRequestHandler.WiFiNetworkAssociation {
-        // Use the system default network or specify one
-        return .defaultSystemNetwork
+        from wifiScanResults: [MatterAddDeviceExtensionRequestHandler.WiFiScanResult]
+    ) async throws -> MatterAddDeviceExtensionRequestHandler.WiFiNetworkAssociation {
+        .defaultSystemNetwork
     }
 
     override func selectThreadNetwork(
-        from networks:
-            [MatterAddDeviceExtensionRequestHandler.ThreadScanResult]
-    ) async throws
-        -> MatterAddDeviceExtensionRequestHandler.ThreadNetworkAssociation {
-        return .defaultSystemNetwork
+        from threadScanResults: [MatterAddDeviceExtensionRequestHandler.ThreadScanResult]
+    ) async throws -> MatterAddDeviceExtensionRequestHandler.ThreadNetworkAssociation {
+        .defaultSystemNetwork
     }
 }
 ```
 
-## Testing with HomeKit Accessory Simulator
+`AttestationChecker`, `CabinBackend` and `CabinFabric` stand for your own
+code. The three attestation values are the Device Attestation Certificate
+(DAC), the Product Attestation Intermediate (PAI) and the Certification
+Declaration (CD). Returning `.defaultSystemNetwork` from either selector lets
+the system choose the network.
+
+## Simulated accessories for testing
+
+The simulator is part of **Additional Tools for Xcode**, downloadable from the
+Apple developer downloads page.
+
+1. Open HomeKit Accessory Simulator.
+2. Create a few virtual accessories: a light, a lock, a sensor.
+3. Pair them with the app running on a device or in Simulator, then drive
+   scenes and triggers against them.
 
-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
+A debug-only dump helps when pairing looks wrong:
 
 ```swift
-// 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)")
+
+#if DEBUG
+let homeLog = Logger(subsystem: "com.example.cabin", category: "homekit")
+
+func dumpDevices(in house: HMHome) {
+    for device in house.accessories {
+        homeLog.debug("\(device.name) reachable=\(device.isReachable)")
+        for service in device.services {
+            homeLog.debug("  \(service.localizedDescription) [\(service.serviceType)]")
         }
     }
 }