The IoT as Bridge SDK 2.1.3 and later support over-the-air (OTA) updates for firmware. This topic 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 procedure of an OTA update.

For more information about how to push firmware from Alibaba Cloud to devices, see Push firmware to devices.

For more information about how to specify topics and data formats for firmware updates, see Firmware updates.

Call operations for OTA updates

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

  • The operation used to submit versions of device firmware

    After being enabled or completing an OTA update, a 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. The syntax is as follows:

    /**
     * Report the firmware version of a device.
     * 
     * @param originalIdentity: the original identifier of the device that matches the device certificate specified in the devices.conf configuration file.
     * @param version: the firmware version to be reported.
     * @return true if succeeded
    */
    boolean reportFirmwareVersion(String originalIdentity, String version)

    Example

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

    After you add firmware 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 Alibaba Cloud, you can call the BridgeBootStrap.setOtaUpgradeHandler() operation and configure a callback. The syntax is as follows:

    /** 
     * set otaUpgradeHandler to receive cloud push ota firmware info 
     * @param otaUpgradeHandler user-define otaUpgradeHandler 
    */ 
    public void setOtaUpgradeHandler(OtaUpgradeHandler otaUpgradeHandler) {
        this.callback.setOtaUpgradeHandler(otaUpgradeHandler); 
    } 
    
    public interface OtaUpgradeHandler {     
        /**     
         * cloud push firmware upgrade info 
         * @param requestId: the ID of the request to push update notifications from Alibaba Cloud.     
         * @param firmwareInfo: the information about OTA updates. 
         * @param session: the current session.  
         * @return
         */
        boolean onUpgrade(String requestId, OtaFirmwareInfo firmwareInfo, Session session);
    } 
    
    public class OtaFirmwareInfo {
    
        /**
         * firmware size
         */
        private long size;
    
        /**
         * signMethod: MD5, SHA256
         */
        private String signMethod;
    
        /**
         * firmware sign value
         * if signMethod is "MD5", then sign is md5 value of the firmware
         */
        private String sign;
    
        /**
         * firmware version
         */
        private String version;
    
        /**
         * firmware download url
         */
        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());        
            //handle ota upgrade        
            return true;    
        } 
    });
  • The operation used to report 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. The syntax is as follows:

    /** 
     * Report the OTA update progress. 
     * @param requestId: the ID of the request. 
     * @param originalIdentity: the original identity 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");