An Introduction to Wokwi Simulator:Revolutionizing Electronics Design and Testing

Embedded development traditionally requires physical breadboards, jumper wires, development boards, and an array of components. With the Wokwi Simulator extension in Visual Studio Code (VS Code), you can write production-ready firmware using PlatformIO and simulate your entire ESP32 hardware layout directly inside your development environment.

Follow this complete walkthrough to install Wokwi, initialize a PlatformIO project, configure circuit diagrams, link compilation binaries, and run your project seamlessly.

Step 1: Install Wokwi

    1. Open Visual Studio Code and head over to the Extensions Marketplace

     (Ctrl+Shift+X or  Cmd+Shift+X).
    2. Search for Wokwi Simulator and click Install.

3. Make sure the PlatformIO IDE extension is also installed in your editor.

Step 2: Set Up a PlatformIO Project

1. Click the PlatformIO icon on the VS Code Activity Bar

2. Under Quick Access, select Create New Project.

3. In the Project Wizard dialog, enter the project configurations:

   • Board: DOIT ESP32 DEVKIT V1

   • Framework: Arduino

   • Location: Use default location

   • Name: Test

4. Click Finish and wait for PlatformIO to set up the directories.

Step 3: Write Initial Firmware & Compile

1. In the VS Code file tree, expand the src folder and click main.cpp.
2. Add your ESP32 test code (e.g., an LED blink routine using GPIO 12):

3. Run the Build task by clicking the checkmark build icon located in the bottom status bar.

4. Take note of the terminal output confirming successful compilation and displaying the file paths for the generated .bin and .elf files inside .pio/build/esp32doit-devkit-v1/.

Step 4: Request and Activate a Wokwi License

Wokwi requires a generated license token to activate simulation inside the editor:

1. Press F1 (or Ctrl+Shift+P) to open the Command Palette.

2. Type and choose Wokwi: Request a New License.

3. Click Open when prompted to open the external browser link.

4. On the Wokwi page, click GET YOUR LICENSE.

5. Authorize the browser to open the link back in VS Code. VS Code will show a confirmation toast: Wokwi: License activated for [your name].

Step 5: Create and Configure diagram.json

The circuit schematic in Wokwi is defined using a JSON file called diagram.json placed in the project root.

1. Right-click in the root explorer pane and choose New File.

2. Name the file diagram.json.

3. When clicked initially, the file opens in the interactive Wokwi graphical editor view (which will appear blank).

4. Right-click on diagram.json in the Explorer list, select Open With..., and choose Text Editor (Default).

5. Paste your JSON circuit layout defining the ESP32 board, LED, resistor, and pin connections:

6. Save the file (Ctrl+S / Cmd+S).

7. Switch back to the Wokwi Diagram Editor tab; the interactive schematic showing the ESP32 connected to the resistor and LED will now load immediately.

Step 6: Create and Configure wokwi.toml

Wokwi requires a configuration file named wokwi.toml in the project root to map your circuit diagram to the compiled binary files produced by PlatformIO.

1. Right-click in the root explorer pane and choose New File.

2. Name the file wokwi.toml.

3. Open wokwi.toml and paste the following base structure:

[wokwi]
version = 1
firmware = "path-to-your-firmware.bin"
elf = "path-to-your-firmware.elf"

4. Replace the placeholder paths with the actual output paths generated by PlatformIO during compilation:

[wokwi]

version = 1

firmware = ".pio/build/esp32doit-devkit-v1/firmware.bin"elf = ".pio/build/esp32doit-devkit-v1/firmware.elf"

5. Save the file (Ctrl+S / Cmd+S).

Step 7: Run the Circuit Simulation

1. Open diagram.json in the editor.

2. Click the green Start the simulation button located at the top-left corner of the canvas.

3. The virtual ESP32 boots up and executes your code. You will see the connected red LED blink ON and OFF at 1-second intervals.

Step 8: Adding Serial Communication

You can monitor serial print outputs directly inside the VS Code integrated terminal.

1. Open src/main.cpp and update the sketch to initialize the serial port and print status messages:

#include <Arduino.h>

#define LED1 12

void setup() {
  pinMode(LED1, OUTPUT);
  Serial.begin(9600); // Initialize serial communication
}

void loop() {
  digitalWrite(LED1, HIGH);
  Serial.println("LED ON");
  delay(1000);

  digitalWrite(LED1, LOW);
  Serial.println("LED OFF");
  delay(1000);
}

Troubleshooting Tip: Ensure every statement ends with a semicolon ; before compiling. Omitting semicolons will trigger build errors in the PlatformIO console.

2. Click Build to recompile your modified project.

3. Return to diagram.json and start the simulation.

4. Look at the embedded Terminal / Serial Monitor console in VS Code. Alongside the blinking LED, real-time log messages will stream continuously:

LED ON
LED OFF
LED ON
LED OFF

Recommended project structure

TEST/
├── .pio/
├── .vscode/
├── include/
├── lib/
├── src/
│   └── main.cpp
├── test/
├── diagram.json
├── platformio.ini
└── wokwi.toml

The .pio directory is generated by PlatformIO, while diagram.json and wokwi.toml are the Wokwi-specific files that make the local VS Code simulation possible.

The complete workflow is

• ·        Install the Wokwi Simulator extension in VS Code.
• ·        Create or open a PlatformIO ESP32 project.
• ·        Configure the target board and Arduino framework in platformio.ini.
• ·        Write the ESP32 application code in main.cpp.
• ·        Request/activate the Wokwi license when required.
• ·        Create diagram.json for the virtual circuit.
• ·        Build the PlatformIO project to generate firmware.
• ·        Open diagram.json with Wokwi and start the simulator.
• ·        Verify the simulated LED behavior.

The embedded ESP32 development workflow is now completely self-contained in VS Code, enabling rapid prototyping, hardware logic debugging, and serial monitoring without touching physical components.

Conclusion:

A path from VS Code setup to a working Wokwi simulation. The key idea is to keep the embedded development workflow inside VS Code: PlatformIO manages the ESP32 project and build, whileWokwi provides the virtual hardware and circuit simulation. The final LED simulation shown in the video confirms the complete workflow.

Related Video: https://youtu.be/ECNTyMm_5PE