Pair Matter Device

Last Updated on : 2024-02-21 07:25:24

Pairing process

AppMatter deviceCloudProcess of pairing Matter deviceCheck whetherQRCode is validBuildConnectDeviceBuilde-rConnect to deviceBuilt successfullyBuildCommissioningParam-etersCommission deviceAttest deviceIgnore attestation failureActivated successfullyAppMatter deviceCloudPairing 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

Before pairing by auto discovery, the app must be granted access to Bluetooth, and the mobile phone is connected to a Wi-Fi network.

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.

The device types indicated by MatterDeviceTypeEnum include:

  • UN_KNOW: unknown device type
  • WIFI: Tuya-enabled Wi-Fi and Bluetooth combo device
  • THREAD: Tuya-enabled Thread device
  • ON_NETWORK: gateway

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.