iOS Matter SDK

A guide to Matter development with Apple system frameworks, covering MatterSupport extensions and Cluster control.

Matter 1.4+iOS 16.1+Mature

Overview

iOS Matter support is built into the system frameworks. Developers use two core frameworks: Matter.framework (low-level protocol stack with Cluster-level control) and MatterSupport (high-level commissioning extension that lets third-party apps join Apple Home's commissioning flow).

Matter.framework shipped with iOS 16.0 and is now in its 4th OS cycle with continuously expanding Cluster APIs. MatterSupport, available from iOS 16.1, is the recommended path for third-party apps.

Framework Selection

iOS Matter development involves three frameworks, each with a distinct role:

Framework	Role	Use Case	Min Version
MatterSupport	High-level commissioning extension	Third-party apps joining Apple Home commissioning	iOS 16.1
Matter.framework	Low-level protocol stack	Direct Cluster control, standalone fabric management	iOS 16.0
HomeKit	Apple Home bridge	Get matterNodeID from HMAccessory, then use Matter.framework	iOS 16.1

Commissioning Flow

Third-party apps participate in system commissioning by implementing a MatterSupport Extension. The system handles BLE discovery and PASE sessions; your extension intervenes at key steps.

1App creates MatterAddDeviceRequest and calls perform()

2System presents commissioning UI with QR scanning

3System discovers device via BLE and establishes PASE session

4Your extension receives validateDeviceCredential callback

5Your extension selects WiFi or Thread network

6Your extension commissions to your own fabric in commissionDevice

7Your extension saves device configuration in configureDevice

Device Control

iOS offers two Cluster API patterns: Stateless (MTRBaseCluster, direct network operations) and Stateful (MTRCluster, subscription-based local cache).

swiftOnOff Control Example

import Matter

// Create a stateless device proxy
let device = MTRBaseDevice(nodeID: nodeID, controller: controller)
let onOff = MTRBaseClusterOnOff(
    device: device,
    endpointID: NSNumber(value: 1),
    queue: .main
)

// Toggle the switch
try await onOff.toggle()

// Read current state
let isOn = try await onOff.readAttributeOnOff()

Reading device types and capabilities

Use MTRBaseClusterDescriptor to read the Descriptor cluster (0x001D) for endpoints, device types and cluster lists, or call readAttributes with wildcards to fetch every raw attribute at once. See Concepts · Reading a device's capabilities for what each field means, and translate the numbers with the Matter ID Lookup.

swiftReading Descriptor and a wildcard read

import Matter

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

// 1. PartsList on endpoint 0: which endpoints exist
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. What this endpoint is (lock endpoint: 0x000A Door Lock + 0x0011 Power Source)
    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. Which clusters this endpoint has
    let servers = try await descriptor.readAttributeServerList() as? [NSNumber] ?? []
}

// Or: a wildcard read returns every raw attribute at once (pass nil for all three)
let all = try await device.readAttributes(withEndpointID: nil, clusterID: nil,
                                          attributeID: nil, params: nil, queue: .main)

Limitations & Caveats

Key limitations in iOS Matter development:

Thread Device Commissioning Blocked

MatterSupport extensions cannot commission Thread devices (returns "Thread Border Router Required" error). This is a known bug (FB15614070). Only the Apple Home app on iOS 18+ with compatible iPhones supports Thread device direct pairing.

Developer Profile Required

The "Bluetooth Central Matter Client Developer Mode" profile must be installed on all test devices (iPhone, HomePod, Apple TV). Without it, BLE commissioning silently fails. The profile expires periodically.

TestFlight Commissioning Issues

TestFlight builds may fail commissioning on devices without the Matter Client Developer Profile.

Separate Fabric Isolation

Commissioning directly via Matter.framework (not through Apple Home) creates a separate fabric. Devices will not appear in Apple Home. Use MatterSupport for production.