Device Pairing

The device pairing service in the BizBundle SDK is encapsulated and extended on top of the Smart Life App SDK. It simplifies the pairing process and improves the reusability of code. Informative pairing status callbacks and error codes enable real-time monitoring of the pairing process and effective troubleshooting.

Feature description

The device pairing service provides unified and parallel device search and activation services. It supports the following capabilities:

• Wi-Fi Easy Connect mode (a.k.a. EZ mode)
• Wi-Fi access point mode (a.k.a. AP mode)
• Pairing with QR code (for smart cameras)
• Zigbee wired gateway pairing
• Zigbee sub-device pairing
• Pairing with QR code (app scans device’s QR code)
  • For directly connected devices
  • For Bluetooth devices
• Pegasus pairing
• NB-IoT device pairing
• Bluetooth device pairing
  • Bluetooth Low Energy (LE) device pairing
  • Bluetooth mesh device pairing
  • Bluetooth LE and Wi-Fi combo device pairing
  • Beacon device pairing
• TuyaLink-based device binding
• Matter device pairing
• Composite scan

Integrate BizBundle SDK

Integrate components

1. Add the following dependency to the Podfile:

   source 'https://github.com/tuya/tuya-pod-specs.git'
   platform :ios, '11.0'
   
   target 'Your_Project_Name' do
       # Build and get ThingSmartCryption from the Tuya Developer Platform (https://platform.tuya.com).
       # After the official edition is purchased, rebuild the SDK on the Tuya Developer Platform and integrate it into your project.
       # ./ The dot slash (./) notation represents that the files that are obtained after ios_core_sdk.tar.gz is extracted are put to the directory at the same directory as podfile.
       # To use another directory, change the path to your desired directory.
       pod 'ThingSmartCryption', :path =>'./'
       pod 'ThingSmartHomeKit'
       pod 'ThingSmartBusinessExtensionKit'
   
       # Bluetooth implementation layer (user-tailorable)
       pod 'ThingSmartBusinessExtensionKitBLEExtra'
   
       # Matter
       pod 'ThingSmartBusinessExtensionKitMatterExtra'
   
   end
   

2. In the root directory of your project, run pod update.

Usage

ThingSmartActivatorActiveProtocol, ThingSmartActivatorSearchProtocol, and ThingSmartActivatorConfigProtocol include the methods for device pairing.

ThingSmartActivatorConfigProtocol includes the initialization method, allowing you to register the pairing type and set the delegate.

@protocol ThingSmartActivatorConfigProtocol <NSObject>

@required

/// Start the basic configuration, this method needs to be called after the App starts.
- (void)loadConfig;

/// Initialize network configuration types
/// @param typeList Network configuration types
- (void)registerWithActivatorList:(NSArray<ThingSmartActivatorTypeModel *>*)typeList;

/// Configure delegate object
/// @param delegate Delegate
- (void)setupDelegate:(nullable id)delegate;

/// Remove delegate object
/// @param delegate Delegate
- (void)removeDelegate:(nullable id)delegate;
@end

ThingSmartActivatorSearchProtocol includes the unified and parallel device search service.

@protocol ThingSmartActivatorSearchProtocol <NSObject>

/// Start searching
/// @param typeList Network configuration types
- (void)startSearch:(NSArray <ThingSmartActivatorTypeModel *>*)typeList;

/// Stop searching
/// @param typeList Network configuration types
/// @param clearCache Whether to clear the cache
- (void)stopSearch:(NSArray <ThingSmartActivatorTypeModel *>*)typeList clearCache:(BOOL)clearCache;

@end

ThingSmartActivatorActiveProtocol includes the device activation service, with unified device activation callbacks.

@protocol ThingSmartActivatorActiveProtocol <NSObject>

/// Activate devices with a single network configuration type
/// @param type Network configuration type
/// @param deviceList Devices to be activated
- (void)startActive:(ThingSmartActivatorTypeModel *)type deviceList:(NSArray<ThingSmartActivatorDeviceModel *>*)deviceList;

/// Stop activating devices
/// @param typeList Array of network configuration types
/// @param clearCache Whether to clear the cache
- (void)stopActive:(NSArray <ThingSmartActivatorTypeModel *>*)typeList clearCache:(BOOL)clearCache;

@end

ThingSmartActivatorType includes the supported pairing capability.

typedef NS_OPTIONS(NSInteger, ThingSmartActivatorType) {
    ThingSmartActivatorTypeDefault =     0,       // Default
    ThingSmartActivatorTypeWired =       1 << 0, // Wired device pairing, such as wired Zigbee gateway and smart camera.
    ThingSmartActivatorTypeBle =         1 << 1, // Bluetooth Low Energy device pairing or Wi-Fi and Bluetooth Low Energy combo device pairing.
    ThingSmartActivatorTypeBleMesh =     1 << 2, // Tuya mesh device pairing.
    ThingSmartActivatorTypeSigMesh =     1 << 3, // Bluetooth mesh device pairing.
    ThingSmartActivatorTypeSubDevice =   1 << 4, // Zigbee device pairing.
    ThingSmartActivatorTypeEZSearch =    1 << 5, // Wi-Fi EZ mode pairing.
    ThingSmartActivatorTypeAuto =        1 << 6, // Password-free pairing.
    ThingSmartActivatorTypeHomeKit =     1 << 7, // HomeKit device pairing (will be supported in later release)
    ThingSmartActivatorTypeRouter =      1 << 8, // Hybrid router pairing.
    ThingSmartActivatorTypePegasus =     1 << 9, // Pegasus pairing.
    ThingSmartActivatorTypeAP =          1 << 10, // Wi-Fi AP mode pairing.
    ThingSmartActivatorTypeQRCode =      1 << 11, // Pair with QR code (for smart cameras)
    ThingSmartActivatorTypeBroadband =   1 << 12, // Broadband pairing.
    ThingSmartActivatorTypeMatter =      1 << 13, // Matter device pairing.
    ThingSmartActivatorTypeNB =          1 << 14, // NB-IoT device pairing.
    ThingSmartActivatorTypeApDirectly = 1 << 15, // AP direct pairing, used for a camera or dash cam over a LAN.
    ThingSmartActivatorTypeThingLink =   1 << 16, // TuyaLink-based device pairing.
    ThingSmartActivatorTypeVirtual =     1 << 17, // Virtual device pairing.
    ThingSmartActivatorTypeMQTTDirectly = 1 << 18, // MQTT-direct device pairing, such as GPRS and LTE Cat.1.
    ThingSmartActivatorTypeInstallCode = 1 << 19, // Zigbee install code pairing.
    ThingSmartActivatorTypeBeacon =      1 << 20, // Beacon device pairing.
    ThingSmartActivatorTypeEnd =         1 << 21,
};

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, ThingSmartActivator 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.