Wokwi Python Client 🚀

Typed Python SDK for the Wokwi Simulation API with both async and synchronous interfaces

TL;DR: Run and control your Wokwi simulations from Python with first-class type hints, zero boilerplate, and both async and synchronous APIs.

---

Wokwi is a platform for creating and running simulations of electronic circuits and embedded systems. It supports a wide range of hardware platforms, including ESP32 family, Arduino, Raspberry Pi, STM32 and more.In addition, it supports a wide range of peripherals, including sensors, displays, motors, and debugging tools.

Wokwi Python Client is a Python SDK for the Wokwi Simulation API. It provides two client interfaces:

• WokwiClient: Async client with full asyncio support for modern Python applications
• WokwiClientSync: Synchronous client that mirrors the async API for traditional blocking code

Both clients allow you to run and control your Wokwi simulations from Python in a typed, easy-to-use way. You can use them to automate your embedded testing and development workflows.

Installation requirements

• Python ≥ 3.10
• An API token from https://wokwi.com/dashboard/ci.

Install the library with:

pip install wokwi-client

Running the examples

Async Example

The basic async example is in the examples/hello_esp32/main.py file. It shows how to:

• Connect to the Wokwi Simulator
• Upload a diagram and firmware files
• Start a simulation
• Monitor serial output asynchronously

You can run the async example with:

pip install -e .[dev]
python -m examples.hello_esp32.main

Sync Example

The synchronous example is in the examples/hello_esp32_sync/main.py file. It demonstrates the same functionality using the blocking WokwiClientSync:

pip install -e .[dev]
python -m examples.hello_esp32_sync.main

ESP-IDF Example

The ESP-IDF example is in the examples/hello_esp32_idf/main.py file. It demonstrates uploading ESP-IDF firmware using flasher_args.json:

pip install -e .[dev]
python -m examples.hello_esp32_idf.main

For more examples, see the examples directory.

Micro SD card

If the diagram includes a micro SD card, upload its files under a common prefix and describe the card when starting the simulation. When the simulation is paused, the card contents can be read back as files or as a raw disk image:

from wokwi_client import SDCardConfig

await client.upload("sdcard/config.json", b'{"volume": 7}')
await client.start_simulation(firmware="firmware.bin", sdcards=[SDCardConfig(prefix="sdcard/")])
...
await client.pause_simulation()
for file in await client.export_sdcard_files():
    print(file.name, len(file.content))
image = await client.export_sdcard_image()  # raw FAT image, e.g. to save as card.img

To upload a whole directory in one call, use card = await client.upload_sdcard_folder("sdcard") and pass sdcards=[card]. Use SDCardConfig(image="card.img") to serve an uploaded raw disk image instead, size_bytes to pick the card capacity (default 8 MB), and part to address a specific card when the diagram has several.

Documentation

The API documentation is available at https://wokwi.github.io/wokwi-python-client/.

Development

To run the tests, set the WOKWI_CLI_TOKEN environment variable (you can get a token from https://wokwi.com/dashboard/ci) and run the following command:

hatch run dev:pytest

To run the linter, run the following command:

hatch run ruff format --check .
hatch run ruff check .

To run the type checker, run the following command:

hatch run mypy .

Creating a new release

To create a new release, run the following commands:

git tag -m "v0.0.6" v0.0.6
git push --follow-tags

Replace 0.0.6 with the new version number.

License

This project is licensed under the MIT License. See the LICENSE file for details.