Device Pairing UI BizBundle

Last Updated on : 2022-06-23 09:22:24download

Device Pairing UI BizBundle is used to implement pairing guidance and smart device activation. It applies to multiple common types of smart devices, such as Wi-Fi devices, Zigbee devices, Bluetooth devices, and devices that support QR code scanning like General Packet Radio Service (GPRS) and Narrow Band Internet of Things (NB-IoT) devices. The UI BizBundle provides the service logic and UI encapsulation to guide pairing and activate smart devices over different protocols.

Feature overview

Wi-Fi device pairing

Wi-Fi smart devices can be paired and connected to cloud services in two modes: Wi-Fi Easy Connect (EZ) mode and access point (AP) or hotspot mode. IP cameras (IPCs) can be paired after QR code scanning.

Term Description
Wi-Fi EZ mode 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 mode Also known as the hotspot mode. 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.
IPC pairing in QR code mode An IPC scans the QR code on the app to get the pairing data.

Zigbee device pairing

Zigbee gateways and sub-devices can be paired.

Term Description
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.

Bluetooth device pairing

Tuya provides the following Bluetooth solutions.

Term Description
Bluetooth LE A peer-to-peer connection is created between a Bluetooth or Bluetooth LE device and a mobile phone.
Bluetooth mesh Enable many-to-many (m:m) device communications over a mesh network released by Bluetooth Special Interest Group (SIG).
Tuya mesh Tuya’s proprietary technology that enables Bluetooth devices to communicate over a mesh network.
Combo devices The devices that support Bluetooth and Wi-Fi combo can be paired over either Bluetooth or Wi-Fi.

QR code pairing

A smart device that supports this pairing mode is connected to Tuya’s cloud services immediately after power on. The app can be used to scan the QR code on the device to implement cloud-based device activation and binding. The QR code must comply with Tuya’s QR code rules. For more information, contact Tuya’s account manager.

Term Description
GPRS devices Smart devices that apply GPRS technologies to connect to the network and access cloud services.
NB-IoT devices Smart devices that apply NB-IoT technologies.

Pairing by auto discovery

Tuya provides efficient pairing features on top of Tuya’s generic pairing technologies for smart devices.

Integrate with the UI BizBundle

Add the components of the Device Pairing UI BizBundle to the Podfile and run the command pod update.

source "https://github.com/tuya/TuyaPublicSpecs.git"
source 'https://cdn.cocoapods.org/'

target 'your_target_name' do
  # TuyaSmartResidence SDK
  pod "TuyaSmartResidenceKit"
  # Adds the Device Pairing UI BizBundle.
  pod 'TuyaSmartResidenceActivatorBizBundle'
end

To implement pairing of Wi-Fi devices, you must get the name of the current Wi-Fi network after the location permissions are enabled in your project. To achieve this purpose, add the following permission declaration to info.plist of your project, create the CLLocationManager sample, and then call the method requestWhenInUseAuthorization:

NSLocationAlwaysAndWhenInUseUsageDescription
NSLocationAlwaysUsageDescription
NSLocationWhenInUseUsageDescription

To implement QR code scanning, the permissions on access to cameras of mobile phones are required. You can add the following permission declaration in info.plist:

NSCameraUsageDescription

Customize settings

Bluetooth device pairing

The Device Pairing UI BizBundle supports device pairing over protocols such as Wi-Fi and Bluetooth. Bluetooth pairing is optional.

  • If your app does not require Bluetooth pairing, you only need to set the needBle property in ty_custom_config.json to false.

  • If your app requires Bluetooth pairing, you must first add the following Bluetooth permission declaration to info.plist of your project, set the needBle property in ty_custom_config.json to true, and then add the following dependencies to your project:

    System permissions

    NSBluetoothAlwaysUsageDescription
    NSBluetoothPeripheralUsageDescription
    

    Settings

    {
    	"config": {
    		"appId": 123,
    		"tyAppKey": "xxxxxxxxxxxx",
    		"appScheme": "tuyaSmart",
    		"hotspotPrefixs": ["SmartLife"],
    		"needBle": true // Sets the value to `true` to support pairing of Bluetooth devices.
    	},
    	"colors":{
    		"themeColor": "#FF5A28",
    	}
    }
    

    Dependencies

    pod 'TYBLEInterfaceImpl', '0.5.3.12'
    pod 'TYBLEMeshInterfaceImpl', '0.0.9-apartmentBizbundle.1.1'
    pod 'TYBLEHomeManager'
    

