平臺已提供了一套完整的配網頁面,如果您希望自己使用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有一定的有效時限,失敗的時候可以主動重試。