Composite Scan

Composite scan currently supports seven pairing types: Wi-Fi EZ mode, Pegasus pairing, wired device pairing, sub-device pairing, gateway router pairing, Bluetooth device pairing, and Matter device pairing. You can choose one or more composite scan capabilities.

Supported scan types

The following are all the pairing types supported by composite scan.

typedef NS_OPTIONS(NSInteger, ThingSmartActivatorType) {
    ThingSmartActivatorTypeWired =       1 << 0, // Wired
    ThingSmartActivatorTypeBle =         1 << 1, // Bluetooth LE
    ThingSmartActivatorTypeSigMesh =     1 << 3, // Bluetooth mesh
    ThingSmartActivatorTypeSubDevice =   1 << 4, // Sub-device
    ThingSmartActivatorTypeEZSearch =    1 << 5, // EZ
    ThingSmartActivatorTypeHomeKit =     1 << 7, // HomeKit
    ThingSmartActivatorTypeRouter =      1 << 8, // Router
    ThingSmartActivatorTypePegasus =     1 << 9, // Pegasus
    ThingSmartActivatorTypeMatter =      1 << 13, // Matter
    ThingSmartActivatorTypeBeacon =      1 << 20, // Beacon
};

Register the pairing type

When the device pairing service is initialized, register the pairing type.

API description

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

Parameter description

Parameters	Description
typeList	The list of pairing types.

Get a token

The SDK gets a pairing token from the cloud before it can start the pairing process. 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

- (void)getTokenWithHomeId:(long long)homeId
                   success:(ThingSuccessString)success
                   failure:(ThingFailureError)failure;

Parameter description

Parameters	Description
homeId	The ID of the home with which the device is bound.
success	The success callback. A pairing token is returned.
failure	The failure callback. An error message is returned.

Start searching

Pass in the registered typeList to start searching.

API description

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

Parameter description

Parameters	Description
typeList	The list of pairing types.

Stop searching

API description

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

Parameter description

Parameters	Description
typeList	The list of pairing types.
clearCache	Specifies whether to clear the cache search result.

Device search callback

After the device is discovered, the callback returns the device information. If the operation fails, the callback returns the error message.

Device discovery callback

API description

/// Device search callback
/// @param service Search instance
/// @param type Network configuration type
/// @param device Discovered device
/// @param errorModel Error callback
- (void)activatorService:(id<ThingSmartActivatorSearchProtocol>)service
            activatorType:(ThingSmartActivatorTypeModel *)type
             didFindDevice:(nullable ThingSmartActivatorDeviceModel *)device
                     error:(nullable ThingSmartActivatorErrorModel *)errorModel;

Parameter description

Parameters	Description
service	The pairing service.
type	The pairing type.
device	The discovered device. The device model is returned on success. nil is returned on failure.
errorModel	This model is returned if pairing fails or times out. nil is returned on success.

Device information update callback

API description

/// Device information update or device rediscovered on a different channel
/// @param service Search instance
/// @param type Network configuration type
/// @param device Device model
- (void)activatorService:(id<ThingSmartActivatorSearchProtocol>)service
            activatorType:(ThingSmartActivatorTypeModel *)type
           didUpdateDevice:(ThingSmartActivatorDeviceModel *)device;

Parameter description

Parameters	Description
service	The pairing service.
type	The pairing type.
device	The updated device information.

Prerequisites

You can incorporate the Wi-Fi EZ mode, password-free pairing, gateway routers, and sub-devices into the display of the search result of pairing types that have a search process such as Bluetooth. The required parameters vary by pairing type. You can inherit from ThingSmartActivatorTypeModel and extend the parameters for each pairing type.

Common parameters

Required parameter	Description
timeout	The timeout value, in milliseconds.
type	The pairing type.
typeName	The name of the pairing type.
action	The extended action.
extensions	The extended parameter.

Bluetooth LE

