平台已提供了一套完整的配网页面,如果您希望自己使用Native开发自己的定制化配网页面,可以阅读本文,使用配网SDK进行开发。

背景信息

配网SDK提供了将Wi-Fi设备连接上家庭路由器和发现局域网内已联网设备的能力,包括一键广播配网(P2P)、设备热点配网、蓝牙辅助配网和设备间相互配网(以下简称零配)等。各配网方式介绍参见Wi-Fi设备配网方案介绍配网SDK

设备热点配网

说明 需确保App已打开位置权限、GPS服务。
  1. 调用配网SDK的setDevice接口设置待配网设备信息。
    待配网设备信息分为指定产品型号productKey和不指定型号productKey两种。

    指定产品型号productKey的待配信息有三种获取方式:

    • 通过直接调用云端接口获取产品列表(非配网SDK提供接口),选择待配网设备对应的产品获取ProductKey。
    • 通过扫描二维码获得待配设备信息,包含设备ProductKey。
    • 调用SDKLocalDeviceMgrstartDiscovery接口,并根据回调获取SOFT_AP_DEVICE类型的待配设备。
  2. 开始配网。
    指定配网方式linkType为ForceAliLinkTypeSoftap,并调用配网SDK的startAddDevice接口开始配网。
  3. 配网准备阶段,传递Wi-Fi的SSID、password。
    App收到onProvisionPrepare prepareType=1回调后,调用SDK的toggleProvision方法传入当前连接路由器的SSID、password。
  4. 配网中,根据回调的参数,提示终端用户连接设备热点或恢复Wi-Fi连接。

    App收到onProvisionStatus回调后,根据以下回调的参数来提示终端用户。

    • 回调参数中status=ProvisionStatus.SAP_NEED_USER_TO_CONNECT_DEVICE_AP:引导终端用户连接设备热点,如引导用户连接adh_{pk}_{mac}格式的设备热点。

      Android 10及以上版本或发现不到设备热点或者连接不上设备热点时会发生该回调。

    • 回调参数中status=ProvisionStatus.SAP_NEED_USER_TO_RECOVER_WIFI:引导终端用户恢复Wi-Fi连接。

      一般当设备Wi-Fi未自动连接或者连接到无效Wi-Fi时,会发生该回调。

  5. 监听配网结果。
    可以在配网完成后调用LocalDeviceMgr getDeviceToken接口获取绑定token,并调用 基于token方式设备绑定完成设备的绑定。

完整示例代码如下。

/**
* 第一步:设置待配网设备信息
*/

DeviceInfo deviceInfo = new DeviceInfo();
//方式一:指定productKey方式
deviceInfo.productKey = "xx"; 
deviceInfo.id = "xxx";// 通过startDiscovery发现的设备会返回该信息,在配网之前设置该信息,其它方式不需要设置
deviceInfo.linkType = "ForceAliLinkTypeSoftAP";
//方式二:不指定型号
deviceInfo.productKey = null;
deviceInfo.protocolVersion = "2.0";
deviceInfo.linkType = "ForceAliLinkTypeSoftAP";

//设置待添加设备的基本信息
AddDeviceBiz.getInstance().setDevice(deviceInfo);

/**
* 第二步:开始配网
* 前置步骤,设置待配信息并开始配网
*/
AddDeviceBiz.getInstance().startAddDevice(context, new IAddDeviceListener(){
    @Override
    public void onPreCheck(boolean b, DCErrorCode dcErrorCode) {
        // 参数检测回调 
    }

    @Override
    public void onProvisionPrepare(int prepareType) {
        /**
         * 第三步:配网准备阶段,传入Wi-Fi信息
         * TODO 修改使用手机当前连接的Wi-Fi的SSID和password
        */
        if (prepareType == 1) {
            AddDeviceBiz.getInstance().toggleProvision("Your Wi-Fi ssid", "Your Wi-Fi password", 60);
        } 
    }

    @Override
    public void onProvisioning() {
        // 配网中
    }

    @Override 
    public void onProvisionStatus(ProvisionStatus provisionStatus) {
        /**
         * 第四步:配网中,配网UI引导
         * TODO 根据配网回调做 UI 引导
        */
        if (provisionStatus == ProvisionStatus.SAP_NEED_USER_TO_CONNECT_DEVICE_AP) {    
            // 比如android 10,或者非android 10发现或连接设备热点失败。    
            // 需要引导用户连接设备热点,否则会配网失败    
            return;
        }
        if (provisionStatus == ProvisionStatus.SAP_NEED_USER_TO_RECOVER_WIFI) {    
            // 引导用户恢复手机Wi-Fi连接,否则会配网失败    
            return;
        }
    }

    @Override
    public void onProvisionedResult(boolean isSuccess, DeviceInfo deviceInfo, DCErrorCode errorCode) {
        /**
         * 第五步:监听配网结果
        */
// 如果配网结果包含token,请使用配网成功带的token做绑定。
    }
});          

蓝牙辅助配网

需要新增以下蓝牙相关SDK依赖。

