ESP32-DevKitC

Board Overview

ESP32-DevKitC

Name:

esp32_devkitc

Vendor:

Espressif Systems

Status:

Maintained

Architecture:

xtensa

SoC:

esp32

Browse board sources

Overview

ESP32 is a series of low cost, low power system on a chip microcontrollers with integrated Wi-Fi & dual-mode Bluetooth. The ESP32 series employs a Tensilica Xtensa LX6 microprocessor in both dual-core and single-core variations. ESP32 is created and developed by Espressif Systems, a Shanghai-based Chinese company, and is manufactured by TSMC using their 40nm process. For more information, check ESP32-DevKitC [6].

Hardware

ESP32 Features

• Dual core Xtensa microprocessor (LX6), running at 160 or 240MHz

• 520KB of SRAM

• 802.11b/g/n/e/i

• Bluetooth v4.2 BR/EDR and BLE

• Various peripherals:

  • 12-bit ADC with up to 18 channels

  • 2x 8-bit DACs

  • 10x touch sensors

  • 4x SPI

  • 2x I2S

  • 2x I2C

  • 3x UART

  • SD/SDIO/MMC host

  • Slave (SDIO/SPI)

  • Ethernet MAC

  • CAN bus 2.0

  • IR (RX/TX)

  • Motor PWM

  • LED PWM with up to 16 channels

  • Hall effect sensor

  • Temperature sensor

• Cryptographic hardware acceleration (RNG, ECC, RSA, SHA-2, AES)

• 5uA deep sleep current

Asymmetric Multiprocessing (AMP)

Boards featuring the ESP32 and ESP32-S3 SoC allows 2 different applications to be executed. Due to its dual-core architecture, each core can be enabled to execute customized tasks in stand-alone mode and/or exchanging data over OpenAMP framework. See Inter-Processor Communication (IPC) folder as code reference.

Note

** AMP and serial output support **

In the current Zephyr ESP32 implementation, access to Zephyr-managed serial drivers (such as printk(), logging, or the console UART) is not yet implemented for applications running on the APPCPU. As a result, serial output APIs provided by Zephyr are only available on the PROCPU.

As a mitigation, applications running on the APPCPU may use ESP32 ROM functions such as ets_printf() to emit diagnostic or debug output.

For more information, check the ESP32 Datasheet [1] or the ESP32 Technical Reference Manual [2].

Supported Features

The esp32_devkitc board supports the hardware features listed below.

on-chip / on-board

Feature integrated in the SoC / present on the board.

2 / 2

Number of instances that are enabled / disabled.
Click on the label to see the first instance of this feature in the board/SoC DTS files.

vnd,foo

Compatible string for the Devicetree binding matching the feature.
Click on the link to view the binding documentation.

esp32_devkitc/esp32/appcpu target

On-target memory for this board target: 128 KiB of RAM, 4 MiB of Flash.

Type	Location	Description	Compatible
CPU	on-chip	Espressif Xtensa LX6 CPU2	espressif,xtensa-lx6
ADC	on-chip	ESP32 ADC2	espressif,esp32-adc
Bluetooth	on-chip	Bluetooth HCI for Espressif ESP321	espressif,esp32-bt-hci
CAN	on-chip	ESP32 Two-Wire Automotive Interface (TWAI)1	espressif,esp32-twai
Clock control	on-chip	ESP32 Clock (Power & Clock Controller Module) Module1	espressif,esp32-clock
Counter	on-chip	ESP32 Counter Driver based on RTC Main Timer1	espressif,esp32-rtc-timer
	on-chip	ESP32 general-purpose timers4	espressif,esp32-timer
	on-chip	ESP32 counters4	espressif,esp32-counter
Cryptographic accelerator	on-chip	Espressif ESP32 SHA Hardware Accelerator1	espressif,esp32-sha
	on-chip	Espressif ESP32 family AES Hardware Accelerator1	espressif,esp32-aes
DAC	on-chip	ESP32 Digital to Analog converter (DAC)1	espressif,esp32-dac
Ethernet	on-chip	ESP32 Ethernet1	espressif,esp32-eth
	on-chip	Synopsys DesignWare MAC MDIO controller1	snps,dwmac-mdio
