设备端OTA升级

更新时间：2024-09-12 06:23:50

OTA（Over-the-Air Technology）即空中下载技术。物联网平台支持通过OTA方式进行设备升级。本文以MQTT协议下的OTA升级为例，介绍OTA升级流程、数据流转使用的Topic和数据格式。

OTA升级流程

MQTT协议下OTA升级流程如下图所示。
设备端OTA升级

OTA升级说明

整包升级前，设备可不上报OTA模块版本。如不上报，配置批量升级时不能针对指定版本进行升级。
若设备需要在首次升级前上报版本号，建议只在系统启动过程中上报一次，不需要周期循环上报。设备升级成功后，需要第一时间上报版本。

从物联网平台控制台发起批量升级后，设备升级操作记录状态是待升级。
物联网平台根据设备端上报的版本号来判断设备端OTA升级是否成功。
设备离线时，不能接收服务端推送的升级消息。
通过MQTT协议接入物联网平台的设备再次上线后，物联网平台自动检测到设备上线，OTA服务端验证该设备是否需要升级。如果需要升级，物联网平台再次推送升级消息给设备，否则不推送消息。

数据格式说明

OTA升级流程及使用的Topic和数据格式如下：
（可选）设备连接OTA服务，上报版本号。

1、设备端通过MQTT协议推送当前设备OTA模块版本号到Topic： /ota/device/inform/${YourProductKey}/${YourDeviceName}。消息格式如下：

{
    "id": "123",
    "params": {
        "version": "1.0.1",
        "module": "MCU"
    }
}

参数	类型	说明
id	String	消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
version	String	OTA模块版本。
module	String	OTA模块名

2、在物联网平台控制台上，添加升级包、验证升级包并发起批量升级任务。
3、您在控制台触发升级操作之后，设备会收到物联网平台OTA服务推送的升级包的URL地址。

设备端订阅Topic：/ota/device/upgrade/${YourProductKey}/${YourDeviceName}。物联网平台对设备发起OTA升级请求后，设备端会通过该Topic收到升级包的存储地址URL。
消息格式如下：

升级包下载协议为HTTPS

{
    "id": "123",
    "code": 200,
    "data": {
        "size": 93796291,
        "sign": "f8d85b250d4d787a9f483d89a974***",
        "version": "10.0.1.9.20171112.1432",
        "isDiff": 1,
        "url": "https://the_firmware_url",
        "signMethod": "MD5",
        "md5": "f8d85b250d4d787a9f48***",
        "module": "MCU",
        "extData":{
            "key1":"value1",
            "key2":"value2",
            "_package_udi":"{\"ota_notice\":\"升级底层摄像头驱动，解决视频图像模糊的问题。\"}"
        }
    }
}

多个文件的OTA升级包仅支持HTTP下载协议，信息如下：

{
    "id": "123",
    "code": 200,
    "data": {
        "version": "2.0.0",
        "isDiff": 1,
        "signMethod": "MD5",
        "files":[
            {
                "fileSize":432944,
                "fileName":"file1-name",
                "fileUrl":"https://iotx***.aliyuncs.com/nop***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7***U%3D&security-token=CAISu***",
                "fileMd5":"93230c3bde425a9d7984a594ac55ea1e",
                "fileSign":"93230c3bde425a9d7984a594ac55****"
            },
            {
                "fileSize":432945,
                "fileName":"file2-name",
                "fileUrl":"https://iotx-***.aliyuncs.com/no***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7P***KU%3D&security-token=CAISuQJ***",
                "fileMd5":"93230c3bde425a9d7984a594ac56ea1f",
                "fileSign":"93230c3bde425a9d7984a594ac56****"
           }
        ],
        "module": "MCU",
        "extData":{
            "key1":"value1",
            "key2":"value2",
            "_package_udi":"{\"ota_notice\":\"升级底层摄像头驱动，解决视频图像模糊的问题。\"}"
        }
    }
}

参数说明

参数	类型	说明
id	Long	消息ID号。每个消息ID在当前设备中具有唯一性。
message	String	结果信息。
code	String	状态码。
version	String	设备升级包的版本信息。
size	Long	升级包文件大小，单位：字节。OTA升级包中仅有一个升级包文件时，包含该参数。
url	String	升级包在对象存储（OSS）上的存储地址。OTA升级包中仅有一个升级包文件，且下载协议为HTTPS时，包含该参数。
dProtocol	String	升级包下载协议。仅升级包下载协议为MQTT时，包含该参数。
streamId	Long	通过MQTT协议下载OTA升级包时的唯一标识。仅升级包下载协议为MQTT时，包含该参数。
streamFileId	Integer	单个升级包文件的唯一标识。仅升级包下载协议为MQTT时，包含该参数。
isDiff	Long	仅当升级包类型为差分时，消息包含此参数。取值为1，表示仅包含新版本升级包与之前版本的差异部分，需要设备进行差分还原。
digestsign	String	OTA升级包文件安全升级后的签名。仅当OTA升级包开启安全升级功能，才有此参数。
sign	String	OTA升级包文件的签名。OTA升级包中仅有一个升级包文件时，包含该参数
signMethod	String	签名方法。取值：SHA256、MD5。对于Android差分升级包类型，仅支持MD5签名方法。
md5	String	当签名方法为MD5时，除了会给sign赋值外还会给md5赋值。OTA升级包中仅有一个升级包文件时，包含该参数。
module	String	升级包所属的模块名。
extData	Object	升级批次标签列表和推送给设备的自定义信息。_package_udi表示自定义信息的字段。单个标签格式：“key”:“value”。
files	Array	多个升级包文件的信息列表。OTA升级包中有多个文件时，包含该参数。每个升级包文件信息如下：fileSize：升级包文件大小。fileName：升级包文件的名称。fileUrl、fileMd5、fileSign：含义与url、md5、sign相同。

