跳转到内容
ESPHome - 让智能家居更简单2026.7.0

ESP32 平台

此组件包含 ESP32 平台特定的选项。

# Example configuration entry
esp32:
  variant: esp32s3

配置变量

Section titled “配置变量”

  • variant (可选, string)：此设备配置要使用的 ESP32 单片机/芯片。为 esp32、 esp32s2、esp32s3、esp32s31、esp32c2、esp32c3、esp32c5、esp32c6、esp32c61、esp32h2、 esp32h4、esp32h21 或 esp32p4 之一。 这必须与所使用的硬件匹配，否则将烧录失败。

  • board (可选, string)：应使用的 PlatformIO 板 ID。从 此列表中选择合适的开发板（名称旁边的 图标可用于复制板 ID）。这只会影响引脚别名和一些内部设置； 不再推荐使用此设置，应改用 variant。

NOTE

必须指定 board 或 variant 中的至少一个。如果仅指定 variant（推荐做法）， 将使用适合该 variant 的标准 Espressif devkit 开发板配置自动填充 board 配置。两者都可以指定（为了向后兼容），但它们必须定义相同的 variant。

  • engineering_sample (可选, boolean)：仅 ESP32-P4。 如果您的开发板具有工程 样片硅（修订版 < 3.0），请设为 true。当使用 variant: esp32p4 而未指定 board 时， 如果未显式设置此选项，会记录一条警告。默认为 false。

  • flash_size (可选, string)：ESP32 开发板/模块上可用的闪存容量。为 2MB、 4MB、8MB、16MB 或 32MB 之一。默认为 4MB。警告：指定大于开发板上实际可用的大小 会导致 ESP32 无法启动。

  • flash_mode (可选, string)：用于访问闪存芯片的 SPI 模式。为 qio、qout、dio、 dout 或 opi（仅限 octal 闪存芯片）之一。未设置时，由开发板定义（PlatformIO）或 ESP-IDF 的默认值决定。警告：指定闪存芯片不支持的模式会导致 ESP32 无法启动。

  • flash_frequency (可选, string)：用于访问闪存芯片的 SPI 频率，例如 80MHz 或 40MHz。支持的值取决于 variant，并在构建时检查。未设置时，由开发板 定义（PlatformIO）或 ESP-IDF 的默认值决定。警告：指定闪存芯片不支持的频率 会导致 ESP32 无法启动。

  • cpu_frequency (可选, string)：要使用的 CPU 频率。默认为该 variant 支持的最大 频率。允许的值取决于 variant：

    • ESP32、ESP32-S2、ESP32-S3、ESP32-C5：80MHz、160MHz、240MHz
    • ESP32-C2：80MHz、120MHz
    • ESP32-C3：80MHz、160MHz
    • ESP32-C6、ESP32-C61：80MHz、120MHz、160MHz
    • ESP32-H2：16MHz、32MHz、48MHz、64MHz、96MHz
    • ESP32-H4、ESP32-H21：48MHz、64MHz、96MHz
    • ESP32-S31：240MHz、320MHz
    • ESP32-P4：40MHz、360MHz、400MHz（工程样片仅限 360MHz）

    一些 ESP32 模块——通常是商用设备中使用的 OEM/单核变体 （例如某些小米灯具）——即使它们被识别为 ESP32，也仅支持 最高 160MHz。如果您的设备在以默认（最高）频率烧录后 出现挂起、重启或无法启动的情况，请将 cpu_frequency 设置为 160MHz（或 更低）来解决此问题。

  • partitions (可选, filename 或 list)：一个分区表 CSV 文件或要添加的自定义分区列表。 参见分区。

  • framework (可选)：ESPHome 使用的底层框架的选项。参见框架。

  • watchdog_timeout (可选, Time)：应用于 ESP-IDF 任务看门狗的超时。如果某个已订阅的任务在此时间段内未能喂狗，设备 将重启。对于需要更长看门狗窗口的电源管理设备或长时间阻塞性操作很有用。 默认为 5s，有效范围为 5s 到 60s。注意：当配置的超时低于该阈值时，OTA 更新会临时将 看门狗提升到 15s。

  • toolchain (可选, Toolchain)：用于构建固件的工具链。

变体

Section titled “变体”

ESPHome 支持以下 ESP32 变体。使用 variant 配置选项为您的硬件选择正确的一种。

ESP32

Section titled “ESP32”

原始的 ESP32 是 Espressif 的旗舰双核芯片，在 ESPHome 中拥有最成熟、经过最充分测试的支持。 它包含 Wi-Fi、经典蓝牙和 BLE，外加一个内置的以太网 MAC，可通过外部 PHY 实现有线联网。 它没有原生 USB；编程和串行控制台需要外部 USB 转串口芯片。

  • CPU： Xtensa LX6 双核，最高 240 MHz
  • Wi-Fi： 802.11 b/g/n 2.4 GHz
  • Bluetooth： 经典蓝牙 4.2 + BLE 4.2
  • USB： 无（需要外部 USB 转串口）
  • Ethernet： 内置 MAC（需要外部 PHY）
  • GPIO： 34 个可用引脚
  • UART： 3
  • I2C： 2
  • SPI： 2（共 4 个控制器，其中 2 个通用）
  • I2S： 2
  • ADC： 18 个通道
  • DAC： 2 个通道
  • Capacitive touch： 10 个引脚

ESP32-S2

Section titled “ESP32-S2”

ESP32-S2 是单核变体，具有原生 USB OTG 和更多 GPIO 引脚。它不包含任何蓝牙/BLE 支持。

  • CPU： Xtensa LX7 单核，最高 240 MHz
  • Wi-Fi： 802.11 b/g/n 2.4 GHz
  • Bluetooth： 无
  • USB： 原生 USB OTG 主机模式（全速）；CDC/TinyUSB 外设模式。
  • Ethernet： 无内置（支持基于 SPI 的控制器）
  • GPIO： 43 个可用引脚
  • UART： 2
  • I2C： 2
  • SPI： 4
  • I2S： 1
  • ADC： 20 个通道
  • DAC： 2 个通道
  • Capacitive touch： 14 个引脚

ESP32-S3

Section titled “ESP32-S3”