Flash controller	on-chip	ESP32 flash controller1	espressif,esp32-flash-controller
GPIO & Headers	on-chip	ESP32 GPIO controller2	espressif,esp32-gpio
I2C	on-chip	ESP32 I2C2	espressif,esp32-i2c
I2S	on-chip	ESP32 I2S2	espressif,esp32-i2s
Input	on-chip	ESP32 touch sensor input1	espressif,esp32-touch
Interrupt controller	on-chip	ESP32 Interrupt controller1	espressif,esp32-intc
IPM	on-chip	ESP32 soft inter processor message1	espressif,esp32-ipm
Mailbox	on-chip	ESP32 soft mailbox1	espressif,mbox-esp32
Memory controller	on-chip	ESP32 pseudo-static RAM controller1	espressif,esp32-psram
MTD	on-chip	Flash node1	soc-nv-flash
Pin control	on-chip	ESP32 pin controller1	espressif,esp32-pinctrl
Pulse IO	on-chip	Espressif Remote Control Transceiver (RMT) pulse_io controller1	espressif,esp32-rmt
PWM	on-chip	ESP32 LED Control (LEDC)1	espressif,esp32-ledc
	on-chip	ESP32 Motor Control Pulse Width Modulator (MCPWM)2	espressif,esp32-mcpwm
RNG	on-chip	ESP32 TRNG (True Random Number Generator)1	espressif,esp32-trng
SDHC	on-chip	ESP32 SDHC controller1	espressif,esp32-sdhc
	on-chip	ESP32 SDHC controller slot2	espressif,esp32-sdhc-slot
Sensors	on-chip	ESP32 Pulse Counter (PCNT)1	espressif,esp32-pcnt
Serial controller	on-chip	ESP32 UART3	espressif,esp32-uart
SPI	on-chip	ESP32 SPI controller2	espressif,esp32-spi
SRAM	on-chip	Generic on-chip SRAM2	mmio-sram
Watchdog	on-chip	ESP32 watchdog11	espressif,esp32-watchdog
Wi-Fi	on-chip	ESP32 SoC Wi-Fi1	espressif,esp32-wifi

esp32_devkitc/esp32/procpu target

On-target memory for this board target: 128 KiB of RAM, 4 MiB of Flash.

Type	Location	Description	Compatible
CPU	on-chip	Espressif Xtensa LX6 CPU2	espressif,xtensa-lx6
ADC	on-chip	ESP32 ADC2	espressif,esp32-adc
Bluetooth	on-chip	Bluetooth HCI for Espressif ESP321	espressif,esp32-bt-hci
CAN	on-chip	ESP32 Two-Wire Automotive Interface (TWAI)1	espressif,esp32-twai
Clock control	on-chip	ESP32 Clock (Power & Clock Controller Module) Module1	espressif,esp32-clock
Counter	on-chip	ESP32 Counter Driver based on RTC Main Timer1	espressif,esp32-rtc-timer
	on-chip	ESP32 general-purpose timers4	espressif,esp32-timer
	on-chip	ESP32 counters4	espressif,esp32-counter
Cryptographic accelerator	on-chip	Espressif ESP32 SHA Hardware Accelerator1	espressif,esp32-sha
	on-chip	Espressif ESP32 family AES Hardware Accelerator1	espressif,esp32-aes
DAC	on-chip	ESP32 Digital to Analog converter (DAC)1	espressif,esp32-dac
Ethernet	on-chip	ESP32 Ethernet1	espressif,esp32-eth
	on-chip	Synopsys DesignWare MAC MDIO controller1	snps,dwmac-mdio
Flash controller	on-chip	ESP32 flash controller1	espressif,esp32-flash-controller
GPIO & Headers	on-chip	ESP32 GPIO controller2	espressif,esp32-gpio
I2C	on-chip	ESP32 I2C11	espressif,esp32-i2c
I2S	on-chip	ESP32 I2S2	espressif,esp32-i2s
Input	on-chip	ESP32 touch sensor input1	espressif,esp32-touch
	on-board	Group of GPIO-bound input keys1	gpio-keys
Interrupt controller	on-chip	ESP32 Interrupt controller1	espressif,esp32-intc
IPM	on-chip	ESP32 soft inter processor message1	espressif,esp32-ipm
Mailbox	on-chip	ESP32 soft mailbox1	espressif,mbox-esp32
Memory controller	on-chip	ESP32 pseudo-static RAM controller1	espressif,esp32-psram
MTD	on-chip	Flash node1	soc-nv-flash
Pin control	on-chip	ESP32 pin controller1	espressif,esp32-pinctrl
Pulse IO	on-chip	Espressif Remote Control Transceiver (RMT) pulse_io controller1	espressif,esp32-rmt
PWM	on-chip	ESP32 LED Control (LEDC)1	espressif,esp32-ledc
	on-chip	ESP32 Motor Control Pulse Width Modulator (MCPWM)2	espressif,esp32-mcpwm
