IoT Platform:OTA updates for devices

Download Link SDK for Android

You can download the demo package of Link SDK for Android that is provided by IoT Platform.

Process of an OTA update

1. A device submits its firmware version number.

2. The device subscribes to the topics about OTA updates.

3. You must configure an OTA update task on the OTA Update page in the IoT Platform console. You can specify multiple conditions to identify the device whose firmware you want to update.

4. If the device successfully subscribed to topics about OTA updates, you can find the device in the OTA update task that you configured. In this case, the device receives a notification that contains the following information:

   • The version to which you can update the device firmware.

   • The download address, size, and message-digest algorithm (MD5) signature of the OTA update package.

5. The device downloads the OTA update package and then the firmware update starts. The device submits the update progress to IoT Platform.

6. After the update is complete, the device automatically submits the new firmware version.

API in Link SDK

For information about the API that is used to perform OTA updates in Link SDK for Android, see IOta.

OTA update configuration by using Link SDK

For information about the sample code, see the OTAActivity.java file in the demo package.

1. Configure an OTA update task in the IoT Platform console to obtain an OTA instance.

          mOta = LinkKit.getInstance().getOta()              

2. Prepare for the OTA update task. Call the tryStartOta function to submit the current version, subscribe to a topic, and receive a notification from the IOta.STEP_RCVD_OTA callback if an OTA update is pushed.

   Note

   • You can use an OTA update task to update multiple modules. By default, the module name of an OTA update task is default or is left empty. You can add custom modules based on your business requirements.

   • The tryStartOta function is called to submit the firmware version number of the default module. If you want to submit the firmware version number of custom modules when you initialize the OTA update task, you can call the reportModuleVersion function for each custom module to submit the firmware version number.

   • You can invoke the IOta.STEP_RCVD_OTA callback to view the module names and firmware version numbers of an OTA update task. This way, you do not need to repeatedly call the tryStartOta function when you want to update multiple custom modules in an OTA update task.  

   • If you return a value of true for the IOta.STEP_RCVD_OTA callback, the OTA update task is accepted and starts. If you return a value of false for the callback, the OTA update task is rejected. If the device disconnects from and then re-connects to IoT Platform or the device requests an OTA update, the OTA update task is reinitiated.

   mOta.tryStartOta(mConfig, new OtaListener(){
       public boolean onOtaProgress(int step, IOta.OtaResult otaResult) {
   
           // The error code that indicates the update status. 
           int code = otaResult.getErrorCode();
           if (code != IOta.NO_ERROR) {
               AppLog.e(TAG, "onOtaProgress error:" + code);
               // show tip for uses.
               return false;
           }
   
           Object data = otaResult.getData();
           switch (step) {
               case IOta.STEP_REPORT_VERSION:
                   // You can receive the notification that the device has submitted the firmware version number to IoT Platform. 
                   break;
               case IOta.STEP_SUBSCRIBE:
                   // You can receive the notification that the device subscribed to messages about OTA updates from IoT Platform. 
                   break;
               case IOta.STEP_RCVD_OTA:
                   // You can receive the notification that contains the target firmware version number, module information, and MD5 signature of the OTA update task. If you want to start the OTA update, return true. If you want to reject the OTA update, return false. When the device disconnects from and then re-connects to IoT Platform or the device requests an OTA update, the OTA update task is reinitiated. 
                   AppLog.d(TAG, "STEP_RCVD_OTA");
                   otaInfo = (OtaInfo) otaResult.getData();
                   AppLog.d(TAG, "STEP_RCVD_OTA,module:"+ otaInfo.module);
                   AppLog.d(TAG, "STEP_RCVD_OTA,ext:"+ otaInfo.extData);
                   break;
               case IOta.STEP_DOWNLOAD:
                   // After the device starts to download the OTA update package, you can obtain the progress in percentage of downloading the OTA update package. For more information, see the demo package of the SDK. 
                   break;
           }
           return true;
       }
   });                  

3. If the device receives a pushed OTA update package and returns true, the device automatically downloads the OTA update package. The download progress is returned by the IOta.STEP_DOWNLOAD callback.

   Note

   • The reportProgress function can be called to submit the update progress of the default module.

   • The reportModuleProgress function can be called to submit the update progress of a custom module.

4. After the OTA update package is downloaded, the device manufacturer can update the device by using a custom OTA-based update method.

5. After the OTA update is complete, the device must submit the new firmware version number to IoT Platform. If the version number that is received by IoT Platform is the same as the target firmware version number, the OTA update is successful. The device can use one of the following methods to submit the firmware version number:

   • The device can call the reportVersion function to submit the current firmware version number. If an OTA update task applies to a module, the device can call the reportModuleVersion function to submit the current firmware version number.

   • The device can call the tryStartOta function to re-configure the OTA update service and submit the firmware version number. You must specify the current firmware version number of a device for the first parameter of the tryStartOta function. After the function is executed, the SDK is used to submit the current firmware version number of the device to IoT Platform.

     Note

     The tryStartOta function cannot be called to submit the version number of a module.

6. If you want to exit the OTA update service and stop listening to messages about OTA updates, call the tryStopOta function.

   If you performed Step 2 and you want to call the LinkKit.getInstance().deinit() function to stop using IoT Platform, you must call the tryStopOta function to ensure that you exited the OTA update service.

Resumable upload

By default, the resumable upload feature is disabled in the SDK. The following sample code provides an example on how to enable the feature.

// If you set the enableContinuousDownload parameter to true, the system enables the resumable upload feature. Default value: false. 
mOta.enableContinuousDownload(true);

// If a download operation unexpectedly ends, the system performs 1,440 retries at an interval of 60 seconds. You can configure the setRetryParams parameter to change the number of retries and the interval based on your business requirements. 
mOta.setRetryParams(24*60, 60);

Download an OTA update package

By default, Link SDK for Android receives OTA update messages from IoT Platform. You can configure Link SDK for Android for a device to query information about OTA updates in the IoT Platform console.

// The device queries OTA update messages in the IoT Platform console. If you set the tryGetOtaFirmware parameter to default, OTA update messages are queried for the default module. You can also specify a custom module name. 
mOta.tryGetOtaFirmware("default");