Configuring Your Project (wokwi.toml)

To simulate your project on Wokwi, you need to create two files in your project's root directory:

• wokwi.toml - a configuration file that tells Wokwi how to run your project.
• diagram.json - a diagram file that describes the circuit.

wokwi.toml

A basic wokwi.toml file looks like this (a PlatformIO project with an [env:esp32dev] environment):

[wokwi]
version = 1
firmware = '.pio/build/esp32dev/firmware.bin'
elf = '.pio/build/esp32dev/firmware.elf'

firmware is the location of the compiled firmware, relative to the wokwi.toml file (that is your workspace's root directory). Where the compiled firmware ends up depends on your toolchain:

Toolchain	firmware	elf	Guide
PlatformIO	.pio/build/<env>/firmware.bin (.hex for AVR)	.pio/build/<env>/firmware.elf	PlatformIO projects
ESP-IDF (idf.py)	build/flasher_args.json	build/<project>.elf	ESP-IDF projects
Arduino CLI (--output-dir build)	build/<sketch>.ino.hex / .ino.bin	build/<sketch>.ino.elf	Arduino example
Pico SDK	build/<name>.uf2	build/<name>.elf	Pico SDK example
Rust	target/<triple>/debug/<name> (ELF)	same file	Rust examples

tip

Don't want to write these files by hand? Run wokwi-cli init in your project directory: it detects PlatformIO, ESP-IDF and Pico SDK projects and generates both wokwi.toml and diagram.json.

The extension of the firmware file depends on the board you are using:

Board	Supported firmware types
Arduino Uno/Mega, ATtiny85	.hex, .elf
Raspberry Pi Pico	.hex, .uf2, .elf
ESP32 Family	.bin, .uf2, .elf, flasher_args.json
STM32 Family	.hex, .bin, .elf

The elf field is optional, but providing it can speed up the simulation in some cases.

You check test your configuration by pressing F1 and then selecting "Wokwi: Start Simulator". Make sure you compile your program before starting the simulation.

warning

Avoid using backslashes (\) in your paths. Use forward slash (/) instead, as it makes it possible to open your project on any platform (Windows, Mac and Linux).

ESP-IDF support

For ESP-IDF apps, set firmware to 'build/flasher_args.json' to automatically load the complete application (including the bootloader, partition table and flash size) to the ESP32. The flasher_args.json file is generated by the idf.py build command. Example:

[wokwi]
version = 1
firmware = 'build/flasher_args.json'
elf = 'build/example_app.elf'

See ESP-IDF projects for the details, and PlatformIO projects if you build ESP-IDF through PlatformIO (its flasher_args.json cannot be used as-is).

ESP32: application image vs. full image

For the ESP32 family, a plain .bin is usually the application only (for example PlatformIO's firmware.bin). Wokwi then adds its own bootloader and a default partition table, and simulates 4 MB of flash. If your project uses a custom partition table, a filesystem (LittleFS / SPIFFS / FATFS), OTA, or more than 4 MB of flash, load a full image that includes the bootloader and partition table instead. See PlatformIO projects for how to build one.

Logic Analyzer VCD Export

If your diagram includes a Logic Analyzer, Wokwi automatically saves the captured signals to a VCD file when the simulation stops. By default, the file is saved as wokwi.vcd in your project root.

You can customize the output path by adding the following to your wokwi.toml file:

[wokwi]
...
vcdFile = 'logic-capture.vcd'

You can then open the VCD file with Surfer, PulseView or GTKWave to analyze the captured signals.

SD card contents

info

Requires Wokwi for VS Code 4.0.0 or newer.

If your diagram has a microSD card, create an sdcard directory next to wokwi.toml. Its contents (including sub-directories) are copied to the card every time the simulation starts. No configuration is needed.

For a different directory, a raw disk image, a bigger card, or to keep the files the firmware writes, add an [[sdcard]] section:

[[sdcard]]
folder = 'assets/sd'   # directory to copy to the card
# image = 'sd.img'     # alternatively, a raw disk image (e.g. dumped from a real card)
size = '32M'           # card capacity (default: 8M, maximum: 256M)
writeback = true       # write the card contents back to the folder/image when the simulation stops

• Use either folder or image. A folder is formatted as FAT16 with the files copied in. An image is served as-is, so it may contain any filesystem your firmware understands. An image smaller than size is padded with zeros.
• size accepts K, M and G suffixes, or a number of bytes.
• writeback mirrors the card into the folder or image when the simulation stops or restarts, including removing files the firmware deleted. It is off by default. Add the folder to .gitignore if you don't want the firmware's output in version control.
• Files are read when the simulation starts. After editing them, restart the simulation.
• With more than one microSD card in the diagram, add one [[sdcard]] section per card and set part to the card's id from diagram.json.

The Wokwi CLI reads the same configuration.

GDB debugging

To debug the simulated firmware with GDB, add a GDB server port to the [wokwi] section of your wokwi.toml file:

gdbServerPort = 3333

Both Wokwi for VS Code and the Wokwi CLI read this setting and listen for GDB on that port.

Serial port forwarding

Wokwi for VS Code allows you to connect to the serial port of the simulated microcontroller using an RFC2217 TCP server. To enable this feature, add the following configuration to your wokwi.toml file, inside the [wokwi] section:

rfc2217ServerPort = 4000

This will start an RFC2217 server on port 4000. You can connect to the serial port using the Serial Monitor extension (select TCP monitor mode) or PuTTY (select Telnet connection type). In addition, you can use PySerial's RFC2217 support to connect to the serial port from your Python code:

import serial

ser = serial.serial_for_url('rfc2217://localhost:4000', baudrate=115200)
ser.write(b'hello')

Note: make sure the simulator tab is visible in VS Code, otherwise the simulation may pause and you won't get any serial output from the microcontroller.

IoT Gateway (ESP32 WiFi)

Wokwi for VS Code includes a bundled version of the Wokwi Private IoT Gateway, which allows you to connect the virtual WiFi of the simulated ESP32 to your local network and the Internet.

You can also connect to the simulated ESP from your computer (e.g. you are running a web server on the ESP32). To do so, set up port forwarding in wokwi.toml. For instance, to forward local port 8180 to port 80 on the ESP32, add the following configuration:

# Forward http://localhost:8180 to port 80 on the simulated ESP32:
[[net.forward]]
from = "localhost:8180"
to = "target:80"

To forward multiple ports, add multiple [[net.forward]] sections.

For a complete example, see the ESP32 Web Server project.

Custom chips

You can load custom chips to the simulation by adding a [[chip]] sections to your wokwi.toml configuration. The following example will load a chip from "chip/inverter.chip.wasm" and make it available under the name chip-inverter in Wokwi's diagram:

[[chip]]
name = 'inverter'  # To use the chip in diagram.json, add a part with "chip-inverter" type.
binary = 'chips/inverter.chip.wasm'

Wokwi also requires a JSON file that describes the chip pins. The JSON file should have the same name as the wasm binary, but with a json extension (e.g. chips/inverter.chip.json in the above example). For a complete example, check out the inverter-chip repo.

You can add multiple chips to your project by adding multiple [[chip]] sections, each with a different name and binary.

diagram.json

You can copy the diagram file from an existing project on Wokwi.com. For instance, if you are working on an ESP32 project, you can copy the contents of diagram.json from https://wokwi.com/projects/new/esp32.

For ESP32 boards, the attrs of the board part control the simulated hardware: flashSize, psramSize, psramType and more. See ESP32 advanced usage.

Troubleshooting

wokwi.toml configuration file not found in workspace

The file must be named exactly wokwi.toml and live in the root of a workspace folder. If it is in a subfolder, press F1 and select "Wokwi: Select Config File" to choose it.

firmware binary <path> not found in workspace

Wokwi looked for the firmware path relative to wokwi.toml and didn't find it. Check that the project has been built (Wokwi doesn't compile your code), that the path matches your build output, and that it uses forward slashes.

no diagram.json file in <folder>

Add a diagram.json next to wokwi.toml (see above).

LittleFS/SPIFFS fails to mount, OTA fails, or the app behaves differently from the real board

You are probably loading an application-only image. See ESP32: application image vs. full image.