文档

OTA升级概述

更新时间:

OTA(Over-the-Air Technology)即空中下载技术,基于无线网络对设备固件、软件或驱动进行更新。通过OTA升级,可以对物联网设备更新功能、修复漏洞、优化性能。本文介绍如何为接入物联网平台的设备进行OTA升级。

使用限制

使用OTA功能的设备必须使用MQTT协议接入物联网平台,设备可以选择MQTT协议或HTTPS协议下载升级包

  • 单个阿里云账号最多有500个升级包,账号下所有RAM用户共享配额。

  • 升级包的数量、大小、格式和地域限制。

    • HTTPS协议下载:可以包括一个或多个文件,单个文件最大为1,000 MB。如果需要更大的OTA升级包可提交工单。仅支持.bin.dav.tar.gz.zip.gzip.apk.tar.gz.tar.xz.pack格式的文件。

    • MQTT协议下载:仅包含一个文件,且文件大小不超过16 MB。目前仅支持中国华东2(上海)、华北2(北京)和华南1(深圳)地域。推荐使用物联网平台提供的C语言Link SDK,开发MQTT下载文件的能力。详细内容,请参见示例代码说明

工作原理

image
说明
  • 公共实例的转移设备仅支持发起升级方式静态升级的批量升级任务。

    • 转移设备的发起方:添加升级包、验证升级包。

    • 转移设备的接收方:查看升级包、发起升级批次。

  • 分发的设备在被分发到目标实例后可正常进行OTA升级。

前提条件

OTA升级步骤

image
说明

本文示例使用C语言Link SDK,其他语言SDK示例请参见设备接入概述

步骤一:设备上报版本号

  1. 配置OTA。

    1. 设备接入物联网平台。登录物联网平台控制台,单击对应实例,在左侧导航栏选择设备管理 > 设备,找到目标设备,查看设备状态。设备状态显示为在线,则表示设备与物联网平台成功连接。

    2. 初始化OTA功能

    3. 配置OTA功能

  2. 设备上报当前版本号。设备需要在首次升级前上报版本号,建议只在系统启动过程中上报一次,不需要周期循环上报。仅支持每次上报一个模块及对应的模块版本,如果需要上报多个模块的版本,请分次上报。上报的Topic和消息格式参见文末的消息格式

步骤二:推送升级包信息

  1. 购买和查看OTA升级次数:查看当前实例下可用的OTA升级次数,如果可用OTA升级次数不足,请先购买套餐包。

    • 对于新版公共实例,提供免费额度10次/自然月。

    • 对于企业版实例,提供免费额度1000次/自然月。

  2. 添加升级包:为产品添加OTA模块和升级包。

    • 模块:由用户自定义,是同产品下设备的不同可升级模块,例如固件、软件、驱动等。默认(default)模块表示整个设备的固件。

    • 整包:完整的升级文件,可以添加单个或多个升级包,如果添加多个示例包必须使用C语言的Link SDK。整包升级前,设备可不上报OTA模块版本。如不上报,配置批量升级时不能针对指定版本进行升级,具体说明,请参见发起升级批次任务

    • 差分:仅包含新版本升级包与之前版本的差异部分,设备需要本地进行差分还原,并还原为完整升级包进行升级,差分升级可有效降低OTA升级次数消耗和设备下载差分包的流量消耗。差分升级前,设备必须上报OTA模块版本。

      • 使用AliOS Things芯片的设备,阿里云提供差分包生成方法和差分还原算法,请参见OTA差分工具使用指南

      • 其他设备,需要您自行生成差分包并完成差分还原算法开发。

  3. (可选)验证升级包:添加升级包时选择升级包是否需要平台验证,则在批量升级前,需选择部分设备用于测试。测试设备升级成功后,才能使用升级包。

    可以选择是否由App确认升级后才能进行OTA升级,App确认升级的流程如下:

    1. 用户自行开发App,平台不会主动推送升级消息给设备,需要App主动查询。

    2. App侧调用ListOTAUnfinishedTaskByDevice,查询未完成状态的设备升级作业。

    3. App侧调用ConfirmOTATask,确认升级任务后,平台才会主动推送升级消息给设备。

  4. 发起升级批次任务:物联网平台向设备批量下发升级相关信息(升级包URL、版本、大小等)。发起批量升级后,在控制台显示的设备状态是待升级待确认。当物联网平台接收到设备上报的升级进度时,设备升级正式开始,在控制台显示的设备状态是升级中