RNG	on-chip	ESP32 TRNG (True Random Number Generator)1	espressif,esp32-trng
SDHC	on-chip	ESP32 SDHC controller1	espressif,esp32-sdhc
	on-chip	ESP32 SDHC controller slot2	espressif,esp32-sdhc-slot
Sensors	on-chip	ESP32 Pulse Counter (PCNT)1	espressif,esp32-pcnt
Serial controller	on-chip	ESP32 UART12	espressif,esp32-uart
SPI	on-chip	ESP32 SPI controller2	espressif,esp32-spi
SRAM	on-chip	Generic on-chip SRAM2	mmio-sram
Watchdog	on-chip	ESP32 watchdog11	espressif,esp32-watchdog
Wi-Fi	on-chip	ESP32 SoC Wi-Fi1	espressif,esp32-wifi

esp32_devkitc/esp32/procpu/qemu target

On-target memory for this board target: 128 KiB of RAM, 4 MiB of Flash.

Type	Location	Description	Compatible
CPU	on-chip	Espressif Xtensa LX6 CPU2	espressif,xtensa-lx6
ADC	on-chip	ESP32 ADC2	espressif,esp32-adc
Bluetooth	on-chip	Bluetooth HCI for Espressif ESP321	espressif,esp32-bt-hci
CAN	on-chip	ESP32 Two-Wire Automotive Interface (TWAI)1	espressif,esp32-twai
Clock control	on-chip	ESP32 Clock (Power & Clock Controller Module) Module1	espressif,esp32-clock
Counter	on-chip	ESP32 Counter Driver based on RTC Main Timer1	espressif,esp32-rtc-timer
	on-chip	ESP32 general-purpose timers4	espressif,esp32-timer
	on-chip	ESP32 counters4	espressif,esp32-counter
Cryptographic accelerator	on-chip	Espressif ESP32 SHA Hardware Accelerator1	espressif,esp32-sha
	on-chip	Espressif ESP32 family AES Hardware Accelerator1	espressif,esp32-aes
DAC	on-chip	ESP32 Digital to Analog converter (DAC)1	espressif,esp32-dac
Ethernet	on-chip	ESP32 Ethernet1	espressif,esp32-eth
	on-chip	Synopsys DesignWare MAC MDIO controller1	snps,dwmac-mdio
Flash controller	on-chip	ESP32 flash controller1	espressif,esp32-flash-controller
GPIO & Headers	on-chip	ESP32 GPIO controller2	espressif,esp32-gpio
I2C	on-chip	ESP32 I2C2	espressif,esp32-i2c
I2S	on-chip	ESP32 I2S2	espressif,esp32-i2s
Input	on-chip	ESP32 touch sensor input1	espressif,esp32-touch
Interrupt controller	on-chip	ESP32 Interrupt controller1	espressif,esp32-intc
IPM	on-chip	ESP32 soft inter processor message1	espressif,esp32-ipm
Mailbox	on-chip	ESP32 soft mailbox1	espressif,mbox-esp32
Memory controller	on-chip	ESP32 pseudo-static RAM controller1	espressif,esp32-psram
MTD	on-chip	Flash node1	soc-nv-flash
Pin control	on-chip	ESP32 pin controller1	espressif,esp32-pinctrl
Pulse IO	on-chip	Espressif Remote Control Transceiver (RMT) pulse_io controller1	espressif,esp32-rmt
PWM	on-chip	ESP32 LED Control (LEDC)1	espressif,esp32-ledc
	on-chip	ESP32 Motor Control Pulse Width Modulator (MCPWM)2	espressif,esp32-mcpwm
RNG	on-chip	ESP32 TRNG (True Random Number Generator)1	espressif,esp32-trng
SDHC	on-chip	ESP32 SDHC controller1	espressif,esp32-sdhc
	on-chip	ESP32 SDHC controller slot2	espressif,esp32-sdhc-slot
Sensors	on-chip	ESP32 Pulse Counter (PCNT)1	espressif,esp32-pcnt
Serial controller	on-chip	ESP32 UART12	espressif,esp32-uart
SPI	on-chip	ESP32 SPI controller2	espressif,esp32-spi
SRAM	on-chip	Generic on-chip SRAM2	mmio-sram
Watchdog	on-chip	ESP32 watchdog11	espressif,esp32-watchdog
Wi-Fi	on-chip	ESP32 SoC Wi-Fi1	espressif,esp32-wifi

System Requirements

Binary Blobs

Espressif HAL requires RF binary blobs in order work. Run the command below to retrieve those files.

west blobs fetch hal_espressif

Note

It is recommended running the command above after west update.

Programming and Debugging

The esp32_devkitc board supports the runners and associated west commands listed below.

	flash	debug	debugserver	attach	rtt
esp32	✅ (default)
openocd	✅	✅ (default)	✅	✅	✅

Simple Boot

The board could be loaded using the single binary image, without 2nd stage bootloader. It is the default option when building the application without additional configuration.

Note

Simple boot does not provide any security features nor OTA updates.

MCUboot Bootloader

User may choose to use MCUboot bootloader instead. In that case the bootloader must be built (and flashed) at least once.

There are two options to be used when building an application:

1. Sysbuild

2. Manual build

Note

User can select the MCUboot bootloader by adding the following line to the board default configuration file.

CONFIG_BOOTLOADER_MCUBOOT=y

Sysbuild

The sysbuild makes possible to build and flash all necessary images needed to bootstrap the board with the ESP32 SoC.

To build the sample application using sysbuild use the command:

west build -b <board> --sysbuild samples/hello_world

By default, the ESP32 sysbuild creates bootloader (MCUboot) and application images. But it can be configured to create other kind of images.

Build directory structure created by sysbuild is different from traditional Zephyr build. Output is structured by the domain subdirectories:

build/
├── hello_world
│   └── zephyr
│       ├── zephyr.elf
│       └── zephyr.bin
├── mcuboot
│    └── zephyr
│       ├── zephyr.elf
│       └── zephyr.bin
└── domains.yaml

Note

With --sysbuild option the bootloader will be re-build and re-flash every time the pristine build is used.

For more information about the system build please read the Sysbuild (System build) documentation.

Manual Build

During the development cycle, it is intended to build & flash as quickly possible. For that reason, images can be built one at a time using traditional build.

The instructions following are relevant for both manual build and sysbuild. The only difference is the structure of the build directory.

Note

Remember that bootloader (MCUboot) needs to be flash at least once.

Build and flash applications as usual (see Building an Application and Run an Application for more details).

# From the root of the zephyr repository
west build -b <board> samples/hello_world

The usual flash target will work with the board configuration. Here is an example for the Hello World application.

# From the root of the zephyr repository
west build -b <board> samples/hello_world
west flash

Note

On targets that expose the built-in USB Serial/JTAG controller, the chip can stay in download mode after west flash and will not boot the new image until it is power cycled. If that happens, flash with a watchdog reset so the chip restarts on its own:

west flash --reset-type watchdog-reset

Faster Flashing

To speed up the development cycle, --esp-skip-flashed skips writing the image when the binary already in flash matches the one being flashed, verified with an MD5 check on the device:

west flash --esp-skip-flashed

For an even faster reflash, --esp-diff writes only the regions that differ from the previously flashed image. It compares against a locally cached copy rather than reading the device, so use it only when the flash was not modified by another tool, board, or manual write since the last west flash:

west flash --esp-diff

Progress output can be suppressed for cleaner logs, which is useful in CI:

west flash --esp-no-progress

Open the serial monitor using the following command:

west espressif monitor

After the board has automatically reset and booted, you should see the following message in the monitor:

***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
Hello World! <board>

Using Espressif QEMU

Espressif boards can be run under Espressif’s QEMU fork for local, hardware-free testing. CONFIG_ESPRESSIF_QEMU generates a merged SPI flash image. Enabling it also selects the hidden CONFIG_ESPRESSIF_QEMU_TARGET board marker. A west build -t run target is available only when the board opts into the espressif_qemu emu platform (the DevKitC boards below do this via a shared board.cmake helper).

There are two ways to enable Espressif QEMU on the reference DevKitC boards:

1. Opt-in with -DCONFIG_ESPRESSIF_QEMU=y on the hardware board target. The same firmware image can then be flashed to hardware (without that option) or run under QEMU. Other boards on a supported SoC can set the Kconfig as well (flash layout export), but they need the same SUPPORTED_EMU_PLATFORMS espressif_qemu wiring for -t run.

2. Board variant on the reference DevKitC targets below (/qemu qualifier). The variant defconfig sets CONFIG_ESPRESSIF_QEMU, so no -D is required. Use these for local and CI west build -t run workflows. Twister simulation: metadata for Espressif QEMU is not wired yet; treat /qemu as a board identifier plus emu platform, not a drop-in for stock qemu_* Twister simulation.

Supported SoCs and boards

