Pair Matter Device

Pairing process

Discover Matter device

Matter devices can be discovered in the following two ways:

• Scan QR code or enter setup code

  A standard pairing method for Matter devices, including Tuya-enabled Matter devices and third-party Matter devices.

• Pair by auto discovery

  Tuya’s proprietary method, currently exclusive to Tuya-enabled Matter devices.

Method 1: Scan QR code or enter setup code

This is the standard method of pairing Matter devices. You can pass the content of the Matter pairing QR code scanned by users or the Matter setup code entered by users to the SDK for parsing. Then, return the parsed object SetupPayload and proceed to the steps as illustrated in the pairing flowchart.

Before device pairing, validate the QR code or setup code attached to the device to ensure a valid Matter setup code is used.

API description

private IMatterActivator mMatterDevActivatorInstance;
...
  mMatterDevActivatorInstance = ThingHomeSdk.getMatterDevActivatorInstance();
if (null == mMatterDevActivatorInstance) return;
SetupPayload setupPayload = mMatterDevActivatorInstance.parseSetupCode("MT:xxxxxxxxx");
if (setupPayload != null) {
  Log.w("parseSetupCode",setupPayload.toString());
}else {
  Log.w("parseSetupCode","Matter Illegal network code");
}

Parameters

Parameter	Description
setupCodeString	The QR code, sharing code, or setup code on the device outer packaging.

Data model

The following table defines the fields in the model SetupPayload.

Property	Type	Description
version	int	The version of the pairing protocol.
vendorId	int	The ID of the manufacturer.
productId	int	The product ID (PID).
setupPinCode	long	The 8-bit random number.
discriminator	Discriminator	The data model of the device identifier.

Method 2: Pair by auto discovery

After users start this pairing method, nearby Matter devices that support this method can be automatically found.

API description

private IMatterDiscoveryActivator mDiscoveryActivatorInstance;
...
  mDiscoveryActivatorInstance = ThingHomeSdk.getDiscoveryActivatorInstance();
if (null== mDiscoveryActivatorInstance)return;
mDiscoveryActivatorInstance.startDiscovery(new IDynamicDiscoveryListener() {
  @Override
  public void onFound(ThingMatterDiscovery discovery) {
    Log.i("startDiscovery","onFound: "+discovery.toString());
  }

  @Override
  public void onError(String errorCode, String errorMsg) {
    Log.e("startDiscovery","onError, errorCode: "+errorCode+" errorMsg: "+errorMsg);
  }
});
}

Parameters

Parameter	Description
discoveryListener	The listener for discovering a device.

Stop auto discovery

API description

void stopDiscovery();

Example

mDiscoveryActivatorInstance.stopDiscovery();

Connect to Matter device

To pair a Matter device, first, parse the setup code of the Matter device, get the SetupPayload model object, and then connect to the Matter device. This way, the device can be commissioned and activated in the cloud.

After the Matter device is connected, the PASE (Passcode-Authenticated Session Establishment) session is established, and the PASE session success callback is invoked.

API description

ConnectDeviceBuilder builder = new ConnectDeviceBuilder();
builder.setSetupPayload(setupPayload);
builder.setSpaceId(homeId);
builder.setTimeout(timeout);
builder.setConnectCallback(new IThingConnectDeviceCallback() {
  @Override
  public void onFound(boolean isThingMatter, MatterDeviceTypeEnum deviceType) {
    // isThingMatter determines whether this is a Tuya-enabled device. Valid values: true: Tuya-enabled device. false: third-party device

  }

  @Override
  public void onConnected(ConnectResult connectResult) {

  }

  @Override
  public void onError(String errorCode, String errorMsg) {

  }
});
mMatterDevActivatorInstance.connectDevice(builder);

Parameters

Parameter	Description	Description
setupPayload	SetupPayload	The device model that is returned after the setup code is parsed.
homeId	long	The home ID. For more information, see Home Management.
timeout	long	The timeout value of a pairing task. Unit: ms.
thingConnectDeviceCallback	IThingConnectDeviceCallback	The callback.

After connectDevice is called successfully, the device type indicated by MatterDeviceTypeEnum is returned.

Data model

ConnectResult is the model that is returned after a Matter device is connected. The following table defines the fields in this model:

Property	Type	Description
discoveryType	DiscoveryType	The device capability of communication through a PASE session. Valid values: DiscoveryType.BLE: discovery via Bluetooth DiscoveryType.MDNS: discovery over multicast DNS (mDNS)
ipAddress	String	The ID assigned by the router to the device. The value is empty when discovery over Bluetooth Low Energy (LE) is used.
port	int	The port assigned by the router to the device. The value is empty when discovery over LE is used.
thingProductId	String	The product ID assigned by the cloud. The value is empty for Tuya-enabled Wi-Fi and Bluetooth combo devices.
accessType	int	Indicates whether this is a Tuya-enabled device by checking cloud services. Valid values: 0: Tuya-enabled Matter device 1: third-party Matter device
isThingMatter	boolean	Indicates whether this is a Tuya-enabled device by parsing advertising data from the device. Valid values: true: Tuya-enabled Matter device false: third-party Matter device
nodeId	long	The ID of the node assigned to the paired device.
typeEnum	MatterDeviceTypeEnum	The type of device.
gwId	String	The gateway ID of the OpenThread Border Router (OTBR) that is associated with a Thread device.

