Network provisioning for native Android apps

Device hot spot provisioning

1. Call the setDevice interface of the network provisioning SDK to set the information for the device that you want to provision.
   You can provision a device with or without specifying its `ProductKey`.

   There are three ways to obtain the provisioning information when you specify a `ProductKey`:

   • Call a cloud API to retrieve the product list. Then, select the product that corresponds to your device to obtain the `ProductKey`. This API is not provided by the network provisioning SDK.
   • Scan a QR code to obtain the device information, which includes the `ProductKey`.
   • Call the LocalDeviceMgr and startDiscovery interfaces of the SDK. Then, retrieve the SOFT_AP_DEVICE type device from the callback.
2. Start provisioning.
   Set the `linkType` provisioning method to ForceAliLinkTypeSoftap and call the startAddDevice interface of the network provisioning SDK to start provisioning.
3. During the preparation stage, pass the Wi-Fi SSID and password.
   When the app receives the onProvisionPrepare prepareType=1 callback, call the toggleProvision method of the SDK. Pass the SSID and password of the router to which you are currently connected.
4. During provisioning, prompt the end user to connect to the device hot spot or restore the Wi-Fi connection based on the callback parameters.

   When the app receives the onProvisionStatus callback, prompt the end user based on the value of the following parameters.

   • If the value of the callback parameter is status=ProvisionStatus.SAP_NEED_USER_TO_CONNECT_DEVICE_AP, instruct the end user to connect to the device hot spot. For example, instruct the user to connect to a hot spot whose name is in the format adh_{pk}_{mac}.

     This callback occurs on Android 10 and later. It also occurs if the device hot spot cannot be found or connected.

   • If the value of the callback parameter is status=ProvisionStatus.SAP_NEED_USER_TO_RECOVER_WIFI, instruct the end user to restore the Wi-Fi connection.

     This callback usually occurs when the device does not automatically connect to Wi-Fi or connects to an invalid Wi-Fi network.

5. Listen for the provisioning result.
   After provisioning is complete, call the LocalDeviceMgr getDeviceToken interface to obtain a binding token. Then, call the token-based device binding API to bind the device.

The following code provides a complete example.

/**
* Step 1: Set the information for the device to be provisioned.
*/

DeviceInfo deviceInfo = new DeviceInfo();
// Method 1: Specify the ProductKey.
deviceInfo.productKey = "xx"; 
// Devices discovered through startDiscovery return this information. Set this information before provisioning. Other methods do not require this setting.
deviceInfo.id = "xxx";
deviceInfo.linkType = "ForceAliLinkTypeSoftAP";
// Method 2: Do not specify a model.
deviceInfo.productKey = null;
deviceInfo.protocolVersion = "2.0";
deviceInfo.linkType = "ForceAliLinkTypeSoftAP";

// Set the basic information for the device to be added.
AddDeviceBiz.getInstance().setDevice(deviceInfo);

/**
* Step 2: Start provisioning.
* Prerequisite: Set the provisioning information and start provisioning.
*/
AddDeviceBiz.getInstance().startAddDevice(context， new IAddDeviceListener(){
    @Override
    public void onPreCheck(boolean b, DCErrorCode dcErrorCode) {
        // Parameter check callback 
    }

    @Override
    public void onProvisionPrepare(int prepareType) {
        /**
         * Step 3: During the preparation stage, pass the Wi-Fi information.
         * TODO: Change to the SSID and password of the Wi-Fi network that the phone is currently connected to.
        */
        if (prepareType == 1) {
            AddDeviceBiz.getInstance().toggleProvision("Your Wi-Fi ssid", "Your Wi-Fi password", 60);
        } 
    }

    @Override
    public void onProvisioning() {
        // Provisioning in progress
    }

    @Override 
    public void onProvisionStatus(ProvisionStatus provisionStatus) {
        /**
         * Step 4: During provisioning, provide UI guidance.
         * TODO: Provide UI guidance based on the provisioning callback.
        */
        if (provisionStatus == ProvisionStatus.SAP_NEED_USER_TO_CONNECT_DEVICE_AP) {    
            // For example, on Android 10, or on other Android versions where discovering or connecting to the device hot spot fails.    
            // You must guide the user to connect to the device hot spot, otherwise provisioning will fail.    
            return;
        }
        if (provisionStatus == ProvisionStatus.SAP_NEED_USER_TO_RECOVER_WIFI) {    
            // Guide the user to restore the phone's Wi-Fi connection, otherwise provisioning will fail.    
            return;
        }
    }

    @Override
    public void onProvisionedResult(boolean isSuccess, DeviceInfo deviceInfo, DCErrorCode errorCode) {
        /**
         * Step 5: Listen for the provisioning result.
        */
// If the provisioning result includes a token, use the token from the successful provisioning to bind the device.
    }
});          

Bluetooth-assisted provisioning

Add the following Bluetooth-related SDK dependency.

compile ('com.aliyun.alink.linksdk:breeze-biz:1.1.4') 

