Wi-Fi EZ Mode

This topic describes the Wi-Fi Easy Connect (EZ) or SmartConfig mode to pair devices. After a user connects a mobile phone to a router, the router broadcasting is used to communicate and pair the mobile phone with the device. It is easy-to-use, but has compatibility requirements for mobile phones and routers. The success rate is lower than that of hotspot or access point (AP) mode.

Pairing process

1. Before pairing

   • Guide the user to reset the device to Wi-Fi EZ mode, typically identified by a fast-blinking Wi-Fi indicator.
   • Guide the user to connect their phone to a Wi-Fi network, usually a 2.4 GHz Wi-Fi network.

2. Get pairing token and Wi-Fi network credentials

   • The app gets the pairing token by calling the method in the SDK.
   • The app gets the Wi-Fi network credentials (SSID and password) input by the user. The SSID can also be obtained through an API call.

3. Start pairing
   The app calls the pairing method in the SDK to set the Wi-Fi network credentials (SSID and password) and the pairing token.

4. Finish pairing
   The app receives a callback from the SDK and finishes the 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

Example

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 and handle the devices and errors in this method. When pairing is successful or fails (in case of pairing timeout or error), callbacks are made on this delegate.

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

Example

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;

Example

Objective-C:

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

Swift:

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