Get pairing token

Get a token

Before the pairing process, the SDK must get a pairing token from the cloud in the networked state. The token is valid for 10 minutes and expires immediately after the device is paired. A new token must be obtained if the device needs to be paired again.

ThingHomeSdk.getActivatorInstance().getActivatorToken(homeId,new IThingActivatorGetToken() {

  @Override
  public void onSuccess(String token) {

  }

  @Override
  public void onFailure(String s, String s1) {

  }
});

Parameters

Parameter	Description
homeId	The home ID. For more information, see Home Management.

Commission device

API description

CommissioningParameters commissioningParameters = new CommissioningParameters.Builder()
  .connectDeviceResult(connectResult)
  .setupPayload(setupPayload)
  .spaceId(homeId)
  .token(token)
  .ssid(wifiSSId)
  .password(wifiPwd)
  .timeOut(timeout)
  .build();
mMatterDevActivatorInstance.commissionDevice(commissioningParameters, new MatterActivatorCallback() {
  @SuppressLint("MissingPermission")
  @Override
  public void onActivatorSuccess(DeviceBean result) {

  }

  @Override
  public void onError(String errorCode, String errorMessage) {

  }

  @Override
  public void onDeviceAttestationFailed(long deviceControllerPtr, long devicePtr, int errorCode){
    // Device attestation failed.
  }
});

Parameters

Parameter	Description	Description
setupPayload	SetupPayload	The device model that is returned after the setup code is parsed.
homeId	long	The home ID. For more information, see Home Management.
timeout	long	The timeout value of a pairing task. Unit: ms.
connectResult	ConnectResult	The model returned by connectDevice.
token	String	The pairing token returned from the cloud.
wifiSSId	String	The SSID of the Wi-Fi network connected to by the device. The value cannot be empty for a comb device.
wifiPwd	String	The password of the Wi-Fi network connected to by the device. The value cannot be empty for a comb device.
gwId	String	The gateway ID. A Tuya-enabled Thread sub-device can be bound with the specified gateway during pairing.

To establish a PASE session with a Thread sub-device, assemble parameters in the following ways:

• Pairing the sub-device relies on the OTBR network provided by the Matter gateway. Therefore, you must set the gateway ID before a CASE session is established.
• In a PASE session, the SDK scans for available Thread networks nearby and selects the optimal gateway ID whose network shows the strongest signal strength. In the callback void onConnected(ConnectResult connectResult);, ConnectResult provides a list of available gateway IDs indicated by gwId. If this parameter is empty or users want to specify a gateway, use a gateway ID for the current home.

Confirm device attestation

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 you choose to continue or give up pairing.

API description

void onDeviceAttestationFailed(long deviceControllerPtr, long devicePtr, int errorCode);

Parameters

Parameter	Description
deviceControllerPtr	The pointer to the DeviceController object.
device	The pointer to the device object address in the pairing option.
error	The error message that is returned when device attestation failed.

Example

@Override
public void onDeviceAttestationFailed(long deviceControllerPtr, long devicePtr, int errorCode){
    // Device attestation failed.
}

Continue or stop pairing

Continues pairing if the device certificate is regarded to be trustable, or stops pairing.

API description

mMatterDevActivatorInstance.continueCommissioningDevice(deviceControllerPtr,devicePtr,ignoreAttestationFailure);

Parameters

Parameter	Description	Description
deviceControllerPtr	long	The pointer to the DeviceController object.
devicePtr	long	The pointer to the device object address in the pairing option.
ignoreAttestationFailure	boolean	Specifies whether to ignore the attestation failure. true: yes false: no

Cancel or terminate pairing

API description

mMatterDevActivatorInstance.cancelActivator();

Error codes

Error code	Description	Remarks
3000	Failed to assign nodeId.	Check the network status and determine whether the user is the administrator of the current home.
3003	Failed to connect to the device over Bluetooth.	Check whether the Bluetooth and location permissions are granted.
3004	A timeout error has occurred while scanning for mDNS advertising data.	Check whether the mobile phone and device run on the same LAN.
3005	Failed to implement commissionDevice.	None.
3007	A timeout error has occurred while establishing a PASE session with a connected device.	Check whether the device is ready for pairing.
3008	commissionDevice timed out.	None.
3011	Failed to establish a PASE session with a connected device.	None.
3017	Failed to activate a third-party Matter device.	None.
3019	The specified gateway does not exist or the gateway is not online on a LAN.	Check whether the mobile phone and the gateway run on the same LAN.
3013	A global error code.	None.