tuya Matter Device Smart App SDK
Discover 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.
The SDK provides two ways to discover 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 ThingSmartMatterSetupPayload and proceed to the steps as illustrated in the pairing flowchart.
API description
Parameters
Example
Objective-C:
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
Example
Objective-C:
Swift:
Device scanning callback
The callback to invoked when a nearby Matter device that supports auto-discovery is automatically found. The callback is invoked once each time a Matter device is discovered.
API description
Parameters
Example
Objective-C:
Define data model of pairing by auto discovery
Generates a data model and returns it to the business layer when a nearby Matter device that supports auto discovery is automatically found.
Parameters
Stop auto-discovery
Stops auto-discovery when the auto-discovery page is closed to avoid unnecessary resource usage.
API description
Example
Objective-C:
Start pairing process
Continues the steps as illustrated in the pairing flowchart, based on the payload property object included in the discovered model object ThingSmartMatterDiscoveryModel. The design of the Matter protocol determines that only one device can be paired at a time during the pairing process. Therefore, in your implementation of pairing, finish pairing a device before starting paring the next device.
Build pairing parameters
Get SetupPayload
For more information about how to get the object of ThingSmartMatterSetupPayload, see Discover device.
Get a token
Before the wired 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.
API description
Parameters
Example
Objective-C:
Assemble pairing parameters into object
Provides required parameters for pairing. This is the last preparation step before pairing can be started.
API description
Parameters
Example
Objective-C:
Pairing process
Connect to device
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
Parameters
Example
Objective-C:
Swift:
Device connection callback
The callback to invoked after an attempt to connect to a device by connect. The callback is intended to notify the business layer of the pairing mode and device type.
API description
Parameters
Example
Objective-C:
Swift:
Matter pairing option callback
The callback to invoked when the optimal pairing option is selected based on the device advertising data. Then, the SDK returns the callback to the business layer to implement the process of displaying the respective page. The following types of URLs are supported:
- Pairing option implemented by Tuya (ThingMatterRoutingTypeThing)
- Sharing and pairing option (ThingMatterRoutingTypeSupport)
- MatterSupport option for third-party Matter devices (ThingMatterRoutingTypeShare)
::: important
To enable pairing with the MatterSupport option, follow the instructions in Prepare for Integration with Matter Device and configure Matter Extension Target. Otherwise, pairing will fail. :::
API description
Parameters
Example
Objective-C:
PASE session establishment callback
After the Matter device is connected, the PASE session is established, and the PASE session success callback is invoked.
API description
Parameters
Example
Objective-C:
Swift:
Assemble parameters for commissioning Tuya-enabled combo device
To establish a Certificate Authenticated Session Establishment (CASE) session with a Tuya-enabled combo device, you must provide and assemble the required parameters. Then, the device can be commissioned. Only Tuya-enabled Matter devices require you to assemble the parameters.
API description
Parameters
Example
Objective-C:
Swift:
Assemble parameters for commissioning Thread sub-device
Pairing the sub-device relies on the OTBR network provided by the Matter gateway. Therefore, you must set the gateway ID before a PASE session is established. In a PASE session, the SDK scans for available Thread networks nearby and selects the optimal gateway ID with the strongest signal strength. In the callback – (void)matterCommissioningSessionEstablishmentComplete:(ThingSmartMatterDeviceModel *)deviceModel;, ThingSmartMatterDeviceModel provides a list of available gateway IDs indicated by gatewayId. If this parameter is empty or users want to specify a gateway, use another gateway ID for the current home. Only Tuya-enabled Matter devices require you to assemble the parameters.
API description
Parameters
Example
Objective-C:
Swift:
Commission Matter device
After a PASE session, certain key information such as the type of device can be obtained. When required parameters have been assembled for a CASE session, to activate the device in the cloud, make this API request to establish a CASE session. Only Tuya-enabled Matter devices require you to make this API request. Third-party devices do not support this API request.
API description
Parameters
Example
Objective-C:
Device attestation callback
The callback to invoke when an attempt is made to pair a device that is not Mattercertified. After this callback is invoked, the pairing process will be suspended until you choose to continue or give up pairing.
API description
Parameters
Example
Objective-C:
Trust unattested device and continue pairing
Continues pairing if the device certificate is regarded to be trustable.
API description
Parameters
Example
Objective-C:
Swift:
Pairing success callback
The callback to invoke when a Matter device is paired and activated in the cloud.
API description
Parameters
Example
Objective-C:
Swift:
Pairing failure callback
The callback to invoke when a Matter device failed to be paired.
API description
Parameters
Example
Objective-C:
Swift:
MatterSupport pairing success callback
The MatterSupport process is designed for a third-party Wi-Fi or Thread device. If this process is used for pairing, MatterSupport is regarded as a part of the whole pairing process. When MatterSupport is finished, invoke this callback to continue the pairing process implemented by Tuya.
API description
Parameters
Example
Objective-C:
Swift:
Error codes
For more information about the description of a specific error code, see the declaration and definition in ThingSmartMatterKitErrors.h.
Documents / Resources
 |
tuya Matter Device Smart App SDK [pdf] Instructions Matter Device Smart App SDK, Device Smart App SDK, Smart App SDK, App SDK, SDK |
