The IoT as Bridge SDK 2.1.3 and later support over-the-air (OTA) updates for firmware. This article describes how to use the IoT as Bridge SDK to update the firmware of a device over the air.

Background information

Note Only the IoT as Bridge SDK 2.1.3 and later support OTA updates.

The following figure shows the process of an OTA update.

Process

For more information about how to push an update package from IoT Platform to devices, see Overview.

For more information about the update process and how to specify topics and data formats for firmware updates, see Update devices by using OTA.

Call operations for OTA updates

The IoT as Bridge SDK encapsulates the operations that are related to OTA updates. To achieve OTA updates, you must use the SDK to call the following three operations:

  • The operation that is used to submit versions of device firmware

    After a device is enabled and updated, the device must submit the current version of the firmware to the following topic: /ota/device/inform/${YourProductKey}/${YourDeviceName}.

    To enable a device to submit a firmware version, you must call the TslUplinkHandler.reportFirmwareVersion operation. Syntax:

    /**
     * The device submits the firmware version to IoT Platform.
     * @param requestId: the ID of the request
     * @param originalIdentity: the original identifier of the device
     * @param version: the firmware version to be submitted
     * @ return: The value true is returned if the firmware version is submitted.
    */
    boolean reportOtaVersion(String requestId, String originalIdentity, String version)

    Example

    TslUplinkHandler tslUplinkHandler = new TslUplinkHandler();
    tslUplinkHandler.doOnline(session, originalIdentity);
    tslUplinkHandler.reportOtaVersion("12345", originalIdentity, "1.0.1");
  • The operation that is used to push update notifications from IoT Platform to devices

    After you add update packages to IoT Platform and initiate OTA updates for multiple devices, IoT Platform pushes update notifications to the devices. The devices must subscribe to the following topic to retrieve update notifications: /ota/device/upgrade/${YourProductKey}/${YourDeviceName}.

    To enable a device to receive the OTA update notification that is pushed from IoT Platform, you can call the BridgeBootStrap.setOtaUpgradeHandler() operation and configure a callback. Syntax:

    /**
     * Configure a callback to receive the OTA update notifications that are pushed from IoT Platform.
     * @ param otaUpgradeHandler: the callback that is set.
    */
    public void setOtaUpgradeHandler(OtaUpgradeHandler otaUpgradeHandler) {
        this.callback.setOtaUpgradeHandler(otaUpgradeHandler);
    }
    
    public interface OtaUpgradeHandler {
    
        /**
         * Push OTA update notifications from IoT Platform.
         * @param requestId: the ID of the request
         * @param firmwareInfo: the information about OTA updates
         * @param session: the current session
         * @return
         */
        boolean onUpgrade(String requestId, OtaFirmwareInfo firmwareInfo, Session session);
    }
    
    public class OtaFirmwareInfo {
    
        /**
         * The size of the update package.
         */
        private long size;
    
        /**
         * Valid signature methods: MD5 and SHA256.
         */
        private String signMethod;
    
        /**
         * The signature of the update package.
         */
        private String sign;
    
        /**
         * The version of the update package.
         */
        private String version;
    
        /**
         * The download URL of the update package.
         */
        private String url;
    }

    Example

    bridgeBootstrap.setOtaUpgradeHandler(new OtaUpgradeHandler() {
        @Override
        public boolean onUpgrade(String requestId, OtaFirmwareInfo firmwareInfo, Session session) {
            log.info("ota onUpgrade, requestId:{}, firmware:{}, identity:{}",
                requestId, firmwareInfo, session.getOriginalIdentity());
            // Implement the OTA update.
            return true;
        }
    });
  • The operation that is used to submit the update progress

    After a firmware update starts, a device must submit the update progress to the following topic: /ota/device/progress/${YourProductKey}/${YourDeviceName}.

    To enable a device to submit the update progress, you can call the TslUplinkHandler.reportOtaProgress operation. Syntax:

    /**
     * Submit the OTA update progress.
     * @param requestId: the ID of the request
     * @param originalIdentity: the original identifier of the device
     * @param step: the current progress
     * @param desc: the description
     * @return
    */
    boolean reportOtaProgress(String requestId, String originalIdentity, String step, String desc)

    Example

    tslUplinkHandler.reportOtaProgress("7979", session.getOriginalIdentity(), "100", "ota success");