Pegasus Pairing

Routers and Wi-Fi devices that have Pegasus pairing enabled can be used to pair other Wi-Fi devices. The Pegasus pairing process consists of two steps: search and activation. In the search step, a server (a device that is paired) searches for a client (a device that is not paired). In the activation step, a server sends the network information directly to the client for connection and activation.

Pairing process

Query Pegasus-enabled devices

You can call the following method in the ThingSmartPegasusActivator to get the Pegasus-enabled devices in the current home.

/// Returns the devices that support Pegasus.
/// @param homeID The home ID.
/// @return A list of devices that support Pegasus.
+ (NSArray <ThingSmartDeviceModel *> *)pegasusDeviceListWithHomeID:(long long)homeID;

Parameters	Description
homeId	The home ID.

Register the pairing type

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

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.

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.

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.

Activate a device

API description

/// 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;

Parameter description

Parameters	Description
type	The pairing type.
deviceList	The list of devices to be activated. Currently, only one device is supported.

Stop activation

API description

/// 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;

Parameter description

Parameters	Description
typeList	The pairing type.
clearCache	Specifies whether to clear the cache search result.

Activation callback

API description

// Device network configuration result callback
/// @param service Device network configuration implementation object
/// @param type Network configuration type
/// @param devices Devices being configured
/// @param errorModel Error encountered during network configuration
- (void)activatorService:(id<ThingSmartActivatorActiveProtocol>)service
           activatorType:(ThingSmartActivatorTypeModel *)type
       didReceiveDevices:(nullable NSArray<ThingSmartActivatorDeviceModel *> *)devices
                   error:(nullable ThingSmartActivatorErrorModel *)errorModel;

Parameter description

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

Error codes

ThingSmartActivatorErrorModel is returned if pairing fails or times out.

@interface ThingSmartActivatorErrorModel : NSObject
@property (nonatomic, strong) ThingSmartActivatorDeviceModel *deviceModel;
@property (nonatomic) NSError *error;
@end

ThingSmartActivatorDiscoveryError includes the definition of error codes. The following are the common error codes.

Error codes	Description
ThingSmartActivatorDiscoveryErrorTimeout	Pairing timeout.
ThingSmartActivatorDiscoveryErrorDeviceAlreadyBound	Strong binding error. The device is already bound with a user. Pairing can work only after the device is unbound from the current user.
ThingSmartActivatorDiscoveryErrorAPPUnsupportProduct	The app used for pairing is not bound with the product.
ThingSmartActivatorDiscoveryErrorTokenExpired	Token expired.
ThingSmartActivatorDiscoveryErrorGuestNotSupportStrongBind	A guest account is not allowed to pair a device of strong binding.
ThingSmartActivatorDiscoveryErrorRemoteApiParamIllegal	Invalid parameter.

Example

Swift:

class pegasusModeConfigurationVC: UITableViewController {

    private var token: String = ""
    var deviceList:[ThingSmartActivatorDeviceModel] = []

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

    lazy var discovery: ThingSmartActivatorDiscovery = {
        let discovery = ThingSmartActivatorDiscovery()
        discovery.register(withActivatorList: [self.typeModel])
        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)
        }

        typeModel.pegasusServerDevIDs = devIds
        discovery.startSearch([self.typeModel])
    }

}

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

        if let device = device {
            SVProgressHUD.dismiss()
            guard let homeID = Home.current?.homeId else { return }
            ThingSmartActivator.sharedInstance()?.getTokenWithHomeId(homeID, success: { [weak self] (token) in
                guard let self = self else { return }
                typeModel.token = token ?? ""
                typeModel.spaceId = homeID
                discovery.startActive(typeModel, deviceList: [device])
                SVProgressHUD.show(withStatus: NSLocalizedString("Activating", comment: "Active pegasus ."))
            }, failure: { (error) in
                let errorMessage = error?.localizedDescription ?? ""
                SVProgressHUD.showError(withStatus: errorMessage)
            })
        }
    }

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

    }

}

extension pegasusModeConfigurationVC: ThingSmartActivatorActiveDelegate {
    func activatorService(_ service: ThingSmartActivatorActiveProtocol, activatorType type: ThingSmartActivatorTypeModel, didReceiveDevices devices: [ThingSmartActivatorDeviceModel]?, error errorModel: ThingSmartActivatorErrorModel?) {
        if (errorModel != nil) {
            SVProgressHUD.showError(withStatus: NSLocalizedString("Failed to Activate pegasus Device", comment: ""))
            return
        }

        if (devices!.count > 0) {
            let deviceModel = devices?.first
            let name = deviceModel?.name ?? NSLocalizedString("Unknown Name", comment: "Unknown name device.")
            SVProgressHUD.showSuccess(withStatus: NSLocalizedString("Successfully Added \(name)", comment: "Successfully added one device."))
        }
    }

}

Objective-C:

- (void)starSearch:(NSString *)token {
  ThingSmartActivatorTypePegasusModel *pegasusModel  = [[ThingSmartActivatorTypePegasusModel alloc] init];
  pegasusModel.type = ThingSmartActivatorTypePegasus;
  pegasusModel.typeName = NSStringFromThingSmartActivatorType(ThingSmartActivatorTypePegasus);
  pegasusModel.timeout = 120;
  pegasusModel.spaceId = homeId;

  NSArray *array = [ThingSmartPegasusActivator pegasusDeviceListWithHomeID:homeId];
  NSMutableArray *devIds = [NSMutableArray array];
  [array enumerateObjectsUsingBlock:^(ThingSmartDeviceModel * _Nonnull obj, NSUInteger idx, BOOL * _Nonnull stop) {
      [devIds addObject:obj.devId];
  }];
  pegasusModel.pegasusServerDevIDs = devIds;

  [self.discovery registerWithActivatorList:@[pegasusModel]];
  [self.discovery setupDelegate:self];
  typeModel.pegasusServerDevIDs = [ThingSmartActivatorLinkTool pegasusDeviceIdList];
  [self.discovery startSearch:@[pegasusModel]];
}

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

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

    if (device) {
        [self _handleDevice:device];
    }
}

- (void)_handleDevice:(ThingSmartActivatorDeviceModel *)deviceModel {
     ThingSmartActivatorTypePegasusModel *pegasusModel = (ThingSmartActivatorTypePegasusModel *)[activatorGateway activatorTypeModelWith:ThingSmartActivatorTypePegasus];

     ThingSmartActivator *activator = [[ThingSmartActivator alloc] init];
    [activator getTokenWithHomeId:homeId success:^(NSString *token) {
        NSLog(@"getToken success: %@", token);
        pegasusModel.token = token;
        [self.discovery startActive:pegasusModel deviceList:@[deviceModel]];
    } failure:^(NSError *error) {
        NSLog(@"getToken failure: %@", error.localizedDescription);
    }];


}

- (void)activatorService:(id<ThingSmartActivatorActiveProtocol>)service
           activatorType:(ThingSmartActivatorTypeModel *)type
       didReceiveDevices:(nullable NSArray<ThingSmartActivatorDeviceModel *> *)devices
                   error:(nullable ThingSmartActivatorErrorModel *)errorModel {
     if (devices && devices.count > 0) {

     }
}

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