热点模式

更新时间:2024-03-21 10:25:31下载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 库。

旧版配网流程

AppSDK设备云服务Wi-Fi 灯慢闪获取 Token获取 Token返回 Token返回 Token连上设备的热点开始配网 ssid/pwd/token发送配置信息 ssid/pwd/token自动关闭热点连上路由器 Wi-Fi去激活设备激活成功激活成功激活成功AppSDK设备云服务热点配网

获取 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 用户的配网成功率,因此引入一套新的配网流程机制,针对新设备固件才有效,只有新设备固件才支持。

App设备云服务连接路由器Wi-Fi 灯慢闪获取 Token返回 Token连上设备热点获取设备扫描到的 Wi-Fi 列表返回 Wi-Fi 列表用户选择对应的 Wi-Fi开始配网,发送配置信息自动关闭热点如果密码错误,连接路由器失败会重启热点内部指定时间内连接热点查询设备配网状态根据配网状态恢复配网重新下发 SSID 和密码根据 Token 每两秒钟轮询一次入网激活设备列表连接路由器成功去激活设备激活成功激活成功,返回设备列表App设备云服务热点配网

获取对应的安全配置列表

接口说明

- (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 列表信息失败