OTA 固件升级

什么是 OTA？

OTA 的全称是 Over-the-Air Technology，即空中升级技术，也就是我们通常说的远程升级，在物联网硬件中特指对固件或系统的升级，有时也称为 FOTA，即 Firmware OTA。

ThingsCloud OTA 有哪些特性？

• 固件下载提供全球加速，任何位置的设备都可享受高速固件下载。
• 版本号支持格式多样化，云平台提供版本号对比检查，设备端无需任何计算。
• 支持设备拉取升级（Poll）和云端推送升级（Push）两种模式。
• 支持云端批量升级同一设备类型下的多台设备。
• 支持云端定时推送升级任务到指定设备或所有设备。
• 支持整包升级和差分升级的场景。
• 可指定一个或多个待升级设备，适用于灰度升级和局部调试。
• 可指定待升级版本和目标版本，适用于差分升级。
• 提供升级包 MD5 等校验计算。
• 固件下载支持 HTTP/HTTPS 可选。
• 支持设备端多模块固件管理，以及分支版本维护。
• 支持查看设备类型下的版本分布，并进一步查看各版本对应的设备。
• 支持跟踪 OTA 命令的下发和升级结果，提供升级成功率和升级完成度统计。
• 支持在 OTA 版本详情页向符合条件的设备手动下发或重新下发升级命令。

OTA 固件版本管理

ThingsCloud 提供了独立的固件托管服务，您只需创建固件版本，并上传固件包。

创建固件版本

进入 维护 > OTA 版本 > 创建 OTA 版本，填写如下内容：

• 版本名称：给固件版本起一个任意的名称。
• 所属设备类型：选择需要升级的设备所属设备类型。设备类型决定了该 OTA 版本可以匹配哪些设备。
• 版本属性：选择设备用于保存和上报当前版本号的属性。只能选择所属设备类型下的字符串类型属性，创建 OTA 版本后不可修改。
• 版本号：支持通用的版本号命名方式，例如：1.0、1.0.0

• 模块：用于表示该固件属于哪个模块，默认为 main，即硬件的主模块。当硬件中有多个需要升级的模块时，可使用不同的模块名称来创建固件。
• 是否指定待升级设备：如果不指定待升级设备，则默认该固件版本对设备类型下所有设备有效。
  使用该功能，可对新固件限定小范围升级，从而验证升级可靠性。另外，也可以根据业务需要，实现灰度升级。
• 是否指定待升级版本：如果不指定待升级版本，则默认该固件版本对设备类型下所有版本的设备有效。
  当进行差分升级时，需要特别约定固件升级前后的版本，适合使用该功能。
• 上传固件：支持文件格式包括：.bin,.img,.dav,.tar,.gz,.zip,.gzip,.apk,.tar.gz。
• 固件下载地址使用 HTTPS：这里的设置决定了云平台下发给设备的升级命令消息中，固件下载地址是否使用 HTTPS。对于不支持 HTTPS 访问的单片机，可以关闭该选项，使用普通的 HTTP 下载地址。

查看和筛选 OTA 版本

进入 维护 > OTA 版本，可以查看项目中的全部 OTA 版本。版本列表支持：

• 输入版本名称或模块关键词进行搜索
• 按设备类型筛选，并查看每个设备类型下的 OTA 版本数量
• 按启用状态筛选
• 按创建时间从新到旧或从旧到新排序

点击版本名称可以进入 OTA 版本详情页。点击所属设备类型可以进入相应的设备类型详情页。

OTA 版本详情

OTA 版本详情页包含 概览、版本分布、升级统计 和 设置 页面。

概览

概览页面集中展示当前 OTA 版本的主要信息：

• 版本信息：所属设备类型、版本属性、模块、目标版本、待升级设备和待升级版本
• 固件信息：固件包大小、MD5，以及下载地址是否使用 HTTPS
• OTA 升级统计：本次升级涉及的设备数量、下发情况和升级结果
• 设备版本分布：展示设备数量最多的前 5 个版本
• 最新升级设备：展示最近成功升级的 10 台设备

点击 查看更多，可以进入对应的版本分布或升级统计页面。

版本分布

版本分布统计 OTA 所属设备类型下所有有效设备的最新版本，包括每个版本的设备数和占比。设备未上报版本属性时，会归入 未上报版本。

版本分布反映设备类型当前的实时版本情况，不受当前 OTA 版本中“待升级设备”和“待升级版本”的限制。因此，版本分布中的设备总数可能多于本次 OTA 实际涉及的设备数。

