iOS 配网 SDK 使用说明

版本历史

目录结构

第1部分----------集成SDK
第2部分----------配网流程说明
第3部分----------使用示例
第4部分----------参考资料

术语说明

1 集成SDK

1.1 添加SDK所需权限

1.1.1 使用 sdk 前请在 Xcode -> Targets -> Signing&Capabilities -> Capability 中添加以下权限

1. Access WiFi Information
2. BackGround Modes

1.1.2 开启手机定位权限，用于获取当前 WiFI 信息

1.2 手动添加相关库

在 Xcode -> Targets -> Build Phases -> Link Binary With Libraries中，添加如下库：

1. AVFoundation.framework
2. libc++.tbd
3. libiconv.2.4.0.tbd

1.3 关闭 Bitcode

请将 Xcode -> Targets -> Build Settings -> Enable Bitcode 设置为 NO。

当你正确完成以上三个步骤后，您就已经成功集成SDK，接下来可以开始使用SDK。

2 配网流程说明

在您开始进行调用配网接口之前，或者当您在调用配网接口过程中遇到疑问时，您可以通过以下流程图大致了解SDK的工作流程，以便您更好的了解和使用配网SDK。

3 使用示例

如果您之前接触过萤石设备，您可能已经了解到支持无线功能的萤石设备支持多种配网方式。对于支持无线功能的某个型号的萤石设备虽然支持一种或者多种配网方式，但是通常情况下至少会有一种默认的配网方式。而默认的配网方式是我们通过SDK成功为设备配网的关键，我们只有通过调用设备默认的配网方式对应的配网接口，我们才有可能成功为设备配网。
目前萤石常用的配网方式有AP配网、SmartConfig配网、声波配网等多种方式，当您从萤石设备的提供方确认好某个型号的萤石设备的默认的配网方式，并且将设备重置到配网状态后，您就可以开始调用配网SDK为设备配网。以下是不同的配网方式对应的配网示例代码，您可以直接复用相关示例代码，并按照示例代码的提示加入您自己的业务逻辑。

3.1 AP配网

关键接口

/**
 AP配网接口，请确保已连接至设备热点

 @param wifiSsid WiFi的名称
 @param wifiPwd WiFi的密码
 @param deviceSerial 设备序列号
 @param verifyCode 设备验证码
 @param resultBlock 配网结果回调
 @return 方法执行结果
 */
- (BOOL) startAPWifiConfigWithWifiName:(NSString *) wifiSsid
                               wifiPwd:(NSString *) wifiPwd
                          deviceSerial:(NSString *) deviceSerial
                            verifyCode:(NSString *) verifyCode
                                reuslt:(void(^)(BOOL ret)) resultBlock;

/**
 停止AP配网，配网结束后需调用
 */
- (void) stopAPWifiConfig;

示例代码

//开启日志回调
[EZWiFiConfigManager setDebugLogOpen:YES logCallBack:^(NSString *logStr) {
        NSLog(@"%@", logStr);
}];

[[EZWiFiConfigManager sharedInstance] startAPWifiConfigWithWifiName:self.ssid.text.length>0?self.ssid.text:SSID
                                                                wifiPwd:self.password.text.length>0?self.password.text:PWD
                                                           deviceSerial:self.deviceSerial.text.length>0?self.deviceSerial.text:DeviceSeiral
                                                             verifyCode:self.verifyCode.text.length>0?self.verifyCode.text:VerifyCode
                                                                 reuslt:^(BOOL ret) {
        NSLog(@"AP config result:%d", ret);
}];

3.2 SmartConfig & 声波配网

关键接口

/* 配网方式 */
typedef NS_ENUM(NSInteger, EZWiFiConfigMode)
{
    EZWiFiConfigSmart        = 1 << 0,   //smart config
    EZWiFiConfigSonic         = 1 << 1,  //声波配网
};
/**
 配网接口，请确保手机与设备处在同一网络环境下，声波配网时将音量调到最大，用以提高配网成功率

 @param wifiSsid WiFi的名称
 @param wifiPwd WiFi的密码
 @param deviceSerial 设备序列号，序列号为空则为批量配网
 @param mode 配网模式，可同时进行两种配网方式
 @param resultBlock 配网结果回调
 @return 方法执行结果
 */
