homekit

HomeKit

控制家庭自动化配件并为 Matter 设备配网。HomeKit 管理家庭／房间／配件模型、操作集和触发器。MatterSupport 负责将设备配网到你的生态系统中。

目录

• 设置
• HomeKit 数据模型
• 管理配件
• 读取和写入特征
• 操作集和触发器
• Matter 配网
• MatterAddDeviceExtensionRequestHandler
• 常见错误
• 检查清单
• 参考资料

设置

HomeKit 配置

1. 在 Xcode 中启用 HomeKit 功能（Signing & Capabilities）
2. 在 Info.plist 中添加 NSHomeKitUsageDescription：

<key>NSHomeKitUsageDescription</key>
<string>This app controls your smart home accessories.</string>

MatterSupport 配置

要将 Matter 设备配网到你自己的生态系统中：

1. 添加 MatterSupport Extension 目标，并将其主类设为某个 MatterAddDeviceExtensionRequestHandler 子类
2. 为 _matter._tcp、_matterc._udp 和 _matterd._udp 添加 NSBonjourServices 条目
3. 仅当调用方以编程方式提供 Matter 设置载荷时，才添加 com.apple.developer.matter.allow-setup-payload

框架边界

需求	框架
家庭、房间、配件、特征、操作、触发器	HomeKit
将 Matter 配网到应用生态系统中	MatterSupport
选择并授权附近的蓝牙或 Wi-Fi 配件	AccessorySetupKit
选择后交换蓝牙 GATT 数据	CoreBluetooth
选择后加入或配置配件的 Wi-Fi 网络	NetworkExtension

HomeKit 数据模型

HomeKit 以层级结构组织家庭自动化：

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)

初始化 Home Manager

创建一个 HMHomeManager，并实现代理，以便获知数据何时加载完成。HomeKit 会异步加载——代理方法触发前，不要访问 homes。

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")
        }
    }
}

访问房间

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()

管理配件

发现并添加配件

添加配件前，请先查看框架边界表；此技能仅涵盖后续的 HomeKit/MatterSupport 工作。

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

列出配件和服务

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")")
        }
    }
}

将配件移至房间

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)")
    }
}

读取和写入特征

读取值

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)")
    }
}

写入值

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

观察变更

启用通知以接收实时更新：

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")")
}

操作集和触发器

创建操作集

HMActionSet 将一起执行的特征写入操作分组：

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")
    }
}

执行操作集

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

创建定时器触发器

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

创建事件触发器

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 配网

使用 MatterAddDeviceRequest 将 Matter 设备配网到你的生态系统中。这与 HMHome 家庭自动化模型相互独立；它负责处理 Matter 设置流程，并调用 MatterSupport 扩展。

基本配网

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()
}

直接提供设置代码时，请导入 Matter，并将 MTRSetupPayload 作为 setupPayload 传入；这种情况需要设置载荷权限。

筛选设备

// Only show devices from a specific vendor
let criteria = MatterAddDeviceRequest.DeviceCriteria.vendorID(0x1234)

let request = MatterAddDeviceRequest(
    topology: topology,
    setupPayload: nil,
    showing: criteria
)

使用 .all([.vendorID(...), .not(.productID(...))]) 组合条件；如果满足任一条件即可，则使用 .any(...)。

MatterAddDeviceExtensionRequestHandler

要获得完整的生态系统支持，请创建 MatterSupport Extension。该扩展负责处理配网回调。重写所需的方法，但不要在这些重写方法中调用 super。 加载完整的高级 Matter 扩展处理程序，了解凭据验证、房间选择、配置、配网和网络关联相关的重写方法。

常见错误

错误	修复方法
委托更新前读取 homes	创建一个 manager，设置其委托，并等待 homeManagerDidUpdateHomes。
使用 HomeKit 设置为 Matter 生态系统配对设备	使用 MatterAddDeviceRequest 和已配置的 MatterSupport 扩展。
Matter 配置不完整	验证主处理程序、Bonjour 服务，并且仅在适用时验证设置载荷权利。
多个 HMHomeManager 实例加载数据库	共享一个保留的 manager/store。
写入 characteristic 时忽略元数据	写入前检查权限、格式、最小值/最大值/步长和允许的值。

审核清单

• 在 Xcode 中启用 HomeKit capability
• Info.plist 中包含 NSHomeKitUsageDescription
• 整个应用共享单个 HMHomeManager 实例
• 已实现 HMHomeManagerDelegate；在 homeManagerDidUpdateHomes 之前不访问 homes
• 为 homes 设置 HMHomeDelegate，以接收 accessory 和 room 变更
• 为 accessories 设置 HMAccessoryDelegate，以接收 characteristic 更新
• 写入值之前检查 characteristic 元数据
• 在所有 completion handlers 中进行错误处理
• 已配置 MatterSupport 扩展 target 和主处理程序
• 已添加 Matter 发现所需的 NSBonjourServices 条目
• 仅在提供设置代码时使用 com.apple.developer.matter.allow-setup-payload
• 执行请求前检查 MatterAddDeviceRequest.isSupported
• Matter 扩展处理程序实现 commissionDevice(in:onboardingPayload:commissioningID:)
• 发布前使用 HomeKit Accessory Simulator 测试 action sets
• 创建后启用 triggers（trigger.enable(true)）

参考资料

• 扩展模式（Matter 扩展、委托连接、SwiftUI）：references/matter-commissioning.md
• HomeKit 框架
• HMHomeManager
• HMHome
• HMAccessory
• HMRoom
• HMActionSet
• HMTrigger
• MatterSupport 框架
• MatterAddDeviceRequest
• MatterAddDeviceExtensionRequestHandler
• 在应用中启用 HomeKit
• 为生态系统添加 Matter 支持