Skip to main content
The idf-wokwi Python package adds simulation support directly to Espressif’s idf.py command. From idf.py, you can run a simulation and pass a selection of options to customize its behavior. Unlike wokwi-cli, you don’t need to initialize a project as idf-wokwi will implicitly generate the relevant files (wokwi.toml/diagram.json) by inferring information from ESP-IDF. You can however still add your own files if you require other components.

​
Getting Started

1

Create an API Token

Create an API token on the Wokwi CI Dashboard. Set the WOKWI_CLI_TOKEN environment variable to the token value.
2

Install the Extension

Install the extension with the following command:
pip install idf-wokwi
3

Run a Simulation

You can now run a simulation by executing:
idf.py wokwi

​
CLI Options

Pass any selection of the following commands to idf.py wokwi to customize its behavior during runtime.
​
--diagram-file
string
Path to diagram.json (defaults to project root)
​
--timeout
number
Simulation timeout in milliseconds (exit code 42 on timeout)
​
--expect-text
string
Exit successfully when this text appears in serial output
​
--fail-text
string
Exit with error when this text appears in serial output
​
--expect-regex
string
Exit successfully when this regex matches a serial output line
​
--fail-regex
string
Exit with error when this regex matches a serial output line

​
Example Usage

export WOKWI_CI_TOKEN="your-token-here"

# Build and simulate
idf.py build
idf.py wokwi

# CI mode: exit when expected text appears
idf.py wokwi --timeout 10000 --expect-text "Hello world!"
The idf-wokwi extension automatically detects your ESP-IDF project configuration and generates the necessary Wokwi files, making it easy to get started with CI testing.

Build docs developers (and LLMs) love

Get started for freeTalk to us