步骤三:设备下载升级包

  1. 设备获取升级包信息。设备离线时不能接收OTA服务端推送的升级消息,设备再次上线后,OTA服务端验证该设备是否需要升级。如果需要升级,物联网平台再次推送升级消息给设备,否则不推送消息。

    • 物联网平台推送升级包信息。设备订阅Topic:/ota/device/upgrade/${YourProductKey}/${YourDeviceName},物联网平台对设备发起OTA升级请求后,设备通过该Topic收到升级信息。具体有以下两种情况:

      • 发起升级任务时设备在线,物联网平台会直接推送升级相关信息。

      • 发起升级任务时设备离线,之后设备上线,物联网平台会推送一次升级相关信息。

    • 设备主动拉取升级包信息。设备向Topic发布消息,物联网平台收到消息并通过另一Topic返回升级包信息。拉取升级包的Topic和消息格式参见文末的消息格式

    • 物联网平台发给设备的HTTPS协议、MQTT协议的下载消息格式参见文末的消息格式

  2. 设备使用HTTPS协议或MQTT协议下载升级包。

  3. 设备上报升级进度。上报进度的Topic和消息格式参见文末的消息格式

    重要

    如果设备上报进度的间隔低于3秒,在物联网平台控制台的OTA升级包详情的批次详情中,可能无法查看到上报的全部进度。

  4. 设备上报最新版本号。设备升级完成后,建议立即重启设备,设备上线后,立即上报新的版本号。设备上线请求和上报版本请求间隔不能超过2秒。

    重要

    如果设备上报的版本与OTA服务要求的版本一致就认为升级成功,反之认为失败,这是物联网平台判断设备升级成功的唯一条件。即使升级进度上报为100%,如果不上报新的版本号,可能因为超过设备升级超时时间导致升级失败。

    • Topic:/ota/device/inform/${YourProductKey}/${YourDeviceName}

    • 消息格式

      {
        "id": 1,
        "params": {
          "version": "2.0.0"
        }
      }

步骤四:查看升级结果

  1. 查看升级情况:查看目标设备升级状态、升级包信息等。

  2. 查看升级包版本和成功率:查看升级后的版本分布和成功率分布统计,分析OTA升级失败原因,进而提升设备升级成功率。

相关文档

消息格式

上报版本号

  • Topic:/ota/device/inform/${YourProductKey}/${YourDeviceName}

  • 消息格式

    {
      "id": 1,
      "params": {
        "version": "1.0.0",
        "module":"mcu"      //该参数如果不填,表示默认版本号default
      }
    }

    参数

    类型

    说明

    id

    String

    消息ID号。数字可为String或Long类型,以设备端上报的数据类型为准。取值范围为0~4294967295,且每个消息ID在当前设备中具有唯一性。

    version

    String

    OTA模块版本。

    module

    String

    OTA模块名。上报默认(default)模块的版本号时,可以不上报module参数。默认(default)模块代表整个设备的固件版本号。

主动拉取升级包

  1. 设备发布消息到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

      升级包所属的模块名。不指定则表示请求默认(default)模块的升级包信息。

      method

      String

      请求方法,取值thing.ota.firmware.get

  2. 物联网平台收到请求后,通过响应Topic:/sys/{productKey}/{deviceName}/thing/ota/firmware/get_reply,向设备端返回升级包信息。

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\":\"升级底层摄像头驱动,解决视频图像模糊的问题。\"}"
        }
    }
}