ESP32-S3 是原始 ESP32 的双核升级版，具有 BLE 5.0、原生 USB OTG，以及 对机器学习应用（如 Micro Wake Word）特别有用的 AI 向量指令扩展。它不包含经典蓝牙。

  • CPU： Xtensa LX7 双核，最高 240 MHz
  • Wi-Fi： 802.11 b/g/n 2.4 GHz
  • Bluetooth： BLE 5.0
  • USB： 原生 USB OTG 主机模式（全速）；USB Serial/JTAG 外设模式
  • Ethernet： 无内置（支持基于 SPI 的控制器）
  • GPIO： 45 个可用引脚
  • UART： 3
  • I2C： 2
  • SPI： 4
  • I2S： 2
  • ADC： 20 个通道
  • DAC： 无
  • Capacitive touch： 14 个引脚
  • AI vector instructions： 有

ESP32-C2

Section titled “ESP32-C2”

ESP32-C2 是一款低成本、节省空间的 RISC-V 芯片，外设集合精简，面向简单的 Wi-Fi + BLE 物联网应用。

  • CPU： RISC-V 单核，最高 120 MHz
  • Wi-Fi： 802.11 b/g/n 2.4 GHz
  • Bluetooth： BLE 5.0
  • USB： 无（仅 UART）
  • Ethernet： 无内置（支持基于 SPI 的控制器）
  • GPIO： 15 个可用引脚
  • UART： 2
  • I2C： 1
  • SPI： 2
  • I2S： 无
  • ADC： 5 个通道
  • DAC： 无

ESP32-C3

Section titled “ESP32-C3”

ESP32-C3 是一款单核 RISC-V 芯片，被设计为 ESP8266 的现代低成本替代品。 它以简单的封装提供 Wi-Fi 和 BLE，并内置 USB Serial/JTAG。

  • CPU： RISC-V 单核，最高 160 MHz
  • Wi-Fi： 802.11 b/g/n 2.4 GHz
  • Bluetooth： BLE 5.0
  • USB： USB Serial/JTAG
  • Ethernet： 无内置（支持基于 SPI 的控制器）
  • GPIO： 22 个可用引脚
  • UART： 2
  • I2C： 1
  • SPI： 3
  • I2S： 1
  • ADC： 6 个通道
  • DAC： 无

ESP32-C5

Section titled “ESP32-C5”

ESP32-C5 是一款 RISC-V 芯片，支持双频 Wi-Fi 6（2.4 GHz 和 5 GHz）和 BLE 5.0， 外加一个用于睡眠模式任务的低功耗协处理器。

  • CPU： RISC-V HP 核，最高 240 MHz + LP 核，最高 40 MHz
  • Wi-Fi： 802.11 b/g/n/ax 2.4 GHz + 5 GHz（Wi-Fi 6）
  • Bluetooth： BLE 5.0
  • USB： USB Serial/JTAG
  • Ethernet： 无内置（支持基于 SPI 的控制器）
  • GPIO： 31 个可用引脚
  • UART： 3
  • I2C： 2
  • SPI： 3
  • I2S： 1
  • ADC： 7 个通道
  • DAC： 无

ESP32-C6

Section titled “ESP32-C6”

ESP32-C6 是一款 RISC-V 芯片，具有 Wi-Fi 6（2.4 GHz）、BLE 5.0，以及用于 Thread 和 Zigbee 网状网络的内置 802.15.4 无线电。它还包含一个低功耗协处理器。

  • CPU： RISC-V HP 核最高 160 MHz + LP 核最高 20 MHz
  • Wi-Fi： 802.11 b/g/n/ax 2.4 GHz（Wi-Fi 6）
  • Bluetooth： BLE 5.0
  • 802.15.4： Thread 和 Zigbee
  • USB： USB Serial/JTAG
  • Ethernet： 无内置（支持基于 SPI 的控制器）
  • GPIO： 31 个可用引脚
  • UART： 3
  • I2C： 2
  • SPI： 3
  • I2S： 1
  • ADC： 7 个通道
  • DAC： 无

ESP32-C61

Section titled “ESP32-C61”

ESP32-C61 是 ESP32-C6 的低成本变体，具有 Wi-Fi 6（2.4 GHz）和 BLE 5.4。它不包含 802.15.4 无线电（没有 Thread 或 Zigbee）。

  • CPU： RISC-V 单核，最高 160 MHz
  • Wi-Fi： 802.11 b/g/n/ax 2.4 GHz（Wi-Fi 6）
  • Bluetooth： BLE 5.4
  • 802.15.4： 无
  • USB： USB Serial/JTAG
  • Ethernet： 无内置（支持基于 SPI 的控制器）
  • GPIO： 26 个可用引脚
  • UART： 3
  • I2C： 2
  • SPI： 3
  • I2S： 1
  • ADC： 7 个通道
  • DAC： 无

ESP32-H2

Section titled “ESP32-H2”

ESP32-H2 是一款 RISC-V 芯片，具有 BLE 5.3 和用于 Thread 和 Zigbee 的内置 802.15.4 无线电。 它不包含 Wi-Fi，适用于低功耗网状网络应用。

  • CPU： RISC-V 单核，最高 96 MHz
  • Wi-Fi： 无
  • Bluetooth： BLE 5.3
  • 802.15.4： Thread 和 Zigbee
  • USB： USB Serial/JTAG
  • Ethernet： 无内置（支持基于 SPI 的控制器）
  • GPIO： 26 个可用引脚
  • UART： 2
  • I2C： 2
  • SPI： 2
  • I2S： 无
  • ADC： 5 个通道
  • DAC： 无

ESP32-P4

Section titled “ESP32-P4”

ESP32-P4 是一款面向边缘计算、图像处理以及丰富显示/摄像头接口的高性能双核 RISC-V 芯片。它没有内置 Wi-Fi 或蓝牙——需要通过 ESP-Hosted 使用单独的协处理器芯片实现无线连接。

  • CPU： RISC-V HP 双核 @ 最高 400 MHz + LP 核 @ 最高 40 MHz
  • Wi-Fi： 无（需要通过 ESP-Hosted 使用协处理器）
  • Bluetooth： 无（需要通过 ESP-Hosted 使用协处理器）
  • USB： 原生 USB OTG 主机模式（全速 + 高速）；USB Serial/JTAG 外设模式
  • Ethernet： 内置 MAC（需要外部 PHY）
  • GPIO： 54 个可用引脚
  • UART： 5 全功能 + 1 精简
  • I2C： 3
  • SPI： 4
  • I2S： 3
  • ADC： 7 个通道
  • DAC： 无
  • MIPI DSI/CSI： 有（显示和摄像头接口）

ESP32-S31

Section titled “ESP32-S31”

ESP32-S31 是一款高性能 RISC-V 芯片，具有 Wi-Fi、蓝牙 LE，以及用于 Thread 和 Zigbee 的内置 802.15.4 无线电。它需要 ESP-IDF 6.1 或更高版本。

  • CPU： RISC-V HP 核，最高 320 MHz + LP 核
  • Wi-Fi： 802.11 b/g/n 2.4 GHz
  • Bluetooth： BLE
  • 802.15.4： Thread 和 Zigbee
  • USB： 原生 USB OTG；USB Serial/JTAG 外设模式
  • Ethernet： 内置 MAC（需要外部 PHY）
  • GPIO： 62 个引脚（0–61）
  • UART： 4 全功能 + 1 精简
  • I2C： 2（外加 1 个低功耗）
  • SPI： 3
  • I2S： 有
  • ADC： 2 个单位，8 个通道
  • DAC： 无
  • Touch： 有（v3）
  • LCD： 并行 RGB / LCD_CAM

ESP32-H4

Section titled “ESP32-H4”

ESP32-H4 是一款低功耗 RISC-V 芯片，具有蓝牙 LE 和用于 Thread 和 Zigbee 的内置 802.15.4 无线电。它没有 Wi-Fi。它需要 ESP-IDF 6.1 或更高版本。

  • CPU： RISC-V 单核，最高 96 MHz
  • Wi-Fi： 无
  • Bluetooth： BLE
  • 802.15.4： Thread 和 Zigbee
  • USB： 原生 USB OTG；USB Serial/JTAG 外设模式
  • Ethernet： 无内置（支持基于 SPI 的控制器）
  • GPIO： 40 个引脚（0–39）
  • UART： 2
  • I2C： 2
  • SPI： 3
  • I2S： 有
  • ADC： 1 个单位，5 个通道
  • DAC： 无
  • Touch： 有（v3）

ESP32-H21

Section titled “ESP32-H21”

ESP32-H21 是一款低功耗 RISC-V 芯片，具有蓝牙 LE 和用于 Thread 和 Zigbee 的内置 802.15.4 无线电。它没有 Wi-Fi。它需要 ESP-IDF 6.1 或更高版本。

  • CPU： RISC-V 单核，最高 96 MHz
  • Wi-Fi： 无
  • Bluetooth： BLE
  • 802.15.4： Thread 和 Zigbee
  • USB： USB Serial/JTAG 外设模式（无 USB OTG）
  • Ethernet： 无内置（支持基于 SPI 的控制器）
  • GPIO： 26 个引脚（0–25）
  • UART： 2
  • I2C： 2
  • SPI： 2
  • I2S： 有
  • ADC： 1 个单位，5 个通道
  • DAC： 无
  • Touch： 无

工具链配置

Section titled “工具链配置”

ESPHome 支持多种用于构建固件的工具链。工具链决定固件的编译方式以及使用哪个构建系统。

目前支持的工具链包括：

  • esp-idf（默认）
  • platformio

默认情况下，ESPHome 使用其原生的 ESP-IDF 集成，包括本文档中描述的自动框架安装和环境管理：文档。

使用 PlatformIO 工具链的示例：

esp32:
  toolchain: platformio

您也可以通过 CLI 选择工具链：

Terminal window
esphome --toolchain platformio compile my_device.yaml

如果未指定，则默认使用 esp-idf。 如果同时设置了 esp32.toolchain 和 --toolchain CLI 选项，则以 CLI 选项为准。

框架

Section titled “框架”

ESPHome 为 ESP32 芯片支持两种框架选项：

ESP-IDF 框架

Section titled “ESP-IDF 框架”

ESP-IDF 是 Espressif 的原生开发框架。对于 ESP32-C2、ESP32-C5、ESP32-C6、ESP32-C61、 ESP32-H2 和 ESP32-P4 变体来说是必需的，因为这些变体不受 Arduino 框架支持。在所有可能的 ESP32 芯片上，它都是默认且推荐的。有关从 Arduino 迁移的帮助，请参阅迁移指南。

# Example configuration entry
esp32:
  board: ...
  framework:
    type: esp-idf

Arduino 框架

Section titled “Arduino 框架”

Arduino 框架作为 ESP-IDF 组件集成。这提供了在 ESP-IDF 构建系统内的 Arduino API 兼容性。Arduino 框架可用于 ESP32（经典）、ESP32-C3、ESP32-S2 和 ESP32-S3 变体。

# Example configuration entry
esp32:
  board: ...
  framework:
    type: arduino

配置变量

Section titled “配置变量”

  • type (可选, string)：框架类型，esp-idf 或 arduino 之一。对于所有 ESP32 变体，默认为 esp-idf。

  • version (可选, string)：要使用的基础框架版本号，来自 ESP32 ESP-IDF releases 或 ESP32 Arduino releases。默认为 recommended。 其它值是：

    • dev ：使用最新的提交，请注意这随时可能出问题
    • latest ：使用最新的 release，即使它尚未被推荐。
    • recommended ：使用推荐的框架版本。

  • source (可选, string)：覆盖框架源。可接受的形式取决于当前使用的工具链。

    当选择 PlatformIO 工具链时，这是针对 pioarduino/framework-arduinoespressif32 或 pioarduino/framework-espidf 包的自定义或修补版本的 PlatformIO 包规格。请参阅 PlatformIO 包规格 了解支持的 URL 方案。示例：

    • https://github.com/user/arduino-esp32/releases/download/archive.zip
    • https://github.com/user/esp-idf.git#branch
    • symlink:///path/to/esp-idf

    当选择原生 ESP-IDF 工具链时，该值可以是以下任一：

    • 一个预捆绑的框架归档 URL（.tar.xz、.tar.gz 或 .zip），例如 https://github.com/esphome-libs/esp-idf/releases/download/v5.2.7/esp-idf-v5.2.7.tar.gz
    • 一个 GitHub 仓库，在可选的 branch 或 tag 上以子模块方式克隆：
      • github://owner/repo[@branch-or-tag]
      • https://github.com/owner/repo.git[@branch-or-tag]

  • platform_version (可选, string)：要使用的 pioarduino/espressif32 包版本。对于已知的框架版本， 此值会自动设置。

  • sdkconfig_options (可选, mapping)：要在 ESP-IDF 项目中设置的自定义 sdkconfig 编译器选项。

  • log_level (可选, string)：框架的日志级别，为 ERROR（默认）、NONE、WARN、INFO、 DEBUG 或 VERBOSE 之一。

  • advanced (可选, mapping)：参见下面的高级配置。

  • components (可选, 组件列表)：参见下面的IDF 组件。

