本章节提供了把WiFi设备配置上家庭路由器以及局域网内已联网设备的发现能力,具体方案包括一键广播配网、手机热点配网、蓝牙辅助配网、智能路由器配网以及设备间相互配网等。

依赖SDK 概述
日志 基础依赖SDK,提供客户端统一日志打印,日志等级控制,分模块日志隔离等能力。
API通道 提供API通道能力,和基础环境配置信息。
Breeze SDK 提供蓝牙辅助配网支持。

初始化

初始化前需确保已集成安全图片,初始化的操作请参见SDK初始化

使用说明

  • 设备发现

    提供获取局域网内已经配网的设备,包括WiFi设备以及以太网设备,以及局域网内已上电的待配设备(前提是当前局域网内内已经有一个已配好网的智能设备,且该设备支持未待配设备进行配网的能力)。

    • 启动发现设备
      发现本地的已配网设备,或者已配网设备、路由器发现的待配设备。发现的待配设备信息可以作为后续设备配网的入参信息。
      // 引入头文件
      #import <IMSDeviceCenter/IMLDeviceCenter.h>
      
      // 本地发现入口
      [[IMLLocalDeviceMgr sharedMgr] startDiscovery:^(NSArray *devices, NSError *err) {
              //devices 为 IMLCandDeviceModel 对象array,
              // 可根据 IMLCandDeviceModel 中的 devType 区分待配网设备联网类型:
              // 0代表wifi设备;1代表ethernet设备(网线连接):2代表路由器 ; @"ble_subtype_2" 代表蓝牙辅助配网设备*/
          }];
    • 获取所有已发现设备
      // 引入头文件
      #import <IMSDeviceCenter/IMLDeviceCenter.h>
      
      NSArray *allLanDevicesArray = [kLKLocalDeviceMgr getLanDevices];
    • 终止发现设备

      停止发现本地已配和线上待配设备,调用该接口会清除已发现设备列表,确保和startDiscovery成对调用。

      // 引入头文件
      #import <IMSDeviceCenter/IMLDeviceCenter.h>
      
      // 停止发现设备
      [kLKLocalDeviceMgr stopDiscovery];
  • 通用配网流程
    • 设置待添加设备信息

      待添加设备信息来源可以为上面本地发现的待配设备,也可以通过扫码等其他途径获取待配设备信息。

      // 引入头文件
      #import <IMSDeviceCenter/IMLDeviceCenter.h>
      
      // 选取本地发现的待配设备
      IMLCandDeviceModel *model = self.localDeviceList[index];
      [kLkAddDevBiz setDevice:model];
      说明 其中(IMLCandDeviceModel *)model 为本地发现待配设备或者云端拉取产品列表组装的model。

      本地发现设备参见上述设备发现部分内容。

      IMLCandDeviceModel 属性说明如下:

      属性 类型 是否必选 描述
      productKey NSString 设备的ProductKey
      deviceName NSString 设备名称
      productId NSString 待配设备产品ID,蓝牙辅助配网时为必选参数
      linkType assign 指定配网方式
      • ForceAliLinkTypeBroadcast:一键广播配网;
      • ForceAliLinkTypeHotspot:手机热点配网;
      • ForceAliLinkTypeSoftap:设备热点配网;
      • ForceAliLinkTypeQR:摄像头扫码配网;
      • ForceAliLinkTypeBLE:蓝牙辅助配网。
    • 设置配网模式
      // 引入头文件
      #import <IMSDeviceCenter/IMLDeviceCenter.h>
      
      [kLkAddDevBiz setAliProvisionMode:ForceAliLinkTypeHotspot];
    • 开始设备配网

      上述设置好待添加设备信息,进入配网。调用startAddDevice接口进入配网流程,并实现监听的协议方法。

      // 引入头文件
      #import <IMSDeviceCenter/IMLDeviceCenter.h>
      
      [kLkAddDevBiz startAddDevice:self];
      
      其中 self 为配网过程中 notifier 监听回调对象(代理)
      - (void)notifyPrecheck:(BOOL)success withError:(NSError *)err
      {
          NSLog(@"notifyPrecheck callback err : %@", err);
          dispatch_async(dispatch_get_main_queue(), ^{
              [self.addVC notifyProgress:LKAddStatePrechecking result:nil withError:err];
          });
      }
      
      // 用户引导页(一键配网和热点配网会有相关回调,指引用户接入相关操作)
      - (void)notifyProvisionPrepare:(LKPUserGuideCode)guideCode
      {
          NSLog(@"notifyProvisionPrepare callback guide code : %ld", guideCode);
          if(guideCode == LKPGuideCodeOnlyInputPwd){
              // TODO:一键广播配网相关引导
          } else if(guideCode == LKPGuideCodeWithUserGuide){
              // TODO:手机热点配网相关引导
          } else if(guideCode == LKPGuideCodeWithUserGuideForSoftAp) {
              // TODO:设备热点配网相关引导
          } else if(guideCode == LKPGuideCodeWithUserGuideForQR) {
              // TODO:摄像头扫码配网相关引导
          }
      
      
      }
      
      -(void)notifyProvisioning
      {
          NSLog(@"notifyProvisioning callback(正在进行配网...) ");
      }
      
      /**
      手机热点配网状态回掉调,提示用户关闭热点并切回以前的wifi,optional。
       */
      - (void)notifyProvisioningNotice{
          NSLog(@"notifyProvisioningNotice");
      }
      
      /*
       设备热点状态回调,optional。
      status 状态码 1=提示应该切换到设备热点; 2=已经切换到设备热点 3=已发送数据(dic里面会有"token") 4=应该切换回路由器 5=已经切换回路由器
      */
      - (void)notifyProvisioningNoticeForSoftAp:(int)status withInfo:(NSDictionary *)dic
      {
          NSLog(@"notifyProvisioningNoticeForSoftAp,%d,%@",status,dic);
      }
      
      /**
      摄像头二维码配网模式相关回调,optional
       @param qrcode 需要UI展现的二维码内容
       */
      - (void)notifyProvisioningNoticeForQR:(NSString *) qrcode;
      
      
      /**
       通知上层UI:配网完成结果回调
      
       @param candDeviceModel 配网结果设备信息返回:配网失败时为 nil
       @param provisionError 错误信息
       */
      - (void)notifyProvisionResult:(IMLCandDeviceModel *)candDeviceModel withProvisionError:(NSError *)provisionError
      {
          NSLog(@"配网成功:%@",candDeviceModel);
      }
    • 输入配网WiFi名称以及密码信息

      在收到- (void)notifyProvisionPrepare:(LKPUserGuideCode)guideCode回调引导完成相关操作(一键广播指引用户输入ssid和密码,热点配网指引用户开启热点,输入ssid和密码等)后,调用- (void)toggleProvision:(NSString *)ssid pwd:(NSString *)pwd timeout:(int)timeout方法,传入WiFi的ssidpassword信息。

      说明 一键广播配网和热点配网才会有notifyProvisionPrepare回调。
      // 引入头文件
      #import <IMSDeviceCenter/IMLDeviceCenter.h>
      
      - (void)notifyProvisionPrepare:(LKPUserGuideCode)guideCode
      {
          NSLog(@"notifyProvisionPrepare callback guide code : %ld", guideCode);
          [self inputSsidAndPassword];
      }
      
      - (void)inputSsidAndPassword
      {
          NSSstring *ssid = @"example ssid";
          NSString *password = @"1qaz@WSX";
          NSInterger timeout = 60;(单位秒,s);
          [kLkAddDevBiz toggleProvision:ssid pwd:password timeout:timeout];
      }
    • 配网过程关键节点监听处理

      针对热点配网必须监听该回调。

      // 引入头文件
      #import <IMSDeviceCenter/IMLDeviceCenter.h>
      
      - (void)notifyProvisionStatus:(LKProvisonStatus)provisionStatus boolSuccess:(BOOL)boolSuccess;
      {
          NSLog(@"notifyProvisionStatus callback provisionStatus:%d boolSuccess:%d", provisionStatus, boolSuccess);
          if(provisionStatus == LKProvisonStatusSwitchAP){
              // 设备回复 switch ap 请求,提示用户切换回之前的 wifi
              NSLog(@"请立即切换回开启热点之前的 wifi 网络");
          }
      }
    • 配网结果监听
      - (void)notifyProvisionResult:(IMLCandDeviceModel *)candDeviceModel withProvisionError:(NSError *)provisionError
      {
          if(candDeviceModel != nil){
              NSLog(@"配网成功:%@",candDeviceModel);
          } else{
              NSLog(@"配网失败,错误信息:%@", provisionError);
          }
      
      }
    • 停止配网
      // 引入头文件
      #import <IMSDeviceCenter/IMLDeviceCenter.h>
      
      [kLkAddDevBiz stopAddDevice];
  • 设备绑定

    当完成设备配网之后,后续需要将设备与用户或者与家庭做一个关联绑定,在绑定的时候需要调用SDK的获取token方法,取得设备token,然后进行设备绑定。获取token的代码如下。

    // 引入头文件
    #import <IMSDeviceCenter/IMLDeviceCenter.h>
    
    // self.productKey 和 self.deviceName 是配网成功后返回的物模型中的 productKey 和 deviceName
    [[IMLLocalDeviceMgr sharedMgr] getDeviceToken:self.productKey deviceName:self.deviceName timeout:20 resultBlock:^(NSString *token, BOOL boolSuccess) {
        NSLog(@"主动获取设备token:%@,boolSuccess:%d", token, boolSuccess);
        if(token){
        // 调用绑定接口进行设备绑定
        } else{
            NSLog(@"获取token失败(超时)");
        }
    }];

使用配网插件

配网插件基于Bone容器实现了完整的配网逻辑,因此在接入Bone容器的前提下,可以直接打开配网插件来完成配网逻辑,然后再自行处理配网之后的逻辑。

目前配网插件ID如下所示:

  • 插件ID国内版:a123kfz2KdRdrfYc
  • 插件ID国际版:a223c2beCJQ2Xpk2

插件ID的具体使用方式,参考见Bone容器部分。也可以参见配网开发指南中调用平台提供的配网插件的内容。

使用配网插件