当前 OTA 的目标版本会标记为 目标版本。点击某个版本右侧的 查看设备，可以进一步查看该版本下的设备，并支持：

• 按设备名称、Device ID 或设备唯一标识搜索
• 按在线或离线状态筛选
• 按设备列表支持的方式排序
• 查看设备告警状态

OTA 升级统计

OTA 升级统计包含以下 6 项指标：

前 4 项数量可以点击。点击后，页面会切换到 升级统计，并在下方列出对应范围的设备。

例如，有 10 台设备当前符合升级条件，只向其中 2 台下发升级命令，并且这 2 台均升级成功：

• 升级成功率为 2 / 2 = 100%
• 升级完成度为 2 / 10 = 20%

升级成功率用于判断已经执行的升级是否成功，升级完成度用于判断本次 OTA 在全部相关设备中的整体推进程度。

相关设备

升级统计页面下方的相关设备列表，由以下两部分设备合并组成：

• 当前仍符合该 OTA 版本升级条件的设备
• 已经下发过该 OTA 版本升级命令的设备

每台设备只会显示以下一种状态：

• 未下发：当前符合升级条件，但尚未下发升级命令
• 已下发未升级：已经下发升级命令，但尚未确认升级成功
• 已成功升级：设备版本属性已更新为该 OTA 的目标版本

列表支持按设备范围筛选，包括全部相关设备、当前可升级设备、已下发升级设备、未下发设备、已下发未升级设备和已成功升级设备。还可以按设备名称、设备 ID 或设备唯一标识搜索，并按升级下发时间或升级成功时间排序。

列表中的 当前版本 始终取设备版本属性的最新值，因此可能高于当前 OTA 的目标版本。设备必须将版本属性更新为该 OTA 的目标版本，平台才会确认本次升级成功。确认成功后，即使设备以后继续升级到更高版本，本次 OTA 的成功记录也不会改变。

手动下发升级命令

在相关设备列表中，可以直接向当前符合升级条件的设备下发 OTA 命令：

• 下发升级：首次向设备下发当前 OTA 版本
• 重新下发：再次向已下发未升级的设备发送当前 OTA 版本

下发前，平台仍会检查设备类型、版本属性、模块、待升级设备、待升级版本和当前版本。设备不再符合升级条件时，不会下发升级命令。

“已下发”表示平台已经完成命令下发处理，不表示设备已经收到命令或完成升级。可以进入设备详情页，在调试日志中查看已下发的命令消息。

详情页手动下发适合少量设备调试和临时操作。需要定时或批量推送时，仍建议使用 OTA 升级任务。

编辑固件版本

在详情页顶部点击 编辑，可以修改：

• 版本名称
• 待升级设备
• 待升级版本
• 固件下载地址是否使用 HTTPS
• 版本描述

版本属性、模块、目标版本和固件包创建后不可修改。标签可以在 设置 页面单独修改。

设置

设置页面提供以下维护操作：

• 修改版本描述和标签
• 重新统计升级状态
• 启用或停用 OTA 版本
• 删除 OTA 版本

如果个别设备已经成功升级，但没有被正常统计，可以点击 重新统计。平台会在后台重新检查已下发未升级的设备，稍后可以返回概览或升级统计页面，点击 刷新 查看最新状态。

OTA 版本停用后，设备检查升级时不会再匹配该版本。只有停用的 OTA 版本可以删除，删除后不可恢复。

设备上报固件当前版本号

在设备进行 OTA 升级之前，云平台需要知道设备当前固件的版本号，从而为每个设备计算是否需要升级，以及需要升级到哪个新版本。

首先需要在设备类型中创建一个字符串类型的属性，例如 version，用于保存设备当前版本。创建 OTA 版本时选择该属性，事件规则和任务也应选择同一个版本属性。

设备通过 MQTT 接入云平台后，通过简单的属性上报即可更新当前版本号。

下面是一个属性上报的例子，代表版本的属性标识符为 version。实际上您可以使用任意标识符，比如 mcu_version、gps_version。

{
    "version": "1.0.0"
}

通常，设备应该在每次上电开机，并成功连接云平台后，首先上报当前版本。

设备完成固件升级并重新启动后，应再次上报版本属性。平台在版本属性值等于 OTA 目标版本时，将对应设备标记为 已成功升级。

OTA 升级方式

ThingsCloud 云平台支持两种 OTA 升级方式：

• 设备端定期检查新版本
• 云平台推送新版本

这两种升级方式可同时使用，既可实现设备端自动升级，也可在特定场景下由云平台主动推送升级，达到最佳的 OTA 升级体验。

设备端定期检查新版本

