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

背景信息

配网SDK提供了把WiFi设备配置上家庭路由器以及局域网内已联网设备的发现能力,具体方案包括一键广播配网(P2P)、手机热点配网、智能路由器配网和设备间相互配网(以下简称零配)等。各配网方式介绍参见配网方案介绍配网SDK

一键配网

  1. 发现设备。
    发现设备即获取待配设备的ProductKey和DeviceName。获取的设备信息主要包括设备的 ProductKey(可以理解为产品类型)、DeviceName(设备名称),可通过以下方式获取如下。
    • 通过直接调用云端接口获取产品列表(非配网 SDK 提供接口),选择待配网设备对应的产品拿到 ProductKey。
    • 通过扫描二维码获得待配设备信息,包含设备 ProductKey 和 DeviceName(可选)。
    • 调用SDKLocalDeviceMgr)。
  2. 开始配网。
    使用步骤1发现设备中获取到的待配网设备信息构造DeviceInfo对象,设置使用的配网方式linkType的值,然后调用SDK setDeviceInfo设置待配网设备信息。
  3. 配网中,收到provisionPrepare回调后,调用SDK toggleProvision方法传入当前连接路由器的ssidpassword
  4. 监听配网结果。
    可以在配网完成之后调用 LocalDeviceMgr

示例代码如下。

/**

* 第一步 发现设备

*/
String productKey = "xxx";//TODO 用户根据实际情况设置
String deviceName = "xxx";//TODO 用户根据实际情况设置,可为空。

