Using the Wokwi simulator in Visual Studio Code

You can develop for ESP32 devices using only a computer using Wokwi. You can use Wokwi directly in your web browser, though you can only save files publicly and compilation may fail if the Wokwi servers are busy.

This guide will show how to create a new PlatformIO ESP32 project and and run it on your computer with Wokwi.

Installing Visual Studio Code, PlatformIO, and Wokwi

Installing Visual Studio Code

Download and install Visual Studio Code.

Installing PlatformIO

In Visual Studio Code, open the Extensions pane.
Search for platformio.
Install the PlatformIO IDE.

Installing and activating Wokwi

In Visual Studio Code, open the Extensions pane.
Search for wokwi.
Install the Wokwi Simulator.
Press Ctrl+Shift+P to open the Command Palette. In the Command Palette, type wokwi. (Do not press Enter.)
Select Wokwi: Request a New License.
Click Open.
Click Get Your License.
Copy the license key.
Press Ctrl+Shift+P to open the Command Palette. In the Command Palette, type wokwi. (Do not press Enter.)
Select Wokwi: Manually Enter License Key.
Paste the license key in and press Enter.

Creating a new PlatformIO ESP32 project and running it with Wokwi

Creating a new Wokwi diagram

Open the Wokwi website at https://wokwi.com/.
Click the ESP32 tile.
Scroll down to Starter Templates and select the first ESP32 tile.
Use the Wokwi diagram editor to add and wire up new components.

For more information about creating Wokwi diagrams, see the Interactive Diagram Editor page in the Wokwi documentation.
Once you've created a diagram, select the diagram.json tab. We will return here once we've created the PlatformIO project.

Creating a new PlatformIO project in Visual Studio Code

In Visual Studio Code, open the Explorer pane.
Click Open Folder.
Navigate to where you want to store the project files and then create a new folder for your project or select an existing folder.
Click Add.

You might receive a warning when you select the folder. If you do, click Yes to continue.
Click the New File button.
Name the new file platformio.ini.
Copy and paste the following configuration into platformio.ini. Then save the file.

Additional information about PlatformIO configuration is available in the PlatformIO documentation (Project Configuration File, ESP32 Dev Module).
```
[env:esp32dev]
platform = espressif32
framework = arduino
board = esp32dev
```
In the Explorer pane, click the New File button.
Name the new file wokwi.toml.
Copy and paste the following Wokwi configuration into the file. Then save the file.

This will tell Wokwi where to find the code compiled by PlatformIO.
```
[wokwi]
version = 1
elf = ".pio/build/esp32dev/firmware.elf"
firmware = ".pio/build/esp32dev/firmware.bin"
```

Adding the Wokwi diagram

In the Explorer pane, click the New File button.
Name the new file diagram.json.
Visual Studio Code will open diagram.json in the Wokwi editor. However, while you will not be able to use the editor in Visual Studio Code without a paid license, you can copy and paste in diagrams created using the online Wokwi editor.

Right-click the diagram.json tab.
Select Reopen Editor With....
Select Text Editor.
Copy and paste the contents of diagram.json in the online Wokwi editor to diagram.json in Visual Studio Code. Then save the file.

Adding the program code

In the Explore pane, click the New Folder button.
Name the new folder src.
In the src folder, create a new file with a name of your choice, with the file extension ino.
Add your program code to the rainbow_led_strip.ino file. Then save the file.

Building and running the program

Press Ctrl+Shift+P to open the Command Palette. In the Command Palette, type platformio. (Do not press Enter.)
Select PlatformIO: Open PlatformIO Core CLI.
A terminal window will appear at the bottom of the window. Type pio run and press Enter.
Press Ctrl+Shift+P to open the Command Palette. In the Command Palette, type wokwi. (Do not press Enter.)
Select Wokwi: Start Simulator.

The Wokwi simulator should show the diagram. Serial output will be displayed at the bottom of the window.

Optional: Installing libraries

If you would like to use libraries, you will need to install them using PlatformIO.

Press Ctrl+Shift+P to open the Command Palette. In the Command Palette, type platformio. (Do not press Enter.)
Select PlatformIO: PlatformIO Home.
Within the PlatformIO homepage, open the Libraries pane.
Enter the name of the library you want to install and press Enter.
Click on the library you want to install.
Click Add to Project.
In the project dropdown menu, select the folder for the current project.
Click Add.

You can now use the installed library.

Additional tips

Setting up a keyboard shortcut to run the Wokwi simulator

Press Ctrl+Shift+P to open the Command Palette. In the Command Palette, type wokwi. (Do not press Enter.)
Click the gear icon in the Wokwwi: Start Simulator entry.
Click the pencil icon next to Wokwi: Start Simulator.
Press the keyboard shortcut you want to use to start the Wokwi Simulator. Then press Enter.