# Wokwi

[中文]

## What Is Wokwi?

Wokwi is an online electronics simulator. You can use it to simulate most of the 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.

- 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 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 three ways:

Browser-based (Online)

  Visit wokwi.com to start simulating immediately in your browser. No installation required.

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

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

## IDE Integration

VS Code

To use Wokwi with VS Code:

1. Install the Wokwi for VS Code extension.

2. Create `wokwi.toml` and `diagram.json` files in your project.

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

- pytest-embedded-wokwi Documentation

- ESP-IDF Tests with Pytest Guide

- pytest-embedded 2.x Documentation

## Advanced Features

Debugging

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

1. Add to `wokwi.toml`:

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

2. 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"
           }
         ]
       }

3. Start simulator with `F1` → `Wokwi: Start Simulator and Wait for Debugger`.

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