compile ('com.aliyun.alink.linksdk:breeze-biz:1.1.4') 
说明 需确保App已打开位置权限、GPS服务、蓝牙。
  1. 调用SDK的setDevice接口设置待配网设备信息。
    蓝牙辅助配网支持指定产品型号productKey进行配网,也支持不指定型号直接开始配网。

    指定产品型号productKey的待配信息有以下三种获取方式:

    • 通过直接调用云端接口获取产品列表(非配网SDK提供接口),选择待配网设备对应的产品获取ProductKey。
    • 通过扫描二维码获得待配设备信息,包含设备ProductKey。
    • 调用SDKLocalDeviceMgrstartDiscovery接口,并根据回调获取BLE_ENROLLEE_DEVICE类型的待配设备。
  2. 开始配网。
    指定配网方式linkType为ForceAliLinkTypeBLE,并调用配网SDK的startAddDevice接口开始配网。
  3. 配网准备阶段,传递Wi-Fi的SSID和password。
    App收到onProvisionPrepare prepareType=1回调后,调用SDK的toggleProvision方法传入当前连接路由器的SSID和password。
  4. 监听配网结果。
    可以在配网完成后调用LocalDeviceMgr getDeviceToken接口获取绑定token,并调用 基于token方式设备绑定完成设备的绑定。

完整代码示例如下。

/**
* 第一步:设置待配网设备信息
*/

DeviceInfo deviceInfo = new DeviceInfo();
//方式一:指定productKey和productId方式
deviceInfo.productKey = "xx"; //必填
deviceInfo.productId = "xxx"; //必填,可通过发现接口返回或者根据productKey或云端换取
deviceInfo.id = "xxx";// 通过startDiscovery发现的设备会返回该信息,在配网之前设置该信息,其它方式不需要设置
deviceInfo.linkType = "ForceAliLinkTypeBLE";
//方式二:不指定型号
deviceInfo.productKey = null;
deviceInfo.productId = null;
deviceInfo.protocolVersion = "2.0";
deviceInfo.linkType = "ForceAliLinkTypeBLE";

//设置待添加设备的基本信息
AddDeviceBiz.getInstance().setDevice(deviceInfo);

/**
* 第二步:开始配网
* 前置步骤,设置待配信息并开始配网
*/
AddDeviceBiz.getInstance().startAddDevice(context, new IAddDeviceListener(){
    @Override
    public void onPreCheck(boolean b, DCErrorCode dcErrorCode) {
        // 参数检测回调 
    }

    @Override
    public void onProvisionPrepare(int prepareType) {        
        /**
         * 第三步:配网准备阶段,传入Wi-Fi信息
         * TODO 修改使用手机当前连接的Wi-Fi的SSID和password
        */
        if (prepareType == 1) {
            AddDeviceBiz.getInstance().toggleProvision("Your Wi-Fi ssid", "Your Wi-Fi password", 60);
        } 
    }

    @Override
    public void onProvisioning() {
        // 配网中
    }

    @Override 
    public void onProvisionStatus(ProvisionStatus provisionStatus) { 
    }

    @Override
    public void onProvisionedResult(boolean isSuccess, DeviceInfo deviceInfo, DCErrorCode errorCode) {
        /**
         * 第四步:监听配网结果
        */
        // 如果配网结果包含token,请使用配网成功带的token做绑定。
    }
});          

一键配网

  1. 调用SDK的setDevice接口设置待配网设备信息。

    一键配网需要指定产品型号productKey进行配网。 获取指定产品型号productKey的待配信息有以下两种方式。

    • 通过直接调用云端接口获取产品列表(非配网SDK提供接口),选择待配网设备对应的产品获取ProductKey。
    • 通过扫描二维码获得待配设备信息,包含设备ProductKey。
  2. 开始配网。
    指定配网方式linkType为ForceAliLinkTypeBroadcast,并调用SDK的startAddDevice接口开始配网。
  3. 配网准备阶段,传递Wi-Fi的SSID和password。
    App收到onProvisionPrepare prepareType=1回调后,调用配网SDK的toggleProvision方法,传入当前连接路由器的SSID和password。
  4. 监听配网结果。
    可以在配网完成后调用LocalDeviceMgr getDeviceToken接口获取绑定token,并调用基于token方式设备绑定完成设备的绑定。

完整示例代码如下。

/**
* 第一步:设置待配网设备信息
*/

DeviceInfo deviceInfo = new DeviceInfo();
deviceInfo.productKey = "xx"; //必填
deviceInfo.linkType = "ForceAliLinkTypeBroadcast";

//设置待添加设备的基本信息
AddDeviceBiz.getInstance().setDevice(deviceInfo);

