Manage Matter Devices

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 Prepare for Integration with Matter Device.

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

Determine Matter device

API description

- (BOOL)isSupportMatter;

Example

Objective-C:

- (void)judgeSupportMatter {
    // self.device = [ThingSmartDevice deviceWithDeviceId:@"your_device_id"];
    BOOL isSupport = [self.device.deiceModel isSupportMatter];
    NSLog(@"judgeSupportMatter: %ld", isSupport);
}

Swift:

func judgeSupportMatter() {
    let isSupport = device?.deviceModel?.isSupportMatter()
}

Control Matter device

Similarly to a generic type of device, call -publishDps:success:failure: in ThingSmartDevice to send a device control data point (DP).

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 local area network (LAN) channel Tuya’s LAN channel MQTT channel	None.
Tuya-enabled Matter over Thread device	Matter local area network (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 ThingSmartDeviceModel to determine whether a Matter device is online or offline.

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.

SDK v5.2.0 or later

API description

- (BOOL)checkPipelineAvailable;

Example

Objective-C:

- (void)preCheck {
    // self.fabricShare = [[ThingSmartMatterMultipleFabricShare alloc] initWithDeviceModel:deviceModel];
    BOOL available = [self.fabricShare checkPipelineAvailable];
    NSLog(@"fabric pipeline available: %d", available);
}

Swift:

func preCheck() {
    let available = fabricShare.checkPipelineAvailable
    print("fabric pipeline available: \(available)")
}

SDKs earlier than v5.2.0

API description

- (void)getConnectedStatusSuccess:(ThingSuccessHandler)success failure:(nullable ThingFailureError)failure;

Example

Objective-C:

- (void)checkConnectStatus {
    // self.fabricShare = [[ThingSmartMatterMultipleFabricShare alloc] initWithDeviceModel:deviceModel];
    [self.fabricShare getConnectedStatusSuccess:^{
        NSLog(@"matter device is connected");
    } failure:^(NSError *error) {
        NSLog(@"matter device not connect: %@", error);
    }];
}

Swift:

func checkConnectStatus() {
    fabricShare.getConnectedStatusSuccess {
        print("matter device is connected")
    } failure: { error in
        print("matter device not connect: \(error)")
    }
}

SDK v5.2.0 or later

Before using the API, you can call the check channel availability API for SDK v5.2.0 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)sendEnhancedCommissioning:(BOOL)forceRefresh
                         ssidInfo:(nullable void(^)(NSString * __nullable ssid))ssidInfo
                          success:(void(^)(NSString *qrCodeStr, NSString *setupCode))success
                          failure:(nullable ThingFailureError)failure

Example

Objective-C:

- (void)openECM {
    // self.fabricShare = [[ThingSmartMatterMultipleFabricShare alloc] initWithDeviceModel:deviceModel];
    [self.fabricShare sendEnhancedCommissioning:YES ssidInfo:^(NSString * __nullable ssid){
        NSLog(@"device ssid: %@", ssid)
    } success:^(NSString * _Nonnull qrCodeStr, NSString * _Nonnull setupCode) {
        NSLog(@"open ecm success: %@, %@", qrCodeStr, setupCode);
    } failure:^(NSError *error) {
        NSLog(@"open ecm fail: %@", error);
    }];
}

Swift:

func openECM() {
    fabricShare.sendEnhancedCommissioning(true) { ssid in
        print("device ssid: \(ssid)")
    } success: { qrcode, setupCode in
        print("open ecm success: \(qrcode) \(setupCode)")
    } failure: { error in
        print("open ecm fail: \(error)")
    }
}

SDKs earlier than v5.2.0

Implement the APIs used in the process of sharing devices across fabrics, as shown in the diagram above. Before using the API, you can call the check channel availability API for SDKs earlier than v5.2.0.

Request maximum number of supported fabrics

The maximum number of supported fabrics can vary, depending on the performance of different Matter devices.

API description

- (void)readSupportedFabricsSuccess:(ThingSuccessInt)success
                                                      failure:(nullable ThingFailureError)failure;

Example

Objective-C:

- (void)readMaxSupportFabricsNumber {
    // self.fabricShare = [[ThingSmartMatterMultipleFabricShare alloc] initWithDeviceModel:deviceModel];
    [self.fabricShare readSupportedFabricsSuccess:^(int maxNum) {
        NSLog(@"max support fabrics number: %i", maxNum);
    } failure:^(NSError *error) {
        NSLog(@"read max support fabrics number fail: %@", error);
    }];
}

Swift:

func readMaxSupportFabricsNumber() {
    fabricShare.readSupportedFabricsSuccess { maxNum in
        print("max support fabrics number: \(maxNum)")
    } failure: { error in
        print("read max support fabrics number fail: \(error)")
    }
}

Request number of used fabrics

API description

- (void)readCommissionedFabricsSuccess:(ThingSuccessInt)success failure:(nullable ThingFailureError)failure;

Example

Objective-C:

- (void)readUsedFabricsNumber {
    // self.fabricShare = [[ThingSmartMatterMultipleFabricShare alloc] initWithDeviceModel:deviceModel];
    [self.fabricShare readCommissionedFabricsSuccess:^(int usedNum) {
        NSLog(@"used fabrics number: %i", usedNum);
    } failure:^(NSError *error) {
        NSLog(@"read used fabrics number fail: %@", error);
    }];
}

Swift:

func readUsedFabricsNumber() {
    fabricShare.readCommissionedFabricsSuccess { usedNum in
        print("used fabrics number: \(usedNum)")
    } failure: { error in
        print("read used fabrics number fail: \(error)")
    }
}

Get SSID of Wi-Fi network connected by device

Returns the SSID of the Wi-Fi network to which a Matter over Wi-Fi device is connected. This API method is unavailable to wired gateways and Thread devices.

API description

- (void)getWifiDeviceSsid:(ThingSuccessString)success failure:(nullable ThingFailureError)failure;

Example

Objective-C:

- (void)fetchDeviceConnectWifi {
    // self.fabricShare = [[ThingSmartMatterMultipleFabricShare alloc] initWithDeviceModel:deviceModel];
    [self.fabricShare getWifiDeviceSsid:^(NSString *result) {
        NSLog(@"now the device connect ssid: %@", result);
    } failure:^(NSError *error) {
        NSLog(@"get the device connect ssid fail: %@", error);
    }];
}

Swift:

func fetchDeviceConnectWifi() {
    fabricShare.getWifiDeviceSsid { ssid in
        print("now the device connect ssid: \(ssid)")
    } failure: { error in
        print("get the device connect ssid fail: \(error)")
    }
}

Open window for sharing and pairing

Returns the model object of ThingSmartMatterMultipleFabricPasscodeModel.

API description

// Gets the data model of PasscodeModel.
- (void)getMultipleFabricPasscodeCompletion:(void(^)(ThingSmartMatterMultipleFabricPasscodeModel *result, NSError *error))completionBlock;

// Forces refresh to return the object of PasscodeModel.
- (void)getMultipleFabricPasscodeForceRefreshCompletion:(void(^)(ThingSmartMatterMultipleFabricPasscodeModel *result, NSError *error))completionBlock;

Example

Objective-C:

- (void)getPassscodeModel {
    // self.fabricShare = [[ThingSmartMatterMultipleFabricShare alloc] initWithDeviceModel:deviceModel];
    [self.fabricShare getMultipleFabricPasscodeCompletion:^(ThingSmartMatterMultipleFabricPasscodeModel * _Nonnull passcodeModel, NSError * _Nonnull error) {
        if (error) {
            NSLog(@"get passcode model fail: %@", error);
            return;
        }
        NSLog(@"get the passcode model: %@", passcodeModel);
    }];
}

- (void)getRefreshPasscodeModel {
    // self.fabricShare = [[ThingSmartMatterMultipleFabricShare alloc] initWithDeviceModel:deviceModel];
    [self.fabricShare getMultipleFabricPasscodeForceRefreshCompletion:^(ThingSmartMatterMultipleFabricPasscodeModel * _Nonnull passcodeModel, NSError * _Nonnull error) {
        if (error) {
            NSLog(@"get refresh passcode model fail: %@", error);
            return;
        }
        NSLog(@"get refresh the passcode model: %@", passcodeModel);
    }];
}

Swift:

func getPassscodeModel() {
    fabricShare.getMultipleFabricPasscodeCompletion { passcodeModel, error in
        if error != nil {
            print("get passcode model fail: \(error)")
            return;
        }
        print("get the passcode model: \(passcodeModel)")
    }
}

func getRefreshPasscodeModel() {
    fabricShare.getMultipleFabricPasscodeForceRefreshCompletion { passcodeModel, error in
        if error != nil {
            print("get refresh passcode model fail: \(error)")
            return;
        }
        print("get refresh passcode model: \(passcodeModel)")
    }
}

Uses the value of passcodeModel obtained in the previous step to open the window for sharing and pairing a device.

API description

- (void)sendEnhancedCommissioningCommandWithFabricPasscodeModel:(ThingSmartMatterMultipleFabricPasscodeModel *)passcodeModel
                                                        success:(void(^)(NSString *qrCodeStr, NSString *setupCode))success
                                                        failure:(nullable ThingFailureError)failure;