多文件包下载

{
    "code": "1000",
    "data": {
        "version": "2.0.0",
        "isDiff": 1,
        "signMethod": "MD5",
        "files":[
            {
                "fileSize":432944,
                "fileName":"file1-name",
                "fileUrl":"https://***/nop***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=***XJEH0qAKU%3D&security-token=CAISuQJ***",
                "fileMd5":"93230c3bde425a9d***",
                "fileSign":"93230c3bde425a9d****"
            },
            {
                "fileSize":432945,
                "fileName":"file2-name",
                "fileUrl":"https://***/no***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=***qAKU%3D&security-token=***q6Ft5B2y***",
                "fileMd5":"93230c3bde425a92***",
                "fileSign":"93230c3bde425a92****"
            }
        ],
        "module": "MCU",
        "extData":{
            "key1":"value1",
            "key2":"value2",
            "_package_udi":"{\"ota_notice\":\"升级底层摄像头驱动,解决视频图像模糊的问题。\"}"
        }
    },
    "id": 1626969597470,
    "message": "success"
}

参数

类型

说明

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升级包开启安全升级功能,才有此参数。开启OTA升级包安全升级功能的方法,请参见添加升级包

sign

String

OTA升级包文件的签名。

OTA升级包中仅有一个升级包文件时,包含该参数。

signMethod

String

签名方法。取值:

  • SHA256

  • MD5

对于Android差分升级包类型,仅支持MD5签名方法。

md5

String

当签名方法为MD5时,除了会给sign赋值外还会给md5赋值。

OTA升级包中仅有一个升级包文件时,包含该参数。

module

String

升级包所属的模块名。模块名为default时,物联网平台不下发module参数。

extData

Object

升级批次标签列表和推送给设备的自定义信息。

_package_udi表示自定义信息的字段。

单个标签格式:"key":"value"

files

Array

多个升级包文件的信息列表。

OTA升级包中有多个文件时,包含该参数。每个升级包文件信息如下:

  • fileSize:升级包文件大小。

  • fileName:升级包文件的名称。

  • fileUrlfileMd5fileSign:含义与urlmd5sign相同。

MQTT协议下载

