跳到主要内容

OTA 固件升级

ESP RainMaker OTA 服务为节点固件远程升级提供了一个简单的接口。宏观上，用户只需将固件镜像上传到某个安全的 Web 服务器 (HTTPS)，并将其 URL 提供给节点。

为简化流程，ESP RainMaker 还提供了固件镜像托管服务以及 Web 管理面板。

在固件中启用 OTA 升级​

使用一个简单的 ESP RainMaker API 即可启用 OTA 升级功能，该 API 有两个变体。

1. 利用参数进行 OTA 升级

此方法通过 终端用户 推送 OTA 固件升级，十分简单，可以从 RainMaker CLI 触发。

    esp_rmaker_ota_config_t ota_config = {
        .server_cert = ESP_RMAKER_OTA_DEFAULT_SERVER_CERT,
    };
    esp_rmaker_ota_enable(&ota_config, OTA_USING_PARAMS);

具体用法可参考 开关示例。

2. 利用主题进行 OTA 升级

利用主题进行 OTA 升级较为复杂，适用于 管理员用户，可以通过 RainMaker 管理面板 进行操作。

    esp_rmaker_ota_config_t ota_config = {
        ..server_cert = ESP_RMAKER_OTA_DEFAULT_SERVER_CERT,
    };
    esp_rmaker_ota_enable(&ota_config, OTA_USING_TOPICS);

要对开发板进行 OTA 升级，首先需要将此 API 添加到固件中，编译并烧录固件到开发板中，然后通过 RainMaker 应用或 RainMaker CLI 为开发板配网。

有关 OTA API 的详细信息，请参阅 RainMaker OTA 文档。

设置 OTA 升级固件镜像​

按照常规流程编译 OTA 升级固件镜像即可，但需确保：

  • 项目名称与已烧录到节点上的固件名称相同。
  • 固件版本与节点已有的版本不同（可查看示例项目 CMakeLists.txt 文件中的 set(PROJECT_VER "1.0")）。

如未满足上述条件，将导致 OTA 升级失败。如需跳过上述条件判断，可设置以下配置选项：

CONFIG_ESP_RMAKER_SKIP_VERSION_CHECK=y
CONFIG_ESP_RMAKER_SKIP_PROJECT_NAME_CHECK=y

升级固件​

利用参数进行 OTA 升级​

利用参数进行 OTA 升级时，需要使用 RainMaker CLI 来升级固件。请参照 CLI 前置设置步骤 完成设置，随后按照以下步骤操作：

$ cd /path/to/esp-rainmaker/cli
$ ./rainmaker.py login # 使用在手机应用程序中设置节点时使用的登录凭证
$ ./rainmaker.py getnodes # 验证用户是否能看到要升级的节点
$ ./rainmaker.py otaupgrade <node_id> <path_to_ota_fw_image>

固件升级开始后，进度将打印如下：

$ ./rainmaker.py otaupgrade 7CDFA1XXXXXX ../examples/switch/switch-2.0.bin
Uploading OTA Firmware Image...
Checking esp.service.ota in node config...
Setting the OTA URL parameter...
OTA Upgrade Started. This may take time.
Getting OTA Status...
[19:49:50] in-progress : Downloading Firmware Image
[19:49:58] in-progress : Downloading Firmware Image
[19:50:07] in-progress : Downloading Firmware Image
[19:50:16] in-progress : Downloading Firmware Image
[19:50:25] in-progress : Downloading Firmware Image
[19:50:34] in-progress : Downloading Firmware Image
[19:50:43] success : OTA Upgrade finished successfully

升级原理​

利用参数进行 OTA 升级主要基于 RainMaker 服务 的概念。调用 esp_rmaker_ota_enable(&ota_config, OTA_USING_PARAMS)，可将 OTA 服务 添加到节点配置中。OTA 服务有三个参数：

  • url（esp.param.ota_url）
  • status（esp.param.ota_status）
  • info（esp.param.ota_info）

使用 CLI 的 OTA 升级命令时，将触发以下操作：

  • CLI 从提供的路径中读取升级固件镜像，并将其上传到 RainMaker 云服务。
  • 返回一个预签名的 URL。请注意，此 URL 仅在有限时间内有效（目前为 1 天，将来可能会更新）。
  • 使用此预签名 URL 的值来设置 url 参数。
  • 节点开始下载固件镜像，并在进度中报告状态和其他信息。
  • CLI 使用 getparams 不断查询并显示状态等信息。
  • 当状态更改为 failed 或 success 时，OTA 升级结束。
  • 如果状态报告为 success，节点将在 10 秒内启动新固件。
  • 此后，三个参数都将被重置为空白默认值。