SoC	Hardware board	QEMU variant (CI)	QEMU binary	-machine
ESP32	esp32_devkitc/esp32/procpu	esp32_devkitc/esp32/procpu/qemu	qemu-system-xtensa	esp32
ESP32-S3	esp32s3_devkitc/esp32s3/procpu	esp32s3_devkitc/esp32s3/procpu/qemu	qemu-system-xtensa	esp32s3
ESP32-C3	esp32c3_devkitc/esp32c3	esp32c3_devkitc/esp32c3/qemu	qemu-system-riscv32	esp32c3
ESP32-C6	esp32c6_devkitc/esp32c6/hpcore	esp32c6_devkitc/esp32c6/hpcore/qemu	qemu-system-riscv32	esp32c6

ESP32-C3 and ESP32-C6 require -icount 3 (added automatically by the run target). Free-running mode is not supported for these machines.

Note

Pre-built Espressif QEMU releases as of esp-develop-9.2.2-20260417 include esp32, esp32s3 and esp32c3 only. ESP32-C6 support was merged into Espressif’s esp-develop branch in https://github.com/espressif/qemu/commit/febae182e132e4055529be423a818225ebddaa3a but is not yet in a published release binary. Build QEMU from the esp-develop branch to run ESP32-C6.

Emulated peripherals

Per-SoC capability is documented in the Espressif QEMU feature matrix. There is no published matrix column for ESP32-C6; the C6 values below follow the current esp-develop esp32c6 machine, not a blind copy of ESP32-C3.

Usable in Zephyr on /qemu DevKitC boards

Peripheral	ESP32	ESP32-S3	ESP32-C3	ESP32-C6
UART console	yes	yes	yes	yes
NOR flash (SPI + MMU)	yes	yes	yes	yes
eFuse	yes (ECO3 image auto)	yes	yes	yes
RNG / TRNG	yes	yes	yes	no
AES / SHA / RSA crypto	yes	yes (+ HMAC, DS)	yes (+ HMAC, DS)	SHA only
Timer groups / SysTimer	yes	yes	yes	yes
TWAI / CAN	modeled	modeled	modeled	no
PSRAM (-m)	QPI 2M/4M	QPI/OPI 2M–32M	N/A	N/A
GDMA	no Zephyr smoke test	yes (SoC)	yes (SoC)	yes (SoC)

Not emulated (disabled in /qemu device trees)

Wi-Fi, Bluetooth, USB, general-purpose SPI, I2C, I2S, RMT, GPIO matrix / IOMUX, ADC/DAC, touch, MCPWM, pulse counter, ULP, and board GPIO keys. LEDC is emulated only on ESP32; SD/MMC is not emulated on ESP32-S3. On ESP32-C6, also disable TRNG, AES, and the HP/LP mailbox (mbox0); leave SHA enabled.

Tests that depend on those peripherals will not run under QEMU.

QEMU variant device tree

Hardware DevKitC targets keep the full device tree. The /qemu board variants include the same hardware *.dts and overlay status = "disabled" (or /delete-node/) for nodes QEMU does not model:

• boards/espressif/esp32_devkitc/esp32_devkitc_procpu_qemu.dts

• boards/espressif/esp32s3_devkitc/esp32s3_devkitc_procpu_qemu.dts

• boards/espressif/esp32c3_devkitc/esp32c3_devkitc_qemu.dts

• boards/espressif/esp32c6_devkitc/esp32c6_devkitc_hpcore_qemu.dts

Common overlays disable Wi-Fi, Bluetooth, I2C, I2S, general-purpose SPI, ADC, and non-emulated PWM-related blocks; remove GPIO key nodes; and clear unsupported chosen properties. The Xtensa variants also disable touch, pulse counter, and MCPWM nodes. ESP32-S3 additionally disables its second I2C/SPI/I2S instances, USB Serial/JTAG and OTG, LEDC, SD/MMC, temperature sensor, and LCD/CAM controller. ESP32-C3 disables USB Serial/JTAG, LEDC, and its temperature sensor. ESP32-C6 disables IEEE 802.15.4, LP UART, MCPWM, pulse counter, TRNG (and zephyr,entropy), AES, and mbox0; SHA stays available.

UART, flash partitions, timer groups, and watchdog nodes stay available for smoke tests (for example samples/hello_world). TRNG and full crypto blocks remain on ESP32 / S3 / C3; ESP32-C6 keeps SHA only. The GPIO controller nodes and CONFIG_GPIO=y must remain enabled because the Espressif UART driver selects the GPIO driver for pin muxing; attempting to disable them produces a Kconfig dependency error. This is boot infrastructure, not a claim that QEMU implements application GPIO or the GPIO matrix. GPIO keys are removed from the device tree.

