ESP32 平台

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

# 示例配置项
esp32:
  variant: esp32s3

配置变量

• variant (Optional, string): 用于此设备配置的 ESP32 MCU/芯片。esp32、esp32s2、esp32s3、esp32c2、esp32c3、esp32c5、esp32c6、esp32c61、esp32h2 或 esp32p4 之一。 这必须与使用的硬件匹配，否则将无法刷写。

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

NOTE

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

• flash_size (Optional, string): ESP32 开发板/模块上可用的闪存大小。2MB、4MB、8MB、16MB 或 32MB 之一。默认为 4MB。警告：指定的大小超过您开发板上可用的大小将导致 ESP32 无法启动。

• cpu_frequency (Optional, string): 要使用的 CPU 频率。40MHz、80MHz、160MHz、240MHz、360MHz 或 400MHz 之一。默认为 160MHz。并非所有值都适用于所有芯片。

• partitions (Optional, filename): 包含要使用的分区方案的文件的名称（可选择包括路径）。未指定时，分区根据 flash_size 自动生成。

• framework (Optional): ESPHome 使用的基础框架选项。请参阅 框架。

框架

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

ESP-IDF 框架

ESP-IDF 是 Espressif 的原生开发框架。ESP32-C2、ESP32-C5、ESP32-C6、ESP32-C61、ESP32-H2 和 ESP32-P4 变体需要它，因为这些变体不被 Arduino 框架支持。在可能的情况下，它是所有 ESP32 芯片的默认和推荐框架。请参阅 迁移指南 以获取从 Arduino 过渡的帮助。

# 示例配置项
esp32:
  board: ...
  framework:
    type: esp-idf

Arduino 框架

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

# 示例配置项
esp32:
  board: ...
  framework:
    type: arduino

配置变量

• type (Optional, string): 框架类型，esp-idf 或 arduino。所有 ESP32 变体默认为 esp-idf。

• version (Optional, string): 要使用的基础框架版本号，来自 ESP32 ESP-IDF 发布 或 ESP32 Arduino 发布。默认为 recommended。 其他值有：

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

• source (Optional, string): 用于框架的 PlatformIO 包。此变量提供框架类型的 pioarduino/framework-arduinoespressif32 或 pioarduino/framework-espidf 包的自定义或修补版本的 git 仓库或文件存档的 URL。请参阅 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

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

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

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

• advanced (Optional, mapping): 请参阅下面的 高级配置。

• components (Optional, 组件列表): 请参阅下面的 IDF 组件。

高级配置

• assertion_level (Optional, enum): ENABLE（默认）、SILENT 或 DISABLE 之一。从默认值更改将减少编译二进制文件的大小，但会牺牲故障排除的便利性。请参阅 Espressif 文档 了解更多信息。

• compiler_optimization (Optional, enum): SIZE（默认）、PERF、NONE 或 DEBUG 之一。从默认值更改将增加编译二进制文件的大小，但可能会提高性能或允许更容易的故障排除。请参阅 Espressif 文档 了解更多信息。

• enable_lwip_assert (Optional, boolean): 可设置为 false 以通过禁用 LWIP 断言来减少编译二进制文件的大小。默认为 true（如 Espressif 推荐）。请参阅 Espressif 文档 了解更多信息。

• execute_from_psram (Optional, boolean): 仅在 ESP32S3 上可设置为 true 以启用从 PSRAM 执行代码。使用八线 PSRAM 时，这可能比从 FLASH 内存执行更快，并且使诸如显示绘图之类的代码在写入 FLASH（例如在 OTA 更新期间）时能够正常执行。默认为 false。

• ignore_efuse_custom_mac (Optional, boolean): 对于内置自定义 MAC 地址无效的设备，可设置为 true。

• ignore_efuse_mac_crc (Optional, boolean): 对于内置 MAC 地址与该 MAC 地址的内置 CRC 不一致的设备，可设置为 true，导致出现类似 Base MAC address from BLK0 of EFUSE CRC error 的错误。仅在使用 esp-idf 框架的原始 ESP32 上有效。

