泛化协议SDK 2.1.3及以上版本支持设备固件OTA升级。本文介绍使用泛化协议SDK调用OTA升级接口,实现设备固件升级。

背景信息

说明 仅泛化协议SDK 2.1.3及以上版本支持OTA升级。

设备OTA升级过程如下图所示。

OTA

云端推送固件操作说明,请参见推送固件到设备端

设备固件升级过程使用的Topic和数据结构等信息,请参见固件升级Topic和数据格式

调用OTA接口

泛化协议SDK中已封装OTA固件升级相关接口。您需配置SDK调用以下三个接口实现OTA升级。

  • 设备上报固件版本接口

    设备启动时和固件升级后,上报当前固件版本到Topic: /ota/device/inform/${YourProductKey}/${YourDeviceName}

    泛化协议SDK调用TslUplinkHandler.reportFirmwareVersion接口,上报固件版本信息。接口设置如下:

    /**
     * Report the firmware version of a device.
     * 
     * @param originalIdentity 设备身份原始标识符,和devices.conf配置文中设备证书对应
     * @param version 待上报的OTA版本
     * @return true if succeeded
    */
    boolean reportFirmwareVersion(String originalIdentity, String version)

    调用示例:

    TslUplinkHandler tslUplinkHandler = new TslUplinkHandler();
    tslUplinkHandler.doOnline(session, originalIdentity);
    tslUplinkHandler.reportOtaVersion("12345", originalIdentity, "1.0.1");
  • 监听云端下发升级通知接口

    您在物联网平台上添加固件,并启动批量升级后,物联网平台向设备下发升级通知。设备需订阅/ota/device/upgrade/${YourProductKey}/${YourDeviceName}获取升级通知。

    泛化协议SDK调用BridgeBootStrap.setOtaUpgradeHandler()接口,并设置一个回调,接收云端推送的OTA升级的信息。接口设置如下:

    /**
     * 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 云端推送固件升级消息的ID
         * @param firmwareInfo OTA固件升级信息
         * @param session 当前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;
    }

    调用示例:

    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;
        }
    });
  • 上报升级进度接口

    设备开始升级,并上报升级进度到Topic:/ota/device/progress/${YourProductKey}/${YourDeviceName}

    泛化协议SDK调用调用TslUplinkHandler.reportOtaProgress接口,上报升级进度。接口设置如下:

    /**
     * 上报OTA升级进度
     * @param requestId  请求消息ID
     * @param originalIdentity 设备原始身份标识符
     * @param step 当前进度
     * @param desc 描述语
     * @return
    */
    boolean reportOtaProgress(String requestId, String originalIdentity, String step, String desc)

    调用示例:

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