在鸿云文档

Appearance

OTA升级 ​

设备管理平台提供OTA升级与固件包管理服务，使用该服务首先要确保设备端支持OTA功能服务，然后在设备管理平台控制台的OTA升级页面，上传新的升级包并指定需要升级的设备和策略。设备管理平台会将OTA升级消息推送给设备，设备即可下载OTA升级包，并进行OTA升级。本文主要介绍OTA升级的使用限制和操作流程。

OTA升级说明 ​

  • 支持通过MQTT协议接入设备管理平台的设备使用OTA升级功能。
  • 一个账号下最多可有500个升级包。
  • 文件大小不能超过2,000 MB，且仅支持.bin、.tar、.gz、.zip、.gzip、.apk、.tar.gz格式的文件。

工作原理 ​

OTA升级步骤 ​

OTA升级流程 ​

设备管理平台OTA升级流程如下：

  • 设备端开发OTA升级功能：配置设备远程OTA升级能力。
  • 添加升级包：在产品下添加OTA模块和升级包。
  • 发起OTA升级任务：设备管理平台向设备批量下发升级相关信息（升级包URL、版本、大小等信息）。
  • 设备端OTA升级：设备端获取设备管理平台发起的OTA升级相关信息，使用升级包URL下载升级包，完成OTA升级。
  • 设备端上报日志：设备端上报OTA升级情况日志。
  • 查看升级情况：查看目标设备升级状态、升级包信息等。
  • 查看升级包版本和成功情况：查看升级后的版本和成功情况，分析OTA升级失败原因，进而使设备升级成功。

设备上报OTA模块和版本 ​

上报topic定义 ​

Topic：tlink/${productKey}/${deviceName}/ota/device/inform

设备通过这个Topic上报当前的OTA模块版本信息。

注意 本Topic只支持单个OTA的模块版本上报。如果需要上报多个模块的版本，请分多次上报，每次上报一个模块的版本信息。 如果是子设备的模块版本信息，topic为子设备的productKey和子设备的deviceName。

上报数据体格式 ​

javascript
{
  "reqid": "0020fdf71f0d491da12ba3cd38b205be",
  "v": "1",
  "t": 1630054074378,
   "method": "tlink.${productKey}.${deviceName}.ota.device.inform",
  "data": {
      "version": "10.00.01",
      "module": "MCU"
  }
}

上报参数说明

参数名称
类型
是否必选
描述
reqidString否消息ID号。全局唯一，用于系统消息追踪
vString否协议版本号，目前协议版本号唯一取值为1
tLong否消息发送时间戳
methodString否TCP连接时必传
dataObject是上报参数。
  versionString是OTA模块的版本。
  moduleString否OTA模块名。不传为默认模块

平台推送OTA升级包信息 ​

设备管理平台通过这个Topic推送OTA升级包信息给设备端， 设备订阅该Topic可以获得升级包信息。

推送topic定义 ​

Topic：tlink/${productKey}/${deviceName}/ota/device/upgrade

推送数据体格式 ​

单个或多个文件的OTA升级包信息，数据协议如下。

javascript
{
  "reqid": "0020fdf71f0d491da12ba3cd38b205be",
   "method": "tlink.${productKey}.${deviceName}.ota.device.upgrade",
  "code": 200,
  "data": {
    "version": "20.00.02",
    "isDiff": 1,
    "module": "MCU",
    "startTime":"00:00",
    "endTime":"23:59",
    "week":"0123456"
    "files":[
        {
            "fileSize":432944,
            "fileName":"file1-name",
            "fileUrl":"http://***/nopoll_0.4.3.tar.gz?Expires=1502***",
            "fileIpUrl":"http://***.***.***.***/nopoll_0.4.3.tar.gz?Expires=1502***",
            "httpsFileUrl":"https://***/nopoll_0.4.3.tar.gz?Expires=1502***",
            "signMethod": 1,
            "fileMd5":"93230c3bde425a9d***"
        },
        {
            "fileSize":432945,
            "fileName":"file2-name",
            "fileUrl":"http://***/nopoll_0.4.4.tar.gz?Expires=150O****",
            "fileIpUrl":"http://***.***.***.***/nopoll_0.4.4.tar.gz?Expires=150O****",
            "httpsFileUrl":"https://***/nopoll_0.4.4.tar.gz?Expires=150O****",
            "signMethod": 1,
            "fileMd5":"93230c3bde425a92***"
        }
    ],
     "extData":{
        "key1":"value1",
        "key2":"value2",
        "remark":"升级包说明"
     }
  }
}