- (BOOL) startWifiConfigWithWifiSsid:(NSString *) wifiSsid
                             wifiPwd:(NSString *) wifiPwd
                        deviceSerial:(NSString *) deviceSerial
                                mode:(EZWiFiConfigMode) mode
                              reuslt:(void(^)(EZWifiConfigStatus status,NSString *deviceSerial,NSError *error)) resultBlock;

/**
 停止配网，配网结束后需调用
 */
- (void) stopWifiConfig;

示例代码

[[EZWiFiConfigManager sharedInstance] startWifiConfigWithWifiSsid:self.ssid.text.length>0?self.ssid.text:SSID
                                                          wifiPwd:self.password.text.length>0?self.password.text:PWD
                                                     deviceSerial:self.deviceSerial.text.length>0?self.deviceSerial.text:DeviceSeiral
                                                             mode:EZWiFiConfigSmart
                                                           reuslt:^(EZWifiConfigStatus status, NSString *deviceSerial, NSError *error) {

    if (error)
    {
        [[EZWiFiConfigManager sharedInstance] stopWifiConfig];
        return;
    }

    switch (status) {
        case DEVICE_WIFI_CONNECTING:
        {
            NSLog(@"Wi-Fi连接中...");
        }
            break;
        case DEVICE_WIFI_CONNECTED:
        {
            NSLog(@"Wi-Fi连接成功");
        }
            break;
        case DEVICE_PLATFORM_REGISTED:
        {
            NSLog(@"注册平台成功");
            [[EZWiFiConfigManager sharedInstance] stopWifiConfig];
        }
            break;
        default:
            break;
    }
}];

3.2 接触式配网（New AP Config）

关键接口

/// 设置apiUrl（默认国内域名）
/// @param url apirUrl
- (void) setApiUrl:(NSString *)url;

/// 获取配网token
/// @param accessToken 开放平台token
/// @param handler 回调
- (BOOL) requestConfigToken:(NSString *)accessToken
          completionHandler:(void(^)(EZConfigTokenInfo *tokenInfo, NSDictionary *msgInfo, NSError *error))handler;

/// 开始NewAP配网（需连接设备热点）
/// @param token 配网token
/// @param ssid WiFi ssid
/// @param password WiFi 密码
/// @param lbsDomain lbs 域名
/// @param handler 回调
- (BOOL) startNewApConfigWithToken:(NSString *)token
                              ssid:(NSString *)ssid
                          password:(NSString *)password
                         lbsDomain:(NSString *)lbsDomain
                 completionHandler:(void(^)(EZNewAPConfigStatus status, NSError *error))handler;

/// 获取设备状态（需连接设备热点）
/// @param handler 回调
- (void) getAccessDeviceInfo:(void(^)(EZAPDevInfo *devInfo, NSError *error))handler;

/// 获取设备当前周边WiFi列表，上限20个（需连接设备热点）
/// @param handler 回调
- (void) getAccessDeviceWifiList:(void(^)(NSArray<EZWiFiItemInfo*> *wifiList, NSError *error))handler;

示例代码

__weak typeof(self) weakSelf = self;
[[EZWiFiConfigManager sharedInstance] requestConfigToken:self.accessToken.text.length>0?self.accessToken.text:AccessToken
                                       completionHandler:^(EZConfigTokenInfo *tokenInfo, NSDictionary *msgInfo, NSError *error) {

    if (error)
    {
        NSLog(@"error:%@",error);
    }
    else
    {
        weakSelf.tokenInfo = tokenInfo;
        NSLog(@"msg:%@\n%@", msgInfo, tokenInfo);
    }
}];

[[EZWiFiConfigManager sharedInstance] startNewApConfigWithToken:self.configToken.text.length>0?self.configToken.text:self.tokenInfo.token
                                                           ssid:self.ssid.text.length>0?self.ssid.text:SSID
                                                       password:self.password.text.length>0?self.password.text:PWD
                                                      lbsDomain:self.tokenInfo.lbsDomain
                                              completionHandler:^(EZNewAPConfigStatus status, NSError *error) {

    if (error)
    {
        NSLog(@"error:%@",error);
    }
    else
    {
        NSLog(@"New AP Config result: %d", (int)status);
    }
}];

4 参考资料

若文档有未尽之处，请参考 demo。点击跳转到github下载