文档

设备端OTA升级

更新时间:

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

OTA升级流程

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

流程

OTA升级说明

  • 差分升级前,设备必须上报OTA模块版本。整包升级前,设备可不上报OTA模块版本。如不上报,配置批量升级时不能针对指定版本进行升级,具体说明,请参见发起升级批次任务

    若设备需要在首次升级前上报版本号,建议只在系统启动过程中上报一次,不需要周期循环上报。设备升级成功后,需要第一时间上报版本。

  • 从物联网平台控制台发起批量升级后,设备升级操作记录状态是待升级。

    实际升级从物联网平台OTA系统,接收到设备上报的升级进度开始。设备升级操作记录状态是升级中。

    说明

    设备端接收到物联网平台推送的升级通知后,可立即下载升级包进行升级,也可在业务空闲后,主动获取升级信息进行升级。

  • 物联网平台根据设备端上报的版本号来判断设备端OTA升级是否成功。

  • 设备离线时,不能接收服务端推送的升级消息。

    通过MQTT协议接入物联网平台的设备再次上线后,物联网平台自动检测到设备上线,OTA服务端验证该设备是否需要升级。如果需要升级,物联网平台再次推送升级消息给设备,否则不推送消息。

数据格式说明

设备端OTA开发流程和代码示例,请参见Link SDK文档中,各语言SDK文档的设备OTA开发章节。

OTA升级流程及使用的Topic和数据格式如下:

  1. (可选)设备连接OTA服务,上报版本号。

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

    {
        "id": "123",
        "params": {
            "version": "1.0.1",
            "module": "MCU"
        }
    }
    表 1. 参数说明
    参数类型说明
    idString消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
    versionStringOTA模块版本。
    moduleStringOTA模块名。
    说明
    • 上报默认(default)模块的版本号时,可以不上报module参数。
    • 设备的默认(default)模块的版本号代表整个设备的固件版本号。
  2. 在物联网平台控制台上,添加升级包、验证升级包并发起批量升级任务。

    具体操作,请参见推送升级包到设备端

  3. 您在控制台触发升级操作之后,设备会收到物联网平台OTA服务推送的升级包的URL地址。

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

    消息格式如下:

    • 单个文件的OTA升级包信息:
      • 升级包下载协议为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\":\"升级底层摄像头驱动,解决视频图像模糊的问题。\"}"
                }
            }
        }
      • 升级包下载协议为MQTT:
        {
            "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"
                }
            }
        }
    • 多个文件的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\":\"升级底层摄像头驱动,解决视频图像模糊的问题。\"}"
              }
          }
      }
    表 2. 参数说明
    参数类型说明
    idLong消息ID号。每个消息ID在当前设备中具有唯一性。
    messageString结果信息。
    codeString状态码。
    versionString设备升级包的版本信息。
    sizeLong升级包文件大小,单位:字节。

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

    urlString升级包在对象存储(OSS)上的存储地址。

    OTA升级包中仅有一个升级包文件,且下载协议为HTTPS时,包含该参数。

    dProtocolString升级包下载协议。

    仅升级包下载协议为MQTT时,包含该参数。

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

    仅升级包下载协议为MQTT时,包含该参数。

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

    仅升级包下载协议为MQTT时,包含该参数。

    isDiffLong仅当升级包类型为差分时,消息包含此参数。

    取值为1,表示仅包含新版本升级包与之前版本的差异部分,需要设备进行差分还原。

    digestsignStringOTA升级包文件安全升级后的签名。仅当OTA升级包开启安全升级功能,才有此参数。开启OTA升级包安全升级功能的方法,请参见安全升级
    signStringOTA升级包文件的签名。

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

    signMethodString签名方法。取值:
    • SHA256
    • MD5
    对于Android差分升级包类型,仅支持MD5签名方法。
    md5String当签名方法为MD5时,除了会给sign赋值外还会给md5赋值。

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

    moduleString升级包所属的模块名。
    说明 模块名为default时,物联网平台不下发module参数。
    extDataObject升级批次标签列表和推送给设备的自定义信息。

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

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

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

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

    • fileSize:升级包文件大小。
    • fileName:升级包文件的名称。
    • fileUrlfileMd5fileSign:含义与urlmd5sign相同。
  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"
    }
    表 4. 参数说明
    参数类型说明
    idString消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
    versionString协议版本,固定为1.0。
    paramsObject请求参数。
    moduleString升级包所属的模块名。
    说明 不指定则表示请求默认(default)模块的升级包信息。
    methodString请求方法,取值thing.ota.firmware.get

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

    • 下发升级包信息。返回数据格式如下:
      • 单个文件的OTA升级包信息:
        • 升级包下载协议为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\":\"升级底层摄像头驱动,解决视频图像模糊的问题。\"}"
                  }
              }
          }
        • 升级包下载协议为MQTT:
          {
              "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"
                  }
              }
          }
      • 多个文件的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\":\"升级底层摄像头驱动,解决视频图像模糊的问题。\"}"
                }
            }
        }
      表 5. 参数说明
      参数类型说明
      idString消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。

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

      codeInteger状态码,200表示成功。
      dataObject升级包信息,其中参数说明,请参见物联网平台推送OTA升级包信息的参数表
    • 无升级包信息下发。返回数据格式如下:
      {
          "id": "123",
          "code": 200,
          "data": {
          }
      }
  5. 设备端SDK收到物联网平台推送的升级包URL后,调用SDK提供的接口,通过HTTPS协议下载升级包。例如C SDK中提供了接口aiot_download_send_request具体操作,请参见设备OTA

    说明

    设备端无法自动下载升级包,可通过调用SDK中接口进行下载。下载须在升级包URL下发后的24小时内完成,否则该URL失效。

  6. 升级过程中,设备端向服务端推送升级进度到Topic:/ota/device/progress/${YourProductKey}/${YourDeviceName}

    消息格式如下:

    {
        "id": "123",
        "params": {
            "step": "-1",
            "desc": "OTA升级失败,请求不到升级包信息。",
            "module": "MCU"
        }
    }
    表 3. 参数说明
    参数类型说明
    idString消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
    stepString

    OTA升级进度。

    取值范围:
    • 1~100的整数:升级进度百分比。
    • -1:升级失败。
    • -2:下载失败。
    • -3:校验失败。
    • -4:烧写失败。

    设备上报的进度值及其描述信息,可根据设备实际升级场景在设备端配置。设备端配置方法,请参见设备端Link SDK的OTA升级

    descString当前步骤的描述信息,长度不超过128个字符。如果发生异常,此字段可承载错误信息。
    moduleString升级包所属的模块名。模块的更多信息,请参见添加升级包
    说明 上报默认(default)模块的OTA升级进度时,可以不上报module参数。
  7. 设备端完成OTA升级后,推送最新的版本信息到Topic:/ota/device/inform/${YourProductKey}/${YourDeviceName}。如果上报的版本与OTA服务要求的版本一致就认为升级成功,反之失败。

    重要
    • 升级成功的唯一判断条件是设备上报正确的版本号。即使升级进度上报为100%,如果不上报新的版本号,会因超时导致升级失败。

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

常见下载升级包错误

  • 签名错误。如果设备端获取的升级包的URL不全或者手动修改了URL内容,就会出现如下错误: 脱敏处理

  • 拒绝访问。URL过期导致。目前,URL有效期为24小时。信息脱敏处理

相关文档

OTA升级实践案例,请参见设备OTA升级实践

  • 本页导读 (1)
文档反馈