• minimum_chip_revision (Optional, 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。

• enable_idf_experimental_features (Optional, boolean): 可设置为 true 以启用实验性功能。使用实验性功能可能会导致不稳定或其他问题。

• loop_task_stack_size (Optional, int): 循环任务堆栈大小（字节）。如果遇到堆栈溢出错误（例如，使用复杂代码或深度递归），请增加此值。较高的值会减少可用堆。有效范围为 8192-32768 字节。默认为 8192 字节。

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

NOTE

OTA 回滚需要使用回滚支持编译引导加载程序。现有设备可能需要通过串口重新刷写以更新引导加载程序 - OTA 更新不会更新引导加载程序。

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

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

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

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

• enable_lwip_bridge_interface (Optional, boolean): 启用桥接口支持以桥接多个网络接口。默认为 false。

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

• enable_lwip_check_thread_safety (Optional, boolean): 启用 LWIP 线程安全检查以检测从多个线程错误使用 TCP/IP 堆栈的情况。这有助于在启用核心锁定时捕获线程安全问题。默认为 true。

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

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

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

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

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

FreeRTOS 内存选项：

• freertos_in_iram (Optional, 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 中的默认行为匹配，其中 CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH 被移除，并由 CONFIG_FREERTOS_IN_IRAM 替换以恢复旧行为（请参阅 ESP-IDF 6.0 重大更改 和 迁移指南）。仅在遇到从禁用闪存缓存的 ISR 错误调用 FreeRTOS 函数的代码问题时设置为 true。默认为 false（FreeRTOS 函数在闪存中以节省 IRAM）。

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

• heap_in_iram (Optional, boolean): 将堆函数（malloc、free、realloc 等）保留在 IRAM 中而不是移动到闪存。默认情况下，堆函数被放入闪存以节省约 4-6 KB 的 IRAM。这是安全的，因为堆函数不应该从 ISR 调用，并且 ESPHome 的设计在正常操作期间最小化堆流失（分配主要发生在设置时，而不是热循环中）。仅在需要更快堆操作的特定用例时设置为 true。默认为 false（堆函数在闪存中以节省 IRAM）。

TLS/证书选项：

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

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

内置 IDF 组件包含：

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

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

某些选项可以禁用以节省闪存，而不影响典型的 ESPHome 功能。性能选项（默认为 true）提高套接字操作性能，但如果您需要更好的多线程可扩展性（这很少见，因为 ESPHome 使用事件循环），可以禁用。

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

调试和开发选项：

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

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

• disable_ocd_aware (Optional, boolean): 禁用 OCD（片上调试器）感知的异常和紧急处理程序。启用时，紧急处理程序检测是否连接了 JTAG 调试器并暂停而不是重置，允许事后调试。大多数 ESPHome 用户不使用 JTAG 调试。禁用此选项可节省代码大小。默认为 true（禁用 OCD 感知以节省闪存）。

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

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

文件系统选项：

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

外设选项：

• disable_regi2c_in_iram (Optional, boolean): 将模拟 I2C 主控制函数（regi2c）从 IRAM 移至闪存。这些函数由 ESP-IDF 内部用于模拟外设（ADC、DAC、温度传感器校准）。将它们移至闪存可节省 IRAM。这对 ESPHome 是安全的，因为没有 ESPHome IRAM 中断服务例程调用 ADC 或其他模拟函数。默认为 true（regi2c 函数在闪存中以节省 IRAM）。

这些默认值旨在减少典型 ESPHome 设备的闪存和 IRAM 使用。仅在具有特定的调试或性能要求并有理由更改它们时才调整它们。

带高级选项的示例配置：

# 示例配置项 - 显式显示所有默认值
esp32:
  board: esp32dev
  framework:
    type: esp-idf
    advanced:
      # 性能选项（默认启用）
      enable_lwip_tcpip_core_locking: true  # 更好的套接字性能
      enable_lwip_check_thread_safety: true  # 线程安全验证

      # VFS 和 LWIP 内存节省选项（默认启用）
      disable_libc_locks_in_iram: true  # 节省约 1.3 KB IRAM
      disable_vfs_support_termios: true  # 节省约 1.8 KB 闪存
      disable_vfs_support_select: true  # 节省约 2.7 KB 闪存（OpenThread 自动启用）
      disable_vfs_support_dir: true  # 节省约 0.5 KB+ 闪存
      enable_lwip_dhcp_server: false  # 仅 WiFi AP 模式需要
      enable_lwip_mdns_queries: true  # .local 主机名解析需要
      enable_lwip_bridge_interface: false  # 仅网络桥接需要

      # TLS 选项（默认禁用以节省资源）
      use_full_certificate_bundle: false  # 节省约 51 KB 闪存
      disable_mbedtls_peer_cert: true  # 每个连接节省约 4 KB 堆
      disable_mbedtls_pkcs7: true  # 节省代码大小

      # 调试选项（默认禁用于生产）
      disable_debug_stubs: true  # 节省代码大小
      disable_ocd_aware: true  # 节省代码大小
      disable_usb_serial_jtag_secondary: true  # 节省资源
      disable_dev_null_vfs: true  # 节省资源

      # 文件系统和外设选项
      disable_fatfs: true  # 节省代码大小（SD 卡组件自动启用）
      disable_regi2c_in_iram: true  # 节省 IRAM

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

# 启用 JTAG 调试的调试功能
esp32:
  board: esp32dev
  framework:
    type: esp-idf
    advanced:
      disable_debug_stubs: false  # 保留 OpenOCD 调试存根
      disable_ocd_aware: false  # 保留 OCD 感知紧急处理程序

Arduino 选择性编译：

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

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

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

# 示例：为自定义 lambda 代码启用 Arduino 库
esphome:
  name: my-device
  libraries:
    - Preferences  # 如果在 lambda 中使用 Arduino Preferences API

esp32:
  board: esp32dev
  framework:
    type: arduino

NOTE

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

IDF 组件

components 选项允许您包含 IDF 组件。这些组件随后将被编译到生成的固件中，并可由 lambda 使用。此选项最常见的用途是包含 ESP 组件注册表 中可用的第三方组件。

简单方式

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

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

高级方式

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

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

配置变量

• name (Required, string): 组件名称，例如 espressif/esp_hosted。
• ref (Optional, string): 组件注册表版本或 git 引用。
• source (Optional, string): 用于组件的 git 仓库。这可用于组件的自定义或修补版本。
• path (Optional, string): git 仓库中组件的路径，或如果未设置 source 则为组件的本地路径。

GPIO 引脚编号

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

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

• GPIO0 用于确定启动时的引导模式；请注意 ESP32 变体使用不同的引脚来确定引导模式。 引导引脚在启动时不应被拉低，以避免在不需要时启动到刷写模式。但是，您仍然可以将引导引脚用作输出引脚。

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

• GPIO32 到 GPIO39: 这些引脚可与 Adc 一起使用来测量电压。

• GPIO2: 在 esp32dev 开发板上，此引脚连接到蓝色 LED。它还支持 触摸板二值传感器（以及其他几个引脚）。

# 示例配置项
binary_sensor:
  - platform: gpio
    name: "引脚 GPIO23"
    pin: GPIO23

另见

• ESPHome 核心配置