/**
* 第二步:开始配网
* 前置步骤,设置待配信息并开始配网
*/
AddDeviceBiz.getInstance().startAddDevice(context, new IAddDeviceListener(){
    @Override
    public void onPreCheck(boolean b, DCErrorCode dcErrorCode) {
        // 参数检测回调 
    }

    @Override
    public void onProvisionPrepare(int prepareType) {        
        /**
         * 第三步:配网准备阶段,传入Wi-Fi信息
         * TODO 修改使用手机当前连接的Wi-Fi的SSID和password
        */
        if (prepareType == 1) {
            AddDeviceBiz.getInstance().toggleProvision("Your Wi-Fi ssid", "Your Wi-Fi password", 60);
        } 
    }

    @Override
    public void onProvisioning() {
        // 配网中
    }

    @Override 
    public void onProvisionStatus(ProvisionStatus provisionStatus) { 
    }

    @Override
    public void onProvisionedResult(boolean isSuccess, DeviceInfo deviceInfo, DCErrorCode errorCode) {
        /**
         * 第四步:监听配网结果
        */
        // 如果配网结果包含token,请使用配网成功带的token做绑定。
    }
});          

零配配网

零配配网需要依赖当前手机Wi-Fi下有一个已配网绑定的设备和一个已上电并进入配网状态的设备,已配网设备发现待配设备后会上报到云端,App端可以获取待配的设备列表。

  1. 调用SDK的setDevice接口设置待配网设备信息。
    零配需要通过调用配网SDK的发现接口,来获取待配的设备信息。

    调用SDK的LocalDeviceMgrstartDiscovery接口,并根据回调获取CLOUD_ENROLLEE_DEVICE类型的待配设备。

  2. 开始配网。
    指定配网方式linkType为ForceAliLinkTypeZeroAP,并调用配网SDKstartAddDevice接口开始配网。
  3. 监听配网结果。
    可以在配网完成后调用LocalDeviceMgr getDeviceToken接口获取绑定token,并调用基于token方式设备绑定接口完成设备的绑定。

完整示例代码如下。

/**
* 第一步:设置待配网设备信息
*/

DeviceInfo toProvisionDeviceInfo = null;
EnumSet<DiscoveryType> enumSet = EnumSet.of(DiscoveryType.CLOUD_ENROLLEE_DEVICE);        
LocalDeviceMgr.getInstance().startDiscovery(this, enumSet, null, new IDeviceDiscoveryListener() {            
    @Override            
    public void onDeviceFound(DiscoveryType discoveryType, List<DeviceInfo> list) {                
        if (list != null && !list.isEmpty() && discoveryType == DiscoveryType.CLOUD_ENROLLEE_DEVICE) {
            // 建议将发现的设备在UI上做展示,让用户触发对某个设备进行配网
            // 发现的待配设备列表缓存在内存中,用户触发配网的时候将待配信息设置到SDK配网接口
        }
    }
}

// list是通过发现接口发现的零配待配设备
toProvisionDeviceInfo = list.get(0); 
toProvisionDeviceInfo.linkType = "ForceAliLinkTypeZeroAP"; 
// 设置待添加设备的基本信息
AddDeviceBiz.getInstance().setDevice(toProvisionDeviceInfo);

/**
* 第二步:开始配网
* 前置步骤,设置待配信息并开始配网
*/
AddDeviceBiz.getInstance().startAddDevice(context, new IAddDeviceListener(){
    @Override
    public void onPreCheck(boolean b, DCErrorCode dcErrorCode) {
        // 参数检测回调 
    }

    @Override
    public void onProvisionPrepare(int prepareType) {        
    }

    @Override
    public void onProvisioning() {
        // 配网中
    }

    @Override 
    public void onProvisionStatus(ProvisionStatus provisionStatus) { 
    }

    @Override
    public void onProvisionedResult(boolean isSuccess, DeviceInfo deviceInfo, DCErrorCode errorCode) {
        /**
         * 第三步:监听配网结果
        */
        // 如果配网结果包含token,请使用配网成功带的token做绑定。
    }
});          

设备绑定

配网SDK提供了获取设备端token的接口,该token可用于账号和设备的绑定(绑定接口非配网SDK提供,请参见基于token方式设备绑定)。

  1. 获取绑定token。
    可通过以下方式获取绑定使用的token。
    • 调用本地发现接口,返回的已配设备列表设备信息中包含token。
    • 主动调用SDK接口获取token。

    第一种方式可以参考零配或者路由器配网的本地发现接口调用示例,本文档主要介绍第二种方式。

  2. 绑定token。
    使用设备的ProductKey、DeviceName、Token调用基于token方式设备绑定接口进行绑定。

    样例代码如下。

    /**
    * 第一步:获取绑定token
    */
    LocalDeviceMgr.getInstance().getDeviceToken(productKey, deviceName, 60*1000, 10*1000, new IOnDeviceTokenGetListener() {
        @Override
        public void onSuccess(String token) {
            // 获取绑定需要的token
            /**
            * 第二步:调用绑定接口
            */
            //TODO 用户根据具体业务场景调用
        }
    
        @Override
        public void onFail(String reason) {
        }
    });                     
    说明
    • 使用本地发现的信息绑定设备时,如果出现超时(如获取token之后过了很久才去绑定),可以主动调用getDeviceToken接口更新绑定token后,重新调用绑定接口。
    • 绑定token有一定的有效时限,失败的时候可以主动重试。