dpearson2699/swift-ios-skills / skills/homekit
homekit
VerifiedControl 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.1 KB |
| evals/evals.json | config | 4.5 KB |
| references/matter-commissioning.md | markdown | 13.1 KB |
references/matter-commissioning.md
View on GitHub# HomeKit + Matter Extended Patterns
Overflow reference for the `homekit` skill. Contains advanced patterns
that exceed the main skill file's scope.
## 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 HomeKit Integration
### HomeKit Store with `@Observable`
```swift
import HomeKit
import SwiftUI
@Observable
@MainActor
final class HomeStore: NSObject {
static let shared = HomeStore()
let homeManager = HMHomeManager()
var homes: [HMHome] = []
var primaryHome: HMHome?
var isAuthorized = false
override init() {
super.init()
homeManager.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)
} else {
continuation.resume()
}
}
}
}
}
extension HomeStore: HMHomeManagerDelegate {
nonisolated func homeManagerDidUpdateHomes(_ manager: HMHomeManager) {
Task { @MainActor in
homes = manager.homes
primaryHome = manager.primaryHome
}
}
nonisolated func homeManager(
_ manager: HMHomeManager,
didUpdate status: HMHomeManagerAuthorizationStatus
) {
Task { @MainActor in
isAuthorized = status.contains(.authorized)
}
}
nonisolated func homeManager(
_ manager: HMHomeManager,
didAdd home: HMHome
) {
Task { @MainActor in
homes = manager.homes
}
}
nonisolated func homeManager(
_ manager: HMHomeManager,
didRemove home: HMHome
) {
Task { @MainActor in
homes = manager.homes
}
}
}
```
### Accessory List View
```swift
struct AccessoryListView: View {
@State private var homeStore = HomeStore.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.")
)
} else {
accessoryList
}
}
.navigationTitle(homeStore.primaryHome?.name ?? "Home")
}
}
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)
}
}
}
}
}
}
struct AccessoryRow: View {
let accessory: HMAccessory
var body: some View {
HStack {
Image(systemName: iconName)
VStack(alignment: .leading) {
Text(accessory.name)
.font(.headline)
Text(accessory.isReachable ? "Reachable" : "Not Reachable")
.font(.caption)
.foregroundStyle(accessory.isReachable ? .green : .secondary)
}
}
}
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"
}
}
}
```
### Light Control View
```swift
struct LightControlView: View {
let accessory: HMAccessory
@State private var isOn = false
@State private var brightness: Double = 100
private var lightbulbService: HMService? {
accessory.services.first {
$0.serviceType == HMServiceTypeLightbulb
}
}
private var powerCharacteristic: HMCharacteristic? {
lightbulbService?.characteristics.first {
$0.characteristicType == HMCharacteristicTypePowerState
}
}
private var brightnessCharacteristic: HMCharacteristic? {
lightbulbService?.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
}
}
brightnessCharacteristic?.readValue { _ in
if let value = brightnessCharacteristic?.value as? Int {
brightness = Double(value)
}
}
}
}
```
## Full Delegate Wiring
### HMHomeDelegate
```swift
extension HomeStore: HMHomeDelegate {
nonisolated func home(
_ home: HMHome,
didAdd accessory: HMAccessory
) {
accessory.delegate = self
Task { @MainActor in
// Refresh accessory list
}
}
nonisolated func home(
_ home: HMHome,
didRemove accessory: HMAccessory
) {
Task { @MainActor in
// Refresh accessory list
}
}
nonisolated func home(
_ home: HMHome,
didAdd room: HMRoom
) {
Task { @MainActor in
// Refresh room list
}
}
nonisolated func home(
_ home: HMHome,
didUpdateNameFor room: HMRoom
) {
Task { @MainActor in
// Update room name display
}
}
}
```
### 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")")
}
}
nonisolated func accessoryDidUpdateReachability(
_ accessory: HMAccessory
) {
Task { @MainActor in
print("\(accessory.name) reachable: \(accessory.isReachable)")
}
}
nonisolated func accessoryDidUpdateName(
_ accessory: HMAccessory
) {
Task { @MainActor in
// Refresh name display
}
}
}
```
## Service Type Discovery
### Finding Specific Service Types
```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 ?? "?")")
}
}
```
### Common Service Types
| Constant | Description |
|---|---|
| `HMServiceTypeLightbulb` | Light control (on/off, brightness, color) |
| `HMServiceTypeThermostat` | Temperature control |
| `HMServiceTypeLockMechanism` | Door lock |
| `HMServiceTypeGarageDoorOpener` | Garage door |
| `HMServiceTypeSwitch` | Generic on/off switch |
| `HMServiceTypeMotionSensor` | Motion detection |
| `HMServiceTypeTemperatureSensor` | Temperature reading |
| `HMServiceTypeContactSensor` | Door/window open/close |
### Common Characteristic Types
| Constant | Value Type | Description |
|---|---|---|
| `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 |
## Advanced Matter Extension Handler
### Full Handler with Network Selection
```swift
import MatterSupport
final class MyMatterHandler: MatterAddDeviceExtensionRequestHandler {
override func validateDeviceCredential(
_ deviceCredential:
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
}
}
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
)
}
override func commissionDevice(
in home: MatterAddDeviceRequest.Home?,
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
)
}
override func selectWiFiNetwork(
from networks:
[MatterAddDeviceExtensionRequestHandler.WiFiScanResult]
) async throws
-> MatterAddDeviceExtensionRequestHandler.WiFiNetworkAssociation {
// Use the system default network or specify one
return .defaultSystemNetwork
}
override func selectThreadNetwork(
from networks:
[MatterAddDeviceExtensionRequestHandler.ThreadScanResult]
) async throws
-> MatterAddDeviceExtensionRequestHandler.ThreadNetworkAssociation {
return .defaultSystemNetwork
}
}
```
## Testing with HomeKit Accessory Simulator
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
```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)")
}
}
}
#endif
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |