Android Matter SDK

基于 Google Home APIs 和 connectedhomeip 的 Matter 开发完整指南。

Matter 1.4.1Android 8.1+GA

概述

Android 的 Matter 开发涉及三层 SDK：Google 的上层 API（配网和设备管理）、开源 connectedhomeip（协议栈和 Cluster 控制）、以及 Thread 网络 SDK。

2026 年 8 月，Google Home APIs 正式 GA（v1.10.1），提供了配网、设备控制和自动化的统一接口。新项目建议直接使用 Home APIs，旧项目可继续沿用 Legacy Mobile SDK。

SDK 选择

根据项目需求选择合适的 SDK 组合：

SDK	Maven 坐标	能力范围	适用场景
Home APIs (新)	play-services-home:17.0.0 + play-services-home-types:17.0.0	配网 + 控制 + 自动化	新项目首选
Legacy Mobile SDK	play-services-home:16.0.0	仅配网和分享	已有项目维护
connectedhomeip	从源码构建 / demo SDK	完整协议栈，Cluster 级控制	自定义 Fabric / 无 GPS 设备
Thread Network SDK	play-services-threadnetwork:16.2.1	Thread 凭据管理	配合 Thread 设备使用

配网流程

Android 配网采用两层架构：Google Play Services 处理 BLE 发现、PASE 会话和网络配置；完成后回调到你的 CommissioningService，在自有 Fabric 上完成入网。

1用户扫描 QR 码

2App 调用 CommissioningClient.commissionDevice()

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

4GPS 下发 WiFi/Thread 凭据，设备入网

5GPS 签发 NOC，设备加入 Android Fabric

6回调你的 CommissioningService.onCommissioningRequested()

7你的 App 通过 ChipDeviceController 配网到自有 Fabric

8调用 sendCommissioningComplete() 完成流程

设备控制

配网完成后，通过 connectedhomeip 的 Cluster API 控制设备。每个 Matter Cluster 对应一个 Java/Kotlin 类。

kotlin开关控制示例

// 获取已连接设备的指针
val devicePtr = suspendCoroutine<Long> { cont ->
    controller.getConnectedDevicePointer(nodeId,
        object : GetConnectedDeviceCallback {
            override fun onDeviceConnected(ptr: Long) = cont.resume(ptr)
            override fun onConnectionFailure(id: Long, e: Exception) =
                cont.resumeWithException(e)
        })
}

// 创建 OnOff Cluster 实例并发送命令
val cluster = ChipClusters.OnOffCluster(devicePtr, endpointId)
cluster.toggle(object : ChipClusters.DefaultClusterCallback {
    override fun onSuccess() { /* 设备已切换 */ }
    override fun onError(ex: Exception) { /* 处理错误 */ }
})

读取设备类型与能力

配网完成后，读 Descriptor（0x001D）就能知道设备有哪些端点、每个端点是什么类型、有哪些 Cluster；再读各 Cluster 的 FeatureMap / AcceptedCommandList 就知道具体能力。字段含义见概念总览 · 配网后怎么读出设备能力，读到的数字可以用 Matter ID 查询翻译。

kotlin读 Descriptor 与 FeatureMap

// 1. 端点 0 的 PartsList：设备有哪些端点
val root = ChipClusters.DescriptorCluster(devicePtr, 0)
root.readPartsListAttribute(object :
    ChipClusters.DescriptorCluster.PartsListAttributeCallback {
    override fun onSuccess(endpoints: List<Int>) {
        endpoints.forEach { ep -> readEndpoint(devicePtr, ep) }
    }
    override fun onError(ex: Exception) { /* 处理错误 */ }
})

// 2. 每个端点的 DeviceTypeList / ServerList：是什么、有哪些 Cluster
fun readEndpoint(devicePtr: Long, ep: Int) {
    val descriptor = ChipClusters.DescriptorCluster(devicePtr, ep)
    descriptor.readDeviceTypeListAttribute(object :
        ChipClusters.DescriptorCluster.DeviceTypeListAttributeCallback {
        override fun onSuccess(types: List<ChipStructs.DescriptorClusterDeviceTypeStruct>) {
            // 门锁端点会得到 0x000A（门锁）和 0x0011（电源）
            types.forEach { Log.d(TAG, "EP$ep type=0x%04X rev=%d".format(it.deviceType, it.revision)) }
        }
        override fun onError(ex: Exception) {}
    })
    descriptor.readServerListAttribute(object :
        ChipClusters.DescriptorCluster.ServerListAttributeCallback {
        override fun onSuccess(clusters: List<Long>) { /* 例如 [3, 29, 47, 257] */ }
        override fun onError(ex: Exception) {}
    })
}

// 3. 某个 Cluster 开了哪些可选功能：FeatureMap（全局属性 0xFFFC）
ChipClusters.DoorLockCluster(devicePtr, 1).readFeatureMapAttribute(object :
    ChipClusters.LongAttributeCallback {
    override fun onSuccess(value: Long) {
        val supportsFingerprint = (value and (1L shl 2)) != 0L  // bit 2 = FGP
    }
    override fun onError(ex: Exception) {}
})