Automatic vs manual QEMU flags

The west build -t run target appends these flags automatically when CONFIG_ESPRESSIF_QEMU is enabled:

• -icount 3 on ESP32-C3 and ESP32-C6

• ESP32 ECO3 eFuse image (see Flash size / ESP32 chip revision)

• -drive file=…/flash_image.bin,if=mtd,format=raw

• -m <size> when CONFIG_ESP_SPIRAM is set; size comes from CONFIG_ESP_SPIRAM_SIZE (default from the board psram0 size property in devicetree)

• -global driver=ssi_psram,property=is_octal,value=true on ESP32-S3 when CONFIG_SPIRAM_MODE_OCT is set

Use the QEMU_EXTRA_FLAGS environment variable for optional cases (watchdog disable, SD card on ESP32, and similar).

Installing Espressif QEMU

Download pre-built binaries from https://github.com/espressif/qemu/releases (Xtensa and RISC-V packages).

Example (Linux x86_64, release esp-develop-9.2.2-20260417):

mkdir -p ~/Downloads ~/opt
cd ~/Downloads
wget https://github.com/espressif/qemu/releases/download/esp-develop-9.2.2-20260417/qemu-xtensa-softmmu-esp_develop_9.2.2_20260417-x86_64-linux-gnu.tar.xz
wget https://github.com/espressif/qemu/releases/download/esp-develop-9.2.2-20260417/qemu-riscv32-softmmu-esp_develop_9.2.2_20260417-x86_64-linux-gnu.tar.xz
tar -xf qemu-xtensa-softmmu-*.tar.xz -C ~/opt --one-top-level=qemu-xtensa-softmmu
tar -xf qemu-riscv32-softmmu-*.tar.xz -C ~/opt --one-top-level=qemu-riscv32-softmmu

Put both bin directories on PATH, or set ESPRESSIF_QEMU_PATH / QEMU_BIN_PATH to a platform path list containing the directories for the SoCs you are targeting. A generic distro QEMU without -machine esp* will not work.

At CMake configure time each qemu-system-xtensa / qemu-system-riscv32 found in ESPRESSIF_QEMU_PATH, QEMU_BIN_PATH and PATH (in that order) is probed with -machine help, and the first one that implements the SoC’s machine is used. This skips the Zephyr SDK’s own QEMU in hosttools, which is an upstream build without the Espressif machines. The selected binary is printed as:

-- Espressif QEMU: /home/user/opt/qemu-xtensa-softmmu/qemu/bin/qemu-system-xtensa (-machine esp32)

Because the lookup happens during configuration, installing QEMU or changing ESPRESSIF_QEMU_PATH after a build requires re-running CMake (west build --pristine).

Building and running (Simple Boot)

west build does not use sysbuild unless --sysbuild is given or build.sysbuild is set in the west config, so a plain build is a Simple Boot image with no MCUboot. --no-sysbuild below makes that explicit and also overrides a build.sysbuild=true west config.

Opt-in (hardware board + CMake cache entry):

west build -b esp32_devkitc/esp32/procpu samples/hello_world \
  --no-sysbuild --pristine \
  -- -DCONFIG_ESPRESSIF_QEMU=y

west build -t run

QEMU board variant (defconfig supplies CONFIG_ESPRESSIF_QEMU):

west build -b esp32_devkitc/esp32/procpu/qemu samples/hello_world \
  --no-sysbuild --pristine

west build -t run

The build produces build/zephyr/flash_image.bin (merged SPI image) and registers the espressif_qemu emu platform (run_espressif_qemu / debugserver_espressif_qemu, aliased as west build -t run / debugserver). On ESP32 it also generates build/zephyr/qemu_efuse_eco3.bin and passes it to QEMU. Equivalent manual invocation:

qemu-system-xtensa -nographic -machine esp32 \
  -drive file=build/zephyr/qemu_efuse_eco3.bin,if=none,format=raw,id=efuse \
  -global driver=nvram.esp32.efuse,property=drive,value=efuse \
  -drive file=build/zephyr/flash_image.bin,if=mtd,format=raw

ESP32-C3 opt-in example:

west build -b esp32c3_devkitc/esp32c3 samples/hello_world \
  --no-sysbuild --pristine \
  -- -DCONFIG_ESPRESSIF_QEMU=y
west build -t run

ESP32-C3 variant (no -D):

