Provisioning SDK

Initialization

To initialize the SDK, see SDK Initialization.

Usage instructions

• Device discovery

  You can discover provisioned devices on the LAN, including Wi-Fi and Ethernet devices. You can also discover powered-on devices on the LAN that are pending provisioning. This requires that a provisioned smart device is already on the LAN and that this device supports provisioning for other devices.

  • Start device discovery

    You can discover locally provisioned devices or devices pending provisioning that are found by other provisioned devices or routers. The information from the discovered devices can be used as input parameters for subsequent device provisioning.

    // Import the header file
    #import <IMSDeviceCenter/IMLDeviceCenter.h>
    
    // Entry for local discovery
    [[IMLLocalDeviceMgr sharedMgr] startDiscovery:^(NSArray *devices, NSError *err) {
            // devices is an array of IMLCandDeviceModel objects.
            // You can distinguish the network connection type of the device pending provisioning based on devType in IMLCandDeviceModel:
            // 0: Wi-Fi device; 1: Ethernet device (connected with a network cable); 2: router; @"ble_subtype_2": Bluetooth-assisted provisioning device */
        }];

  • Retrieve all discovered devices

    // Import the header file
    #import <IMSDeviceCenter/IMLDeviceCenter.h>
    
    NSArray *allLanDevicesArray = [kLKLocalDeviceMgr getLanDevices];

  • Stop device discovery

    Stop discovering locally provisioned devices and online devices that are pending provisioning. Calling this interface purges the list of discovered devices. Ensure that this method is called in pairs with startDiscovery.

    // Import the header file
    #import <IMSDeviceCenter/IMLDeviceCenter.h>
    
    // Stop device discovery
    [kLKLocalDeviceMgr stopDiscovery];

