热点模式

更新时间:2024-06-26 05:51:02下载pdf

热点配网又称 热点模式 或 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 即可。

ssidpassword 是需要填写的路由器的热点名称和密码,而不是设备的热点名称和密码。

停止配网

开始配网操作后,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 列表信息失败