Required permission: System Bluetooth and app’s access to Bluetooth
Search for the model ThingSmartActivatorTypeBleModel. The fields in the model can be ignored during the search.

Wi-Fi EZ mode

Required permission: local network. The permission com.apple.developer.networking.multicast must be enabled.

Required parameter	Description
ssid	The name of the target Wi-Fi network.
password	The password of the target Wi-Fi network.
token	The identifier for authentication.
action	The extended action.
spaceId	The home ID.

Wired gateway

The device must be on the same network as the mobile phone, with no additional parameters needed.

Gateway router

Required parameter	Description
routerActiveDeviceList	The list of device IDs that support the gateway router.
token	The identifier for authentication.

Pegasus pairing

Required parameter	Description
pegasusServerDevIDs	The list of device IDs that support the Pegasus pairing.

Matter device

Required permission: System Bluetooth and app’s access to Bluetooth

Sub-device

Required parameter	Description
gwDevId	The gateway ID.

Example

Start scanning

Swift:

class searchModeConfigurationVC: UITableViewController {

    var typeList:[ThingSmartActivatorTypeModel] = []

    private var sigModel: ThingSmartActivatorTypeSigMeshModel = {
        let type = ThingSmartActivatorTypeSigMeshModel()
        type.type = ThingSmartActivatorType.sigMesh
        type.typeName = NSStringFromThingSmartActivatorType(ThingSmartActivatorType.sigMesh)
        type.timeout = 120
        return type
    }()

    private var bleModel: ThingSmartActivatorTypeBleModel = {
        let type = ThingSmartActivatorTypeBleModel()
        type.type = ThingSmartActivatorType.ble
        type.typeName = NSStringFromThingSmartActivatorType(ThingSmartActivatorType.ble)
        type.timeout = 120
        return type
    }()

    private var beaconModel: ThingSmartActivatorTypeBeaconModel = {
        let type = ThingSmartActivatorTypeBeaconModel()
        type.type = ThingSmartActivatorType.beacon
        type.typeName = NSStringFromThingSmartActivatorType(ThingSmartActivatorType.beacon)
        type.timeout = 120
        return type
    }()

    private var subDeviceModel: ThingSmartActivatorTypeSubDeviceModel = {
        let type = ThingSmartActivatorTypeSubDeviceModel()
        type.type = ThingSmartActivatorType.subDevice
        type.typeName = NSStringFromThingSmartActivatorType(ThingSmartActivatorType.subDevice)
        type.timeout = 120
        type.gwDevId = selectedGateway.deviceId
        return type
    }()

    private var pegasusModel: ThingSmartActivatorTypePegasusModel = {
        let type = ThingSmartActivatorTypePegasusModel()
        type.type = ThingSmartActivatorType.pegasus
        type.typeName = NSStringFromThingSmartActivatorType(ThingSmartActivatorType.pegasus)
        type.timeout = 120
        return type
    }()

    private var routerModel: ThingSmartActivatorTypeRouterModel = {
        let type = ThingSmartActivatorTypeRouterModel()
        type.type = ThingSmartActivatorType.router
        type.typeName = NSStringFromThingSmartActivatorType(ThingSmartActivatorType.router)
        type.timeout = 120
        return type
    }()

    private var wiredModel: ThingSmartActivatorTypeWiredModel = {
        let type = ThingSmartActivatorTypeWiredModel()
        type.type = ThingSmartActivatorType.wired
        type.typeName = NSStringFromThingSmartActivatorType(ThingSmartActivatorType.wired)
        type.timeout = 120
        return type
    }()

    private var EZModel: ThingSmartActivatorTypeEZModel = {
        let type = ThingSmartActivatorTypeEZModel()
        type.type = ThingSmartActivatorType.ezSearch
        type.typeName = NSStringFromThingSmartActivatorType(ThingSmartActivatorType.ezSearch)
        type.timeout = 120
        return type
    }()