4、可选）设备端SDK接收到物联网平台推送的升级包URL后，若未在24小时内完成升级包下载，该URL失效。设备端可通过调用以下topic，重新向物联网平台主动请求获取升级任务。
设备端发起请求的Topic为/sys/{productKey}/{deviceName}/thing/ota/firmware/get，消息格式如下。

{
    "id": "123",
    "version": "1.0",
    "params": {
        "module": "MCU"
    },
    "method": "thing.ota.firmware.get"
}

参数说明：

参数	类型	说明
id	String	消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
version	String	协议版本，固定为1.0。
params	Object	请求参数。
module	String	升级包所属的模块名。
method	String	请求方法，取值thing.ota.firmware.get。

物联网平台收到请求后，通过响应Topic：/sys/{productKey}/{deviceName}/thing/ota/firmware/get_reply，向设备端返回升级包信息。下发升级包信息。
返回数据格式如下，单个文件的OTA升级包信息：
a、升级包下载协议为HTTPS：

{
    "id": "123",
    "code": 200,
    "data": {
        "size": 93796291,
        "sign": "f8d85b250d4d787a9f483d89a974***",
        "version": "10.0.1.9.20171112.1432",
        "isDiff": 1,
        "url": "https://the_firmware_url",
        "signMethod": "MD5",
        "md5": "f8d85b250d4d787a9f48***",
        "module": "MCU",
        "extData":{
            "key1":"value1",
            "key2":"value2",
            "_package_udi":"{\"ota_notice\":\"升级底层摄像头驱动，解决视频图像模糊的问题。\"}"
        }
    }
}

b、多个文件的OTA升级包仅支持HTTP下载协议，信息如下：

{
    "id": "123",
    "code": 200,
    "data": {
        "version": "2.0.0",
        "isDiff": 1,
        "signMethod": "MD5",
        "files":[
            {
                "fileSize":432944,
                "fileName":"file1-name",
                "fileUrl":"https://iotx***.aliyuncs.com/nop***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7***U%3D&security-token=CAISu***",
                "fileMd5":"93230c3bde425a9d7984a594ac55ea1e",
                "fileSign":"93230c3bde425a9d7984a594ac55****"
            },
            {
                "fileSize":432945,
                "fileName":"file2-name",
                "fileUrl":"https://iotx-***.aliyuncs.com/no***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7P***KU%3D&security-token=CAISuQJ***",
                "fileMd5":"93230c3bde425a9d7984a594ac56ea1f",
                "fileSign":"93230c3bde425a9d7984a594ac56****"
           }
        ],
        "module": "MCU",
        "extData":{
            "key1":"value1",
            "key2":"value2",
            "_package_udi":"{\"ota_notice\":\"升级底层摄像头驱动，解决视频图像模糊的问题。\"}"
        }
    }
}

参数说明：

参数	类型	说明
id	String	消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。此处消息ID返回的是设备请求中的消息ID，即请求Topic/sys/${productKey}/${deviceName}/thing/ota/firmware/get数据中的id。
code	Integer	状态码，200表示成功。
data	Object	升级包信息

无升级包信息下发。返回数据格式如下：

{
    "id": "123",
    "code": 200,
    "data": {
    }
}

5、设备端SDK收到物联网平台推送的升级包URL后，调用SDK提供的接口，通过HTTPS协议下载升级包。
6、升级过程中，设备端向服务端推送升级进度到Topic：/ota/device/progress/${YourProductKey}/${YourDeviceName}。

消息格式如下：

{
    "id": "123",
    "params": {
        "step": "-1",
        "desc": "OTA升级失败，请求不到升级包信息。",
        "module": "MCU"
    }
}

参数说明：

参数	类型	说明
id	String	消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
step	String	OTA升级进度。取值范围：1~100的整数：升级进度百分比。-1：升级失败。-2：下载失败。-3：校验失败。-4：烧写失败。
desc	String	当前步骤的描述信息，长度不超过128个字符。如果发生异常，此字段可承载错误信息。
module	String	升级包所属的模块名。模块的更多信息，

7、设备端完成OTA升级后，推送最新的版本信息到
Topic：/ota/device/inform/${YourProductKey}/${YourDeviceName}。如果上报的版本与OTA服务要求的版本一致就认为升级成功，反之失败。

升级成功的唯一判断条件是设备上报正确的版本号。即使升级进度上报为100%，如果不上报新的版本号，会因超时导致升级失败。
设备升级完成后，建议立即重启设备，设备上线后，立即上报新的版本号。设备上线请求和上报版本请求间隔不能超过2秒。

上一篇查看升级数据

下一篇安全隧道