Batch provisioning development guide

Solution overview

Batch provisioning is based on the device hotspot provisioning method. Your devices must support both device hotspot provisioning and zero-configuration provisioning. The following sequence diagram illustrates the batch provisioning process.

1. Put all devices to be provisioned into device hotspot provisioning mode. You can do this by powering on the devices or pressing a button on them.
2. Use the app to provision one of the devices through device hotspot provisioning. Complete the provisioning and binding operations. For information about which SDKs to call, see Android App SDK and iOS App SDK.
3. Designate the device that completed provisioning in step 2 as the primary device. Use the primary device to discover other devices that are waiting for provisioning.

   The primary device sends a broadcast message. Other devices that are waiting for provisioning receive the message and switch to zero-configuration mode. The primary device can then discover the devices that entered zero-configuration mode. The app SDK callback returns information about the discovered devices.

4. The other devices that are returned in the previous step are provisioned using the zero-configuration method. The app SDK callback returns the provisioning result.

Integrate the device client

1. Obtain IoT Platform for Lifestyle SDK V1.3.0 or later. For more information, see Obtain the SDK.
2. Enable the feature module in the SDK.

   Add the configuration item GLOBAL_CFLAGS += -DAWSS_BATCH_DEVAP_ENABLE to the application's .mk file. If your development is based on living_platform, the living_platform.mk file already contains this configuration item, as shown in the following figure.

   

   The device SDK and the chip must support the following basic capabilities.

   • SDK requirements
     • Device hotspot provisioning
     • Zero-configuration provisioning
     • Device hotspot batch provisioning
   • Chip or module requirements
     • Receive Wi-Fi management frames while the device hotspot is enabled.
     • Switch channels and send Wi-Fi management frames while connected to an access point (AP).
     • For devices that support device hotspot batch provisioning, the device hotspot must be set to channel 1, 6, or 11.
3. Handle the calls to the SDK feature module interfaces and callbacks in the application.
   1. In the awss_open_dev_ap()awss_dev_ap_reg_modeswit_cb() function.

      void awss_open_dev_ap(void *p)
      {
          iotx_event_regist_cb(linkkit_event_monitor);
          LOG("%s\n", __func__);
          if (netmgr_start(false) != 0) {
              aos_msleep(2000);
      #ifdef AWSS_BATCH_DEVAP_ENABLE
              awss_dev_ap_reg_modeswit_cb(awss_dev_ap_modeswitch_cb); // Add this call
      #endif
              awss_dev_ap_start();
          }
          aos_task_exit(0);
      }

   2. Implement the application layer callback function awss_dev_ap_modeswitch_cb().

      #ifdef AWSS_BATCH_DEVAP_ENABLE
      #define DEV_AP_ZCONFIG_TIMEOUT_MS  120000 // (ms)
      extern void awss_set_config_press(uint8_t press);
      extern uint8_t awss_get_config_press(void);
      extern void zconfig_80211_frame_filter_set(uint8_t filter, uint8_t fix_channel);
      void do_awss_dev_ap();
      
      static aos_timer_t dev_ap_zconfig_timeout_timer;
      static uint8_t g_dev_ap_zconfig_timer = 0;   // This timer is created once and can be restarted.
      static uint8_t g_dev_ap_zconfig_run = 0;
      
      static void timer_func_devap_zconfig_timeout(void *arg1, void *arg2)
      {
          LOG("%s run\n", __func__);
      
          if (awss_get_config_press()) {
              // Still in the zero-configuration provisioning stage. Stop and switch to device AP.
              do_awss_dev_ap();
          } else {
              // Zero-configuration provisioning is finished.
          }
      
          awss_set_config_press(0);
          zconfig_80211_frame_filter_set(0xFF, 0xFF);
          g_dev_ap_zconfig_run = 0;
          aos_timer_stop(&dev_ap_zconfig_timeout_timer);
      }
      
      static void awss_dev_ap_switch_to_zeroconfig(void *p)
      {
          LOG("%s run\n", __func__);
          // Stop device AP provisioning.
          awss_dev_ap_stop();
          // Start and enable zero-configuration provisioning.
          iotx_event_regist_cb(linkkit_event_monitor);
          awss_set_config_press(1);
      
          // Start a timer to count the duration for the zero-configuration provisioning timeout.
          if (!g_dev_ap_zconfig_timer) {
              aos_timer_new(&dev_ap_zconfig_timeout_timer, timer_func_devap_zconfig_timeout, NULL, DEV_AP_ZCONFIG_TIMEOUT_MS, 0);
              g_dev_ap_zconfig_timer = 1;
          }
          aos_timer_start(&dev_ap_zconfig_timeout_timer);
      
          // This holds the thread while AWSS is running.
          netmgr_start(true);
      
          LOG("%s exit\n", __func__);
          aos_task_exit(0);
      }
      
      int awss_dev_ap_modeswitch_cb(uint8_t awss_new_mode, uint8_t new_mode_timeout, uint8_t fix_channel)
      {
          if ((awss_new_mode == 0) && !g_dev_ap_zconfig_run) {
              g_dev_ap_zconfig_run = 1;
              // Receive only zero-configuration provisioning packets.
              zconfig_80211_frame_filter_set(0x00, fix_channel);
              LOG("switch to awssmode %d, mode_timeout %d, chan %d\n", 0x00, new_mode_timeout, fix_channel);
              // Switch to zero-configuration.
              aos_task_new("devap_to_zeroconfig", awss_dev_ap_switch_to_zeroconfig, NULL, 2048);
          }
      }
      #endif