Hotspot name settings

  • By default, the hotspot name of each Powered by Tuya (PBT) device is prefixed with SmartLife.

  • If the hotspot prefix of the current smart device is modified, you must set the hotspotPrefixs property in ty_custom_config.json to the current hotspot prefix.

    {
    	"config": {
    		"appId": 123,
    		"tyAppKey": "xxxxxxxxxxxx",
    		"appScheme": "tuyaSmart",
    		"hotspotPrefixs": ["SL"], // The supported hotspot prefix is set to `SL`.
    		"needBle": true
    	},
    "colors":{
    		"themeColor": "#FF5A28",
    	}
    }
    

Service protocols

Provide services

The UI BizBundle relies on the implementation of the protocol TuyaSmartResidenceActivatorProtocol to provide services. You can view the TuyaSmartResidenceActivatorProtocol.h file in the TYModuleServices component.

@protocol TuyaSmartResidenceActivatorProtocol <NSObject>

/**
 Jump to Equipment matching page
 */
- (void)gotoActivatorVC;

/**
 *  Obtain device information after each device connection
 *  @param customJump default false, set true for process not need to jump to de device panel
 */
- (void)activatorCustomJump:(BOOL)customJump completionBlock:(void (^)(NSArray * _Nullable deviceList))callback;

@end

To customize the returned list of categories or products for pairing, implement the protocol methods provided by TYActivatorExternalExtensionProtocol.

TYActivatorExternalExtensionProtocol

/**
 *  Back action form category View Controller
 *  Need to implement when additional operations are needed
 */
- (BOOL)categoryViewControllerCustomBackAction;

Usage instruction

Things to note

  • Before the UI BizBundle is called, the following method must be implemented for the site:
[self.site fetchSiteDetailWithSuccess:^(TuyaResidenceSiteModel * _Nonnull siteModel) {
	
} failure:^(NSError *error) {

}];
  • Then, implement the protocol method currentFamilyId in TYFamilyProtocol.
#import <TuyaSmartBizCore/TuyaSmartBizCore.h>
#import <TYModuleServices/TYFamilyProtocol.h>

- (void)initCurrentSite {
	// Registers the protocol to be implemented.
	[[TuyaSmartBizCore sharedInstance] registerService:@protocol(TYFamilyProtocol) withInstance:self];
}

// Implements the target protocol method.
- (long long)currentFamilyId {
	return @"site id";
}

Start the pairing mode

#import <TuyaSmartBizCore/TuyaSmartBizCore.h>
#import <TYModuleServices/TuyaSmartResidenceActivatorProtocol.h>

- (void)gotoDeviceConfig {
    id<TuyaSmartResidenceActivatorProtocol> impl = [[TuyaSmartBizCore sharedInstance] serviceOfProtocol:@protocol(TuyaSmartResidenceActivatorProtocol)];
    [impl gotoActivatorVC];

    // Returns the pairing result.
    [impl activatorCustomJump:NO completionBlock:^(NSArray * _Nullable deviceList) {
        NSLog(@"deviceList: %@", deviceList);
    }];
}

Query custom categories for pairing

#import <TuyaSmartBizCore/TuyaSmartBizCore.h>
#import <TYModuleServices/TYActivatorExternalExtensionProtocol.h>

- (void)registerService {
    // Registers the protocol to be implemented.
    [[TuyaSmartBizCore sharedInstance] registerService:@protocol(TYActivatorExternalExtensionProtocol) withInstance:self];
}

// Implements the protocol method.
- (BOOL)categoryViewControllerCustomBackAction {
    [self.navigationController popToRootViewControllerAnimated:YES];
    return YES;
}