高级配置

Section titled “高级配置”

  • assertion_level (可选, enum)：为 ENABLE（默认）、SILENT 或 DISABLE 之一。更改 默认值会减小编译后二进制的大小，但代价是排查问题更困难。更多信息请参阅 Espressif 文档。

  • compiler_optimization (可选, enum)：为 SIZE（默认）、PERF、NONE 或 DEBUG 之一。更改 默认值会增加编译后二进制的大小，但可能提高性能或便于排查问题。更多信息请参阅 Espressif 文档。

  • enable_lwip_assert (可选, boolean)：可设为 false，通过 禁用 LWIP 断言来减小编译后二进制的大小。默认为 true（Espressif 推荐）。更多信息请参阅 Espressif 文档。

  • execute_from_psram (可选, boolean)：仅在 ESP32S3 和 ESP32P4 上可设为 true，以启用从 PSRAM 执行代码。 使用 octal 或 hex PSRAM 时，这可能比从 FLASH 执行更快，并且可以在写入 FLASH 时（例如 在 OTA 更新期间）让显示绘制之类的代码正常执行。默认为 false。

  • ignore_efuse_custom_mac (可选, boolean)：对于烧录的自定义 MAC 地址无效的设备，可设为 true。

  • ignore_efuse_mac_crc (可选, boolean)：对于烧录的 MAC 地址与其 CRC 不一致的设备 （会产生类似 Base MAC address from BLK0 of EFUSE CRC error 的错误）， 可设为 true。仅在使用 esp-idf 框架的原始 ESP32 上有效。

  • minimum_chip_revision (可选, string)：设置固件所需的最低 ESP32 芯片修订版本。 为 0.0、1.0、1.1、2.0、3.0 或 3.1 之一。仅在原始 ESP32 上有效。

    将其设为 3.0 或更高版本，可以通过排除针对旧芯片缺陷的补丁代码来减小闪存大小。对于 PSRAM 用户，它还可以通过将 C 库函数保留在 ROM 中（而非使用 PSRAM 缓存缺陷补丁重新编译它们）来节省大量 IRAM。

    重要： 固件将无法在低于指定修订版本的芯片上启动。如果对带有 较旧芯片的设备进行 OTA 更新，引导加载程序将拒绝新固件并回滚到以前的版本（当 OTA 回滚已启用时，默认情况下其启用）。

    要查找您芯片的修订版本，请检查 ESPHome 启动日志中类似 ESP32 Chip: ESP32 r3.0, 2 core(s) 的行， 或使用 esptool.py chip_id。

  • sram1_as_iram (可选, boolean)：将 SRAM1 内存区域用作额外的 IRAM，提供额外的 40 KB IRAM。 这会回收以前为引导加载程序的 DRAM 保留且应用程序无法使用的内存。 额外的 IRAM 扩大了 XIP（原地执行）的闪存缓存窗口，减少缓存未命中，并改善 所有从闪存运行的代码（WiFi、BLE、API 服务器等）的性能。它还有助于避免 IRAM 溢出 编译错误（section '.iram0.text' will not fit in region 'iram0_0_seg'）。由于此内存从未属于 堆，因此不会减少空闲堆/DRAM。 仅在使用 esp-idf 框架的原始 ESP32 上有效。 默认为 false。

    重要： 这需要 ESP-IDF v5.1 或更高版本的引导加载程序。通过 USB 烧录会自动更新 引导加载程序，但 OTA 更新不会。如果设备有较旧的引导加载程序，启用此选项会导致设备 无法启动。如果您之前使用较新版本的 ESPHome 通过 USB 烧录过设备， 那么引导加载程序已经是兼容的。如果 ESPHome 在启动时检测到兼容的引导加载程序 而此选项尚未启用，它会记录一条建议。

  • enable_idf_experimental_features (可选, boolean)：可设为 true 以启用实验性功能。使用 实验性功能可能导致不稳定或其它问题。

  • loop_task_stack_size (可选, int)：loop 任务栈大小，单位为字节。如果遇到栈溢出 错误（例如代码复杂或递归过深）则增大该值。较大的值会减少可用的堆。有效范围为 8192-32768 字节。默认为 8192 字节。

  • enable_ota_rollback (可选, boolean)：启用 OTA 回滚支持。启用后，如果设备在启动被标记为成功之前崩溃或复位，引导加载程序将 自动回滚到以前的固件。这与 safe_mode 组件配合使用——在 boot_is_good_after 时间（默认 60s）之后，固件被标记为有效。如果设备在此之前崩溃， 它将回滚到以前的可用固件。默认为 true。

    NOTE

    OTA 回滚要求引导加载程序编译时带有回滚支持。现有设备可能需要通过串口重新烧录以更新引导加载程序——OTA 更新不会更新引导加载程序。

  • signed_ota_verification (可选, mapping)：启用 无硬件安全启动的签名应用验证。 配置后，OTA 固件更新将使用加密签名进行验证。这可以保护 设备免遭来自基于网络的攻击的被篡改固件，而无需硬件安全启动（eFuse）。 支持安全启动 V2（RSA-3072 或 ECDSA-V2）和安全启动 V1（ECDSA）签名方案。 包含以下选项：

    添加此块——即使内部没有任何选项——也会将签名验证编译进固件： 设备将拒绝任何未经受信任密钥签名的 OTA 更新。下面的选项只控制 固件如何被签名。

    • signing_key (可选, filename)：PEM 编码的私钥签名密钥路径。提供后，固件 在构建期间自动使用 espsecure 签名。这是最简单的流程——公钥 自动派生并嵌入签名块中。省略时，固件在构建期间不签名； 您必须在烧录前在外部签名，这适用于私钥存储在安全保管库中的 CI/CD 流水线。与 verification_key 互斥。

    • verification_key (可选, filename)：公钥验证密钥路径，仅用于 ecdsa_v1 方案。安全启动 V1 签名不携带公钥，因此当固件在外部签名时， 必须将公钥嵌入构建中以验证更新。密钥为原始二进制格式（.bin）； 使用以下命令从 PEM 私钥提取： espsecure.py extract_public_key --keyfile private.pem public_key.bin。 与 signing_key 互斥。

      NOTE

      安全启动 V2 方案（rsa3072 和 ecdsa256）不使用验证密钥——更新通过 运行中固件自身签名块中携带的公钥进行验证。要使用 V2 方案在外部签名， 省略两个密钥即可；一个空的块就是完整的配置：

      esp32:
        framework:
          advanced:
            # Verify OTA updates against externally-applied rsa3072 signatures
            signed_ota_verification:

    • signing_scheme (可选, string)：签名算法。为 rsa3072、ecdsa256 或 ecdsa_v1 之一。 默认为 rsa3072。并非所有变体都支持所有方案——请参阅下表。

      • rsa3072：RSA-3072（安全启动 V2）。大多数变体的推荐选择。
      • ecdsa256：ECDSA 与 NIST P-256（安全启动 V2）。用于不支持 RSA 的变体。
      • ecdsa_v1：ECDSA 与 NIST P-256（安全启动 V1）。仅适用于原始 ESP32——用于 修订版本低于 3.0 且不支持安全启动 V2 的芯片。
      变体rsa3072ecdsa256ecdsa_v1
      ESP32（rev 3.0+）yesnoyes
      ESP32（rev < 3.0）nonoyes
      ESP32-S2yesnono
      ESP32-S3yesnono
      ESP32-C2noyesno
      ESP32-C3yesnono
      ESP32-C5yesyesno
      ESP32-C6yesyesno
      ESP32-C61noyesno
      ESP32-H2yesyesno
      ESP32-P4yesyesno

      NOTE

      在原始 ESP32 上使用 rsa3072 要求将 minimum_chip_revision 设置为 "3.0" 或更高 （安全启动 V2 RSA 仅在 ESP32 芯片修订版本 3.0+ 上可用）。对于较旧的芯片修订版本，请使用 ecdsa_v1。

    WARNING

    请妥善保管签名密钥！ 如果您丢失了私钥签名密钥，您将无法对任何运行使用该密钥签名的固件的设备进行 OTA 更新。没有签名密钥，您必须通过串口重新烧录设备。

    NOTE

    烧录到设备的第一个固件也必须签名。使用 signing_key 时，这会 自动完成；在外部签名时，请在通过串口烧录之前对镜像签名——运行未签名 固件的设备没有受信任的密钥，无法验证（或接受）任何 OTA 更新。 所有后续的 OTA 更新都将根据运行中固件中的公钥进行验证。

    要生成签名密钥，请使用 ESP-IDF 中的 espsecure.py 工具：

    Terminal window
    # Generate an RSA-3072 signing key (Secure Boot V2 — most variants)
    espsecure.py generate-signing-key --version 2 --scheme rsa3072 secure_boot_signing_key.pem
    

    # Generate an ECDSA signing key (Secure Boot V1 — original ESP32 pre-rev 3.0)
    espsecure.py generate-signing-key --version 1 secure_boot_signing_key.pem
    

    # Extract the public verification key (only needed for ecdsa_v1 external signing)
    espsecure.py extract_public_key --keyfile secure_boot_signing_key.pem secure_boot_verification_key.bin

  • nvs_encryption (可选, mapping)：加密设备的非易失性存储（NVS），ESPHome 可能在其中保存敏感数据，如 Wi-Fi 凭据和 API 加密密钥。这可以让 任何读取设备闪存的人都无法读取这些数据。加密密钥在设备首次启动时 在设备本身上创建，因此您的配置中不存储任何密钥材料。相关背景信息，请参阅 ESP-IDF NVS 加密文档。 包含以下选项：

    • key_id (必选, integer)：设备用来存储其加密密钥的硬件密钥槽（0–5）。 选择一个未被其它任何东西使用的槽位。

    此功能仅在以下具有所需硬件支持的变体上可用：

    • ESP32-S2
    • ESP32-S3
    • ESP32-C3
    • ESP32-C5
    • ESP32-C6
    • ESP32-H2
    • ESP32-P4

    它在原始 ESP32 或 ESP32-C2 上不可用。

    WARNING

    • 加密密钥在设备首次启动时永久写入芯片（是的，我们指永久）， 之后无法更改或移除——即使您擦除和/或重新烧录您的 ESP——因此请仔细选择 key_id。在大多数情况下，这不成问题——只需选择一个密钥槽并一直用它。
    • 打开加密（或稍后关闭）会清除一次之前保存的任何偏好设置，因为旧数据将无法 再被读取。

  • enable_ota_downgrade_protection (可选, boolean)：拒绝固件版本低于设备 当前运行版本的 OTA 更新。版本取自 project 键下的 version，它被嵌入固件镜像中，并 在允许新镜像启动之前在设备上进行比较。默认为 false。

    此选项需要：

    • 一个 project，其 version 为点分数字形式（例如 1.2.3 或 2024.1.0）。版本会按 单个数字进行比较，因此 1.10.0 比 1.9.0 新。烧录相同版本始终允许。
    • 启用 signed_ota_verification。版本从签名镜像内部读取，因此签名 验证就是防止被篡改的更新宣称比其实际包含的版本更高。

    NOTE

    这保护设备上的无线更新路径。直接的串口烧录不进行版本检查，因此您 始终可以通过串口烧录来恢复设备。

LWIP 优化选项（仅限 ESP-IDF）：

以下选项在使用 ESP-IDF 框架时可在 advanced 部分下使用，以优化 LWIP（轻量级 IP）的行为。有些选项提高性能，而另一些则节省闪存：

  • enable_lwip_dhcp_server (可选, boolean)：启用 DHCP 服务器功能。仅在设备将充当 DHCP 服务器时才需要（WiFi AP 模式所必需）。使用 WiFi 组件时，它会根据是否配置了 AP 模式来自动处理 DHCP 服务器的启用/禁用。 未使用 WiFi 时，默认为 false。

  • enable_lwip_mdns_queries (可选, boolean)：在 DNS 解析器中启用 mDNS 查询支持。这允许解析 用于 MQTT 代理和其它服务的本地主机名（例如 broker.local ）。虽然 ESPHome 有自己的 mDNS 应答器 用于通告，解析 mDNS 名称仍需要此选项。默认为 true。

  • enable_lwip_bridge_interface (可选, boolean)：启用网桥接口支持，用于桥接多个网络 接口。默认为 false。

  • enable_lwip_tcpip_core_locking (可选, boolean)：启用 LWIP TCP/IP 内核锁定以获得更好的套接字性能。 这使用带互斥保护的直接函数调用，而不是线程之间的邮箱消息传递。启用此 选项可将套接字操作性能提高 20-200%，但可能降低多线程可伸缩性。默认为 true。

  • enable_lwip_check_thread_safety (可选, boolean)：启用 LWIP 线程安全检查，以检测从多个线程 对 TCP/IP 堆栈的错误使用。这在启用内核锁定时有助发现线程安全问题。默认为 true。

  • disable_libc_locks_in_iram (可选, boolean)：禁止将 libc 锁函数放入 IRAM。通过将这些函数放入 闪存中，可节省约 1.3 KB 的 IRAM。这对 ESPHome 是安全的，因为没有 IRAM 中断服务 例程（在缓存禁用时运行的 ISR）使用 libc 锁 API。默认为 true（禁用 IRAM 放置以节省 RAM）。

VFS（虚拟文件系统）优化选项：

以下选项禁用未使用的 VFS 功能以节省闪存：

  • disable_vfs_support_termios (可选, boolean)：禁用 VFS 对 termios（终端 I/O）函数的支持。ESPHome 不在 ESP32 上使用 termios 函数（它们仅在 Linux/macOS 的主机 UART 驱动程序中使用）。禁用此 选项可节省约 1.8 KB 的闪存。默认为 true（禁用 VFS termios 以节省闪存）。

  • disable_vfs_support_select (可选, boolean)：禁用 VFS 对带文件描述符的 select() 的支持。ESPHome 使用 lwip_select() 进行套接字操作，它独立于 VFS select 支持工作。VFS select 仅对 UART 和 eventfd 文件描述符需要。禁用此选项后，套接字操作继续正常工作。需要 VFS select 的组件（例如 OpenThread）无论此设置如何都会自动启用它。禁用此选项可节省约 2.7 KB 的 闪存。默认为 true（禁用 VFS select 以节省闪存）。

  • disable_vfs_support_dir (可选, boolean)：禁用 VFS 对目录相关函数（opendir、readdir、 mkdir、rmdir 等）的支持。ESPHome 在 ESP32 上不使用目录操作。需要目录支持的组件（例如 未来的存储组件）无论此设置如何都会自动启用它。禁用此选项可节省约 0.5 KB+ 的闪存。默认为 true（禁用 VFS 目录支持以节省闪存）。

FreeRTOS 内存选项：

  • freertos_in_iram (可选, boolean)：将 FreeRTOS 函数保留在 IRAM 中，而不是移动到闪存。默认情况下， 非 ISR FreeRTOS 函数放在闪存中以节省最多 8 KB 的 IRAM。ISR 安全的函数（FromISR 变体）始终 保留在 IRAM 中。在 ESP-IDF 5.5 上使用蓝牙代理进行的测试显示，得益于从闪存的快速 XIP（原地 执行），性能没有差异。蓝牙代理是最占用 IRAM 且对时序最敏感的使用场景之一，这很可能是 Espressif 在 IDF 6.0 中将其设为默认值的原因。这与 ESP-IDF 6.0 中的默认行为一致，在 6.0 中 CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH 被移除，取而代之的是 CONFIG_FREERTOS_IN_IRAM 以恢复旧行为（参见 ESP-IDF 6.0 破坏性更改 和迁移指南）。 仅当您在闪存缓存被禁用时从 ISR 错误调用 FreeRTOS 函数而遇到问题时才设为 true。默认为 false（将 FreeRTOS 函数放入闪存以节省 IRAM）。

  • ringbuf_in_iram (可选, boolean)：将环形缓冲区函数保留在 IRAM 中，而不是移动到闪存。默认情况下， 环形缓冲区函数放在闪存中以节省约 1.5 KB 的 IRAM。环形缓冲区函数通常仅对音频组件每 约 10 ms 调用一次，因此从闪存加载与从 IRAM 加载的开销与实际数据处理相比可忽略不计。 这与 ESP-IDF 6.0 中的默认行为一致（参见迁移指南）。 仅在遇到问题时才设为 true。默认为 false（将环形缓冲区函数放入闪存以节省 IRAM）。

  • heap_in_iram (可选, boolean)：将堆函数（malloc、free、realloc 等）保留在 IRAM 中，而不是移动 到闪存。默认情况下，堆函数放在闪存中以节省约 4-6 KB 的 IRAM。这是安全的，因为堆函数 绝不应从 ISR 中调用，而且 ESPHome 的设计在正常操作期间最大限度地减少了堆变化（分配主要 发生在设置阶段，而不是在热循环中）。仅在您有需要更快堆操作的特定使用场景时才设为 true。 默认为 false（将堆函数放入闪存以节省 IRAM）。

TLS/证书选项：

  • use_full_certificate_bundle (可选, boolean)：使用完整的证书包，而不是常用 CA 包。 默认情况下，ESPHome 使用 CMN（常用 CA）包，其中仅包含市场份额 大于 1% 的证书颁发机构。这涵盖约 99% 的网站，包括 Let’s Encrypt、DigiCert、Google Trust Services、Amazon Trust Services 以及其它主要 CA。CMN 包对大多数使用场景（包括 GitHub （常用于通过 HTTP Request 进行 OTA 更新）、Home Assistant Cloud 和典型的 HTTPS 端点）都足够了。仅在连接到使用不常见证书颁发机构的服务时才设为 true。默认为 false （CMN 包可节省约 51 KB 闪存）。

  • disable_mbedtls_peer_cert (可选, boolean)：禁止在 TLS 握手完成后保留对端证书。 这可为每个 TLS 连接节省约 4 KB 的堆内存，但会阻止在握手后检查对端的证书。 大多数 ESPHome 使用场景不需要握手后访问证书。需要对端证书访问的组件会 自动启用它，无论此设置如何。默认为 true（不保留对端证书以节省堆）。

