热点模式

更新时间：2024-06-24 06:51:53下载pdf

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

配网方式

商用照明 App SDK 提供两个版本的热点模式配网方式：

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

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

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

旧版配网流程

获取 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 即可。

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

停止配网

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

获取对应的安全配置列表

接口说明

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

上一篇快连模式