TopStack 文档

主题

OTA 升级 ​

OTA（Over-the-Air Technology）即空中下载技术，基于无线网络对设备固件、软件或驱动进行更新。通过OTA升级，可以对物联网设备更新功能、修复漏洞、优化性能。

使用限制 ​

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

  • 升级包的数量、大小、格式和地域限制。
    • HTTP协议下载：可以包括一个或多个文件。仅支持.bin、.dav、.tar、.gz、.zip、.gzip、.apk、.tar.gz、.tar.xz、.pack格式的文件。
    • MQTT协议下载：仅包含一个文件，且文件大小不超过16 MB。

管理升级包 ​

产品管理 ​

在【设备互联】【OTA升级】页面，左侧显示的是产品列表。

image-20241210131008508

模块管理 ​

OTA模块是同产品下设备的不同可升级模块，例如固件、软件、驱动等。默认（default）模块表示整个设备的固件，支持自定义其他OTA模块。

选中相应的产品后，在模块列表页签，单击添加模块，配置模块信息，单击确认。

参数说明
所属产品选择模块所属产品。
模块名称设置模块名称。模块名称需要在产品下唯一，创建后不可修改。支持英文字母、数字、半角句号（.）、短划线（-）和下划线（_），长度限制为1~64个字符。
模块别名设置模块别名。支持英文字母、数字、半角句号（.）、短划线（-）和下划线（_），长度限制为4~64个字符。
模块描述可描述该模块的用途等信息。描述长度不超过100个字符，一个中文计为一个字符。

升级包管理 ​

在OTA升级页面，选中相应的产品，单击升级包列表页签，单击添加升级包。

配置升级包信息，上传升级包文件，单击确认。

参数描述
升级包类型整包：您上传的升级包文件是完整的升级包文件，会推送整包升级包给设备进行升级。差分：您上传的升级包文件仅包含新版本升级包与之前版本的差异部分，仅推送差异部分至设备，设备进行差分还原，还原为完整升级包。差分升级可有效减少升级对设备资源的占用，和减少下发升级包的流量消耗。
升级包模块选择升级包所属OTA模块。您可以单击添加模块，在弹出的对话框中新增一个模块。
升级包版本号设置该升级包的版本号。版本号支持英文字母、数字、半角句号（.）、短划线（-）和下划线（_），长度限制为1~64个字符。升级包类型选择为整包时，需设置的参数。
待升级版本号输入或选择待升级设备的OTA模块版本号。下拉列表中，会展示当前产品下所有设备的OTA模块版本号，选择一个待升级的版本。升级包类型选择为差分时，需设置的参数。
签名算法支持MD5和SHA256算法。
上传升级包上传升级包文件。最多支持上传20个文件，总文件大小不能超过1,000 MB。文件格式仅支持.bin、.dav、.tar、.gz、.zip、.gzip、.apk、.tar.gz、.tar.xz、.pack。上传多个升级包文件时，需注意：文件名称不能重复，单个文件名称长度不能超过32个字符。物联网平台会校验多个文件的签名是否一致，若文件签名一致，则视其为重复的文件。
升级包描述可描述该升级包的功能等信息。描述长度不超过1024个字符，一个中文计为一个字符。添加升级包成功后，可在升级包详情页面的升级包信息页签，单击编辑，修改升级包描述。

OTA 升级步骤 ​

image-20241210133139947

步骤一：设备上报版本号 ​

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

步骤二：推送升级包信息 ​

  1. 添加升级包：为产品添加OTA模块和升级包。
    • **模块：**由用户自定义，是同产品下设备的不同可升级模块，例如固件、软件、驱动等。默认（default）模块表示整个设备的固件。
    • **整包：**完整的升级文件，可以添加单个或多个升级包。
    • **差分：**仅包含新版本升级包与之前版本的差异部分，设备需要本地进行差分还原，并还原为完整升级包进行升级。差分升级前，设备必须上报OTA模块版本。
  2. 发起升级批次任务：物联网平台向设备下发升级相关信息（升级包URL、版本、大小等）。发起批量升级后，在控制台显示的设备状态是待升级或待确认。当物联网平台接收到设备上报的升级进度时，设备升级正式开始，在控制台显示的设备状态是升级中。

步骤三：设备下载升级包 ​

  1. 设备离线时不能接收OTA服务端推送的升级消息，设备再次上线后，OTA服务端验证该设备是否需要升级。如果需要升级，平台再次推送升级消息给设备，否则不推送消息。
    • 平台推送升级包信息。平台对设备发起OTA升级请求后，设备通过该 MQTT 收到升级信息。
    • 设备主动拉取升级包信息。设备向平台发布 MQTT 消息，平台收到消息并通过 MQTT 推送升级包信息。
    • 平台发给设备的HTTP协议、MQTT协议的下载消息格式参见 TopLink-V3 协议文档。
  2. 设备使用HTTP协议或MQTT协议下载升级包。
  3. 设备上报升级进度。
  4. 设备上报最新版本号。设备升级完成后，建议立即重启设备，设备上线后，立即上报新的版本号。设备上线请求和上报版本请求间隔不能超过2秒。

IMPORTANT

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