ESP32 Platform

Edit this page on GitHub

ESP32 Platform

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

# Example configuration entry
esp32:
  variant: esp32s3

Configuration variables

  • variant (Optional, string): The ESP32 mcu/chip to use for this device configuration. One of esp32, esp32s2, esp32s3, esp32c2, esp32c3, esp32c5, esp32c6, esp32h2 or esp32p4. This must match the hardware in use, or it will fail to flash.

  • board (Optional, 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 and some internal settings; This setting is no longer recommended, variant should be used instead.

ℹ️ Note

At least one of board or variant must be specified. If variant alone is specified (the recommended practice), the board configuration will be automatically filled using a standard Espressif devkit board suitable for that variant. Both may be specified (for backwards compatibility) but they must define the same variant.

  • 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.

  • framework (Optional): Options for the underlying framework used by ESPHome. See Framework.

Framework

ESPHome supports two framework options for ESP32 chips:

Arduino Framework

The Arduino framework is integrated as an ESP-IDF component. This provides Arduino API compatibility within the ESP-IDF build system. Arduino framework is available for ESP32 (classic), ESP32-C3, ESP32-S2, and ESP32-S3 variants.

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

ESP-IDF Framework

ESP-IDF is Espressif’s native development framework. It is required for ESP32-C2, ESP32-C5, ESP32-C6, ESP32-H2, and ESP32-P4 variants, as these are not supported by the Arduino framework. It is recommended for all ESP32 chips when possible. See the migration guide for help transitioning from Arduino.

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

Configuration variables

  • type (Optional, string): The framework type, either esp-idf or arduino. Defaults to arduino for ESP32 (classic), ESP32-C3, ESP32-S2, and ESP32-S3. Defaults to esp-idf for ESP32-C2, ESP32-C5, ESP32-C6, ESP32-H2, and ESP32-P4 (Arduino is not supported on these variants)

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

    • dev : Use the latest commit, note this may break at any time
    • latest : Use the latest release, even if it hasn’t been recommended yet.
    • recommended : Use the recommended framework version.

  • 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.

  • log_level (Optional, string): Log level of the framework, one of ERROR (default), NONE, WARN, INFO, DEBUG or VERBOSE.

  • 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.

  • execute_from_psram (Optional, boolean): On ESP32S3 only may be set to true to enable executing code from PSRAM. With octal PSRAM this can be faster than executing from FLASH memory, and enables code such as display drawing to execute normally when writing to FLASH, e.g. during an OTA update. The default is false.

  • 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. 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 optimize LWIP (Lightweight IP) behavior. Some options improve performance while others save flash memory:

  • 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. This allows resolving local hostnames (like broker.local ) for MQTT brokers and other services. While ESPHome has its own mDNS responder for advertising, this option is needed for resolving mDNS names. Defaults to true.

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

  • enable_lwip_tcpip_core_locking (Optional, boolean): Enable LWIP TCP/IP core locking for better socket performance. This uses direct function calls with mutex protection instead of mailbox message passing between threads. Enabling this improves socket operation performance by 20-200% but may reduce multi-threaded scalability. Defaults to true.

  • enable_lwip_check_thread_safety (Optional, boolean): Enable LWIP thread safety checks to detect incorrect usage of the TCP/IP stack from multiple threads. This helps catch thread safety issues when core locking is enabled. Defaults to true.

Some options can be disabled to save flash memory without affecting typical ESPHome functionality. The performance options (defaulting to true ) improve socket operation performance but can be disabled if you need better multi-threaded scalability (which is uncommon since ESPHome uses an event loop).

Example configuration with advanced LWIP options:

# Example configuration entry
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

      # Memory saving options
      enable_lwip_dhcp_server: false  # Disabled by default, only needed for AP mode
      enable_lwip_mdns_queries: false  # Enabled by default, can disable if not using .local hostnames
      enable_lwip_bridge_interface: false  # Disabled by default

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

ESP32 Platform

Edit this page on GitHub