Wokwi

What Is Wokwi?

Wokwi is an online electronics simulator. You can use it to simulate most Espressif chips and supported parts and sensors.

Wokwi provides a browser-based interface and IDE integrations that offer a simple and intuitive way to start coding your next IoT project within seconds. It supports ESP-IDF projects and provides Wi-Fi simulation, virtual logic analyzers, advanced debugging with GDB and screenshot capture for automated testing.

Key Features

Wokwi provides many features for embedded development:

Wi-Fi Simulation: Test IoT projects without physical hardware.
Virtual Logic Analyzers: Debug digital signals and timing.
Advanced GDB Debugging: Set breakpoints and inspect variables.
idf.py Integration: Use the familiar idf.py interface to control Wokwi (see Set Up a Project with idf-wokwi).
VS Code Integration: Develop and simulate directly from VS Code.
CLion Plugin: Professional development workflow with CLion.
Screenshot Capture: Automated visual testing for CI/CD.
Custom Chips API: Build your own virtual chips in addition to the main MCU.

Note

Simulation results may differ from real hardware. Always test your project on actual hardware before deployment.

Installation

Wokwi can be used in the following ways:

Browser-based (Online): Visit wokwi.com to start simulating immediately in your browser. No installation required.
Via idf.py using the idf-wokwi package: Install the idf-wokwi package to integrate Wokwi controls directly into idf.py.
VS Code Extension: Install the Wokwi for VS Code extension to integrate simulation directly into your development environment.
CLion Plugin: Install the Wokwi Simulator plugin for CLion to use Wokwi with professional IDE features and embedded development tools.

Configuration

Set Up a Project with wokwi-cli

For local development and CI/CD integration, you can use wokwi-cli to configure your ESP-IDF project for Wokwi simulation.

To install wokwi-cli, please refer to the official Wokwi CLI installation guide.

Once installed, run the following command in your ESP-IDF project directory:

wokwi-cli init

The wokwi-cli init command will prompt you with a few questions and automatically create the necessary configuration files in your project directory.

Wokwi projects are configured using two main files:

wokwi.toml: A configuration file that specifies firmware paths, ELF files for debugging, and simulator settings.
diagram.json: A circuit diagram file that describes the board, connected components, and their wiring.

For detailed information about configuration files, see the Wokwi project configuration guide.

You are encouraged to read the official ESP32 Simulation guide to understand which boards, languages, and features are supported by Wokwi.

Set Up a Project with idf-wokwi

Similar to wokwi-cli, you can use idf-wokwi for local development and CI/CD integration. The advantage of using idf-wokwi is not only that the workflow remains within idf.py, but also that Wokwi will be able to automatically fetch information from ESP-IDF. This avoids the need for wokwi.toml and diagram.json to exist — Wokwi will implicitly generate these files.

Choose Between wokwi-cli and idf-wokwi

Comparison of Wokwi integration options
Feature	`wokwi-cli`	`idf-wokwi`
Config files	Required (`wokwi.toml` and `diagram.json`)	Auto-generated from ESP-IDF
Build integration	Manual (build first, then simulate)	Automatic via `idf.py`
ESP-IDF version	Any version	6.0 or greater only
Use case	Non-ESP-IDF projects, custom workflows	ESP-IDF 6.0+ projects, native workflow

Prerequisites

Before using idf-wokwi, ensure that you have:

ESP-IDF 6.0 or greater (idf.py module extensions require this)
Wokwi API token (You can create an API token on the Wokwi CI Dashboard)

Getting Started

Install and configure idf-wokwi:

# Install the package
pip install idf-wokwi

# Set your API token
export WOKWI_CLI_TOKEN=your_token_here

# Run simulation
idf.py wokwi

Important

Module extensions to idf.py are only supported on ESP-IDF versions 6.0 or greater.

Tip

idf.py wokwi automatically builds your project before simulation. Skip build with idf.py wokwi --no-build if firmware already exists.

Available CLI Options

`idf.py wokwi` command options
Option	Description
`--diagram-file`	Path to `diagram.json` (defaults to project root)
`--timeout`	Simulation timeout in milliseconds (exit code 42 on timeout)
`--expect-text`	Exit successfully when this text appears in serial output
`--fail-text`	Exit with error when this text appears in serial output
`--expect-regex`	Exit successfully when this regex matches a serial output line
`--fail-regex`	Exit with error when this regex matches a serial output line

Example Output

Running idf.py wokwi produces output similar to the following:

$ idf.py wokwi
Running Wokwi simulation...
Firmware: build/your_project.bin
ELF: build/your_project.elf
Simulator ready at: https://wokwi.com/...
Press Ctrl+C to stop...

I (123) main: Hello, World!
I (145) main: System initialized

Troubleshooting

Module not found or No module named 'idf_wokwi'
Verify that idf-wokwi is installed in the same Python environment used by ESP-IDF:
pip show idf-wokwi xtensa-esp32-elf-gdb --version # Verify ESP-IDF environment
idf.py: error: no such option: wokwi

