Wired Device Pairing

A wired device connects to a router over an Ethernet cable. During the pairing process, users do not need to enter the name and password of the router.

Pairing process

Register the pairing type

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

API description

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

Parameter description

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

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

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

Device search callback

After the wired device is discovered in the LAN, 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

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

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

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 table lists the common error codes.

Example

Swift:

class zigbeeGatewaymodeConfigurationVC: UITableViewController {

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

    private var typeModel: ThingSmartActivatorTypeWiredModel = {
        let type = ThingSmartActivatorTypeWiredModel()
        type.type = ThingSmartActivatorType.wired
        type.typeName = NSStringFromThingSmartActivatorType(ThingSmartActivatorType.wired)
        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() {
        discovery.startSearch([self.typeModel])
    }

}

extension zigbeeGatewaymodeConfigurationVC: 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
                let dList = [device]
                discovery.startActive(typeModel, deviceList: [device])
                SVProgressHUD.show(withStatus: NSLocalizedString("Activating", comment: "Active zigbeeGateway."))
            }, failure: { (error) in
                let errorMessage = error?.localizedDescription ?? ""
                SVProgressHUD.showError(withStatus: errorMessage)
            })
        }
    }

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

    }

}

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

        if (devices!.count > 0) {
            SVProgressHUD.showError(withStatus: NSLocalizedString("Success to Activate BLE Device", comment: ""))
        }
    }
}

Objective-C:

/// Get token
- (void)getToken {
    ThingSmartActivator *wiredActivator = [[ThingSmartActivator alloc] init];
    [wiredActivator getTokenWithHomeId:homeId success:^(NSString *token) {
        NSLog(@"getToken success: %@", token);
        [self startConfigWi-Fi:token];
    } failure:^(NSError *error) {
        NSLog(@"getToken failure: %@", error.localizedDescription);
    }];
}

/// Start search device
- (void)startConfigWi-Fi:(NSString *)token {
  ThingSmartActivatorTypeWiredModel *wiredModel = [[ThingSmartActivatorTypeWiredModel alloc] init];
  wiredModel.type = ThingSmartActivatorTypeWired;
  wiredModel.typeName = NSStringFromThingSmartActivatorType(ThingSmartActivatorTypeEZSearch);
  wiredModel.timeout = 120;
  wiredModel.spaceId = homeId;
  wiredModel.token = token;

  [self.discovery registerWithActivatorList:@[wiredModel]];
  [self.discovery setupDelegate:self];

  [self.discovery startSearch:@[wiredModel]];
}

/// device search callback
- (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];
    }
}

// device activate
- (void)_handleDevice:(ThingSmartActivatorDeviceModel *)deviceModel {
     ThingSmartActivatorTypeWiredModel *wiredModel = (ThingSmartActivatorTypeWiredModel *)[activatorGateway activatorTypeModelWith:ThingSmartActivatorTypeWired];
    [self.discovery startActive:wiredModel deviceList:@[deviceModel]];
}

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

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