ESP32 Platform

This component contains platform-specific options for the ESP32 platform.

# Example configuration entry
esp32:
  board: esp32dev

Configuration variables:

  • board (Required, string): The PlatformIO board ID that should be used. Choose the appropriate board from this list (the icon next to the name can be used to copy the board ID). This only affects pin aliases, flash size and some internal settings; if unsure or you cannot find your exact board, using a generic board (from Espressif) such as esp32dev almost always works just fine.

  • flash_size (Optional, string): The amount of flash memory available on the ESP32 board/module. One of 2MB, 4MB, 8MB, 16MB or 32MB. Defaults to 4MB. Warning: specifying a size larger than that available on your board will cause the ESP32 to fail to boot.

  • cpu_frequency (Optional, string): The CPU frequency to use. One of 40MHz, 80MHz, 160MHz, 240MHz, 360MHz or 400MHz. Defaults to 160MHz. Not all values are available for all chips.

  • partitions (Optional, filename): The name of (optionally including the path to) the file containing the partitioning scheme to be used. When not specified, partitions are automatically generated based on flash_size.

  • variant (Optional, string): The variant of the ESP32 that is used on this board. One of esp32, esp32s2, esp32s3, esp32c2, esp32c3, esp32c5, esp32c6, esp32h2 and esp32p4. Defaults to the variant that is detected from the board; if a board that’s unknown to ESPHome is used, this option is mandatory.

  • framework (Optional): Options for the underlying framework used by ESPHome. See Arduino framework and ESP-IDF framework.

Arduino framework

This is the default framework for ESP32 chips at the moment.

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

Configuration variables:

ESP-IDF framework

This is an alternative base framework for ESP32 chips; it is recommended for variants of the ESP32 like ESP32S2, ESP32S3, ESP32P4 and single-core ESP32 chips.

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

Configuration variables:

  • version (Optional, string): The base framework version number to use, from ESP32 ESP-IDF releases. Defaults to recommended. Additional values are:

  • source (Optional, string): The PlatformIO package or repository to use for the framework. This can be used to use a custom or patched version of the framework.

  • platform_version (Optional, string): The version of the pioarduino/espressif32 package to use.

  • sdkconfig_options (Optional, mapping): Custom sdkconfig compiler options to set in the ESP-IDF project.

  • advanced (Optional, mapping): See Advanced Configuration below.

  • components (Optional, list of components): See IDF Components below.

Advanced Configuration

  • assertion_level (Optional, enum): One of ENABLE (default), SILENT or DISABLE. Changing away from the default will reduce the size of the compiled binary, albeit at the expense of ease of troubleshooting. See Espressif’s documentation for more information.

  • compiler_optimization (Optional, enum): One of SIZE (default), PERF, NONE or DEBUG. Changing away from the default will increase the size of the compiled binary but may increase performance or allow for easier troubleshooting. See Espressif’s documentation for more information.

  • enable_lwip_assert (Optional, boolean): Can be set to false to reduce the size of the compiled binary by disabling LWIP assertions. Defaults to true (as recommended by Espressif). See Espressif’s documentation for more information.

  • ignore_efuse_custom_mac (Optional, boolean): Can be set to true for devices on which the burned-in custom MAC address is not valid.

  • ignore_efuse_mac_crc (Optional, boolean): Can be set to true for devices on which the burned-in MAC address is not consistent with the burned-in CRC for that MAC address, resulting in an error like Base MAC address from BLK0 of EFUSE CRC error. Valid only on original ESP32 with esp-idf framework.

  • enable_idf_experimental_features (Optional, boolean): Can be set to true to enable experimental features in the ESP-IDF framework. Not valid for the Arduino framework. Use of experimental features may cause instability or other issues.

LWIP Optimization Options (ESP-IDF only):

The following options are available under the advanced section when using the ESP-IDF framework to disable unused LWIP (Lightweight IP) features and save flash memory (approximately 4KB):

  • enable_lwip_dhcp_server (Optional, boolean): Enable DHCP server functionality. Only needed if the device will act as a DHCP server (necessary for WiFi AP mode). When the WiFi component is used, it automatically handles enabling/disabling the DHCP server based on whether AP mode is configured. When WiFi is not used, defaults to false.

  • enable_lwip_mdns_queries (Optional, boolean): Enable mDNS query support in the DNS resolver. ESPHome uses its own mDNS implementation, so this is rarely needed. Defaults to true.

  • enable_lwip_bridge_interface (Optional, boolean): Enable bridge interface support for bridging multiple network interfaces. Defaults to false.

These optimizations are applied automatically and save flash memory without affecting typical ESPHome functionality. The features can be enabled if needed by setting the corresponding option to true.

IDF Components

The components option allows you to include IDF components. These components will then be compiled into the resulting firmware and may be used by lambdas. The most common usage of this option is to include third-party components that are available in the ESP Component Registry. They can be added by listing their name under this option. It is also possible to use specific versions, or to fetch components from a file or git repository.

  • name (Required, string): Name of the component e.g. espressif/esp_hosted.

  • ref (Optional, string): Component registry version or a git ref.

  • source (Optional, string): The git repository to use for the component. This can be used for a custom or patched version of the component.

  • path (Optional, string): The path of the component in the git repository or a local path to the component if source is not set.

GPIO Pin Numbering

The ESP32 boards often use the internal GPIO pin numbering based on the microcontroller, so you likely don’t have to worry about pin alias names or numbering…yay!

Some notes about the pins on the original ESP32:

  • GPIO0 is used to determine the boot mode on startup; note that ESP32 variants use different pins to determine the boot mode. Bootstrapping pin(s) should not be pulled LOW on startup to avoid booting into flash mode when it’s not desired. You can, however, still use the strapping pins as output pins.

  • GPIO34 to GPIO39: These pins cannot be used as outputs (yes, even though GPIO stands for “general purpose input/output”…).

  • GPIO32 to GPIO39: These pins can be used with the Analog To Digital Sensor to measure voltages.

  • GPIO2: On the esp32dev board, this pin is connected to the blue LED. It also supports the touch pad binary sensor (in addition to a few other pins).

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

See Also