OTA升级概述

使用限制

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

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

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

  • HTTPS协议下载：可以包括一个或多个文件，单个文件最大为1,000 MB。仅支持.bin、.dav、.tar、.gz、.zip、.gzip、.apk、.tar.gz、.tar.xz、.pack格式的文件。

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

工作原理

前提条件

• 使用物联网卡的设备、使用C LinkSDK 2.x版本及以下的设备，需要获取OTA升级的域名。

  OTA升级服务于2023年09月01日00:00起，变更下载升级包的域名。如果您的设备（例如，使用蜂窝网络的物联网设备）需要针对访问域名设置白名单，本次变更有可能会造成您的设备无法正常下载新的升级包。您可以提交工单获取OTA升级服务的最新域名列表。具体内容，请参见【升级】【阿里云】【物联网平台】OTA升级功能服务域名调整通知。

• 将设备接入物联网平台。使用Link SDK的设备，请参见获取C Link SDK、设备接入引导。搭载AliOS Things芯片的设备，请参见AliOS Things文档。

OTA升级步骤

步骤一：设备上报版本号

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协议下载升级包。

   • HTTPS协议下载单个文件。

   • 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升级失败原因，进而提升设备升级成功率。

相关文档

• 设备OTA升级失败的常见问题和解决方法，请参见如何解决设备OTA升级失败问题。

• 可以在物联网平台控制台，查询云端运行日志。该日志包含了物联网平台、设备、您的应用程序三者之间的交互通信记录。

• 物联网平台可能返回给设备端的错误码及说明，请参见设备端接收的错误码。

• 如果需要将设备上报的升级信息，通过AMQP通道推送至您的服务器，请参见配置AMQP服务端订阅。OTA升级相关Topic数据，经过消息转发后的数据格式，请参见数据格式。

消息格式

上报版本号

• 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"
}

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：升级包文件的名称。 fileUrl、fileMd5、fileSign：含义与url、md5、sign相同。

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。

   • 响应消息的结构

     

     结构项	说明
     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参数。