利用主题进行 OTA 升级​

利用主题进行 OTA 升级要求对节点有管理员访问权限。请参考 管理员用户章节，获取管理员访问权限，随后参考 ESP RainMaker 管理面板 并按照以下步骤操作：

上传 OTA 升级固件镜像​

  • 打开管理面板侧边栏的 Firmware Images 标签页，点击 Add Image。
  • 在弹出的窗口中填写详细信息。可跳过固件版本和型号（与项目名称相同），这两个参数将直接从二进制文件中读取。
  • 选择并添加刚刚编译好的升级固件镜像。
  • 该镜像会显示在 Firmware Images 镜像列表中。

启动 OTA 升级​

  • 在 OTA 镜像列表中查看将用于 OTA 升级的 OTA 固件镜像。
  • 在该镜像中点击 Start OTA。
  • 为 OTA 任务输入名称，并选择要升级的节点。

在测试时，请勾选 Force Push 选项，以便将 OTA 任务信息立即发送到节点。否则，节点将根据预定义的 OTA 升级策略获取 OTA URL，例如在启动时查看或定期检查，导致实际升级过程延迟。可以通过选项 CONFIG_ESP_RMAKER_OTA_AUTOFETCH 和 CONFIG_ESP_RMAKER_OTA_AUTOFETCH_PERIOD 控制此功能。

监控 OTA 任务​

  • 一旦启动 OTA 并升级成功，将直接获取 Go to job details 链接，通过该链接可查看 OTA 任务的状态。此外，也可以在管理面板侧边栏中的 OTA Job 页面查看 OTA 任务状态。
  • OTA Job 页面展示了 OTA 任务的整体情况以及各个节点的状态。
  • 升级过程中可以取消任务，但已获取 URL 的节点将继续进行升级。

升级原理​

这一方法利用主题进行 OTA 升级。

  • 节点连接到 MQTT 代理时会订阅主题 node/<node_id>/otaurl。
  • 每次在管理面板上通过 Force Push 选项触发 OTA 时，云服务会将此信息发送到 node/<node_id>/otaurl 上的节点。
{
    "url": "<ota_image_url>",
    "ota_job_id": "<ota_job_id>",
    "file_size": <num_bytes>
}
  • 节点随即从接收到的 <ota_image_url> URL 开始下载镜像，并在 node/<node_id>/otastatus 上发布进度，格式如下：
{
    "ota_job_id": "<ota_job_id>",
    "status": "<in-progress/success/fail>",
    "additional_info": "<additional_info>"
}
  • 当所有节点报告 success 或 failed 时，OTA 任务结束。

配置自动获取​

大多数情况下，我们希望将 OTA 升级分阶段地发送到节点，以避免同时向服务器发送过多的镜像下载请求。此外，当云服务发布到 node/<node_id>/otaurl 时，节点可能处于离线状态，因此需要其他方法来重新获取升级信息。

设置 CONFIG_ESP_RMAKER_OTA_AUTOFETCH=y 后，节点会根据 CONFIG_ESP_RMAKER_OTA_AUTOFETCH_PERIOD 指定的间隔时间来定期获取 OTA 升级信息。这一过程中，以下数据会被发布至 node/<node_id>/otafetch：

{
    “node_id": “<node_id>",
    “fw_version": “<fw_version>"
}

发现任何待处理的节点 OTA 任务时，云服务会根据以上数据内容将其发布到 node/<node_id>/otaurl，以触发该 OTA 任务。

服务器验证​

OTA 配置中需接收服务器证书 server_cert，用于验证获取 OTA 固件镜像的服务器，并防止 DNS 欺骗攻击。默认证书 ESP_RMAKER_OTA_DEFAULT_SERVER_CERT 用于验证 ESP RainMaker Firmware Image 托管服务器。如需使用自己的服务器（仅对 OTA_USING_PARAMS 有效），可以将相应的 server.crt 文件复制到 main/ 文件夹中，并在 main/CMakeLists.txt 中包含以下命令行，将其嵌入到二进制文件中：

target_add_binary_data(${COMPONENT_TARGET} "server.crt" TEXT)

使用以下代码可对其进行访问:

extern const uint8_t ota_server_cert[] asm("_binary_server_crt_start");

{
    ...
    esp_rmaker_ota_config_t ota_config = {
        .server_cert = (char *)ota_server_cert,
    };
    esp_rmaker_ota_enable(&ota_config, OTA_USING_PARAMS);
    ...

如果需要跳过服务器验证，或需要使用 HTTP 服务器（不推荐，一般使用 HTTPS），请在 sdkconfig 中设置 CONFIG_OTA_ALLOW_HTTP=y。