Matter 设备配网

Matter 设备配网支持涂鸦 Matter 设备和三方 Matter 设备配网，两者接入的 API 调用一致，但配网表现有不同。Matter 设备配网类型包含自发现、扫描二维码、手动输入编码配网三种方式。

设备要求

Matter 设备对 Android 系统有最低版本要求：

• Android O（6.0，API 级别 23 或更高版本）
• 所需权限：蓝牙权限、定位权限、Wi-Fi 权限

方式一：通过二维码或手动码解析配网

第一步：解析二维码或手动码

若二维码和手动码错误，则接口不会返回设备模型。

val payload = ThingActivatorCoreKit.getMatterOperateManager().checkMatterCodeInvalid(qrString)

参数说明

参数	说明
qrString	二维码或者手动设备码信息

第二步：连接设备

val builder = ConnectDeviceBuilder().apply {
                spaceId = homeId
                setupPayload = matterQrCodeBean
                timeout = 60
                connectCallback = object : IThingConnectDeviceCallback {
                    override fun onFound(
                        isThingMatter: Boolean,
                        deviceType: MatterDeviceTypeEnum?
                    ) {

                    }

                    override fun onConnected(connectResult: ConnectResult?) {

                    }

                    override fun onError(errorCode: String?, errorMsg: String?) {

                    }
                }
            }

ThingActivatorCoreKit.getMatterOperateManager().connectDevice(builder)

参数说明

参数	说明
spaceId	设备将要绑定的家庭 ID
setupPayload	刚扫码、手动输入码解析后的设备实体
timeout	超时时间，单位为秒（s）
connectCallback	连接回调

第三步：设备配网

SDK 会根据设备广播包自动选择最合适的配网链路，并回调给业务层进行相应的页面显示。共有三种类型：

• 涂鸦链路
• 分享配网链路
• 三方配网链路

val builder = ThingDeviceActiveBuilder().apply {
            connectResult = matterConnectResult
            matterPayload = matterQrCodeBean
            relationId = spaceId
            ssid = ssid
            password = password
            timeOut = timeOut
              gwId = gwId
            activeModel = ThingDeviceActiveModeEnum.MATTER
            listener = object :IThingMatterThirdPartDeviceActiveExt{
                override fun onActiveError(errorBean: ThingDeviceActiveErrorBean) {

                }

                override fun onActiveLimited(limitBean: ThingDeviceActiveLimitBean) {

                }

                override fun onActiveSuccess(deviceBean: DeviceBean) {

                }

                override fun onDeviceAttestationFailed(deviceControllerPtr: Long,devicePtr: Long,errorCode: Int){
                    //Uncertified device

                }

                override fun onBind(devId: String) {

                }

                override fun onFind(devId: String) {

                }

            }
        }
val activeManager = ThingActivatorCoreKit.getActiveManager().newThingActiveManager()
activeManager.startActive(builder)

参数说明

参数	说明
ssid	Wi-Fi 名称，如果是双模设备，该参数不可为空
password	Wi-Fi 密码，如果是双模设备，该参数不可为空
gwId	网关 ID，涂鸦 Thread 子设备配网绑定至对应网关下
connectResult	connect 接口返回的数据模型
matterPayload	解析配网码获取的设备模型
relationId	当前家庭 ID
timeout	超时时间，单位为秒（s）
activeModel	配网能力枚举
listener	配网结果回调

方式二：通过扫描配网附近 Matter 设备

第一步：扫描附近设备

SDK 提供发现处于配网状态的有线 Matter 网关设备、Thread 子设备、Matter 双模设备的功能。查询设备前，(发现有线 Matter 网关设备手机需与设备接入同一网络)，然后注册查询有线设备的通知。待 SDK 收到 Matter 设备的广播，即会通过通知转发设备信息。