west build -b esp32c3_devkitc/esp32c3/qemu samples/hello_world \
  --no-sysbuild --pristine
west build -t run
# or:
qemu-system-riscv32 -nographic -icount 3 -machine esp32c3 \
  -drive file=build/zephyr/flash_image.bin,if=mtd,format=raw

MCUboot / sysbuild

With sysbuild, CONFIG_ESPRESSIF_QEMU merges MCUboot (boot_partition) and the signed application (slot0_partition) into the same flash image:

west build -b esp32_devkitc/esp32/procpu samples/hello_world \
  --sysbuild --pristine \
  -- -DCONFIG_ESPRESSIF_QEMU=y

west build --domain hello_world -t run

--domain is required here: run is defined by the application image, and the sysbuild top-level build has no such target. The image is written to build/<app>/zephyr/flash_image.bin rather than build/zephyr/.

The merge consumes ../mcuboot/zephyr/zephyr.bin from the bootloader domain. Sysbuild adds each image as an independent external project, so these DevKitC boards’ sysbuild.cmake always orders the application after mcuboot whenever both ExternalProject targets exist (the dependency is not gated on CONFIG_ESPRESSIF_QEMU, which is not reliably visible in the sysbuild CMake context). Without that ordering the two domains build concurrently and the merge can read an incomplete bootloader binary.

A non-sysbuild build with CONFIG_BOOTLOADER_MCUBOOT does not produce a bootloader binary in the tree (on hardware MCUboot is already flashed). For QEMU, either use --sysbuild or pass an existing bootloader image with -DESPRESSIF_QEMU_MCUBOOT_BIN=<path to mcuboot zephyr.bin>. The path must be absolute, because the merge runs inside the build directory.

GDB debugging

Start QEMU with the CPU held in reset and a GDB stub on port 1234:

west build -t debugserver

Under sysbuild, add --domain <app> as for run. Then attach from another terminal, using the GDB that ships with the Zephyr SDK:

$ZEPHYR_SDK_INSTALL_DIR/gnu/xtensa-espressif_esp32_zephyr-elf/bin/xtensa-espressif_esp32_zephyr-elf-gdb \
  build/zephyr/zephyr.elf \
  -ex "target remote :1234" \
  -ex "tb main" -ex "c"

For the RISC-V SoCs (ESP32-C3, ESP32-C6) use gnu/riscv64-zephyr-elf/bin/riscv64-zephyr-elf-gdb instead. The ESP-IDF toolchain GDBs (xtensa-esp32-elf-gdb, riscv32-esp-elf-gdb) also work if you have an ESP-IDF environment on PATH.

Advanced QEMU arguments

Extra flags can be injected via the QEMU_EXTRA_FLAGS environment variable (space-separated) read at CMake configure time: set it before the first build or re-run CMake for a change to take effect. Options not appended automatically:

• Disable TG watchdogs: -global driver=timer.esp32.timg,property=wdt_disable,value=true (ESP32-S3, ESP32-C3, and ESP32-C6 use the timer.esp32c3.timg property name)

• SD/MMC (ESP32 only): -drive file=sdcard.img,if=sd,format=raw

• Custom eFuse storage: configure with -DESPRESSIF_QEMU_EFUSE_HEX_FILE=/path/to/efuse.hex. Whitespace is allowed in the hex file. The build copies it into the build directory, decodes it with Python, and passes the resulting binary to the machine’s eFuse device. Without this override, ESP32 uses a built-in ECO3 image and the other SoCs attach no eFuse drive. The source tree is never written.

  See the per-SoC pages under https://github.com/espressif/esp-toolchain-docs/tree/main/qemu for efuse layouts and strap modes.

PSRAM (automatic when SPIRAM is enabled)

When CONFIG_ESP_SPIRAM is enabled, CMake appends -m <size> where <size> is derived from CONFIG_ESP_SPIRAM_SIZE (bytes ÷ 1 MiB, suffixed with M). Unsupported sizes fail configure (do not pass a half-supported -m). The ESP32 /qemu variant clamps psram0 to 4M because the hardware WROVER N4R8 tree defaults to 8M.

Documented QEMU sizes:

• ESP32: 2M, 4M (PSRAM MMU is not fully emulated)

• ESP32-S3: 2M, 4M, 8M, 16M, or 32M; octal (OPI) mode also adds the ssi_psram is_octal global when CONFIG_SPIRAM_MODE_OCT=y

Override or supplement with QEMU_EXTRA_FLAGS if needed.

Flash size