由设备端定期向云平台发起检查新版本的请求，云平台回应设备是否存在新版本需要升级。序列图如下：

创建 OTA 事件规则

设备向云平台请求新版本的过程，是借助事件上报消息来实现的。

我们需要创建一个事件上报的规则，来实现 OTA 升级检查。

进入 规则 > 创建规则 ，填写如下内容：

• 规则名称：起一个规则名称，例如：MCU OTA 升级检查。
• 规则类型：选择 事件上报。
• 设备来源类型：选择 设备类型
• 选择来源：选择您需要 OTA 升级的设备所属的设备类型。
• 事件名称：输入 otaCheck，也可以使用其它您喜欢的标识符，只要和随后事件消息中的标识符一致即可。

如下图：

进入下一步，添加操作，选择 OTA 升级检查 ，如下图：

在弹出的设置窗口中，填写如下：

• 版本属性：填写属性上报时，代表版本的属性标识符，这里是 version。
• 模块：填写创建固件版本时对应的模块名称，默认是 main。

事件规则创建完成。

设备上报事件消息

接下来，就可以在设备端通过 MQTT 协议向云平台发送事件上报消息，如下：

{
	"method": "otaCheck",
	"params": {}
}

设备接收命令消息

云平台收到设备上报的事件消息后，会立即在 OTA 固件版本库中查找是否有符合的新版本，如果不存在新版本，则下发如下命令消息：

{
	"method": "otaUpgrade",
	"params": {
		"module": "main",
		"upgrade": false
	}
}

如果存在新版本，则下发包含新版本信息的命令消息，例如：

{
	"method": "otaUpgrade",
	"params": {
		"module": "main",
		"upgrade": true,
		"version": "1.0.1",
		"url": "https://xxx.xxx.com/xxx.bin",
		"md5": "1586515d5f0216eb7d2d28204321edf5",
		"size": 1363713
	}
}

云平台推送新版本

另一种 OTA 升级方式是由云平台主动推送包含新版本固件信息的消息给设备端，设备端收到消息后下载固件并完成升级。

这种方式和前一种方式的区别，主要在于不需要设备端主动上报事件来检查新版本，而是由工作人员手动触发推送。可以在 OTA 版本详情页向单台设备下发，也可以通过任务定时或批量推送。

序列图如下：

通过云平台主动推送新版本给设备，可以使用以下方式：

• 在 OTA 版本详情页的相关设备列表中，向符合条件的设备手动下发
• 创建 OTA 升级推送 任务，对指定设备或设备类型进行批量、定时推送

OTA 升级推送任务会对运行的目标设备进行版本对比检查。如果版本库中存在新版本可升级，则下发命令消息给设备。

创建 OTA 升级推送任务

进入 任务 > 创建任务，填写如下内容：

• 任务名称：起一个任务名称，例如：MCU OTA 升级推送
• 目标类型：选择设备类型
• 选择目标：选择需要 OTA 升级的设备所属的设备类型。
• 任务类型：选择命令下发
• 选择任务：选择 OTA 升级推送
• 定时方式：可选择关闭定时，也可根据需要选择相应的定时策略。

在 OTA 升级推送 的配置窗口中，类似事件规则的填写：

• 版本属性：填写属性上报时，代表版本的属性标识符，这里是 version。
• 模块：填写创建固件版本时对应的模块名称，默认是 main。

任务创建完成。

运行 OTA 升级推送任务

进入项目的 任务 或当前设备类型的 任务，可以看到刚刚创建的任务，点击运行图标，可手动触发运行任务。

这里可以选择对设备类型下所有设备运行升级推送任务，或者指定一个或多个设备运行该任务。在任务详情页的设备列表中，也可以勾选多台设备，批量执行当前任务。

设备端接收命令消息

这里和设备主动请求新版本时的下发命令完全相同，可参考：设备接收命令消息

网关子设备的固件升级

OTA 固件升级功能不仅可用于直连设备（也包括网关本身），还可以用于网关子设备。只需为子设备建立前边提到的相关规则和任务，并为子设备的设备类型创建固件版本信息。

例如，我们为子设备类型创建了事件规则，绑定在子设备的 otaCheck 事件。如下图：

接下来，网关上报子设备的事件，用来检查该子设备是否有新的固件版本可以升级，上报的消息如下：

{
	"device": "DEVICE1",
	"event": {
		"method": "otaCheck",
		"params": {},
		"id": 1000
	}
}

在 MQTT.fx 中模拟，如下图：

如果存在新的固件版本，网关会马上收到云平台下发的 OTA 升级推送命令，如下图：