• General provisioning flow

  • Set information for the device to add

    The information for the device to add can be obtained from a locally discovered device that is pending provisioning, or through other methods such as scanning a QR code.

    // Import the header file
    #import <IMSDeviceCenter/IMLDeviceCenter.h>
    
    // Select a locally discovered device that is pending provisioning
    IMLCandDeviceModel *model = self.localDeviceList[index];
    [kLkAddDevBiz setDevice:model];

    Note

    The (IMLCandDeviceModel *)model is assembled from a locally discovered device pending provisioning or from a product list pulled from the cloud.

    For information about local device discovery, see the Device discovery section.

    The properties of IMLCandDeviceModel are described as follows:

    Property	Type	Required	Description
    productKey	NSString	Yes	The ProductKey of the device.
    deviceName	NSString	No	The device name.
    productId	NSString	No	The product ID of the device pending provisioning. This parameter is required for Bluetooth-assisted provisioning.
    linkType	assign	No	Specifies the provisioning method. ForceAliLinkTypeBroadcast: One-click broadcast provisioning. ForceAliLinkTypeHotspot: Mobile hot spot provisioning. ForceAliLinkTypeSoftap: Device hot spot provisioning. ForceAliLinkTypeQR: Camera QR code provisioning. ForceAliLinkTypeBLE: Bluetooth-assisted provisioning.

  • Set the provisioning mode

    // Import the header file
    #import <IMSDeviceCenter/IMLDeviceCenter.h>
    
    [kLkAddDevBiz setAliProvisionMode:ForceAliLinkTypeHotspot];

  • Start device provisioning

    After you set the information for the device to add, call the startAddDevice interface to begin the provisioning flow and implement the listener protocol methods.

    // Import the header file
    #import <IMSDeviceCenter/IMLDeviceCenter.h>
    
    [kLkAddDevBiz startAddDevice:self];
    
    // Here, self is the notifier listener callback object (delegate) during the provisioning process.
    - (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];
        });
    }
    
    // User guide page (One-click and hot spot provisioning have related callbacks to guide the user through the required operations)
    - (void)notifyProvisionPrepare:(LKPUserGuideCode)guideCode
    {
        NSLog(@"notifyProvisionPrepare callback guide code : %ld", guideCode);
        if(guideCode == LKPGuideCodeOnlyInputPwd){
            // TODO: Guide for one-click broadcast provisioning
        } else if(guideCode == LKPGuideCodeWithUserGuide){
            // TODO: Guide for mobile hot spot provisioning
        } else if(guideCode == LKPGuideCodeWithUserGuideForSoftAp) {
            // TODO: Guide for device hot spot provisioning
        } else if(guideCode == LKPGuideCodeWithUserGuideForQR) {
            // TODO: Guide for camera QR code provisioning
        }
    
    
    }
    
    -(void)notifyProvisioning
    {
        NSLog(@"notifyProvisioning callback (Provisioning in progress...) ");
    }
    
    /**
     Callback for mobile hot spot provisioning status. Prompts the user to turn off the hot spot and switch back to the previous Wi-Fi. Optional.
     */
    - (void)notifyProvisioningNotice{
        NSLog(@"notifyProvisioningNotice");
    }
    
    /*
     Callback for device hot spot status. Optional.
     status code: 1=Prompt to switch to the device hot spot; 2=Switched to the device hot spot; 3=Data sent (dic will contain "token"); 4=Prompt to switch back to the router; 5=Switched back to the router
    */
    - (void)notifyProvisioningNoticeForSoftAp:(int)status withInfo:(NSDictionary *)dic
    {
        NSLog(@"notifyProvisioningNoticeForSoftAp,%d,%@",status,dic);
    }
    
    /**
     Callback for camera QR code provisioning mode. Optional.
     @param qrcode The QR code content to be displayed in the UI.
     */
    - (void)notifyProvisioningNoticeForQR:(NSString *) qrcode;
    
    
    /**
     Notifies the upper-layer UI: Callback for the provisioning result.
    
     @param candDeviceModel The device information returned as the provisioning result. This is nil if provisioning failed.
     @param provisionError The error information.
     */
    - (void)notifyProvisionResult:(IMLCandDeviceModel *)candDeviceModel withProvisionError:(NSError *)provisionError
    {
        NSLog(@"Provisioning successful: %@",candDeviceModel);
    }

  • Enter the Wi-Fi name and password for provisioning

    After you receive the - (void)notifyProvisionPrepare:(LKPUserGuideCode)guideCode callback and complete the guided operations, call the - (void)toggleProvision:(NSString *)ssid pwd:(NSString *)pwd timeout:(int)timeout method. The guided operations can include entering the ssid and password for one-click broadcast provisioning, or enabling the hot spot and entering the ssid and password for hot spot provisioning. Pass the Wi-Fi ssid and password to the method.

    Note

    Only one-click broadcast provisioning and hot spot provisioning trigger the notifyProvisionPrepare callback.

    // Import the header file
    #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";
        NSInteger timeout = 60; // Unit: seconds (s)
        [kLkAddDevBiz toggleProvision:ssid pwd:password timeout:timeout];
    }

  • Handle listeners for key provisioning steps

    You must listen for this callback for hot spot provisioning.

    // Import the header file
    #import <IMSDeviceCenter/IMLDeviceCenter.h>
    
    - (void)notifyProvisionStatus:(LKProvisonStatus)provisionStatus boolSuccess:(BOOL)boolSuccess;
    {
        NSLog(@"notifyProvisionStatus callback provisionStatus:%d boolSuccess:%d", provisionStatus, boolSuccess);
        if(provisionStatus == LKProvisonStatusSwitchAP){
            // The device responds to the switch AP request. Prompt the user to switch back to the previous Wi-Fi.
            NSLog(@"Please switch back to the Wi-Fi network you were using before enabling the hot spot immediately.");
        }
    }

  • Listen for the provisioning result

    - (void)notifyProvisionResult:(IMLCandDeviceModel *)candDeviceModel withProvisionError:(NSError *)provisionError
    {
        if(candDeviceModel != nil){
            NSLog(@"Provisioning successful: %@",candDeviceModel);
        } else{
            NSLog(@"Provisioning failed. Error message: %@", provisionError);
        }
    
    }

  • Stop provisioning

    // Import the header file
    #import <IMSDeviceCenter/IMLDeviceCenter.h>
    
    [kLkAddDevBiz stopAddDevice];

• Device binding

  After device provisioning is complete, you need to bind the device to a user or a family. To do this, call the SDK method to retrieve the device token, and then perform the binding. The following code shows how to retrieve the token.

  // Import the header file
  #import <IMSDeviceCenter/IMLDeviceCenter.h>
  
  // self.productKey and self.deviceName are the productKey and deviceName from the Thing Specification Language model returned after successful provisioning.
  [[IMLLocalDeviceMgr sharedMgr] getDeviceToken:self.productKey deviceName:self.deviceName timeout:20 resultBlock:^(NSString *token, BOOL boolSuccess) {
      NSLog(@"Actively get device token: %@, boolSuccess: %d", token, boolSuccess);
      if(token){
      // Call the binding interface to bind the device.
      } else{
          NSLog(@"Failed to get token (timeout)");
      }
  }];

Use the provisioning plugin

The provisioning plugin implements the complete provisioning logic based on the Bone container. Therefore, if you have integrated the Bone container, you can directly open the provisioning plugin to complete the provisioning logic and then handle the post-provisioning logic.

The current provisioning plugin IDs are as follows:

• Plugin ID (China site): a123kfz2KdRdrfYc

• Plugin ID (International site): a223c2beCJQ2Xpk2

For details about how to use the plugin ID, see the Bone container section. For more information about calling the platform-provided provisioning plugin, see Provisioning Development Guide.