热点模式

热点配网又称 热点模式 或 AP (Access Point) 配网，是一种通过 Wi-Fi 进行配网的连接能力。将手机连接到配网设备 Wi-Fi 热点后，App 与设备直接通过 Wi-Fi 进行通信配网。成功率高、可靠性好，可适配 2.4G/5G 混频路由器配网，但用户需要手动切换手机的 Wi-Fi 设置。

配网方式

智能生活 App SDK 提供了两个版本的热点模式配网方式：

• 旧版配网流程：此流程直接向云端获取配网 Token 实现设备与云端的连接。

  接入条件：适用于所有设备。

• 新版配网流程：此流程会先与设备建立连接，通过设备扫描当前环境 Wi-Fi 列表，扫描出的 Wi-Fi 都是设备支持的配网的 Wi-Fi。如此，过滤了设备可能不支持 5G 网络的情况，从而提高用户配网体验，并提高配网成功率。

  接入条件：

  • 待配网设备的应用固件使用的 TuyaOS 版本号，不能低于 3.6.1。
  • 您需要登录 苹果开发者平台 为应用申请 Hotspot 权限。
  • 应用必须接入 ThingSmartHotspotCredentialKit 库。

旧版配网流程

1. 准备阶段。

   • 引导用户，将设备重置到热点模式，通常设备的 Wi-Fi 指示灯处于慢闪状态。
   • 引导用户，将手机连接到 Wi-Fi，通常是 2.4 GHz Wi-Fi。

2. 获取配网 Token 和 Wi-Fi 信息。

   • App 通过调用 SDK 提供的接口，获取配网 Token。
   • App 通过 UI 交互，获取用户输入的 Wi-Fi 信息，包括 SSID 和 password，其中 SSID 也可以通过调用系统 API 获取。

3. 热点连接。
   引导用户，将手机的网络连接切换到设备所发出的热点。

4. 开始配网。
   App 通过调用 SDK 提供的配网接口，设置 Wi-Fi 信息（SSID、password）和配网 Token 等参数，开始为设备配网。

5. 完成配网。
   配网完成后，设备的热点会自动关闭，App 会收到 SDK 的完成回调，结束配网流程。

获取 Token

开始配网之前，SDK 需要在联网状态下从涂鸦查询配网 Token，然后才可以开始热点模式配网。Token 的有效期为 10 分钟，且配置成功后就会失效。再次配网时，需要重新查询 Token。

接口说明

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

参数说明

参数	说明
homeId	设备将要绑定到的家庭的 ID
success	成功回调，返回配网 Token
failure	失败回调，返回失败原因

示例代码

Objective C：

- (void)getToken {
        ThingSmartActivator *apActivator = [[ThingSmartActivator alloc] init];
    [apActivator 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)")
    })
}

配网代理回调

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

参数说明

参数	说明
activator	配网使用 ThingSmartActivator 对象实例
deviceModel	配网成功时，返回此次配网的设备模型，失败时返回 nil
error	配网失败时，表示错误信息，成功时为 nil

开始配网

接口说明

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

参数说明

参数	说明
mode	配网模式
ssid	Wi-Fi 名称
password	Wi-Fi 密码
token	配网 Token
timeout	超时时间

示例代码

Objective C：

- (void)startConfigWiFi:(NSString *)ssid password:(NSString *)password token:(NSString *)token {
    // 设置 ThingSmartActivator 的 delegate，并实现 delegate 方法
    self.apActivator.delegate = self;

    // 开始配网，热点模式对应 mode 为 ThingActivatorModeAP
    [self.apActivator startConfigWiFi:ThingActivatorModeAP ssid:ssid password:password token:token timeout:100];
}

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

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

    if (!error && deviceModel) {
        //配网成功
    }

    if (error) {
        //配网失败
    }
}

