Matter Devices

What is Matter?

The Matter standard, organized by the Connectivity Standards Alliance (CSA, formerly the Zigbee Alliance), is jointly promoted by Amazon, Google, Apple, and the CSA. Matter aims to allow all IoT devices to become interoperable and implement device control simply on top of a single protocol. This topic describes how to implement management and control of Matter devices after they are integrated into your project.

Preparation

Before a Matter device comes into use, you must finish the configuration of the development project and implement pairing with the Matter device. For more information, see the documentation on pairing Matter devices.

Then, the Matter device can be added to your app for further use.

Determine Matter device

API description

DeviceBean.java

boolean isMatter();

Example

Java:

DeviceBean deviceBean = ThingHomeSdk.getDataInstance().getDeviceBean(devId);
if(deviceBean != null) {
  boolean isMatter = deviceBean.isMatter();
}

Control Matter device

Similarly to a generic type of device, call publishDps to send a device control data point (DP).

IThingDevice iThingDevice = ThingHomeSdk.newDeviceInstance(devId);
iThingDevice.publishDps(dps, new IResultCallback() {
  @Override
  public void onError(String code, String error) {

  }

  @Override
  public void onSuccess() {

  }
});

The following table lists the channels supported by Matter devices.

Device type	Supported channel	Remarks
Tuya-enabled Matter over Wi-Fi device	Matter local area network (LAN) channel MQTT channel	Tuya’s LAN channel requires support by hardware firmware in the near future.
Tuya-enabled Matter gateway	Matter LAN channel Tuya’s LAN channel MQTT channel	None.
Tuya-enabled Matter over Thread device	Matter LAN channel Tuya’s LAN channel MQTT channel	None.
Third-party Matter device	Matter LAN channel	None.

Determine whether Matter device is online

Similarly to other types of devices, use the isOnline field of DeviceBean to determine whether a Matter device is online or offline.

API description

DeviceBean.java

boolean getIsOnline();

Example

Java:

DeviceBean deviceBean = ThingHomeSdk.getDataInstance().getDeviceBean(devId);
if(deviceBean != null) {
  boolean isMatter = deviceBean.getIsOnline();
}

Multiple Fabrics

The Multiple Fabrics feature is exclusive to Matter devices. This feature allows a Matter device to be interoperable among different manufacturers and ecosystems. Therefore, this device can be activated and used seamlessly on multiple Matter-enabled apps. For example, the Matter device can be used on a Tuya-enabled app, such as the Smart Life app. It can also be accessed with Apple Home, Google Home, and Amazon Alexa.

The Multiple Fabrics feature includes two parts: share among fabrics and manage fabrics.

Check channel availability

Check if the mobile app can communicate with the device before you invoke sharing among fabrics and fabrics management.

Channel availability check for SDK v2.1.0-cube or later

API description

boolean checkPipelineAvailable();

Example

Java:

IThingMatterMultipleFabricDevice mThingMatterFabricDevice;
...
private void preCheck(String devId){
   mThingMatterFabricDevice = ThingHomeSdk.newMatterMultipleFabricDeviceInstance(devId);
   boolean pipelineAvailable = mThingMatterFabricDevice.checkPipelineAvailable();
}

Share among fabrics

Sharing among fabrics for SDK v2.1.0-cube or later

Before using the API, you can invoke a channel availability check for SDK v2.1.0-cube or later.

Open window for sharing and pairing

This API incorporates all the necessary methods to share devices across fabrics. You can request the maximum number of supported fabrics, the number of used fabrics, and the SSID of the Wi-Fi network connected by the device, and open and close the window for sharing and pairing.

API description

void sendEnhancedCommissioningCommand(boolean forceRefresh, IThingMultipleFabricCallback callback);

Example

Java:

private void openECM() {
mThingMatterMultipleFabricDevice.sendEnhancedCommissioningCommand(true, new IThingMultipleFabricCallback() {
@Override
public void onNetworkInfo(String ssid) {
    Log.d(TAG,"device ssId: "+ssid);
}

@Override
public void onSuccess(IThingMatterMultipleFabricDevice.SetupCodePayload setupCodePayload) {
    Log.d(TAG,"open ecm success: "+setupCodePayload.toString());
}

@Override
public void onError(String errorCode, String errorMessage) {
    Log.d(TAG,"open ecm fail: "+errorCode);
}
});

Manage fabrics

Matter devices can be used on multiple Matter-enabled apps. The following sections describe how to get the list of fabrics among which a Matter device is shared and revoke the sharing permission.

Get list of fabrics

API description

void readFabrics(IThingDataCallback<List<OperationalFabricInfo>> callback);

Data model

The following table defines the fields in the model OperationalFabricInfo.

Property	Type	Description
vendorId	Integer	The ID of the manufacturer.
nodeId	Long	The value of nodeId provided by the specified fabric during pairing.
fabricId	Long	The value of fabricId provided by the specified fabric during pairing.
fabricIndex	String	The value of index provided by the specified fabric during pairing.
label	NSString	The value of label provided by the specified fabric during pairing.
isCurrent	boolean	Indicates whether the current app is working with the specified fabric.

Example

Java:

public void readFabrics() {
  if (mThingMatterFabricDevice == null) {
    return;
  }
  mThingMatterFabricDevice.readFabrics(new IThingDataCallback<List<OperationalFabricInfo>>() {
    @Override
    public void onSuccess(List<OperationalFabricInfo> result) {
      if (result != null) {
        Log.d("readFabrics", "ReadFabrics success: Result = " + Arrays.toString(result.toArray()));
      }
    }

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

      Log.e("readFabrics", "ReadFabrics error: ErrorCode = " + errorCode + "; ErrorMessage = " + errorMessage);
    }
  });
}

Remove specified fabric

The fabricIndex of the fabric to be removed cannot be the one used by the current app. You can use the isCurrent field of OperationalFabricInfo to determine whether the current app is working with the target fabric.

API description

void removeFabric(Integer fabricIndex, IThingDataCallback<Integer> callback);

Example

Java:

mThingMatterFabricDevice.removeFabric(Integer.parseInt(fabricIndex), new IThingDataCallback<Integer>() {
  @Override
  public void onSuccess(Integer result) {
    if (result ==0){
      Log.i("removeFabric","RemoveFabric success");
    }
  }

  @Override
  public void onError(String errorCode, String errorMessage) {
    Log.e("removeFabric", "RemoveFabric error: ErrorCode = " + errorCode + "; ErrorMessage = " + errorMessage);
  }
});

Error codes

Error codes	Meaning
3027	The device is offline on all channels.
3051	Failed to open the window for sharing and pairing a device.
3037	Failed to read device properties. Example: Failed to get the number of times a device can be shared. Failed to get the number of times a device has been used. Failed to get the status of the device pairing window. Failed to get fabricList. Failed to get the basic information of a device.
3055	Failed to remove fabricIndex of a device.
3057	Failed to make the API request, for example, for fabric passcode.
3058	Failed to close the device pairing window.
3059	The number of available fabrics is zero.