推送参数说明

参数名称
类型
是否必选
描述
reqidString是消息ID号。全局唯一，用于系统消息追踪
methodString否TCP连接时必传
codeInteger是结果状态码。成功为200，其他为失败
dataObject是推送数据体。
  versionString是升级包的版本信息。
  isDiffInteger是当升级包类型为整包时，取值为0
当升级包类型为差分时，取值为1，表示仅包含新版本升级包与之前版本的差异部分，需要设备进行差分还原。
当升级包类型为流式差分时，取值为2
当升级包类型为流式整包时，取值为3
  moduleString是升级包所属的模块名。
  startTimeString是指定升级开始时间。
  endTimeString是指定升级结束时间。
  weekString是指定升级周期：0123456 表示每天 01表示星期天星期一执行
  filesList是单个或多个升级包文件的信息列表。
    fileSizeLong是升级包文件大小，单位：字节。
    fileNameString是文件名称。
    fileUrlString是升级包http下载地址。 默认24小时失效
    fileIpUrlString是升级包ip下载地址。 默认24小时失效
    httpsFileUrlString是升级包https下载地址。 默认24小时失效
    signMethodInteger是文件的加密方式，1为MD5，2为SHA-256。
    fileMd5String是文件的加密值。
  extDataObject是升级自定义信息。表示自定义信息的字段。单个格式："key":"value"，如："remark":"升级包说明"。
    key1String否自定义：key1
    key2String否自定义：key2
    remarkString是升级包说明

设备上报OTA升级进度 ​

OTA升级过程中，设备可以通过这个Topic上报OTA升级的进度百分比。

上报topic定义 ​

Topic：tlink/${productKey}/${deviceName}/ota/device/progress

上报数据体格式 ​

javascript
{
  "reqid": "0020fdf71f0d491da12ba3cd38b205be",
  "v": "1",
  "t": 1630054074378,
   "method": "tlink.${productKey}.${deviceName}.ota.device.progress",
  "data": {
    "step": "-1",
    "module": "MCU",
    "desc": "OTA升级失败，请求不到升级包信息。"
  }
}

上报参数说明

参数名称
类型
是否必选
描述
reqidString否消息ID号。注意：请使用下发升级包时给的reqid，方便追踪对应请求
vString否协议版本号，目前协议版本号唯一取值为1
tLong否消息发送时间戳
methodString否TCP连接时必传
dataObject是上报参数。
  stepString是OTA升级进度。
1~100的整数：升级进度百分比 ；
100表示升级成功,-1：升级失败 -2: 下载失败 -3: 校验失败 -4:烧写失败.-5:电量, -6:网络, -7:存储不够。
200:下载开始, 201:下载成功。设备上报的进度值及其描述信息，可根据设备实际升级场景在设备端配置。
  moduleString否升级包所属的模块名。不传为默认模块
  descString否当前步骤的描述信息，长度不超过128个字符。如果发生异常，此字段可承载错误信息

设备请求OTA升级包信息 ​

请求topic定义 ​

Topic：tlink/${productKey}/${deviceName}/ota/device/get

数据流向：设备发布消息，平台监听消息

请求数据体格式 ​