The merged image is padded to the board’s zephyr,flash size from devicetree so the SPI flash header and the QEMU MTD size match. Espressif QEMU supports 2, 4, 8 and 16 MB; use a board or overlay whose flash size is one of those values.

ESP32 chip revision

Default QEMU efuses report ESP32 revision 0, which Zephyr rejects unless CONFIG_ESP32_USE_UNSUPPORTED_REVISION is enabled. With CONFIG_ESPRESSIF_QEMU, the run / debugserver targets automatically attach an ECO3 eFuse image (CHIP_VER_REV1 and CHIP_VER_REV2 set) so the guest reports chip revision v3.0.

At configure time the ECO3 hex is written under the build directory and decoded with Python into build/zephyr/qemu_efuse_eco3.bin. Override with -DESPRESSIF_QEMU_EFUSE_HEX_FILE=... at configure time (or pass the same -D on a later west build / west build -t run, which re-runs CMake). An environment variable alone is not enough: the path is read only during CMake configure. The layout matches Emulating ESP32 ECO3.

Equivalent manual QEMU invocation:

qemu-system-xtensa -nographic -machine esp32 \
  -drive file=build/zephyr/qemu_efuse_eco3.bin,if=none,format=raw,id=efuse \
  -global driver=nvram.esp32.efuse,property=drive,value=efuse \
  -drive file=build/zephyr/flash_image.bin,if=mtd,format=raw

Board variants using Snippets

ESP32 boards can be assembled with different modules using multiple combinations of SPI flash sizes, PSRAM sizes and PSRAM modes. The snippets under snippets/espressif provide a modular way to apply these variations at build time without duplicating board definitions.

The following snippet-based variants are supported:

Snippet name	Description
Flash memory size
espressif-flash-4M	Board with 4MB of flash
espressif-flash-8M	Board with 8MB of flash
espressif-flash-16M	Board with 16MB of flash
espressif-flash-32M	Board with 32MB of flash
espressif-flash-64M	Board with 64MB of flash
espressif-flash-128M	Board with 128MB of flash
PSRAM memory size
espressif-psram-2M	Board with 2MB of PSRAM
espressif-psram-4M	Board with 4MB of PSRAM
espressif-psram-8M	Board with 8MB of PSRAM
PSRAM utilization
espressif-psram-reloc	Relocate flash to PSRAM
espressif-psram-wifi	Wi-Fi buffers in PSRAM

To apply a board variant, use the -S flag with west build:

west build -b <board> -S espressif-flash-32M -S espressif-psram-4M samples/hello_world

Note

These snippets are only applicable to boards with compatible hardware support for the selected flash/PSRAM configuration.

• If no FLASH snippet is used, the board default flash size will be used.

• If no PSRAM snippet is used, the board default psram size will be used.

Debugging

OpenOCD Debugging

Espressif chips require a custom OpenOCD build with ESP32-specific patches. Download the latest release from OpenOCD for ESP32 [3].

For detailed JTAG setup instructions, see JTAG debugging for ESP32 [5].

Zephyr Thread Awareness

OpenOCD supports Zephyr RTOS thread awareness, allowing GDB to:

• List all threads with info threads

• Display thread names, priorities, and states

• Switch between thread contexts

• Show backtraces for any thread

Requirements:

• OpenOCD ESP32 v0.12.0-esp32-20251215 [4] or later

• Build with CONFIG_DEBUG_THREAD_INFO=y

Example:

# From the root of the zephyr repository
west build -b <board> samples/hello_world -- -DCONFIG_DEBUG_THREAD_INFO=y -DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>
west debug

Using a Custom OpenOCD

The Zephyr SDK includes a bundled OpenOCD, but it may not have ESP32 support. To use the Espressif OpenOCD, specify the path when building:

# From the root of the zephyr repository
west build -b <board> samples/hello_world -- -DOPENOCD=/path/to/openocd -DOPENOCD_DEFAULT_PATH=/path/to/openocd/scripts
west debug

On the ESP32-DevKitC board, the JTAG pins are not run to a standard connector (e.g. ARM 20-pin) and need to be manually connected to the external programmer (e.g. a Flyswatter2):

ESP32 pin	JTAG pin
3V3	VTRef
EN	nTRST
IO14	TMS
IO12	TDI
GND	GND
IO13	TCK
IO15	TDO

References

[1]

https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf

[2]

https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf

[3]

https://github.com/espressif/openocd-esp32/releases

[4]

https://github.com/espressif/openocd-esp32/releases/tag/v0.12.0-esp32-20251215

[5]

https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html

[6]

https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32/esp32-devkitc/index.html