// v4.0.0 新增：特殊安全设备在配网过程会回调中间过程
- (void)activator:(ThingSmartActivator *)activator didPassWIFIToSecurityLevelDeviceWithUUID:(NSString *)uuid {
        // 这时，引导用户连接到用户输入的 Wi-Fi 上
    // 即手机连接到与 `- startConfigWiFi:password:token:` 入参的 ssid 相同的 Wi-Fi 上

      // 您可以通过获取 SSID 名称，比对一致后调用 `- continueConfigSecurityLevelDevice` 来继续第二阶段的配网

//    UIAlertController *vc = [UIAlertController alertControllerWithTitle:@"SecurityLevelDevice" message:@"continue pair? (Please check you phone connected the same Wi-Fi as you Inputed)" preferredStyle:UIAlertControllerStyleAlert];
//    [vc addAction:[UIAlertAction actionWithTitle:@"cancel" style:UIAlertActionStyleCancel handler:nil]];
//    [vc addAction:[UIAlertAction actionWithTitle:@"continue" style:UIAlertActionStyleDestructive handler:^(UIAlertAction * _Nonnull action) {
//
//        NSString *wifi = [self getCurrentWiFi];
//        if ([wifi isEqualToString:self.inputSSID]) {
//            [self.apActivator continueConfigSecurityLevelDevice];
//        }
//    }]];
//    [self presentViewController:vc animated:YES completion:nil];
}

Swift：

func startConfigWiFi(withSsid ssid: String, password: String, token: String) {
    // 设置 ThingSmartActivator 的 delegate，并实现 delegate 方法
    apActivator.delegate = self

    // 开始配网
    apActivator.startConfigWiFi(ThingActivatorModeAP, ssid: ssid, password: password, token: token, timeout: 100)
}

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

#pragma mark - ThingSmartActivatorDelegate
func activator(_ activator: ThingSmartActivator!, didReceiveDevice deviceModel: ThingSmartDeviceModel!, error: Error!) {
    if deviceModel != nil && error == nil {
        //配网成功
    }

    if let e = error {
        //配网失败
        print("\(e)")
    }
}

// v4.0.0 新增：特殊安全设备在配网过程会回调中间过程
func activator(_ activator: ThingSmartActivator!, didPassWIFIToSecurityLevelDeviceWithUUID uuid: String!) {
        // 这时，引导用户连接到用户输入的 Wi-Fi 上
    // 即手机连接到与 `- startConfigWiFi:password:token:` 入参的 ssid 相同的 Wi-Fi 上

      // 您可以通过获取 ssid 名称比对一致后调用 `- continueConfigSecurityLevelDevice` 来继续第二阶段的配网

//        let alert = UIAlertController(title: "SecurityLevelDevice", message: "continue pair? (Please check you phone connected the same Wi-Fi as you Inputed)", preferredStyle: .alert);
//        alert.addAction(UIAlertAction(title: "cancel", style: .cancel))
//        alert.addAction(UIAlertAction(title: "continue", style: .destructive, handler: { _ in
//            let wifi = getCurrentWiFi()
//            if wifi == inputSSID {
//                apActivator.continueConfigSecurityLevelDevice()
//            }
//        }))
//        present(alert, animated: true)
}

热点模式配网与 快连模式 类似，把 [self.apActivator startConfigWiFi:ssid:password:token:timeout:] 的第一个参数改为 ThingActivatorModeAP 即可。

停止配网

开始配网操作后，App 会持续广播配网信息，直到配网成功，或者超时。如果需要中途取消操作或配网完成，请调用 [ThingSmartActivator stopConfigWiFi] 方法。

接口说明

- (void)stopConfigWiFi;

示例代码

Objective C：

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

Swift：

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

新版配网流程

为了提高用户的配网体验，减少出错概率，提高 SDK 用户的配网成功率，因此引入一套新的配网流程机制，针对新设备固件才有效，只有新设备固件才支持。

1. 准备阶段。
   引导用户，将设备重置到热点模式，通常设备的 Wi-Fi 指示灯处于慢闪状态。

2. 获取配网 Token 和安全配置信息。
   App 通过调用 SDK 提供的接口，获取配网 Token、安全配置信息。

3. 热点连接。
   引导用户，将手机的网络连接切换到设备所发出的热点。

4. 获取设备扫描到的 Wi-Fi 列表。
   App 通过调用 SDK 提供的接口，获取设备扫描到的、可以连接的 Wi-Fi 列表。

5. Wi-Fi 列表展示和信息获取。
   App 通过 UI 展示获取到的 Wi-Fi 列表，供用户选择一个 Wi-Fi 并输入对应的 password，获得 Wi-Fi 信息（SSID、password）。

6. 开始配网。
   App 通过调用 SDK 提供的配网接口，设置 Wi-Fi 信息、配网 Token、安全配置信息等参数，开始为设备配网。

7. 恢复配网（若发生错误）。
   当发生密码错误的情况下，App 可以调用 SDK 的恢复配网接口，更正 Wi-Fi 信息，恢复配网。