内置 IDF 组件引入：

  • include_builtin_idf_components (可选, 字符串列表)：要在构建中重新启用的内置 ESP-IDF 组件名称列表。 ESPHome 默认排除某些内置 IDF 组件以减少编译时间。如果您 需要使用一个被排除的内置 IDF 组件（例如在 lambda 中使用需要特定 IDF 库的自定义代码时）， 您可以在此显式包含它。示例：["esp_http_client", "mqtt"]。

    注意：这不同于 components 选项，后者从 ESP 组件注册表添加外部组件。此选项重新启用默认被排除的内置 ESP-IDF 组件。

C 库选项：

  • enable_full_printf (可选, boolean)：启用完整的基于 FILE* 的 printf 支持。默认情况下，ESPHome 用 使用 vsnprintf() + fwrite() 的轻量级存根包装 printf()、vprintf() 和 fprintf()， 从而消除 newlib 的 _vfprintf_r 并节省约 11 KB 的闪存。ESPHome 会在 启动时替换 ESP-IDF 日志处理器，因此这些 libc printf 函数在运行时基本上是死代码。崩溃回溯和 panic 输出 不受影响——它们使用 esp_rom_printf()，这是一个 ROM 函数，不经过 libc。仅在 外部组件需要输出长于 512 字节的完整基于 FILE* 的 fprintf() 时才设为 true。 默认为 false（使用轻量级存根以节省闪存）。

有些选项可以禁用以节省闪存，而又不影响典型的 ESPHome 功能。性能 选项（默认为 true）提高套接字操作性能，但如果您需要更好的 多线程可伸缩性（由于 ESPHome 使用事件循环，这种情况并不常见），可以禁用它们。

  • disable_mbedtls_pkcs7 (可选, boolean)：禁用 mbedTLS 中的 PKCS#7 支持。PKCS#7 用于特定的证书 验证场景，ESPHome 通常不使用。需要 PKCS#7 的组件无论此设置如何都会自动启用它。 禁用此选项可减小代码大小。默认为 true（禁用 PKCS#7 以节省闪存）。

调试与开发选项：

以下选项禁用生产环境 ESPHome 部署中很少需要的调试功能：

  • disable_debug_stubs (可选, boolean)：禁用 OpenOCD 调试存根。它们用于通过 OpenOCD/JTAG 调试器进行片上调试，典型的 ESPHome 使用很少需要。禁用此选项可减小代码大小。默认为 true （禁用调试存根以节省闪存）。

  • disable_ocd_aware (可选, boolean)：禁用 OCD（片上调试器）感知的异常和 panic 处理器。启用时， panic 处理器会检测是否连接了 JTAG 调试器，并暂停而不是复位，从而实现事后调试。 大多数 ESPHome 用户不使用 JTAG 调试。禁用此选项可减小代码大小。默认为 true（禁用 OCD 感知 以节省闪存）。

  • disable_usb_serial_jtag_secondary (可选, boolean)：禁用辅助 USB Serial/JTAG 控制台。这是当 UART0 是主控制台但未连接时 的回退控制台输出。在以 USB Serial/JTAG 作为默认主控制台的芯片 （ESP32-C3、ESP32-C5、ESP32-C6、ESP32-H2、ESP32-P4、ESP32-S3）上，此设置无效果，因为主控制台已经是 USB Serial/JTAG。 像 logger 这样需要 USB Serial/JTAG 的组件无论此设置如何都会自动启用它。默认为 true （禁用辅助控制台以节省资源）。

  • disable_dev_null_vfs (可选, boolean)：禁用 /dev/null VFS 初始化。ESPHome 通常不需要 /dev/null。 禁用此选项可节省少量资源。默认为 true（禁用 /dev/null）。

文件系统选项：

  • disable_fatfs (可选, boolean)：禁用 FAT 文件系统支持。ESPHome 默认不使用 FATFS。需要 FATFS 的组件 （例如 SD 卡组件）无论此设置如何都会自动启用它。禁用此选项可节省 代码大小。默认为 true（禁用 FATFS 以节省闪存）。

外设选项：

  • disable_regi2c_in_iram (可选, boolean)：将模拟 I2C 主控制函数（regi2c）从 IRAM 移动到闪存。 ESP-IDF 在内部使用这些函数来处理模拟外设（ADC、DAC、温度传感器校准）。将 它们移动到闪存可节省 IRAM。这对 ESPHome 是安全的，因为没有 ESPHome IRAM 中断服务 例程调用 ADC 或其它模拟函数。默认为 true（将 regi2c 函数放入闪存以节省 IRAM）。
  • adc_oneshot_in_iram (可选, boolean)：将 ADC oneshot 控制函数放入 IRAM。当在后台闪存操作期间 （WiFi、BLE、Zigbee、Thread、电源管理等由 NVS 写入引起）禁用闪存缓存时， 如果这些函数在闪存中，ADC 读取将会崩溃。使用 ADC 组件时，它会自动启用此选项。 默认为 false（由 ADC 组件自动启用）。

这些默认值旨在为典型的 ESPHome 设备减少闪存和 IRAM 的使用。仅在您有具体的 调试或性能需求证明有必要时才调整它们。

包含高级选项的示例配置：

