Device OTA updates

Get the SDK

You can download the Android Link SDK Demo from IoT Platform.

Basic OTA update process

1. The device reports its version number.

2. The device subscribes to OTA update-related topics.

3. In the IoT Platform console, you can configure an OTA update task on the OTA Update page. You can specify the devices to update based on multiple dimensions.

4. A device that has subscribed to the OTA update topics receives a push message for the configured OTA update task. The message includes:

   • The version number to which the device can be updated.

   • The URL, size, and MD5 hash of the OTA update package.

5. The device downloads the OTA update package, starts the update, and reports the update progress.

6. After the update is complete, the device automatically reports the new version number.

For more information about how to configure an OTA update, see OTA update overview.

Limits

The Android Link SDK supports only HTTPS for downloading update packages during an OTA update.

• When you verify an update package and create a batch update task in the IoT Platform console, set Upgrade Package Download Protocol to HTTPS. For more information, see Verify an update package and Create a batch update task.

• When you call the server-side API operations to verify an update package (CreateOTAVerifyJob) and create a batch update task (CreateOTAStaticUpgradeJob and CreateOTADynamicUpgradeJob), set the DownloadProtocol request parameter to HTTPS.

SDK API reference

For more information about the API operations for OTA updates in the SDK, see IOta API.

SDK integration method

For a specific code implementation, see the OTAActivity.java file in the SDK demo.

1. In the IoT Platform console, you can configure an OTA update task and obtain the OTA instance:

          mOta = LinkKit.getInstance().getOta()              

2. You can prepare the OTA update task. The tryStartOta method reports the current version and subscribes to topics. When an OTA update is pushed, the IOta.STEP_RCVD_OTA callback is triggered.

   Note

   • You can use OTA to update multiple modules. The default module name for an OTA task is default or empty. You can also define custom modules.

   • The tryStartOta method reports the version number of the default module. To report the version number of a custom module at startup, you can call reportModuleVersion for each module.

   • You can view the module name and version number of the OTA task in the callback result of IOta.STEP_RCVD_OTA. Therefore, you do not need to repeatedly call tryStartOta when you use multiple custom OTA modules. 

   • In this callback, you can return true to proceed with the OTA update or return false to reject it. If you reject the update, the OTA task is sent again when the device goes online or actively requests the task.

   mOta.tryStartOta(mConfig, new OtaListener(){
       public boolean onOtaProgress(int step, IOta.OtaResult otaResult) {
   
           // The status of the current update process (error code).
           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:
                   // Notifies that the device version number has been reported to the server.
                   break;
               case IOta.STEP_SUBSCRIBE:
                   // Notifies that the device has subscribed to OTA messages from the server.
                   break;
               case IOta.STEP_RCVD_OTA:
                   // Notifies about the version number, module information, and MD5 hash of the current OTA task. Return true to proceed with the OTA update. Return false to reject the OTA update. If you reject the update, the OTA task is sent again when the device goes online or actively requests the task.
                   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:
                   // The OTA update package is being downloaded. You can get the download percentage. For more information, see the demo.
                   break;
           }
           return true;
       }
   });                  

3. When the device receives a pushed OTA update package, it returns true to trigger an automatic download. The download progress is reported through the IOta.STEP_DOWNLOAD callback.

   Note

   • For the default module, you can report the update progress using reportProgress.

   • For a custom module, you can report the update progress using reportModuleProgress.

4. After the device downloads the OTA update package, the device manufacturer can update the device using their own OTA method.

5. After the device OTA update is complete, you must report the latest version number to the server. The server then determines whether the reported version number matches the expected version number of the update package. If they match, the OTA update is considered successful.

   • You can report the current version number by calling the reportVersion method. For an OTA task of a module, you can call the reportModuleVersion method.

   • You can also report the version number when the device re-registers the OTA update service by calling the tryStartOta method. The first input parameter of this method must specify the current version number of the device. After this method is executed, the SDK reports the current version number of the device to the server.

     Note

     The tryStartOta method cannot report the version number of a module.

6. When you need to exit the OTA update service and stop listening for OTA update messages, you can call the tryStopOta method.

   If you have already performed Step 2, you must call tryStopOta to ensure that the previous OTA service has exited before you call LinkKit.getInstance().deinit() to exit the IoT service.

Resumable downloads

By default, the resumable download feature is disabled in the SDK. To enable this feature, follow these instructions.

// Set to true to enable resumable downloads. The default value is false.
mOta.enableContinuousDownload(true);

// After an abnormal download disconnection, retry 24*60 times at 60-second intervals. You can adjust these values as needed.
mOta.setRetryParams(24*60, 60);

Proactively download an OTA update package

By default, the SDK passively receives update messages from the server. The SDK also allows a device to proactively query the cloud for OTA update package messages.

// The device proactively queries the cloud for OTA update package messages. "default" indicates the default module. You can also specify other module names.
mOta.tryGetOtaFirmware("default");