空中升级 (Over-the-Air Updates)

ESPHome 支持通过”空中”（OTA）方式远程更新设备。每种更新机制都是基础 ota 组件的一个平台，并拥有自己的配置变量。

在 2024.6.0 版本中，ota 组件从一个独立的组件转变为平台组件。这一更改旨在支持使用多种更新机制，从而提供更大的灵活性。

可用平台：

esphome: 使用 ESPHome 原生协议的默认 OTA 方式（由仪表板和 CLI 使用）
http_request: 从远程 Web 服务器拉取固件更新
web_server: 通过设备的 Web 界面启用固件上传，或从 CLI 通过 esphome upload/esphome run 并配合 --ota-platform web_server 参数（参见 Web Server OTA 页面）
zephyr_mcumgr: 为 nRF52 平台启用固件上传支持

# 示例配置条目
ota:
  - platform: ...

平台

配置变量

on_begin (可选, 自动化): 当 OTA 更新启动时要执行的动作。参见 on_begin。
on_progress (可选, 自动化): 在 OTA 更新进行期间要执行的动作（大约每秒一次）。参见 on_progress。
on_end (可选, 自动化): 在 OTA 更新成功完成之后要执行的动作。参见 on_end。
on_error (可选, 自动化): 在 OTA 更新失败之后要执行的动作。参见 on_error。
on_state_change (可选, 自动化): 当 OTA 更新状态发生变化时要执行的动作。参见 on_state_change。

OTA 自动化

OTA 组件提供了各种自动化，可用于在 OTA 更新过程中提供反馈。在使用这些自动化触发器时，请注意：

OTA 更新在进行期间会阻塞主应用程序循环。您将无法使用那些仅从自身的 loop() 方法更新输出的组件来表示状态变化。换一种说法：如果您试图使用组件 X 来显示 OTA 进度，但更新仅在 OTA 更新完成后才显示，那么组件 X 就不能用于提供 OTA 更新反馈。
您的自动化动作不得消耗大量时间；如果这样做，OTA 更新可能会失败。

`on_begin`

此自动化将在 OTA 更新启动时触发。

ota:
  - platform: ...
    on_begin:
      then:
        - logger.log: "OTA start"

`on_progress`

使用此自动化，可以报告 OTA 更新的进度。它将在 OTA 更新期间反复触发。您可以通过变量 x 从触发器中获取实际的进度百分比（一个介于 0 和 100 之间的值）。

ota:
  - platform: ...
    on_progress:
      then:
        - logger.log:
            format: "OTA progress %0.1f%%"
            args: ["x"]

`on_end`

此自动化将在 OTA 更新成功完成时触发，紧接在设备重启之前。

由于更新已经完成，您可以安全地使用需要一些时间才能完成的（多个）自动化动作。例如，如果您想闪烁一个 LED，在重启之前需要多次暂停/延迟才能让 LED 闪烁几次。此时 OTA 更新不可能失败，因为它已经完成了。

ota:
  - platform: ...
    on_end:
      then:
        - logger.log: "OTA end"

`on_error`

此自动化将在 OTA 更新失败时触发。您可以通过变量 x 获取内部错误代码。

与 on_end 一样，由于 OTA 更新过程已经结束，您可以安全地使用需要一些时间才能完成的自动化。

ota:
  - platform: ...
    on_error:
      then:
        - logger.log:
            format: "OTA update error %d"
            args: ["x"]

`on_state_change`

此自动化将在每次状态变化时触发。您可以通过变量 state 获取实际状态，其中将包含 OTAState 枚举的值之一。这些值为：

ota::OTA_STARTED
ota::OTA_IN_PROGRESS (在更新期间将被反复调用)
ota::OTA_COMPLETED
ota::OTA_ERROR

ota:
  - platform: ...
    on_state_change:
      then:
        - if:
            condition:
              lambda: return state == ota::OTA_STARTED;
            then:
              - logger.log: "OTA start"

安全模式 (Safe Mode)

除了 OTA 更新外，ESPHome 还支持”安全模式”以在更新未按预期工作时帮助恢复。ota 组件会自动启用此功能，但如果需要也可以禁用。详情请参见安全模式。

空中升级 (Over-the-Air Updates)

平台

配置变量

OTA 自动化

on_begin

on_progress

on_end

on_error