8. 完成配网。
   配网完成后，设备的热点会自动关闭，App 会收到 SDK 的完成回调，结束配网流程。

获取对应的安全配置列表

接口说明

- (void)getDeviceSecurityConfigs:(ThingSuccessDict)success
                         failure:(ThingFailureError)failure;

示例代码

Objective C：

self.activator = [[ThingSmartActivator alloc] init];
self.activator.delegate = self;
[self.activator getDeviceSecurityConfigs:^(NSDictionary *dict) {
  // 获取成功
} failure:^(NSError *error) {
  // 获取失败
}];

Swift：

activator.getDeviceSecurityConfigs { res in
  // 获取配置成功
} failure: { error in
  // 获取失败
}

查询设备扫描到的 Wi-Fi 列表

SDK 会先查询设备此时的状态，如果处于异常状态，例如 SDK 未能识别的状态，则不会查询 Wi-Fi 列表。

接口说明

- (void)connectDeviceAndQueryWifiListWithTimeout:(NSTimeInterval)timeout;

参数说明

参数	说明
timeout	可选项，如果大于 0，则会开启超时计时，单位为秒

示例代码

Objective C：

[self.activator connectDeviceAndQueryWifiListWithTimeout:120];

Swift：

activator.connectDeviceAndQueryWifiList(withTimeout: 120)

开始配网

可以根据查询到 Wi-Fi 列表，让用户选择。

接口说明

- (void)resumeAPPlusWithSSID:(NSString *)ssid
                    password:(NSString *)password
                       token:(NSString *)token
                     timeout:(NSTimeInterval)timeout;

参数说明

参数	说明
ssid	配网之后，设备工作 Wi-Fi 的名称
password	配网之后，设备工作 Wi-Fi 的密码
token	配网所需要的激活 Token
timeout	配网的超时时间设置，必传，单位是秒

示例代码

Objective C：

[self.activator resumeAPPlusWithSSID:@"SSID" password:@"password" token:@"token" timeout:120];

Swift：

activator.resumeAPPlus(withSSID: "SSID", password: "password", token: "token", timeout: 120)

恢复配网

一般在密码错误情况下，可以使用恢复配网，重新传入 Wi-Fi 名称和密码，恢复配网。

在配网过程中，SDK 会在指定时间内自动去连接热点，如果连上后，SDK 内部会去获取设备状态，上报给业务方。(只针对新设备固件有效)

接口说明

- (int)resumeConfigWiFi:(ThingSmartPairingResumeConfigWiFiParam*)param error:(NSError**)error;

参数说明

ThingSmartPairingResumeConfigWiFiParam

参数	说明
ThingActivatorMode	配网模式，此处传入 ThingActivatorModeAPPlus
ssid	路由器 SSID
password	路由器密码

示例代码

Objective C：

ThingSmartPairingResumeConfigWiFiParam *param = [ThingSmartPairingResumeConfigWiFiParam new];
param.ssid = activatorParam.apActivatorParams.ssid;
param.password = activatorParam.apActivatorParams.pwd;
param.mode = ThingActivatorModeAPPlus;
[self.activator resumeConfigWiFi:param error:nil];

Swift：

let param = ThingSmartPairingResumeConfigWiFiParam()
param.mode = .apPlus
param.ssid = "ssid"
param.password = "password"
activator.resumeConfigWiFi(param, error: nil)

停止配网

在配网停止后，或者是资源销毁时需要手动调用结束。

示例代码

Objective C：

[self.activator stopConfigWiFi];

Swift：

activator.stopConfigWiFi(）

错误码

错误码跟设备连接强关联，设备信息错误都是通过向设备获取。

错误码	说明
207201	和设备建立连接通道失败
207206	查询设备状态，设备返回了不能识别的状态，即非正常状态
207207	设备不支持获取 Wi-Fi 列表功能
207209	设备收到配网信息后,配网信息错误
207210	设备收到配网信息后，找不到路由器
207211	设备收到配网信息后，密码错误
207212	设备收到配网信息后，连接路由器失败
207213	设备收到配网信息后，DHCP 失败
207214	设备连接云端信息激活错误
207215	设备连接云端失败
207216	设备激活接口失败
207218	设备激活云端接口请求失败
207219	设备激活时，和云端 iot-dns 连接失败
207220	配网超时
207222	获取设备 Wi-Fi 列表信息失败