Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/esphome/esphome.io/llms.txt

Use this file to discover all available pages before exploring further.

The esp32: component provides all platform-specific configuration for the large family of ESP32 microcontrollers supported by ESPHome. Espressif’s ESP32 line spans dual-core Xtensa chips, RISC-V single-core variants, high-performance compute chips, and everything in between — each with different peripheral sets, CPU speeds, and wireless capabilities. The most important settings are variant (which chip you have) and framework (the underlying build system, ESP-IDF or Arduino). ESP-IDF is the default and recommended choice for all variants.

​
Minimal Example

esp32:
  variant: esp32s3

# Classic ESP32 with explicit framework
esp32:
  board: esp32dev
  framework:
    type: esp-idf

​
Configuration Variables

​
variant
string
Selects the ESP32 chip/MCU variant. Must match the physical hardware. When specified without a board, ESPHome automatically selects a standard Espressif devkit board for that variant.Options: esp32, esp32s2, esp32s3, esp32c2, esp32c3, esp32c5, esp32c6, esp32c61, esp32h2, esp32p4
​
board
string
PlatformIO board ID. Affects pin aliases and some internal defaults. No longer recommended — use variant instead. At least one of board or variant must be specified; if both are given, they must agree on the chip variant.
​
flash_size
string
Flash memory size of the module. Defaults to 4MB. Specifying a size larger than what is physically present will cause boot failures.Options: 2MB, 4MB, 8MB, 16MB, 32MB
​
cpu_frequency
string
CPU frequency. Defaults to the maximum for the variant. If a device resets or hangs at the default frequency, try reducing (some OEM single-core ESP32 modules are only stable at 160MHz).
  • ESP32/S2/S3/C5: 80MHz, 160MHz, 240MHz
  • ESP32-C2: 80MHz, 120MHz
  • ESP32-C3: 80MHz, 160MHz
  • ESP32-C6/C61: 80MHz, 120MHz, 160MHz
  • ESP32-H2: 16MHz–96MHz
  • ESP32-P4: 40MHz, 360MHz, 400MHz
​
partitions
filename or list
Custom partition table. Provide a path to a CSV file for full control, or a list of partition definitions to append to the auto-generated table. See Partitions below.
​
framework
mapping
Framework configuration. See Framework below.
​
watchdog_timeout
Time
ESP-IDF task watchdog timeout. If a subscribed task fails to feed the watchdog within this period, the device reboots. Range: 5s–60s. Defaults to 5s. OTA updates temporarily raise this to 15s when needed.
​
toolchain
string
Build toolchain. Options: platformio (default), esp-idf. Can also be set via the --toolchain CLI flag (which takes precedence over this setting).
​
engineering_sample
boolean
ESP32-P4 only. Set to true for engineering sample silicon (chip revision < 3.0). Defaults to false.

​
Framework

ESPHome supports two frameworks for ESP32 compilation: Espressif’s native development framework. Required for ESP32-C2, C5, C6, C61, H2, and P4. Default for all variants. 
esp32:
  variant: esp32s3
  framework:
    type: esp-idf
    version: recommended

​
Arduino

Arduino API compatibility layer built on top of ESP-IDF. Available for classic ESP32, C3, S2, and S3. 
esp32:
  board: esp32dev
  framework:
    type: arduino
    version: recommended

​
Framework Configuration Variables

