Simulate ESP32 circuits in the browser with Wokwi before you wire

Wokwi is an electronics simulator that runs in the browser. Drop in an ESP32, wire up LEDs, buttons and sensors, and run real firmware before you own the board. Use it to try ideas, find bugs in code and check your pin wiring before you plug in real wires. It cuts out a lot of “upload, guess, fix, upload again”.

This lesson draws on the Wokwi docs and the Wokwi page in Espressif’s ESP-IDF guide, as of October 2026. If you have never wired a circuit, start with an LED on an ESP32, then build the same circuit in Wokwi and compare.

Which chips, and how much of each

Wokwi simulates ESP32, ESP32-C3, ESP32-S2, ESP32-S3, ESP32-C6, ESP32-C61 and ESP32-H2. ESP32-C5 and ESP32-S31 are alpha and ESP32-P4 is beta. Support varies by chip; this table covers the parts toys use most.

Feature	Status in Wokwi
GPIO, UART, SPI, ADC, LEDC PWM, RMT, timers	Supported on every chip in the table
Wi-Fi	Supported (P4 through ESP-Hosted)
I2C	Master only, no 10-bit addressing
I2S	Partial, original ESP32 only
USB Serial/JTAG	Serial yes, JTAG no (S3, C3, C5, C6, P4)
PSRAM	ESP32, S3, C5, P4
Bluetooth	Not yet

So a toy with buttons, WS2812 LEDs (via RMT), a servo (via LEDC) and I2C sensors simulates almost completely. A toy controlled from a phone over BLE has to be tested on a real board.

CPU speed: why some code is slower than real

The default cpuFrequency is auto, which caps the simulated CPU at about 8 MHz. You can set max, but the docs advise against it because it slows the whole simulation. Crucially, the cap only affects instruction speed; peripheral timing stays correct.

Example:

1. A real ESP32-S3 runs at 240 MHz; the simulation at about 8 MHz. That is 240 ÷ 8 = 30 times slower for pure computation.
2. A loop that takes 20 ms on the board may take about 20 × 30 = 600 ms in Wokwi.
3. But delay(500) still blinks every 500 ms, and a servo’s 50 Hz PWM is still 50 Hz, because those are peripheral timings.

If an LED animation looks sluggish in Wokwi, suspect the computation in your loop before deciding the code is wrong.

Simulated Wi-Fi

The simulated ESP32 sees an access point called Wokwi-GUEST, with no password, on channel 6. Passing the channel when you connect skips the scan and saves about 4 seconds every run.

// Arduino-ESP32 in Wokwi
WiFi.begin("Wokwi-GUEST", "", 6);  // channel 6

Internet traffic goes through one of two IoT gateways:

	Public Gateway	Private Gateway
Cost	Free, the default	Paid users
Traffic monitored	Yes	No
Reaches your home network	No	Yes
Browse a web server on the ESP32	No	Yes, via localhost:9080
ESP32 IP	10.10.0.2	10.13.37.2

The gateway handles TCP and UDP but not ICMP, so ping won’t work. To reach a program on your own computer from simulated code (through the Private Gateway), use the hostname host.wokwi.internal.

The Public Gateway is monitored. Keep your home Wi-Fi password, API tokens and anything personal out of projects that run through it.

Logic analyser: see the signals you can’t see

Add the “Logic Analyzer (8 channels)” part, with channels D0–D7. Wire the pins you want to watch and run. When you stop the simulation you get wokwi-logic.vcd; open it in PulseView (Import Value Change Dump) or GTKWave.

Example: debugging I2C on a BME280 sensor

1. The analyser samples at 1 GHz. The docs suggest a downsampling factor of 50 on import: 1,000 ÷ 50 = 20 MHz.
2. Standard-mode I2C is 100 kHz, so one bit lasts 1 ÷ 100,000 = 10 µs.
3. At 20 MHz that is 20,000,000 × 0.00001 = 200 samples per bit, plenty for PulseView’s I2C decoder to show the address and ACK/NACK.

A NACK right after the address means the address in your code doesn’t match the part you wired. No need to pull real wires apart to find that out.

Running it in VS Code and CI

The Wokwi for VS Code extension simulates firmware you build locally, with PlatformIO, ESP-IDF, Arduino CLI, MicroPython, Rust, Zephyr and others. Steps:

1. Install the extension, press F1, choose “Wokwi: Request a new License” and sign in to your Wokwi account.
2. Build your firmware as usual.
3. Create wokwi.toml (where the files are) and diagram.json (parts and wiring).
4. Press F1 → “Wokwi: Start Simulator”.

# wokwi.toml (example PlatformIO project)
[wokwi]
version = 1
firmware = '.pio/build/esp32dev/firmware.bin'
elf = '.pio/build/esp32dev/firmware.elf'

For ESP-IDF 6.0 and newer there is the idf-wokwi package: pip install idf-wokwi, set WOKWI_CLI_TOKEN, then run idf.py wokwi; it generates the config files for you. Older versions use wokwi-cli instead. It works in GitHub Actions too, for example idf.py wokwi --timeout 30000 --expect-text "Tests passed". Keep the token in a secret and never commit it.

Common mistakes

• Skipping real measurements because the simulation passed. Wokwi can’t tell whether your supply is enough; see powering an ESP32.
• Setting flashSize smaller than the partition table. LittleFS or SPIFFS then fails to mount.
• Testing BLE in Wokwi. It isn’t supported yet.
• Setting the CPU to max to speed things up. It makes the overall simulation slower.
• Putting secrets in a project that uses the Public Gateway.

Sources

• ESP32 Simulation — Wokwi Docs
• ESP32 WiFi Networking — Wokwi Docs
• Logic Analyzer — Wokwi Docs
• Getting Started with Wokwi for VS Code — Wokwi Docs
• Wokwi — ESP-IDF Programming Guide (ESP32-C6) — Espressif