/**

* 第二步 开始配网

* 设置待配信息 开始配网

*/
DeviceInfo info = new DeviceInfo();
info.productKey = productKey;
info.deviceName = deviceName; 
info.linkType = LinkType.ALI_BROADCAST.getName();
AddDeviceBiz.getInstance().setDevice(info);
AddDeviceBiz.getInstance().startAddDevice(context, new IAddDeviceListener() {
            @Override
            public void onPreCheck(boolean isSuccess, DCErrorCode dcErrorCode) {
            }

            @Override
            public void onProvisionPrepare() {
                /**
                * 第三步 配网中 传入WiFi 信息
                */
                AddDeviceBiz.getInstance().toggleProvision(mSsid, mPwd, 60);
            }

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

            @Override
            public void onProvisionStatus(ProvisionStatus provisionStatus) {} //Deprecated

            @Override
            public void onProvisionedResult(boolean isSuccess, DeviceInfo info, DCErrorCode dcErrorCode) {
                /**
                * 第四步 监听结果回调
                */
        });
			

在收到onProvisionedResult且配网失败时,可按照错误信息做进一步的处理。

  • 如果收到codeName="NETWORK_ERROR"&subcode=60101错误信息,则表示当前手机连接的是5G WiFi,可以提示用户切换到2.4G WiFi。
  • 如果收到codeName="NETWORK_ERROR"&subcode= 60102错误信息,则表示当前手机未连接 WiFi,可提示用户连接WiFi。

热点配网

  1. (可选)发现设备。
    发现设备即获取待配设备的ProductKey和DeviceName。可通过以下方式获取。
    • 通过直接调用云端接口获取产品列表(非配网 SDK 提供接口),选择待配网设备对应的产品获取ProductKey。
    • 通过扫描二维码获得待配设备信息,包含设备 ProductKey 和 DeviceName。
    • 调用SDK LocalDeviceMgr startDiscovery()本地发现接口发现设备(热点配网情况下使用这种方式发现需要当前局域网有一个已配的设备)。
  2. 开始配网。
    1. 手机开启热点。
      调用HotspotHelper
      • 如果返回失败,提示用户手动开启aha热点,开启成功之后进行下一步。
      • 如果返回成功,则进行下一步。
    2. 发现连上热点的设备。
      调用接口发现设备时,需确认是否为需要配网的设备,一般手机在通知栏会提示有设备连接上热点。
      说明 设备可能需要触发才会进入配网模式,请根据提示操作。
    3. 设置WiFi连接信息。
      调用SDK接口,会发送WiFi连接信息到选择的设备上。
    4. 恢复网络连接。
      调用SDK接口关闭热点,并恢复网络连接。如果恢复网络后连接的不是之前连接的热点,则需要手动切换到之前的热点。
    5. 设置待配网设备信息。
      1. 使用设备信息构造DeviceInfo对象。
      2. 设置配网方式linkType为热点配网。
      3. 调用SDKsetDeviceInfo设置待配网设备信息。
      4. 调用 SDKstartAddDevice配网方法,开始配网。
  3. 配网中,可进行配网中间状态回调。
  4. 监听配网结果。
    可以在配网完成后调用LocalDeviceMgr getDeviceToken接口获取绑定token,完成绑定操作。

示例代码如下。

/**

* 第一步 发现设备
*/
String productKey = "xxx";//TODO 用户根据实际情况设置
String deviceName = "xxx";//TODO 用户根据实际情况设置,可为空。
/**

* 第二步 开始配网
* 前置步骤 设置待配信息 开始配网

*/
// 2.1 开启热点
HotspotHelper.getInstance().setupWifiAP(context, new HotspotHelper.ISetupWifiAPListener() {
    @Override
    public void onEnable() {
        // 热点开启成功
    }

    @Override
    public void onFail() {
        //TODO 热点开启失败,提示用户手动开启 aha 热点,密码 12345678,之后进行下一步操作。
    }
});


// 2.2 发现连接到热点的设备 (开启热点成功之后调用)
private LocalDevice foundDevice = null;
HotspotHelper.getInstance().discoveryDevices(new HotspotHelper.IPAPDiscoveryListener() {
    @Override
    public void onFound(final LocalDevice device) {
        // 每发现一个设备返回一个
        if(device != null && device.productKey.equals(productKey)){ // TODO 根据需要配置的设备做匹配
            foundDevice = device; //发现了需要配网的设备
        } 
    }
});

// 2.3 发送 ssid 和 password (发现需要配网的设备之后调用)
String ssid = "xxx"; //TODO 开启热点之前的ssid,可以开启热点之前获取并保留
String password = "xxx"; //TODO 由用户输入
DeviceInfo toProvisionDeviceInfo = null;
HotspotHelper.getInstance().switchAP(foundDevice, ssid,
    mPassword, new HotspotHelper.ISwitchApResultListenr() {
    @Override
    public void onSucc(final DeviceInfo deviceInfo) {
        toProvisionDeviceInfo = deviceInfo;

        // 2.4 恢复网络连接
        HotspotHelper.getInstance().recoverWiFiConnect(this);
        // 2.5 设置待配设备信息 开始监听配网结果
        startConfig(toProvisionDeviceInfo);
    }

    @Override
    public void onFail(String msg) {
        // 切换失败 可根据错误信息判断是否
    }
});


public void startConfig(DeviceInfo toProvisionDeviceInfo){
        DeviceInfo info = toProvisionDeviceInfo;
        info.linkType = LinkType.ALI_PHONE_AP.getName();
        AddDeviceBiz.getInstance().setDevice(info);
        AddDeviceBiz.getInstance().startAddDevice(context, new IAddDeviceListener() {
            @Override
            public void onPreCheck(boolean isSuccess, DCErrorCode dcErrorCode) {}

            @Override
            public void onProvisionPrepare() {}

            @Override
            public void onProvisioning() {
                /**
                 * 第三步 配网中
                 * 根据实际场景处理
                 */
            }

            @Override
            public void onProvisionStatus(ProvisionStatus provisionStatus) {}

            @Override
            public void onProvisionedResult(boolean isSuccess, DeviceInfo info, DCErrorCode dcErrorCode) {
                // TODO 配网成功或失败的处理操作
                /**
                 * 第四步 配网结果
                 * 根据实际场景处理
                 */
            }
        });
    }           

零配

  1. 发现设备。
    调用配网SDK LocalDeviceMgr
  2. 开始配网。
    使用 发现设备步骤中获取到设备信息(DeviceInfo对象),调用方法设置待配网设备。无需设置配网方式,直接透传发现到的设备信息对象(DeviceInfo对象),SDK自动匹配使用哪种配网方式。

    调用开始配网接口,设置监听回调。

  3. 配网中,可进行配网中间状态回调。
  4. 监听配网结果。
    可以在配网完成之后调用LocalDeviceMgr getDeviceToken接口获取绑定token,完成绑定操作。

示例代码如下。

/**

* 第一步 发现设备
*/
DeviceInfo toProvisionDeviceInfo = null;
LocalDeviceMgr.getInstance().startDiscovery(context, new IDiscoveryListener() {
    @Override
    public void onLocalDeviceFound(DeviceInfo deviceInfo) {
        // 发现到的已配网设备  发现一个返回一个   可用来做绑定操作
    }

    @Override
    public void onEnrolleeDeviceFound(List<DeviceInfo> devices) {
        // 发现到的待配网设备 可能多次返回 
        if(true){//TODO 用户根据需要配置的设备做匹配或者将设备全部露出,让用户点击选择
            toProvisionDeviceInfo = devices.get(i);
        }
    }
});

/**

* 第二步 开始配网
*       使用前面选择的待配设备的信息透传到设置设备信息接口并开始配网
*/
AddDeviceBiz.getInstance().setDevice(toProvisionDeviceInfo);
AddDeviceBiz.getInstance().startAddDevice(getApplicationContext(), new IAddDeviceListener() {
    @Override
    public void onPreCheck(boolean isSuccess, DCErrorCode dcErrorCode) { }

    @Override
    public void onProvisionPrepare() {}

    @Override
    public void onProvisioning() {
 /**
 * 第三步 配网中
 * 根据实际场景处理
 */
    }

    @Override
    public void onProvisionStatus(ProvisionStatus provisionStatus) {}

    @Override
    public void onProvisionedResult(boolean isSuccess, DeviceInfo info, DCErrorCode dcErrorCode) {
        // TODO 配网成功或失败的处理操作
        /**
 * 第四步 配网结果
* 根据实际场景处理
*/
});           

该方式配网失败时,可以考虑切换到其他配网方式,调用 AddDeviceBiz.getInstance().setAliProvisionMode("xxx")接口,其中,xxx指具体配网方式,如ForceAliLinkTypeBroadcast为使用一键广播。

路由器配网

  1. 发现设备。
    调用配网SDK LocalDeviceMgr
  2. 开始配网。
    使用发现设备中获取到设备信息(DeviceInfo对象),调用方法设置待配网设备。无需设置配网方式,直接透传发现到的设备信息对象(DeviceInfo对象),SDK自动匹配使用哪种配网方式,当然也可以强制指定使用其他配网方式。

    调用开始配网接口,设置监听回调。

  3. 配网中,可进行配网中间状态回调。
  4. 监听配网结果。
    可以在配网完成之后调用LocalDeviceMgr getDeviceToken接口获取绑定token,完成绑定操作。

示例代码如下。

/**

* 第一步 发现本地设备
*/
DeviceInfo toProvisionDeviceInfo = null;
LocalDeviceMgr.getInstance().startDiscovery(context, new IDiscoveryListener() {
    @Override
    public void onLocalDeviceFound(DeviceInfo deviceInfo) {
        // 发现到的已配网设备  发现一个返回一个   可用来做绑定操作
    }

    @Override
    public void onEnrolleeDeviceFound(List<DeviceInfo> devices) {
        // 发现到的待配网设备 可能多次返回 
        if(true){//TODO 用户根据需要配置的设备做匹配或者将设备全部露出,让用户点击选择
            toProvisionDeviceInfo = devices.get(i);
        }
    }
});

/**

* 第二步 开始配网
*       使用前面选择的待配设备的信息透传到设置设备信息接口并开始配网
*/
AddDeviceBiz.getInstance().setDevice(toProvisionDeviceInfo);
AddDeviceBiz.getInstance().startAddDevice(getApplicationContext(), new IAddDeviceListener() {
    @Override
    public void onPreCheck(boolean isSuccess, DCErrorCode dcErrorCode) { }

    @Override
    public void onProvisionPrepare() {}

    @Override
    public void onProvisioning() {
        /**
        * 第三步 配网中
        * 根据实际场景处理
        */
    }

    @Override
    public void onProvisionStatus(ProvisionStatus provisionStatus) {}

    @Override
    public void onProvisionedResult(boolean isSuccess, DeviceInfo info, DCErrorCode dcErrorCode) {
        // TODO 配网成功或失败的处理操作
        /**
        * 第四步 配网结果
        * 根据实际场景处理
        */
});
			

该方式配网失败时,可以考虑切换到其他配网方式,调用 AddDeviceBiz.getInstance().setAliProvisionMode("xxx")接口,其中,xxx指具体配网方式,如ForceAliLinkTypeBroadcast为使用一键广播。

设备绑定

介绍本SDK提供的获取绑定token的接口。绑定接口非本SDK提供。

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

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

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

    样例代码如下。

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