​
type
string
Framework type: esp-idf (default) or arduino.
​
version
string
Framework version. recommended (default), latest (newest release), or dev (latest commit). Or specify an exact release tag (e.g. 5.3.1).
​
source
string
Custom PlatformIO package URL or git repository for a patched framework version. Supports the same URL schemes as PlatformIO’s pkg install (e.g. https://github.com/user/arduino-esp32.git#branch, symlink:///path/to/esp-idf).
​
platform_version
string
Version of the pioarduino/espressif32 PlatformIO platform package. For known framework versions this is set automatically and does not need to be specified.
​
sdkconfig_options
mapping
ESP-IDF only. Custom sdkconfig options injected into the build. For advanced SDK tuning.
​
log_level
string
Framework log level (separate from ESPHome’s logger). One of NONE, ERROR (default), WARN, INFO, DEBUG, VERBOSE.
​
components
list
IDF components to add from the ESP Component Registry. Use shorthand owner/component@version or advanced mapping with name, source, ref, and path.
​
advanced
mapping
Fine-grained ESP-IDF optimization flags for IRAM/flash usage, TLS, FreeRTOS, LWIP, and debug features. See Advanced Configuration below.

​
Partitions

ESPHome auto-generates a partition table based on flash_size. Use partitions to customize: 
esp32:
  partitions: my_partitions.csv  # Full custom table

# Or append partitions to the auto-generated table:
esp32:
  partitions:
    - name: my_data
      type: data
      subtype: spiffs
      size: 0x10000
​
name
string
required
Partition name. Cannot be one of the reserved names: nvs, app0, app1, otadata, eeprom, spiffs, phy_init.
​
type
string or int
required
Partition type: app, data, or a custom integer (0x40–0xFE).
​
subtype
string or int
required
Partition subtype. For data: nvs, nvs_keys, spiffs, coredump, efuse, fat, littlefs. For app: factory, test.
​
size
int
required
Size in bytes, 4 KB (0x1000) aligned.

​
ESP32 Variant Comparison

VariantCoreMax MHzWi-FiBluetoothUSBNotable Features
ESP32Xtensa LX6 ×22402.4 GHzBT + BLE 4.2No (external)Built-in Ethernet MAC
ESP32-S2Xtensa LX7 ×12402.4 GHzNoneUSB OTG FS43 GPIOs, 2 DACs
ESP32-S3Xtensa LX7 ×22402.4 GHzBLE 5.0USB OTG FSAI vector, Micro Wake Word
ESP32-C2RISC-V ×11202.4 GHzBLE 5.0NoUltra-low-cost
ESP32-C3RISC-V ×11602.4 GHzBLE 5.0USB Serial/JTAGESP8266 replacement
ESP32-C5RISC-V ×1240Dual-band (Wi-Fi 6)BLE 5.0USB Serial/JTAG5 GHz Wi-Fi support
ESP32-C6RISC-V ×11602.4 GHz (Wi-Fi 6)BLE 5.0USB Serial/JTAG802.15.4 (Thread/Zigbee)
ESP32-H2RISC-V ×196NoneBLE 5.3USB Serial/JTAGThread/Zigbee, no Wi-Fi
ESP32-P4RISC-V ×2400None (co-proc)None (co-proc)USB OTG HSEdge compute, MIPI DSI/CSI

​
Advanced Configuration

esp32:
  board: esp32dev
  framework:
    type: esp-idf
    advanced:
      # 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
      disable_vfs_support_dir: true      # Saves ~0.5 KB flash
      disable_mbedtls_peer_cert: true    # Saves ~4 KB heap/connection
      use_full_certificate_bundle: false # Saves ~51 KB flash
      enable_ota_rollback: true          # Auto-rollback bad OTA

​
GPIO Notes (Classic ESP32)

  • GPIO34–GPIO39: Input only — cannot be used as outputs.
  • GPIO32–GPIO39: ADC-capable.
  • GPIO0: Strapping pin — must be HIGH at boot to avoid flash download mode.
  • GPIO2: Connected to the blue LED on esp32dev boards.
binary_sensor:
  - platform: gpio
    name: "Motion Sensor"
    pin: GPIO23
At least one of board or variant must be specified. Using variant alone (without board) is the recommended approach for new configurations.
Specifying a flash_size larger than the physical flash on your module will cause the ESP32 to fail to boot. Check your module’s datasheet before changing this value.
For devices that hang or reset unexpectedly after flashing, try reducing cpu_frequency to 160MHz. Some OEM single-core ESP32 modules shipped in commercial products are only rated for 160 MHz despite being identified as standard dual-core ESP32.

Build docs developers (and LLMs) love

Get started for freeTalk to us