javascript
{
  "reqid": "0020fdf71f0d491da12ba3cd38b205be",
  "v": "1",
  "t": 1630054074378,
   "method": "tlink.${productKey}.${deviceName}.ota.device.get",
  "data": {
    "module": "MCU"
  }
}

请求参数说明

参数名称
类型
是否必选
描述
reqidString否消息ID号。全局唯一，用于系统消息追踪
vString否协议版本号，目前协议版本号唯一取值为1
tLong否消息发送时间戳
methodString否TCP连接时必传
dataObject是上报参数。
  moduleString否请求升级包所属的模块名。不传为默认模块

平台响应设备请求OTA升级包信息 ​

设备管理平台收到设备请求后，响应请求。下发升级包信息

响应topic定义 ​

Topic：tlink/${productKey}/${deviceName}/ota/device/get_reply

数据流向：平台发布消息，设备监听消息

响应数据体格式 ​

单个或多个文件的OTA升级包信息，响应数据协议如下。

javascript
{
  "reqid": "0020fdf71f0d491da12ba3cd38b205be",
   "method": "tlink.${productKey}.${deviceName}.ota.device.get_reply",
  "code": 200,
  "data": {
    "version": "20.00.02",
    "isDiff": 1,
    "module": "MCU",
    "startTime":"00:00",
    "endTime":"23:59",
    "week":"0123456"
    "files":[
        {
            "fileSize":432944,
            "fileName":"file1-name",
            "fileUrl":"http://***/nopoll_0.4.3.tar.gz?Expires=1502***",
            "fileIpUrl":"http://***.***.***.***/nopoll_0.4.3.tar.gz?Expires=1502***",
            "httpsFileUrl":"https://***/nopoll_0.4.3.tar.gz?Expires=1502***",
            "signMethod": 1,
            "fileMd5":"93230c3bde425a9d***"
        },
        {
            "fileSize":432945,
            "fileName":"file2-name",
            "fileUrl":"http://***/nopoll_0.4.4.tar.gz?Expires=150O****",
            "fileIpUrl":"http://***.***.***.***/nopoll_0.4.3.tar.gz?Expires=1502***",
            "httpsFileUrl":"https://***/nopoll_0.4.3.tar.gz?Expires=1502***",
            "signMethod": 1,
            "fileMd5":"93230c3bde425a92***"
        }
    ],
     "extData":{
        "key1":"value1",
        "key2":"value2",
        "remark":"升级包说明"
     }
  }
}

响应参数说明

参数名称
类型
是否必选
描述
reqidString是消息ID号。和请求的对应
methodString否TCP连接时必传
codeInteger是结果状态码。成功为200，其他为失败
dataObject是推送数据体。
  versionString是升级包的版本信息。
  isDiffInteger是当升级包类型为整包时，取值为0
当升级包类型为差分时，取值为1，表示仅包含新版本升级包与之前版本的差异部分，需要设备进行差分还原。
当升级包类型为流式差分时，取值为2
当升级包类型为流式整包时，取值为3
  moduleString是升级包所属的模块名。
  startTimeString是指定升级开始时间。
  endTimeString是指定升级结束时间。
  weekString是指定升级周期：0123456 表示每天 01表示星期天星期一执行
  filesList是单个或多个升级包文件的信息列表。
    fileSizeLong是升级包文件大小，单位：字节。
    fileNameString是文件名称。
    fileUrlString是升级包http下载地址。 默认24小时失效
    fileIpUrlString是升级包ip下载地址。 默认24小时失效
    httpsFileUrlString是升级包https下载地址。 默认24小时失效
    signMethodInteger是文件的加密方式，1为MD5，2为SHA-256。
    fileMd5String是文件的MD5。
  extDataObject是升级自定义信息。表示自定义信息的字段。单个格式："key":"value"，如："remark":"升级包说明"。
    key1String否自定义：key1
    key2String否自定义：key2
    remarkString是升级包说明