Device Pairing

Last Updated on : 2022-03-03 06:43:16download

Tuya Smart Residence App SDK empowers smart devices to be paired through routers or gateways. The typical pairing mode is Wi-Fi Easy Connect (EZ). In this mode, the SDK gets the pairing token from the cloud and enables the app to broadcast the pairing information. The router ID, password, and pairing token are published. Then, the smart device receives the pairing information and starts the activation process. The activated device is connected to both the app and the cloud. Now, you have kicked off your journey with smart control in the cloud.

Before you get started on the development of device pairing, you must get to know the basic logic of the Smart Residence App SDK. Basic operations such as login and site creation are finished based on the SDK.

Functional description

Device pairing supports the following features:

  • Wi-Fi device pairing, including the following modes:

    • Wi-Fi EZ
    • Access point (AP), also known as the hotspot mode
  • Wired device pairing

  • Sub-device pairing

  • Device pairing in QR code mode

  • Smart camera pairing in QR code mode

    This mode is only available to smart cameras. For more information, see QR code mode.

  • Lightning search and pairing

  • HomeKit device pairing

  • NB-IoT device pairing

  • Bluetooth device pairing

    For more information about Bluetooth device pairing, see Bluetooth Devices.


The following table lists specific terms and definitions that are used in this topic. For more information, see Glossary.

Term Description
Wi-Fi device A smart device that uses a Tuya Wi-Fi module to connect to a router and interact with apps and the cloud.
Wi-Fi Easy Connect Also known as the EZ mode. This pairing mode is implemented through the following steps:
  1. The app encapsulates the pairing data into the specified section of an IEEE 802.11 packet and sends the packet to the network.
  2. The Wi-Fi module of a smart device runs in promiscuous mode and listens for and captures all packets over the network.
  3. The Wi-Fi mode parses the packets that carry the pairing data from the app into the data format specified by the protocol.
AP pairing Also known as the hotspot mode or access point (AP) pairing. A mobile phone acts as a station (STA) and connects to the hotspot of a smart device. Then, both devices are paired to establish a socket connection between them and exchange data through the specified ports.
Smart camera pairing in QR code mode A smart camera scans the QR code on the app to get the pairing data.
Wired device A device that connects to a router through an Ethernet cable. For example, a wired device can be a Zigbee wired gateway or a wired camera.
Sub-device A device that interacts with apps and the cloud through a gateway. For example, a Zigbee sub-device is such a device.
Zigbee Zigbee is a short-range, simple, low-power, low-data-rate, cost-efficient, and two-way wireless communication technology.
It applies to short-range, low-power, and low-rate data transfers between various electronic devices, periodic data transfers, intermittent data transfers, and data transfers at a long interval.
Zigbee gateway The device that integrates the coordinator with Wi-Fi features on a Zigbee network. The gateway is responsible to formulate the Zigbee network and store data.
Zigbee sub-device A router or a terminal on a Zigbee network. Each Zigbee sub-device is responsible to forward data, or respond to terminal control commands.

Functional description

Class name Description Scenario
TuyaSmartActivator (singleton) Supports multiple pairing modes, such as Wi-Fi EZ mode, hotspot mode, wired pairing, and sub-device pairing. This class is called in the main thread.

Version compatibility

iOS 14

Starting from iOS 14, when users perform device pairing or control over a local area network (LAN), the local network privacy setting dialog box is triggered.

  • The app can send data to the LAN only after users tap OK.
  • Otherwise, if users tap Don’t Allow, the app cannot access the LAN.

Currently, Apple does not provide APIs to process this privacy setting. We recommend that you guide users to allow the app to access LAN data when features that require LAN connection cannot work. Specifically, go to Settings, choose Privacy > Local Network, and then allow the app to access the LAN.

iOS 13

Starting from iOS 13, if users do not allow the app to access location data, when the Wi-Fi feature is enabled, [[TuyaSmartActivator sharedInstance] currentWifiSSID] cannot get a valid Wi-Fi service set identifier (SSID) or basic service set identifier (BSSID). In this case, iOS returns the following default values:

  • SSID: WLAN or Wi-Fi. WLAN is returned for users in mainland China.
  • BSSID: 00:00:00:00:00:00.

If the Wi-Fi feature cannot be used as expected, the following troubleshooting methods are recommended:

  1. Check whether the app can access location data.
  2. If the returned BSSID is 00:00:00:00:00:00, it is the default system value. Then, you can guide users to manually enter the Wi-Fi name.

Get the SSID of the connected Wi-Fi network

API description

/// Get the SSID of the current Wi-Fi asynchronously.
/// @see TuyaSmartActivator::currentWifiSSID
/// @param success Called when the task finishes successfully. TYSuccessString will be returned.
/// @param failure Called when the task is interrupted by an error.
+ (void)getSSID:(TYSuccessString)success



[TuyaSmartActivator getSSID:^(NSString *result) {

    } failure:^(NSError *error) {



TuyaSmartActivator.getSSID { (_: String?) in

        } failure: { (Error) in