val scanKey = ThingActivatorCoreKit.getScanDeviceManager()
            .startMatterDeviceSearch(120 * 1000, object : ThingActivatorScanCallback {
                override fun deviceFound(deviceBean: ThingActivatorScanDeviceBean) {

                }

                override fun deviceRepeat(deviceBean: ThingActivatorScanDeviceBean) {

                }

                override fun deviceUpdate(deviceBean: ThingActivatorScanDeviceBean) {

                }

                override fun scanFailure(failureBean: ThingActivatorScanFailureBean) {

                }

                override fun scanFinish() {

                }

            })

参数说明

参数	说明
timeout	超时时间，单位为毫秒（ms）

第二步：设备配网

SDK 会根据设备广播包自动选择最合适的配网链路，并回调给业务层进行相应的页面显示。共有三种类型，涂鸦链路，分享配网链路，以及三方配网链路。

val builder = ThingDeviceActiveBuilder().apply {
              thingActivatorScanDeviceBean = scanDevicebean
            relationId = spaceId
            ssid = ssid
            password = password
            timeOut = timeOut
              gwId = gwId
            activeModel = ThingDeviceActiveModeEnum.MATTER_DISCOVERY
            listener = object :IThingMatterThirdPartDeviceActiveExt{
                override fun onActiveError(errorBean: ThingDeviceActiveErrorBean) {

                }

                override fun onActiveLimited(limitBean: ThingDeviceActiveLimitBean) {

                }

                override fun onActiveSuccess(deviceBean: DeviceBean) {

                }

                override fun onDeviceAttestationFailed(deviceControllerPtr: Long,devicePtr: Long,errorCode: Int){
                    //Uncertified device

                }

                override fun onBind(devId: String) {

                }

                override fun onFind(devId: String) {

                }

            }
        }
val activeManager = ThingActivatorCoreKit.getActiveManager().newThingActiveManager()
activeManager.startActive(builder)

参数说明

参数	说明
thingActivatorScanDeviceBean	扫描发现返回的设备实体
ssid	Wi-Fi 名称，如果是双模设备，该参数不可为空
password	Wi-Fi 密码，如果是双模设备，该参数不可为空
gwId	网关 ID，涂鸦 Thread 子设备配网绑定至对应网关下
relationId	当前家庭 ID
timeout	超时时间，单位为秒（s）
activeModel	配网能力枚举
listener	配网结果回调

设备认证回调

如果您配对的是一个未经过官方认证的 Matter 设备，那么会触发认证回调。如果触发了该回调，在您选择继续或放弃前，配网流程将会暂停。

fun onDeviceAttestationFailed(
        deviceControllerPtr: Long,
        devicePtr: Long,
        errorCode: Int
    )

参数说明

参数	说明
deviceControllerPtr	DeviceController 对象的指针
devicePtr	配网链路中的设备对象地址指针
errorCode	未通过认证的错误信息

信任未认证的设备并继续配网

如您认为该设备证书可以被信任，可以调用该接口继续配网。

ThingActivatorCoreKit.getMatterOperateManager()
                                    .continueCommissioningAfterAttestationFailure(
                                        deviceControllerPtr,
                                        devicePtr, true
                                    )

参数说明

参数	说明
deviceControllerPtr	设备 Controller 指针
devicePtr	配网设备指针
ignoreAttestationFailure	是否忽略认证继续配网： true：继续 false：取消

错误码

错误码	说明	备注
3000	分配 nodeId 失败	检查网络状态、检查是否为当前家庭管理员
3003	通过蓝牙连接设备失败	检查蓝牙和定位权限
3004	扫描 mDNS 广播超时	检查手机和设备是否在同一个局域网内
3005	commissionDevice 失败	-
3007	连接设备建立 PASE 会话超时	检查设备是否在配网状态
3008	commissionDevice 超时	-
3011	与设备连接 PASE 会话失败	-
3017	非涂鸦 Matter 设备激活失败	-
3019	网关不存在或网关局域网不在线	检查当前手机是否和网关是否在同一局域网内
3013	通用错误码	-
10002	参数不合法	-
10003	创建配网 Token 失败	-