Device Pairing (iOS)

Last Updated on : 2022-02-17 05:23:40download

Device Pairing SDK allows smart devices to be paired through routers. The following pairing modes are supported:

  • Wi-Fi Easy Connect (EZ)
  • Access point (AP), also known as the hotspot mode
  • Wired pairing
  • Sub-device pairing
  • Device paring in QR code mode
  • Bluetooth device pairing (For more information, see Bluetooth Series)


Term Description
Wi-Fi device A smart device that uses a 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 over a wired network. 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 transfer between various electronic devices, periodic data transfer, intermittent data transfer, and data transfer at a longer 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 responds to terminal control commands.

Usage notes

Class name Description Important
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.

Compatibility with iOS

Compatibility with iOS 14

Starting from iOS 14, when users pair devices or control devices 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.

Compatibility with iOS 13

Changes in Wi-Fi permissions

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, WLAN or Wi-Fi is returned by default. Apple has sent the following email:

  • As we announced at WWDC19, we’re making changes to further protect user privacy and prevent unauthorized location tracking. Starting with iOS 13, the CNCopyCurrentNetworkInfo API will no longer return valid Wi-Fi SSID and BSSID information. Instead, the information returned by default will be:
  • SSID: “Wi-Fi” or “WLAN” (“WLAN” will be returned for the China SKU)
  • BSSID: “00:00:00:00:00:00”
  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.

Changes in Bluetooth permissions

If you use the SDK development to integrate Powered by Tuya Bluetooth devices, you must learn about the new feature of iOS 13: Bluetooth permissions for apps.
In iOS 13, Bluetooth permissions can be enabled for both the mobile operating system (OS) and each app that runs on the mobile OS. If an app requires the Bluetooth feature, Bluetooth permissions are requested at app startup on iOS 13.

In iOS 13, Apple has replaced the original field NSBluetoothPeripheralUsageDescription that is used to request Bluetooth permissions with the field NSBluetoothAlwaysUsageDescription. The new field is added to info.plist.

Device Pairing (iOS)

If users do not allow Bluetooth permissions for the app, it cannot use the Bluetooth feature as expected. CBCentralManager shows the Bluetooth state CBCentralManagerStateUnauthorized. Then, we recommend that you guide users to enable the Bluetooth feature.

Device Pairing (iOS)

Get the SSID of the connected Wi-Fi network

API method

/// Asynchronously returns the SSID of the current Wi-Fi network.
/// @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