Skip to main content
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: 
[wokwi]
version = 1
firmware = 'path-to-your-firmware.hex'
elf = 'path-to-your-firmware.elf'
Replace “path-to-your-firmware” with the location of the compiled firmware, relative to the wokwi.toml file (that is your workspace’s root directory). The extension of the firmware file depends on the board you are using:
BoardSupported 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 can test your configuration by pressing F1 and then selecting “Wokwi: Start Simulator”. Make sure you compile your program before starting the simulation.
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 and partition table) to ESP32. The flasher_args.json file is automatically generated by the idf.py build command. 
[wokwi]
version = 1
firmware = 'build/flasher_args.json'
elf = 'build/example_app.elf'

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

​
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: 
import serial

ser = serial.serial_for_url('rfc2217://localhost:4000', baudrate=115200)
ser.write(b'hello')
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 [[chip]] sections to your wokwi.toml configuration. The following example will load a chip from “chips/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.

Build docs developers (and LLMs) love

Get started for freeTalk to us