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.9
• 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.

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.