Matter Device Pairing

Matter device pairing applies to both the Tuya-enabled and third-party Matter devices. The API calls for both types of devices remain consistent, but their pairing behavior differs. Matter device pairing supports auto-discovery, QR code scan, and manual setup code.

System requirements

To control a Matter device, the following requirements must be met.

• Android O (6.0, API level 23 or later).
• Required permissions: Bluetooth, location, and Wi-Fi.

Method 1: QR code or manual setup code

Step 1: Parse QR code or manual setup code

If the code is wrong, the device model is not returned.

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

Parameter description

Step 2: Connect to a device

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)

Parameter description

Step 3: Pair a device

The SDK automatically selects the optimal pairing option based on the advertising data. It then sends the selection to the business layer through the callback for displaying on the respective app page. There are three pairing options:

• Tuya-specific pairing
• Sharing and pairing
• Third-party pairing

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)

Parameter description

Method 2: Matter device scan

Step 1: Scan for nearby devices

The SDK can discover wired Matter gateways, Thread sub-devices, and Matter combo devices in pairing mode. Before the scan, register the notification of the scan result. For a wired Matter gateway, it must be on the same network as the mobile phone in order to be discovered. When the SDK receives the Matter broadcast packet, it forwards the device information through a notification.

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

                }

            })

Parameter description

Step 2: Pair a device

The SDK automatically selects the optimal pairing option based on the advertising data. It then sends the selection to the business layer through the callback for displaying on the respective app page. There are three pairing options: Tuya-specific pairing, sharing and pairing, and third-party pairing.

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)

Parameter description

Device attestation callback

The callback to invoke when an attempt is made to pair a device that is not Matter-certified. After this callback is invoked, the pairing process will be suspended until the user chooses to continue or cancel.

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

Parameter description

Trust uncertified device and continue pairing

If the user chooses to add an uncertified Matter device, call this method to continue the pairing process.

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

Parameter description

Error codes