tuya Smart App SDK User Guide

tuya-LOGO

tuya Smart App SDK

tuya-Smart-App-SDK-PRODUCT

This topic describes the access point (AP) or hotspot mode to pair devices. It is a connection capability for pairing over Wi-Fi. After a mobile phone is connected to the Wi-Fi hotspot of a target device, the device is paired and communicates with the mobile phone over Wi-Fi. With a high success rate and good reliability, this mode adapts to 2.4 GHz and 5 GHz dual-band routers. However, users need to manually switch between the Wi-Fi bands connected to the mobile phone.

Pairing methods

Smart Life App SDK supports the following AP pairing processes:

  • Legacy AP pairing: Get the pairing token from the cloud and implement a connection between the device and the cloud.
    Prerequisite: suitable for all devices.
  • New AP pairing: Users connect the device with the app first. Then, access the device on the app and scan for available Wi-Fi networks. Only compatible Wi-Fi networks are discovered. This way, the unsupported 5 GHz Wi-Fi networks are automatically filtered out. Users do not need to manually handle them and can enjoy a higher success rate of pairing.

Prerequisite:

  • The TuyaOS version of the firmware built into the target device must be v3.6.1 or later.
  • Log in to the Apple Developer platform and enable Hotspot.
  • Integrate the ThingSmartHotspotCredentialKit library into your project.

Legacy pairing process

  1. Before pairing
    • Guide the user to reset the device to Wi-Fi AP mode, typically identified by a slow-blinking Wi-Fi indicator.
    • Guide the user to connect their phone to a Wi-Fi network, usually a 2.4 GHz Wi-Fi network.
  2. Get pairing token and Wi-Fi network credentials
    • The app gets the pairing token by calling the method in the SDK.
    • The app gets the Wi-Fi network credentials (SSID and password) input by the user. The SSID can also be obtained through an API call.
  3. Connect to AP
    Guide the user to connect their phone to the AP emitted by the device.
  4. Start pairing
    The app calls the pairing method in the SDK to set the Wi-Fi network credentials (SSID and password) and the pairing token.
  5. Finish pairing
    The device automatically turns off the AP. The app receives a callback from the SDK and finishes the pairing process.

Get the token
Before the AP 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 generated if the device needs to be paired again.

API description
tuya-Smart-App-SDK (2)Parameters

tuya-Smart-App-SDK (3)

Example

Objective-C: tuya-Smart-App-SDK (4)

Swift: tuya-Smart-App-SDK (5)

Callback of pairing delegate tuya-Smart-App-SDK (6)Parameters tuya-Smart-App-SDK (7)Start pairing

API description tuya-Smart-App-SDK (8)Parameters tuya-Smart-App-SDK (9)Example
Objective-C: tuya-Smart-App-SDK (10) tuya-Smart-App-SDK (11)Swifttuya-Smart-App-SDK (12)The AP mode is similar to the EZ mode, except that the first parameter of  self. apActivator startConfigWiFi:ssid:password:token:timeout: is set to ThingActivatorModeAP for the AP mode.
ssid and password, respectively, specify the hotspot name and password of the router rather than that of the device.

Stop pairing
After the pairing process is started, the app continuously broadcasts the pairing data until a device is paired or the process times out. To allow users to cancel or complete pairing during the process, you must call the API method  ThingSmartActivator
stop ConfigWiFi to stop pairing.

API descriptiontuya-Smart-App-SDK (13)Example

Objective-C: tuya-Smart-App-SDK (14)Swift tuya-Smart-App-SDK (15)

New pairing process

To improve the user experience and success rate of pairing, Tuya provides a new pairing process that is available to the new device firmware version only.

  1. Before pairing
    Guide the user to reset the device to Wi-Fi AP mode, typically identified by a slow-blinking Wi-Fi indicator.
  2. Get pairing token and security configuration
    The app gets the pairing token and security configuration by calling the method in the SDK.
  3. Connect to AP
    Guide the user to connect their phone to the AP emitted by the device.
  4. Get the list of discovered Wi-Fi networks
    The app gets the list of available Wi-Fi networks by calling the method in the SDK.
  5. Display available Wi-Fi networks and get Wi-Fi network credentials The app displays the list of available Wi-Fi networks and guides the user to select one and enter the password.
  6. Start pairing
    The app calls the pairing method in the SDK to set the Wi-Fi network credentials, pairing token, and security configuration.
  7. Restart pairing (if error occurs)
    When the user enters an incorrect password, the app guides the user to enter the password again to restart the pairing process.
  8. Finish pairing
    The device automatically turns off the AP. The app receives a callback from the SDK and finishes the pairing process.

Get device security configurations

API description

tuya-Smart-App-SDK (16)Example
Objective-C: tuya-Smart-App-SDK (17)Swift

tuya-Smart-App-SDK (18) Query Wi-Fi networks discovered by device
Before this call, the SDK checks the device status first. If the device has a status exception, for example, an unknown state, the system will not query the Wi-Fi networks discovered by the device.

API description tuya-Smart-App-SDK (19)Parameters tuya-Smart-App-SDK (20)

Example

Objective-C: tuya-Smart-App-SDK (21)Swift:tuya-Smart-App-SDK (21)

Start pairing
You can display the returned list of Wi-Fi networks for users to choose from. API descriptiontuya-Smart-App-SDK (22)Parameters tuya-Smart-App-SDK (23)

Example
Objective-C: tuya-Smart-App-SDK (24)Swifttuya-Smart-App-SDK (25)

Restart pairing
Asks users to provide the correct Wi-Fi name and password, and restarts pairing if the entered password is incorrect.
During the pairing process, the SDK automatically connects to the device within a certain period. After the device is connected, the SDK gets and reports the device status. This feature is supported by the latest firmware version only.

API description tuya-Smart-App-SDK (26)

Parameters
Thing Smart Pairing Resume Config WiFiParam

tuya-Smart-App-SDK (27)Example
Objective-C: tuya-Smart-App-SDK (28)Swifttuya-Smart-App-SDK (29)

Stop pairing
You need to manually call this API method when the pairing task is stopped or resources are destroyed.

Example
Objective-C: tuya-Smart-App-SDK (30)Swifttuya-Smart-App-SDK (31)

Error codes
The following error codes occur while processing device connection. The error messages can be obtained from the device.

tuya-Smart-App-SDK (32)tuya-Smart-App-SDK (1)

Documents / Resources

PDF thumbnailSmart App SDK
User Guide · Smart App SDK, App
PDF thumbnailSmart App SDK
User Guide · Smart App SDK, App SDK, SDK

References

Ask a Question

Use this section to ask about setup, compatibility, troubleshooting, or anything missing from this manual.

Ask a Question

Ask about setup, compatibility, troubleshooting, or anything missing from this manual. Name and email are optional.