ESPHome OTA 更新

ESPHome 的 Over-The-Air (OTA) 平台允许您通过设备的网络接口（Wi-Fi / 以太网 / Thread）远程安装修改后或更新后的固件二进制文件到您的 ESPHome 设备上。

ESPHome 仪表板以及命令行界面（CLI）（通过 esphome run ... ）均使用此平台将固件安装到受支持的设备上。

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

# 示例配置条目
ota:
  - platform: esphome
    password: !secret ota_password

配置变量

password (可选, string): 用于更新时的密码。
allow_partition_access (可选, boolean): 仅在 esp32 上可用。允许更新更多分区类型。用于更新分区表和引导加载程序。默认为 false。

IMPORTANT

始终为 OTA 更新使用强密码且唯一的密码。更多信息请参见安全最佳实践指南。

port (可选, int): OTA 更新使用的端口。默认值：
- 3232 用于 ESP32
- 8266 用于 ESP8266
- 2040 用于 RP2040
- 8892 用于 Beken 芯片
- 8082 用于主机平台
id (可选, ID): 手动指定用于代码生成的 ID。
version (可选, int): 要使用的 OTA 协议版本。版本 2 更稳定。要降级为旧版 ESPHome，应先用 OTA 版本 1 更新设备。默认为 2。
由 Ota 支持的所有自动化。

NOTE

串行上传后，ESP8266 模块在 OTA 更新生效之前必须重置。如果您尝试执行 OTA 更新并收到错误信息 Bad Answer: ERR: ERROR[11]: Invalid bootstrapping，则 ESP 模块/开发板必须断电重启。

更新密码

更改现有密码

由于配置的密码同时用于编译和上传，常规的 esphome run <file> 命令将不起作用。此问题可以通过在 on_boot 触发器中分别执行操作来解决：

esphome:
  on_boot:
    - lambda: |-
        id(my_ota).set_auth_password("New password");

ota:
  - platform: esphome
    id: my_ota
    password: "Old password"

OTA 代码块中的 “id: my_ota” 很重要。它会在 lambda 中被引用。在利用此技巧更改密码后，可以移除 on_boot 触发器，并将旧的密码替换为 ota: 部分中的新密码。

添加密码

如果 OTA 已在不设置密码的情况下启用，只需在现有 ota: 配置块中添加 password: 一行即可。

移除密码

如果您知道密码但想要移除它，请输入空字符串：id(my_ota).set_auth_password(""); 而不是进行更改。
如果您已经忘记了密码并且已激活 Web 服务器：
- 从配置中移除 OTA 密码
- 在本地构建新镜像。
- 通过 web_server OTA 平台上传；可以通过设备的 Web 界面或运行 esphome upload <config.yaml> --ota-platform web_server （参见 Web Server OTA CLI 用法部分）。

更新 ESP32 上的分区表

在 ESP32 上，可以通过 OTA 更新修改分区表。此功能可用于更新无法通过串行刷写且带有旧的 NVS 分区较小的分区表的小的设备。它还可用于将运行 Tasmota 的设备转换为 ESPHome。在更新分区表之前，您需要将选项 allow_partition_access: true 添加到配置中并将其安装到您的设备上。

ota:
  - platform: esphome
    allow_partition_access: true

CAUTION

如果分区表更新过程中断电或 ESP 被重置，存在使设备变砖的风险，需要通过串行刷写来修复。请确保您有稳定的电源。更新通常在运行 esphome upload 命令后不到 15 秒内完成。

IMPORTANT

如果在分区表更新过程中 NVS 分区的位置发生变化，其中存储的数据在更新后将不可用。在这种情况下，如果您曾使用 Captive Portal 或 Improv 来配置 Wi-Fi 凭证，则需要在更新后重新配置它们。

打开 ESPHome 日志以获取潜在错误的详细信息。要执行分区表更新，可以运行以下命令：

esphome upload --partition-table name-of-your-config.yaml

要从 CSV 文件上传自定义分区表，可以运行以下命令。gen_esp32part.py 是 ESP-IDF 的一部分，可以在这里找到。

python3 gen_esp32part.py partitions.csv partitions.bin
esphome upload --partition-table --file partitions.bin name-of-your-config.yaml

CAUTION

当将 Tasmota ESP32 设备转换为 ESPHome 时，必须在首次上传到设备的 ESPHome 固件中添加 allow_partition_access: true。在分区表更新完成之前，常规的 OTA 更新将不起作用。

更新 ESP32 上的引导加载程序

在 ESP32 上，可以通过 OTA 更新引导加载程序。这对于无法通过串行刷写且需要较新引导加载程序的设备很有用，例如启用 OTA 回滚或将 SRAM1 作为 IRAM。在更新引导加载程序之前，您需要将选项 allow_partition_access: true 添加到配置中并将其安装到您的设备上。

ota:
  - platform: esphome
    allow_partition_access: true

CAUTION

如果在引导加载程序更新过程中断电或 ESP 被重置，存在使设备软变砖的风险，需要通过串行刷写来恢复。请确保有稳定的电源，并在失败时准备好通过 USB 重新刷写。

打开 ESPHome 日志以获取潜在错误的详细信息。要执行引导加载程序更新，请运行：

esphome upload --bootloader name-of-your-config.yaml

不指定 --file 时，将使用最近编译的引导加载程序镜像（原生 ESP-IDF 为 build/bootloader/bootloader.bin，PlatformIO 为 .pioenvs/<name>/bootloader.bin）。

要上传自定义引导加载程序二进制文件，请运行：

esphome upload --bootloader --file bootloader.bin name-of-your-config.yaml

ESPHome OTA 更新

配置变量

更新密码

更改现有密码

添加密码

移除密码

更新 ESP32 上的分区表

更新 ESP32 上的引导加载程序

另请参阅