1. Call the setDevice interface of the SDK to set the information for the device that you want to provision.
   Bluetooth-assisted provisioning supports provisioning with a specified `ProductKey`. You can also start provisioning without specifying a model.

   There are three ways to obtain the provisioning information when you specify a `ProductKey`:

   • Call a cloud API to retrieve the product list. Then, select the product that corresponds to your device to obtain the `ProductKey`. This API is not provided by the network provisioning SDK.
   • Scan a QR code to obtain the device information, which includes the `ProductKey`.
   • Call the LocalDeviceMgr and startDiscovery interfaces of the SDK. Then, retrieve the BLE_ENROLLEE_DEVICE type device from the callback.
2. Start provisioning.
   Set the `linkType` provisioning method to ForceAliLinkTypeBLE and call the startAddDevice interface of the network provisioning SDK to start provisioning.
3. During the preparation stage, pass the Wi-Fi SSID and password.
   When the app receives the onProvisionPrepare prepareType=1 callback, call the toggleProvision method of the SDK. Pass the SSID and password of the router to which you are currently connected.
4. Listen for the provisioning result.
   After provisioning is complete, call the LocalDeviceMgr getDeviceToken interface to obtain a binding token. Then, call the token-based device binding API to bind the device.

The following code provides a complete example.

/**
* Step 1: Set the information for the device to be provisioned.
*/

DeviceInfo deviceInfo = new DeviceInfo();
// Method 1: Specify the productKey and productId.
deviceInfo.productKey = "xx"; // Required
// Required. Can be returned by the discovery interface or obtained from the cloud based on the productKey.
deviceInfo.productId = "xxx"; 
// Devices discovered through startDiscovery return this information. Set this information before provisioning. Other methods do not require this setting.
deviceInfo.id = "xxx";
deviceInfo.linkType = "ForceAliLinkTypeBLE";
// Method 2: Do not specify a model.
deviceInfo.productKey = null;
deviceInfo.productId = null;
deviceInfo.protocolVersion = "2.0";
deviceInfo.linkType = "ForceAliLinkTypeBLE";

// Set the basic information for the device to be added.
AddDeviceBiz.getInstance().setDevice(deviceInfo);

/**
* Step 2: Start provisioning.
* Prerequisite: Set the provisioning information and start provisioning.
*/
AddDeviceBiz.getInstance().startAddDevice(context， new IAddDeviceListener(){
    @Override
    public void onPreCheck(boolean b, DCErrorCode dcErrorCode) {
        // Parameter check callback 
    }

    @Override
    public void onProvisionPrepare(int prepareType) {        
        /**
         * Step 3: During the preparation stage, pass the Wi-Fi information.
         * TODO: Change to the SSID and password of the Wi-Fi network that the phone is currently connected to.
        */
        if (prepareType == 1) {
            AddDeviceBiz.getInstance().toggleProvision("Your Wi-Fi ssid", "Your Wi-Fi password", 60);
        } 
    }

    @Override
    public void onProvisioning() {
        // Provisioning in progress
    }

    @Override 
    public void onProvisionStatus(ProvisionStatus provisionStatus) { 
    }

    @Override
    public void onProvisionedResult(boolean isSuccess, DeviceInfo deviceInfo, DCErrorCode errorCode) {
        /**
         * Step 4: Listen for the provisioning result.
        */
        // If the provisioning result includes a token, use the token from the successful provisioning to bind the device.
    }
});          

One-click provisioning

1. Call the setDevice interface of the SDK to set the information for the device that you want to provision.

   One-click provisioning requires you to specify a `ProductKey`. There are two ways to obtain the provisioning information for a specified `ProductKey`.

   • Call a cloud API to retrieve the product list. Then, select the product that corresponds to your device to obtain the `ProductKey`. This API is not provided by the network provisioning SDK.
   • Scan a QR code to obtain the device information, which includes the `ProductKey`.
2. Start provisioning.
   Set the `linkType` provisioning method to ForceAliLinkTypeBroadcast and call the startAddDevice interface of the SDK to start provisioning.
3. During the preparation stage, pass the Wi-Fi SSID and password.
   When the app receives the onProvisionPrepare prepareType=1 callback, call the toggleProvision method of the network provisioning SDK. Pass the SSID and password of the router to which you are currently connected.
4. Listen for the provisioning result.
   After provisioning is complete, call the LocalDeviceMgr getDeviceToken interface to obtain a binding token. Then, call the token-based device binding API to bind the device.

The following code provides a complete example.

/**
* Step 1: Set the information for the device to be provisioned.
*/

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

// Set the basic information for the device to be added.
AddDeviceBiz.getInstance().setDevice(deviceInfo);

