iOS Matter SDK

基于 Apple 系统框架的 Matter 开发指南，覆盖 MatterSupport 扩展和 Cluster 控制。

Matter 1.4+iOS 16.1+成熟

概述

iOS 的 Matter 支持内建于系统框架中，开发者使用两个核心框架：Matter.framework（底层协议栈，提供 Cluster 级控制）和 MatterSupport（高层配网扩展，让第三方 App 参与 Apple Home 的配网流程）。

Matter.framework 从 iOS 16.0 开始提供，目前已进入第 4 个 OS 周期，Cluster API 持续扩充。MatterSupport 从 iOS 16.1 开始可用，是第三方 App 接入 Matter 生态的推荐方式。

框架选择

iOS 上 Matter 开发涉及三个框架，各自定位不同：

框架	定位	适用场景	最低版本
MatterSupport	高层配网扩展	第三方 App 参与 Apple Home 配网流程	iOS 16.1
Matter.framework	底层协议栈	直接 Cluster 控制、独立 Fabric 管理	iOS 16.0
HomeKit	Apple Home 桥接	获取已入网设备的 matterNodeID 后用 Matter.framework 控制	iOS 16.1

配网流程

第三方 App 通过实现 MatterSupport Extension 参与系统配网流程。系统处理 BLE 发现和 PASE 会话，你的扩展在关键节点介入。

1App 创建 MatterAddDeviceRequest 并调用 perform()

2系统弹出配网 UI，扫描 QR 码或手动输入

3系统通过 BLE 发现设备，建立 PASE 会话

4你的扩展收到 validateDeviceCredential 回调

5你的扩展选择 WiFi 或 Thread 网络

6你的扩展在 commissionDevice 中配网到自有 Fabric

7你的扩展在 configureDevice 中保存设备配置

设备控制

iOS 提供两种 Cluster API 模式：Stateless（MTRBaseCluster，直接网络操作）和 Stateful（MTRCluster，带本地缓存的订阅模式）。

swift开关控制示例

import Matter

// 创建 Stateless 设备代理
let device = MTRBaseDevice(nodeID: nodeID, controller: controller)
let onOff = MTRBaseClusterOnOff(
    device: device,
    endpointID: NSNumber(value: 1),
    queue: .main
)

// 切换开关状态
try await onOff.toggle()

// 读取当前状态
let isOn = try await onOff.readAttributeOnOff()

读取设备类型与能力

用 MTRBaseClusterDescriptor 读 Descriptor（0x001D）拿到端点、设备类型和 Cluster 列表；也可以用 readAttributes 做通配读取，一次拿回全部原始属性。字段含义见概念总览 · 配网后怎么读出设备能力，读到的数字可以用 Matter ID 查询翻译。

swift读 Descriptor 与通配读取

import Matter

let device = MTRBaseDevice(nodeID: nodeID, controller: controller)

// 1. 端点 0 的 PartsList：设备有哪些端点
let root = MTRBaseClusterDescriptor(device: device, endpointID: 0, queue: .main)
let endpoints = try await root.readAttributePartsList() as? [NSNumber] ?? []

for ep in endpoints {
    let descriptor = MTRBaseClusterDescriptor(device: device, endpointID: ep, queue: .main)

    // 2. 这个端点是什么设备（门锁端点：0x000A 门锁 + 0x0011 电源）
    let types = try await descriptor.readAttributeDeviceTypeList()
        as? [MTRDescriptorClusterDeviceTypeStruct] ?? []
    for t in types {
        print("EP(ep) type=0x(String(t.deviceType.uint32Value, radix: 16)) rev=(t.revision)")
    }

    // 3. 这个端点有哪些 Cluster
    let servers = try await descriptor.readAttributeServerList() as? [NSNumber] ?? []
}

// 或者：通配读取，一次拿回设备全部原始属性（三个参数都传 nil）
let all = try await device.readAttributes(withEndpointID: nil, clusterID: nil,
                                          attributeID: nil, params: nil, queue: .main)