# Example configuration entry - all defaults shown explicitly
esp32:
  board: esp32dev
  framework:
    type: esp-idf
    advanced:
      # Performance options (enabled by default)
      enable_lwip_tcpip_core_locking: true  # Better socket performance
      enable_lwip_check_thread_safety: true  # Thread safety validation


      # VFS and LWIP memory saving options (enabled by default)
      disable_libc_locks_in_iram: true  # Saves ~1.3 KB IRAM
      disable_vfs_support_termios: true  # Saves ~1.8 KB flash
      disable_vfs_support_select: true  # Saves ~2.7 KB flash (auto-enabled by OpenThread)
      disable_vfs_support_dir: true  # Saves ~0.5 KB+ flash
      enable_lwip_dhcp_server: false  # Only needed for WiFi AP mode
      enable_lwip_mdns_queries: true  # Needed for .local hostname resolution
      enable_lwip_bridge_interface: false  # Only needed for network bridging


      # TLS options (disabled by default to save resources)
      use_full_certificate_bundle: false  # Saves ~51 KB flash
      disable_mbedtls_peer_cert: true  # Saves ~4 KB heap per connection
      disable_mbedtls_pkcs7: true  # Saves code size


      # C library options
      enable_full_printf: false  # Saves ~11 KB flash


      # Debug options (disabled by default for production)
      disable_debug_stubs: true  # Saves code size
      disable_ocd_aware: true  # Saves code size
      disable_usb_serial_jtag_secondary: true  # Saves resources
      disable_dev_null_vfs: true  # Saves resources


      # Filesystem and peripheral options
      disable_fatfs: true  # Saves code size (auto-enabled by SD card components)
      disable_regi2c_in_iram: true  # Saves IRAM
      adc_oneshot_in_iram: false  # Auto-enabled by ADC component


      # ESP32 (original) only options
      # sram1_as_iram: true  # +40 KB IRAM (requires bootloader from ESP-IDF >= 5.1)

用于 JTAG 开发/调试的示例：

# Enable debug features for JTAG debugging
esp32:
  board: esp32dev
  framework:
    type: esp-idf
    advanced:
      disable_debug_stubs: false  # Keep OpenOCD debug stubs
      disable_ocd_aware: false  # Keep OCD-aware panic handlers

Arduino 选择性编译：

使用 Arduino 框架时，ESPHome 使用选择性编译，只构建您的配置实际需要的 Arduino 库。这显著减少了闪存占用、RAM 占用和构建时间。大多数 Arduino 库（WiFi、Network、BLE、Zigbee、Matter、RainMaker 等）默认被禁用，因为 ESPHome 直接使用 ESP-IDF API。

以前，许多 Arduino 库即使 ESPHome 从未调用过它们也会被编译。在大多数 Arduino 配置中，这些库实际上都没有被使用，但它们却使二进制文件膨胀了 50% 以上，并占用了大量 RAM。

需要特定 Arduino 库的组件会自动启用它们。对于库无法被自动检测到的边缘情况（例如使用 Arduino API 的自定义 lambda），您可以使用 libraries 配置选项显式启用库。

# Example: Enabling Arduino libraries for custom lambda code
esphome:
  name: my-device
  libraries:
    - Preferences  # If using Arduino Preferences API in lambda


esp32:
  board: esp32dev
  framework:
    type: arduino

NOTE

如果您已经通过 libraries 配置添加了库，或调用了 cg.add_library()，则无需任何操作。如果您之前在 lambda 中直接使用 Arduino 库 API（例如 Preferences、Wire、SPI）而没有将它们添加到 libraries 配置中，您将需要显式添加它们。

IDF 组件

Section titled “IDF 组件”

components 选项允许您引入 IDF 组件。这些组件随后会被编译进最终的 固件中，并可由 lambda 使用。此选项最常见的用途是引入 ESP 组件注册表中可用的第三方组件。

简单

Section titled “简单”

对于来自 ESP 组件注册表的组件，您可以使用简写语法 owner/component<operator>version。 支持所有 IDF 组件管理器版本运算符 （例如 ^、~、==、>=）：

esp32:
  framework:
    components:
      - espressif/esp_hosted^2.6.1

高级

Section titled “高级”

对于更复杂的配置（自定义 git 仓库、本地路径等），请使用高级语法：

esp32:
  framework:
    components:
      - name: my_custom_component
        source: https://github.com/user/component.git
        ref: main
        path: components/custom

配置变量

Section titled “配置变量”
  • name (必选, string)：组件名称，例如 espressif/esp_hosted。
  • ref (可选, string)：组件注册表版本或 git ref。
  • source (可选, string)：用于该组件的 git 仓库。可用于组件的 自定义或修补版本。
  • path (可选, string)：组件在 git 仓库中的路径；如果未设置 source，则为本地路径。

分区

Section titled “分区”

默认情况下，ESPHome 会根据 flash_size 自动生成分区表。partitions 选项允许您 提供自定义分区表 CSV 文件以完全控制布局，或向自动生成的表中添加额外分区。

esp32:
  partitions: my_partitions.csv

或者，您可以提供一个自定义分区列表，追加到自动生成的表中。app 分区大小会自动 减小以腾出空间。有效的分区类型和子类型在 ESP-IDF 分区表文档中有说明。

esp32:
  partitions:
    - name: my_data
      type: data
      subtype: spiffs
      size: 0x10000

配置变量

Section titled “配置变量”
  • name (必选, string)：分区名称。不能是任何保留名称：nvs、app0、app1、otadata、eeprom、spiffs、phy_init。
  • type (必选, string 或 integer)：分区类型。为 app 或 data 之一，或者是 0x40 到 0xFE 之间的整数自定义类型。
  • subtype (必选, string 或 integer)：分区子类型。对于 app 类型：factory 或 test。对于 data 类型：nvs、nvs_keys、spiffs、coredump、efuse、fat、undefined 或 littlefs。也可以是 0x0 到 0xFE 之间的整数。
  • size (必选, integer)：分区大小，单位为字节。必须是 4KB（0x1000）对齐。

GPIO 引脚编号

Section titled “GPIO 引脚编号”

ESP32 开发板通常使用基于微控制器的内部 GPIO 引脚编号，因此您可能不必 担心引脚别名或编号……太好了！

关于原始 ESP32 上的引脚的一些说明：

  • GPIO0 用于在启动时确定启动模式；请注意，ESP32 变体使用不同的引脚来确定 启动模式。 在启动时不应将 strapping 引脚拉为低电平，以避免在 不希望时进入闪存模式。不过，您仍然可以将 strapping 引脚用作输出引脚。

  • GPIO34 到 GPIO39 ：这些引脚不能用作输出（是的，即使 GPIO 代表”通用 输入/输出”……）。

  • GPIO32 到 GPIO39 ：这些引脚可用于 ADC 来测量电压。

  • GPIO2 ：在 esp32dev 开发板上，此引脚连接到蓝色 LED。它还支持 触摸板二进制传感器（除此之外还有几个其它引脚）。

# Example configuration entry
binary_sensor:
  - platform: gpio
    name: "Pin GPIO23"
    pin: GPIO23

另请参阅

Section titled “另请参阅”