/**
* Step 2: Start provisioning.
* Prerequisite: Set the provisioning information and start provisioning.
*/
AddDeviceBiz.getInstance().startAddDevice(context， new IAddDeviceListener(){
    @Override
    public void onPreCheck(boolean b, DCErrorCode dcErrorCode) {
        // Parameter check callback 
    }

    @Override
    public void onProvisionPrepare(int prepareType) {        
        /**
         * Step 3: During the preparation stage, pass the Wi-Fi information.
         * TODO: Change to the SSID and password of the Wi-Fi network that the phone is currently connected to.
        */
        if (prepareType == 1) {
            AddDeviceBiz.getInstance().toggleProvision("Your Wi-Fi ssid", "Your Wi-Fi password", 60);
        } 
    }

    @Override
    public void onProvisioning() {
        // Provisioning in progress
    }

    @Override 
    public void onProvisionStatus(ProvisionStatus provisionStatus) { 
    }

    @Override
    public void onProvisionedResult(boolean isSuccess, DeviceInfo deviceInfo, DCErrorCode errorCode) {
        /**
         * Step 4: Listen for the provisioning result.
        */
        // If the provisioning result includes a token, use the token from the successful provisioning to bind the device.
    }
});          

Zero-touch provisioning

Zero-touch provisioning requires two devices on the same Wi-Fi network as your phone: one device that is already provisioned and bound, and another device that is powered on and in provisioning mode. The provisioned device discovers the new device and reports it to the cloud. Your app can then retrieve a list of devices that are ready for provisioning.

1. Call the setDevice interface of the SDK to set the information for the device that you want to provision.
   For zero-touch provisioning, you must call the discovery interface of the network provisioning SDK to obtain the device information.

   Call the LocalDeviceMgr and startDiscovery interfaces of the SDK. Then, retrieve the CLOUD_ENROLLEE_DEVICE type device from the callback.

2. Start provisioning.
   Set the `linkType` provisioning method to ForceAliLinkTypeZeroAP and call the startAddDevice interface of the network provisioning SDK
3. Listen for the provisioning result.
   After provisioning is complete, call the LocalDeviceMgr getDeviceToken interface to obtain a binding token. Then, call the token-based device binding API to bind the device.

The following code provides a complete example.

/**
* Step 1: Set the information for the device to be provisioned.
*/

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) {
            // Display the discovered devices in the UI and let the user trigger provisioning for a specific device.
            // The list of discovered devices is cached in memory. When the user triggers provisioning, set the provisioning information in the SDK's provisioning interface.
        }
    }
}

// 'list' contains the zero-touch devices ready for provisioning, discovered through the discovery interface.
toProvisionDeviceInfo = list.get(0); 
toProvisionDeviceInfo.linkType = "ForceAliLinkTypeZeroAP"; 
// Set the basic information for the device to be added.
AddDeviceBiz.getInstance().setDevice(toProvisionDeviceInfo);

/**
* Step 2: Start provisioning.
* Prerequisite: Set the provisioning information and start provisioning.
*/
AddDeviceBiz.getInstance().startAddDevice(context， new IAddDeviceListener(){
    @Override
    public void onPreCheck(boolean b, DCErrorCode dcErrorCode) {
        // Parameter check callback 
    }

    @Override
    public void onProvisionPrepare(int prepareType) {        
    }

    @Override
    public void onProvisioning() {
        // Provisioning in progress
    }

    @Override 
    public void onProvisionStatus(ProvisionStatus provisionStatus) { 
    }

    @Override
    public void onProvisionedResult(boolean isSuccess, DeviceInfo deviceInfo, DCErrorCode errorCode) {
        /**
         * Step 3: Listen for the provisioning result.
        */
        // If the provisioning result includes a token, use the token from the successful provisioning to bind the device.
    }
});          

Device binding

The network provisioning SDK provides an interface to retrieve a token from the device. This token can be used to bind an account to the device. The binding interface itself is not part of the network provisioning SDK. For more information, see token-based device binding.

1. Obtain the binding token.
   You can obtain the token for binding in the following ways.

   • Call the local discovery interface. The token is included in the device information that is returned in the list of provisioned devices.
   • Call the SDK interface to retrieve the token.

   For an example of the first method, see the local discovery interface calls for zero-touch provisioning or router provisioning. This topic focuses on the second method.

2. Bind the token.
   Call the token-based device binding interface with the device's `ProductKey`, `DeviceName`, and `Token` parameters to bind the device.

   The following is a code sample.

   /**
   * Step 1: Get the binding token.
   */
   LocalDeviceMgr.getInstance().getDeviceToken(productKey, deviceName, 60*1000, 10*1000， new IOnDeviceTokenGetListener() {
       @Override
       public void onSuccess(String token) {
           // Get the token required for binding.
           /**
           * Step 2: Call the binding interface.
           */
           // TODO: The user calls this based on the specific business scenario.
       }
   
       @Override
       public void onFail(String reason) {
       }
   });                     

   Note

   • When you bind a device using information from local discovery, a timeout might occur if you wait too long after obtaining the token. If this happens, call the getDeviceToken interface to obtain a new token, and then call the binding interface again.
   • The binding token is valid for a limited time. If the binding fails, you can retry the operation.