4. Compile the firmware and flash it to the device.

Integrate the iOS app client

1. Obtain the SDK.
   Update the provisioning SDK to version 1.11.0 or later. We recommend that you use the latest version from the official website.

   You can download the SDK from the IoT Platform for Lifestyle console (for more information, see Download and integrate the SDK) or integrate the following code.

   pod 'IMSDeviceCenter', '~>1.11.0'

2. Start or stop batch discovery.

   /**
    Batch discovery feature. Discovers nearby devices using a provisioned device. This requires support from specific devices.
   
    @param targetProductKey The ProductKey of the target devices to search for. If nil, all devices are targeted.
    @param searcherProductKey The ProductKey of the provisioned device that acts as the searcher.
    @param searchDeviceName The DeviceName of the provisioned device that acts as the searcher.
    @param batchResultBlock The callback that is triggered when a device is discovered. This is called multiple times.
    */
   - (void)startBatchDiscoveryForTargetProductKey:(NSString *) targetProductKey bySearcherProductKey:(NSString *) searcherProductKey deviceName:(NSString *) searchDeviceName resultBlock:(void(^)(NSArray * devices, NSError * err))batchResultBlock;
   
   /**
    Stops the provisioned device from searching for nearby devices.
    */
   - (void)stopBatchDiscovery;

3. Start batch provisioning.

       IMLCandDeviceModel *model = [[IMLCandDeviceModel alloc] init];
       model.productKey = productKey; // The ProductKey of the device to be provisioned.
       model.regProductKey = productKey; // The ProductKey of the provisioned device.
       model.regDeviceName = deviceName; // The DeviceName of the provisioned device.
       model.linkType = ForceAliLinkTypeZeroInBatches; // Specifies the provisioning mode as batch provisioning.
   
       [[IMLAddDeviceBiz sharedInstance] setDevice:model];
       [[IMLAddDeviceBiz sharedInstance] startAddDevice:notifier];

4. Handle the batch provisioning success callback.
   Similar to standard provisioning, the callback is returned through notifyProvisionResult. The callback is triggered once for each successfully provisioned device. If the callback indicates a failure, it means the entire batch provisioning process has failed or timed out.

   /**
    Notifies the upper layer UI: callback for the provisioning completion result.
   
    @param candDeviceModel Returns the device information of the provisioning result. This is nil if provisioning fails.
    @param provisionError Error message.
    */
   - (void)notifyProvisionResult:(IMLCandDeviceModel *)candDeviceModel withProvisionError:(NSError *)provisionError;

Integrate the Android app client

1. Obtain the SDK.

   You can download the SDK from the IoT Platform for Lifestyle console (for more information, see Download and integrate the SDK) or integrate the following code.

   // Maven repository address
   maven {
       url "http://maven.aliyun.com/nexus/content/repositories/releases"
   }
   
   api('com.aliyun.alink.linksdk:ilop-devicecenter:1.7.3')

2. Start or stop batch discovery.

   For the API reference, see LocalDeviceMgr.

   /**
    * Throws IllegalArgumentException if parameters are invalid.
    * @param context context
    * @param listener The discovery results. The callback is triggered at least once.
    */
   void startBatchDiscovery(Context context, BatchDiscoveryParams params, IDiscovery listener);
   
   /**
    * Stop batch provisioning.
    * @param productKey The ProductKey of the provisioned device.
    * @param deviceName The DeviceName of the provisioned device.
    */
   void stopBatchDiscovery(String productKey, String deviceName);

3. Start batch provisioning and listen for callback results.

   For a description of each startAddDevice callback, see Provisioning SDK.

   DeviceInfo info = new DeviceInfo();
   info.linkType = LinkType.ALI_ZERO_IN_BATCHES.getName();
   info.productKey = pk; // The ProductKey of the device to be provisioned.
   info.regProductKey = regPk; // The ProductKey of the provisioned device.
   info.regDeviceName = regdn; // The DeviceName of the provisioned device.
   // Set provisioning information.
   AddDeviceBiz.getInstance().setDevice(info);
   // Start batch provisioning.
   AddDeviceBiz.getInstance().startAddDevice(context, new IAddDeviceListener() {
       @Override
       public void onPreCheck(boolean isSuccess, DCErrorCode dcErrorCode) {
           // Precheck.
       }
   
       @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 dcErrorCode) {
           // Provisioning result callback. This is called once for each successfully provisioned device. Determine if provisioning is complete based on the list of discovered devices at the start and the number of successful provisioning callbacks.
       }
   });