Manage Matter Devices

Last Updated on : 2024-06-12 10:23:45download

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.

A fabric is a group of networked devices (also known as nodes) that share the same security domain. This enables secure communications among these nodes within the fabric. Nodes in the same fabric share the same Certificate Authority’s (CA) top-level certificate (Root of Trust) and, within the context of the CA, a unique 64-bit identifier named Fabric ID.

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.

  1. Smart Life App SDK v5.2.0 or later supports multiple channels for sharing among fabrics and fabrics management, with a new method for checking the availability of channels.
  2. Multichannel communication requires the respective support from the device firmware. The new API method is compatible with legacy devices, so you are recommended to migrate to it.

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)")
    }
}

Smart Life App SDK v5.2.0 or later simplifies the API used to generate the Multiple Fabrics sharing code and supports multiple communication channels for improved pairing rate.

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.

Smart Life App SDK v5.2.0 or later supports multiple communication channels for improved pairing success rate. The usage of fabrics management APIs remains unchanged.

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.

The fabricIndex of the fabric to be removed cannot be the one used by the current app. You can use the isCurrent field of ThingSmartMatterMultipleFabricInfoModel to determine whether the current app is working with the target 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.