Example

Objective-C:

- (void)openECM {
    // self.fabricShare = [[ThingSmartMatterMultipleFabricShare alloc] initWithDeviceModel:deviceModel];
    [self.fabricShare sendEnhancedCommissioningCommandWithFabricPasscodeModel:passcodeModel success:^(NSString * _Nonnull qrCodeStr, NSString * _Nonnull setupCode) {
        NSLog(@"open ecm success: %@, %@", qrCodeStr, setupCode);
    } failure:^(NSError *error) {
        NSLog(@"open ecm fail: %@", error);
    }];
}

Swift:

func openECM() {
    fabricShare.sendEnhancedCommissioningCommand(with: passcodeModel) { qrCode, setupCode in
        print("open ecm success: \(qrCode) \(setupCode)")
    } failure: { error in
        print("open ecm fail: \(error)")
    }
}

Close window for sharing and pairing

The window for sharing and pairing a device cannot be opened again when it is already opened. This window must be closed before it can be opened again.

API description

- (void)revokeCommissioningCommandSuccess:(ThingSuccessHandler)success failure:(nullable ThingFailureError)failure;

Example

Objective-C:

- (void)revokeCommissioning {
    // self.fabricShare = [[ThingSmartMatterMultipleFabricShare alloc] initWithDeviceModel:deviceModel];
    [self.fabricShare revokeCommissioningCommandSuccess:^{
        NSLog(@"revoke commission success");
    } failure:^(NSError *error) {
        NSLog(@"revoke commission fail: %@", error);
    }];
}

Swift:

func revokeCommissioning() {
    fabricShare.revokeCommissioningCommandSuccess {
        print("revoke commission success")
    } failure: { error in
        print("revoke commission fail: \(error)")
    }
}

Manage fabrics

A Matter device can be shared across ecosystems. In terms of fabric management, you can make API requests to get a list of current fabrics and remove a specific fabric.

Get list of fabrics

Returns a list of fabrics that support control of a specific device. This step provides a data reference for removing a specific fabric.

API description

- (void)readFabricsWithSuccess:(void(^)(NSArray<ThingSmartMatterMultipleFabricInfoModel *> *fabrics))success
                       failure:(nullable ThingFailureError)failure;

Data model

The following table defines the fields in the model ThingSmartMatterMultipleFabricInfoModel.

Property	Type	Description
vendorId	NSNumber	The ID of the manufacturer.
nodeId	long long	The value of nodeId provided by the specified fabric during pairing.
fabricId	long long	The value of fabricId provided by the specified fabric during pairing.
fabricIndex	NSInteger	The value of index provided by the specified fabric during pairing.
label	NSString	The value of nodeLabel provided by the specified fabric during pairing.
isCurrent	BOOL	Indicates whether the current app is working with the specified fabric.

Example

Objective-C:

- (void)fetchFabricList {
    // self.fabricShare = [[ThingSmartMatterMultipleFabricShare alloc] initWithDeviceModel:deviceModel];
    [self.fabricShare readFabricsWithSuccess:^(NSArray<ThingSmartMatterMultipleFabricInfoModel *> * _Nonnull fabrics) {
        NSLog(@"read fabrics success");
    } failure:^(NSError *error) {
        NSLog(@"read fabrics fail: %@", error);
    }];
}

Swift:

func fetchFabricList() {
    fabricShare.readFabrics { fabricInfoModels in
        print("read fabrics success: \(fabricInfoModels)")
    } failure: { error in
        print("read fabrics fail: \(error)")
    }
}

Remove specified fabric

Removes the specified fabric. Then, the target paired device cannot be controlled in this fabric.

API description

- (void)removeFabricIndex:(NSInteger)fabricIndex
                  success:(ThingSuccessHandler)success
                  failure:(nullable ThingFailureError)failure;

Example

Objective-C:

- (void)removeFabricIndex:(NSInteger)fabricIndex {
    // self.fabricShare = [[ThingSmartMatterMultipleFabricShare alloc] initWithDeviceModel:deviceModel];
    [self.fabricShare removeFabricIndex:fabricIndex success:^{
        NSLog(@"remove success");
    } failure:^(NSError *error) {
        NSLog(@"remove fail: %@", error);
    }];
}

Swift:

func remove(fabricIndex: Int) {
    fabricShare.removeFabricIndex(fabricIndex) {
        print("remove success")
    } failure: { error in
        print("remove fail: %@", error)
    }
}

Error codes

For more information about the description of a specific error code, see the declaration and definition in ThingSmartMatterKitErrors.h.

Error codes	Description
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.