AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 云市场 伙伴产品指南 Tuya物联网平台阿里云版 操作指南 监控运维 OTA升级 设备端 OTA 升级

设备端 OTA 升级

更新时间：
我的收藏

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

OTA升级流程

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

image

OTA升级说明

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

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

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

说明

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

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

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

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

数据格式说明

设备端OTA开发流程和代码示例，请参见设备接入概述中，各语言SDK文档的设备OTA开发章节。

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

  1. （可选）设备连接OTA服务，上报版本号。

设备端通过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模块名。

说明

  • 上报默认（default）模块的版本号时，可以不上报module参数。

  • 设备的默认（default）模块的版本号代表整个设备的固件版本号。

  1. 在物联网平台控制台上，添加升级包、验证升级包并发起批量升级任务。具体操作，请参见推送升级包到设备端。

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

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

消息格式如下：

  • 单个文件的OTA升级包信息：

    • 升级包下载协议为HTTPS：

{
  "id": "123",
  "code": 200,
  "message": "success",
  "data": {
    "size": 93796291,
    "sign": "f8d85b250d4d787a9f483d89a974***",
    "version": "10.0.1.9.20171112.1432",
    "url": "https://the_firmware_url",
    "signMethod": "MD5",
    "md5": "f8d85b250d4d787a9f48***",
    "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时，包含该参数。

sign

String

OTA升级包文件的签名。

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

signMethod

String

签名方法。取值：

  • SHA256

  • MD5

md5

String

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

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

module

String

升级包所属的模块名。

说明

模块名为default时，物联网平台不下发module参数。

extData

Object

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

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

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

  1. 可选）设备端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

升级包所属的模块名。

说明

不指定则表示请求默认（default）模块的升级包信息。

method

String

请求方法，取值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",
    "url": "https://the_firmware_url",
    "signMethod": "MD5",
    "md5": "f8d85b250d4d787a9f48***",
    "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

升级包信息，其中参数说明如下

version

String

设备升级包的版本信息。

size

Long

升级包文件大小，单位：字节。

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

url

String

升级包在对象存储（OSS）上的存储地址。

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

sign

String

OTA升级包文件的签名。

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

signMethod

String

签名方法。取值：

  • SHA256

  • MD5

md5

String

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

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

module

String

升级包所属的模块名。

说明

模块名为default时，物联网平台不下发module参数。

extData

Object

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

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

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

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

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

  1. 设备端SDK收到物联网平台推送的升级包URL后，调用SDK提供的接口，通过HTTPS协议下载升级包。例如C SDK中提供了接口aiot_download_send_request，具体操作，请参见设备OTA。

说明

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

  1. 升级过程中，设备端向服务端推送升级进度到Topic：/ota/device/progress/${YourProductKey}/${YourDeviceName}。

    1. 消息格式如下：

      1. {
  "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：烧写失败。

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

desc

String

当前步骤的描述信息，长度不超过128个字符。如果发生异常，此字段可承载错误信息。

module

String

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

说明：上报默认（default）模块的OTA升级进度时，可以不上报module参数。

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

重要

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

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

常见下载升级包错误

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

    • image

  • 拒绝访问。URL过期导致。目前，URL有效期为24小时。

    • image

相关文档

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

上一篇：查看升级情况下一篇：子设备 OTA 升级