Your ESP-IDF version is earlier than 6.0 and does not support module extensions. Upgrade ESP-IDF or use wokwi-cli instead.
Invalid token or 401 Unauthorized
Verify that WOKWI_CLI_TOKEN is set correctly:
echo $WOKWI_CLI_TOKEN # Should show your token, not empty
Get a new token at Wokwi CI Dashboard if needed.

CI/CD Integration

For automated testing in CI/CD pipelines, idf-wokwi integrates seamlessly with GitHub Actions:

- name: Simulate with Wokwi
  run: |
    export WOKWI_CLI_TOKEN=${{ secrets.WOKWI_CLI_TOKEN }}
    idf.py wokwi --timeout 30000 --expect-text "Tests passed"

Note

Store your WOKWI_CLI_TOKEN as a secret in your CI/CD platform (e.g., GitHub Secrets). Never commit tokens to the repository.

For automated testing frameworks, also see the Testing with pytest-embedded section below.

Additional documentation is available on the official Wokwi ESP-IDF simulation extension usage page.

IDE Integration

VS Code

To use Wokwi with VS Code:

Install the Wokwi for VS Code extension.
Create wokwi.toml and diagram.json files in your project.
Press F1 and select Wokwi: Start Simulator to begin simulation.

CLion

The Wokwi Simulator plugin for CLion provides:

Integration with CLion's embedded development tools.
Professional debugging workflow.
Support for ESP-IDF projects.
Seamless simulator access from the IDE.

Espressif IDE

Version 2.9.0 and later of Espressif IDE includes Wokwi integration:

Build applications in the IDE.
Flash directly to the Wokwi simulator.
View serial monitor output in the IDE console while communicating with the simulator.

Testing with pytest-embedded

Wokwi integrates with ESP-IDF's testing framework through pytest-embedded-wokwi. This enables:

Automated unit and integration testing.
CI/CD pipeline integration with GitHub Actions.
Screenshot validation for visual testing.
Regression testing without physical hardware.

Basic Usage

Run Wokwi simulations from the command line with wokwi-cli:

# Run simulation and expect specific text in output
wokwi-cli --timeout 5000 --expect-text "Hello World"

# Take a screenshot after 4.5 seconds
wokwi-cli --screenshot-part esp --screenshot-time 4500 --screenshot-file screenshot.png

# Save serial output to a file
wokwi-cli --serial-log-file output.log --timeout 10000

For a complete project template with CI/CD configured, see the ESP-IDF Project Template with CI and Wokwi.

Related Resources

Advanced Features

Debugging

Wokwi provides built-in GDB server support for advanced debugging:

Add to wokwi.toml:

[wokwi]
version = 1
firmware = 'build/your_app.bin'
elf = 'build/your_app.elf'
gdbServerPort = 3333

Create a VS Code launch configuration (.vscode/launch.json):

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Wokwi GDB",
      "type": "cppdbg",
      "request": "launch",
      "program": "${workspaceFolder}/build/your_app.elf",
      "cwd": "${workspaceFolder}",
      "MIMode": "gdb",
      "miDebuggerPath": "xtensa-esp32-elf-gdb",
      "miDebuggerServerAddress": "localhost:3333"
    }
  ]
}

Start simulator with F1 → Wokwi: Start Simulator and Wait for Debugger.
Press F5 in VS Code to attach the debugger.

For more details, see the Wokwi debugging guide.

Wi-Fi Networking

Wokwi supports Wi-Fi simulation for IoT projects. See the ESP32 Wi-Fi networking guide for information on:

Connecting to Wi-Fi networks.
MQTT, HTTP, and HTTPS protocols.
WebSocket communication.
Network testing without physical hardware.

CI/CD Integration

Automate testing in GitHub Actions using Wokwi:

- name: Simulate & take screenshot
  run: |
    wokwi-cli \
      --screenshot-part "esp" \
      --screenshot-time 5000 \
      --screenshot-file "screenshot-${{ matrix.board }}.png" \
      "boards/${{ matrix.board }}"

- name: Upload screenshot
  uses: actions/upload-artifact@v4
  with:
    name: screenshot-${{ matrix.board }}
    path: screenshot-${{ matrix.board }}.png

This enables automated visual regression testing and ensures consistent behavior across commits.

Resources

Videos

DevCon24 - Flash Less, Do More: The Magic of Virtual Hardware: Learn about the power of simulation for embedded development

Documentation

Wokwi Documentation: Comprehensive resource for all Wokwi features
ESP32 Simulation Guide: Supported boards, languages, and features
ESP32 Wi-Fi Networking: Wi-Fi simulation for IoT projects
VS Code Integration: Setup and configuration guide
CLion Plugin: CLion integration details
Wokwi Articles on Developer Portal: Collection of tutorials and use cases

Getting Help

Wokwi Community: Join the Wokwi Discord server to get help from the community

Was this page helpful?

Thank you! We received your feedback.
If you have any comments, fill in Espressif Documentation Feedback Form.

We value your feedback.
Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.