Wi-Fi EZ Mode

This topic describes pairing a device using the Wi-Fi EZ mode, also known as Wi-Fi Easy Connect or SmartConfig. In the pairing process, a mobile phone connects to the router and broadcasts the Wi-Fi credentials and pairing token. This enables the smart device to get this information for connection and pairing. It is easy-to-use, but has compatibility requirements for mobile phones and routers. The success rate is lower than that of AP mode.

Pairing process

Get a token

Before the Wi-Fi EZ pairing process, the SDK must get a pairing token from the cloud in the networked state. 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;

Parameters

Sample code

Objective-C:

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

Swift:

func getToken() {
    let ezActivator = ThingSmartActivator()
    ezActivator.getTokenWithHomeId(homeId, success: { token in
        print("getToken success: \(token)")
        // TODO: startConfigWiFi
    }, failure: { error in
        print("getToken failure: \(error.localizedDescription)")
    })
}

Callback of pairing delegate

For pairing in the Wi-Fi EZ mode, you only need to implement this delegate callback method to handle devices and errors. A callback will be made on this delegate when pairing is successful or fails such as pairing timeout and error.

API description

- (void)activator:(ThingSmartActivator *)activator didReceiveDevice:(ThingSmartDeviceModel *)deviceModel error:(NSError *)error;

Parameters

Start pairing

API description

- (void)startConfigWiFi:(ThingActivatorMode)mode
                   ssid:(NSString *)ssid
               password:(NSString *)password
                  token:(NSString *)token
                timeout:(NSTimeInterval)timeout;

Parameters

Sample code

Objective-C:

- (void)startConfigWiFi:(NSString *)ssid password:(NSString *)password token:(NSString *)token {
    // Implements the delegate method of ThingSmartActivator.
    self.ezActivator.delegate = self;
    // Start Wi-Fi EZ pairing, in which mode is set to ThingActivatorModeEZ.
    [self.ezActivator startConfigWiFi:ThingActivatorModeEZ ssid:ssid password:password token:token timeout:100];
}

- (ThingSmartActivator *)ezActivator {
    if (!_ezActivator) {
        _ezActivator = [[ThingSmartActivator alloc] init];
    }
    return _ezActivator;
}

#pragma mark - ThingSmartActivatorDelegate
- (void)activator:(ThingSmartActivator *)activator didReceiveDevice:(ThingSmartDeviceModel *)deviceModel error:(NSError *)error {

    if (!error && deviceModel) {
        // The device is paired.
    }

    if (error) {
        // Failed to pair the device.
    }
}

Swift:

func startConfigWiFi(ssid: String, password: String, token: String) {
     // Implements the delegate method of ThingSmartActivator.
    ezActivator.delegate = self
    // Start Wi-Fi EZ pairing, in which mode is set to ThingActivatorModeEZ.
    ezActivator.startConfigWiFi(.ez, ssid: ssid, password: password, token: token, timeout: 100)
}

lazy var ezActivator: ThingSmartActivator = {
     let activator = ThingSmartActivator()
    return activator
}()

// Implements the protocol method ThingSmartActivatorDelegate.
 func activator(_ activator: ThingSmartActivator, didReceiveDevice deviceModel: ThingSmartDeviceModel?, error: Error?)  {
    if let error = error {
        // Failed to pair the device.
        print("Config WiFi failed: \(error.localizedDescription)")
    } else if let deviceModel = deviceModel {
        // The device is paired.
        print("Config WiFi success: \(deviceModel)")
    }
}

Stop pairing

After the pairing process is started, the app continuously broadcasts the pairing data until a device is paired or the process times out. To allow users to cancel or complete pairing during the process, you must call the API method [ThingSmartActivator stopConfigWiFi] to stop pairing.

API description

- (void)stopConfigWiFi;

Sample code

Objective-C:

- (void)stopConfigWifi {
    self.ezActivator.delegate = nil;
    [self.ezActivator stopConfigWiFi];
}

Swift:

func stopConfigWifi() {
    ezActivator.delegate = nil
    ezActivator.stopConfigWiFi()
}