    private var matterModel: ThingSmartActivatorTypeMatterModel = {
        let type = ThingSmartActivatorTypeMatterModel()
        type.type = ThingSmartActivatorType.matter
        type.typeName = NSStringFromThingSmartActivatorType(ThingSmartActivatorType.matter)
        type.timeout = 120
        return type
    }()

    lazy var discovery: ThingSmartActivatorDiscovery = {
        let discovery = ThingSmartActivatorDiscovery()
        self.typeList = [self.matterModel,self.EZModel,self.wiredModel,self.pegasusModel,self.bleModel,self.sigModel,self.beaconModel,self.subDeviceModel,self.routerModel]
        discovery.register(withActivatorList: self.typeList)
        discovery.setupDelegate(self)
        discovery.loadConfig()
        return discovery
    }()

    private func startSearch() {
        guard let homeID = Home.current?.homeId else { return }
        let deviceArray = ThingSmartPegasusActivator.pegasusDeviceList(withHomeID: homeID)
        var devIds: [String] = []

        deviceArray.forEach { (obj) in
            devIds.append(obj.devId)
        }

        pegasusModel.pegasusServerDevIDs = devIds

        EZModel.spaceId = homeID;
        EZModel.token = token
        EZModel.ssid =  ssid
        EZModel.password = password

        routerModel.token = token
        sigModel.spaceId = homeID
        matterModel.spaceId = homeID
        wiredModel.spaceId = homeID
        bleModel.spaceId = homeID


        let routerActivator = ThingSmartRouterActivator()
        routerModel.routerActiveDeviceList = routerActivator.autoActiveRouterDeviceList(withHomeId: homeID)

        discovery.startSearch(typeList)
    }


}

extension searchModeConfigurationVC: ThingSmartActivatorSearchDelegate {
    func activatorService(_ service: ThingSmartActivatorSearchProtocol, activatorType type: ThingSmartActivatorTypeModel, didFindDevice device: ThingSmartActivatorDeviceModel?, error errorModel: ThingSmartActivatorErrorModel?) {

        if let device = device {
            /// discovery Device
        }
    }

    func activatorService(_ service: ThingSmartActivatorSearchProtocol, activatorType type: ThingSmartActivatorTypeModel, didUpdateDevice device: ThingSmartActivatorDeviceModel) {

    }

}

Objective-C:

- (void)startSearch {
    self.typedic = [NSMutableDictionary dictionary];

    ThingSmartActivatorTypeSubDeviceModel *subType = [[ThingSmartActivatorTypeSubDeviceModel alloc] init];
    subType.type = ThingSmartActivatorTypeSubDevice;
    subType.typeName = NSStringFromThingSmartActivatorType(ThingSmartActivatorTypeSubDevice);
    subType.gwDevId = gwDevId;
    [self.typedic setObject:subType forKey:subType.typeName];

    ThingSmartActivatorTypeBleModel *bleModel  = [[ThingSmartActivatorTypeBleModel alloc] init];
    bleModel.type = ThingSmartActivatorTypeBle;
    bleModel.scanType = ThingBluetoothScanTypeNoraml;
    bleModel.typeName = NSStringFromThingSmartActivatorType(ThingSmartActivatorTypeBle);

    ThingSmartActivatorTypeSigMeshModel *sigModel  = [[ThingSmartActivatorTypeSigMeshModel alloc] init];
    sigModel.type = ThingSmartActivatorTypeSigMesh;
    sigModel.typeName = NSStringFromThingSmartActivatorType(ThingSmartActivatorTypeSigMesh);
    sigModel.spaceId = homeId;

    ThingSmartActivatorTypeBeaconModel *beaconModel = [[ThingSmartActivatorTypeBeaconModel alloc] init];
    beaconModel.type = ThingSmartActivatorTypeBeacon;
    beaconModel.typeName = NSStringFromThingSmartActivatorType(ThingSmartActivatorTypeBeacon);

    [self.typedic setObject:bleModel forKey:bleModel.typeName];
    [self.typedic setObject:sigModel forKey:sigModel.typeName];
    [self.typedic setObject:beaconModel forKey:beaconModel.typeName];


    ThingSmartActivatorTypeRouterModel *routerType = [[ThingSmartActivatorTypeRouterModel alloc] init];
    routerType.type = ThingSmartActivatorTypeRouter;
    routerType.typeName = NSStringFromThingSmartActivatorType(ThingSmartActivatorTypeRouter);
    routerType.routerActiveDeviceList = [[[ThingSmartRouterActivator alloc]init] autoActiveRouterDeviceListWithHomeId:homeId];
    routerType.token = token;
    [self.typedic setObject:routerType forKey:routerType.typeName];


    ThingSmartActivatorTypeWiredModel *wiredType = [[ThingSmartActivatorTypeWiredModel alloc] init];
    wiredType.type = ThingSmartActivatorTypeWired;
    wiredType.typeName = NSStringFromThingSmartActivatorType(ThingSmartActivatorTypeWired);
    wiredType.spaceId = homeId;
    [self.typedic setObject:wiredType forKey:wiredType.typeName];

    ThingSmartActivatorTypePegasusModel *typeModel = [[ThingSmartActivatorTypePegasusModel alloc] init];
    typeModel.type = ThingSmartActivatorTypePegasus;
    typeModel.typeName = NSStringFromThingSmartActivatorType(ThingSmartActivatorTypePegasus);

    NSArray *array = [ThingSmartPegasusActivator pegasusDeviceListWithHomeID:homeId];
    NSMutableArray *devIds = [NSMutableArray array];
    [array enumerateObjectsUsingBlock:^(ThingSmartDeviceModel * _Nonnull obj, NSUInteger idx, BOOL * _Nonnull stop) {
        [devIds addObject:obj.devId];
    }];
    typeModel.pegasusServerDevIDs = devIds;
    typeModel.spaceId = homeId;
    [self.typedic setObject:typeModel forKey:typeModel.typeName];

    ThingSmartActivatorTypeEZModel *ezModel  = [[ThingSmartActivatorTypeEZModel alloc] init];
    ezModel.type = ThingSmartActivatorTypeEZSearch;
    ezModel.typeName = NSStringFromThingSmartActivatorType(ThingSmartActivatorTypeEZSearch);
    ezModel.spaceId = homeId;
    ezModel.token = token;
    ezModel.ssid = ssid;
    ezModel.password = password;
    [self.typedic setObject:ezModel forKey:ezModel.typeName];

    ThingSmartActivatorTypeMatterModel *matterModel = [[ThingSmartActivatorTypeMatterModel alloc] init];
    matterModel.type = ThingSmartActivatorTypeMatter;
    matterModel.typeName = NSStringFromThingSmartActivatorType(ThingSmartActivatorTypeMatter);
    matterModel.spaceId = homeId;
    [self.typedic setObject:matterModel forKey:matterModel.typeName];

    [self.discovery registerWithActivatorList:self.typedic.allValues];
    [self.discovery setupDelegate:self];
    [self.discovery startSearch:self.typedic.allValues];
}

- (void)activatorService:(id<ThingSmartActivatorSearchProtocol>)service activatorType:(ThingSmartActivatorTypeModel *)type didFindDevice:(ThingSmartActivatorDeviceModel *)device error:(ThingSmartActivatorErrorModel *)errorModel {

    if (errorModel) {
        [self _connectWifiError:errorModel];
        return;
    }

    if (self.typeModel.type == device.activatorType) {
        [self _handleDevice:device];
    }
}

- (ThingSmartActivatorDiscovery *)discovery {
    if (!_discovery) {
        _discovery = [[ThingSmartActivatorDiscovery alloc] init];
    }
    return _discovery;
}

Stop scanning

Swift:

discovery.stopSearch(typeList, clearCache: true)

Objective-C:

[self.discovery stopSearch:self.typedic.allValues clearCache:YES];