升级包下载协议为MQTT时,只支持单文件包下载。设备端获取OTA升级包信息后,可以选择整包下载分片下载

  1. 整包下载

    • 消息格式

      {
          "id": "123",
          "code": 200,
          "data":{
              "size":432945,
              "digestsign":"A4WOP***SYHJ6DDDJD9***",
              "version":"2.0.0",
              "isDiff":1,
              "signMethod":"MD5",
              "dProtocol":"mqtt",
              "streamId":1397345,
              "streamFileId":1,
              "md5":"93230c3bde***",
              "sign":"93230c3bde42***",
              "module":"MCU",
              "extData":{
                  "key1":"value1",
                  "key2":"value2"
              }
          }
      }
    • 参数说明

      参数

      类型

      说明

      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升级包开启安全升级功能,才有此参数。开启OTA升级包安全升级功能的方法,请参见添加升级包

      sign

      String

      OTA升级包文件的签名。

      OTA升级包中仅有一个升级包文件时,包含该参数。

      signMethod

      String

      签名方法。取值:

      • SHA256

      • MD5

      对于Android差分升级包类型,仅支持MD5签名方法。

      md5

      String

      当签名方法为MD5时,除了会给sign赋值外还会给md5赋值。

      OTA升级包中仅有一个升级包文件时,包含该参数。

      module

      String

      升级包所属的模块名。模块名为default时,物联网平台不下发module参数。

      extData

      Object

      升级批次标签列表和推送给设备的自定义信息。

      _package_udi表示自定义信息的字段。

      单个标签格式:"key":"value"

      files

      Array

      多个升级包文件的信息列表。

      OTA升级包中有多个文件时,包含该参数。每个升级包文件信息如下:

      • fileSize:升级包文件大小。

      • fileName:升级包文件的名称。

      • fileUrlfileMd5fileSign:含义与urlmd5sign相同。

  2. 可选:分片下载。获取上面的升级包信息后,设备通过以下Topic分片下载OTA升级包文件。

    • 请求Topic:/sys/${productKey}/${deviceName}/thing/file/download

    • 响应Topic:/sys/${productKey}/${deviceName}/thing/file/download_reply

    • 请求消息格式

      {
       "id": "123456",
       "version": "1.0",
       "params": {
       "fileToken":"1bb8***",
       "fileInfo":{
       "streamId":1234565,
       "fileId":1
       },
       "fileBlock":{
       "size":256,
       "offset":2
       }
       }
      }
    • 请求消息的参数说明

      参数

      类型

      说明

      id

      String

      消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。

      version

      String

      协议版本,固定为1.0。

      params

      Object

      请求参数。

      fileToken

      String

      文件的唯一标识Token,非必填参数。支持数字、英文字母、下划线(_)和英文句号(.),不超过16个字符。

      使用说明:

      • 若传入该参数,物联网平台响应设备请求时,会返回该参数,便于您在设备端多文件下载场景下,从响应消息中确认下载的对应文件。

      • 若确认设备端在下载文件的请求和响应周期内,不需要对其他文件发起下载请求,可不设置该参数。

      fileInfo

      Object

      OTA升级包文件信息。

      streamId

      Long

      通过MQTT协议下载OTA升级包时的唯一标识。

      fileId

      Integer

      单个升级包文件的唯一标识。

      fileBlock

      Object

      文件分片信息。

      size

      Integer

      请求下载的文件分片大小,单位字节,取值范围为256~131072。若为最后一个文件分片,取值范围为1~131072。

      offset

      Integer

      文件分片对应字节的起始地址。取值范围为0~16777216。

    • 响应消息的结构

      image

      结构项

      说明

      JSON Bytes Length

      表示响应数据中JSON字符串对应的字节数组长度,必须占位2个字节,高位字节在前,低位字节在后。

      例如,响应的JSON字符串使用UTF-8编码转码成字节数组的长度为十进制的87,对应十六进制57,则高位字节为0x00,低位字节为0x57。

      JSON String Bytes

      表示响应数据中JSON字符串对应的字节数组,编码格式为UTF-8。具体内容,请参见下文的“响应的JSON数据格式”。

      File Block Bytes

      表示当前文件分片的字节数组,字节顺序按照相对于文件头的偏移量从小至大排列。

      CRC16/IBM

      表示文件分片的校验值,仅支持CRC16/IBM,占位2个字节,低位字节在前,高位字节在后。

      例如,文件分片的校验值为0x0809,则低位字节为0x09,高位字节为0x08。

    • 响应消息格式

      {
       "id": "123456",
       "code":200,
       "msg":"file size has exceeded the limit 16 MB",
       "data": {
       "fileToken":"1bb8***",
       "fileLength":1238848,
       "bSize":1491,
       "bOffset":2
       }
      }
    • 响应消息的参数说明

      参数

      类型

      说明

      id

      String

      消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。

      此处消息ID返回的是设备请求中的消息ID,即请求Topic/sys/${productKey}/${deviceName}/thing/file/download数据中的id

      code

      Integer

      状态码,200表示成功。

      msg

      String

      请求失败时,返回的错误信息。

      data

      Object

      返回设备端的数据。

      fileToken

      String

      文件的唯一标识Token。若请求参数传入了fileToken值,则返回该参数。

      fileLength

      Integer

      文件的总大小,单位字节。

      bSize

      Integer

      当前文件分片的大小,单位字节。

      bOffset

      Integer

      当前文件分片对应字节的起始地址,与请求数据中的offset值相同。单位字节。

上报升级进度

  • 设备发布消息到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

    升级包所属的模块名。模块的更多信息,请参见添加升级包

    上报默认(default)模块的OTA升级进度时,可以不上报module参数。

  • 本页导读 (1)