# Wokwi Python Client 🚀
Typed Python SDK for the **Wokwi Simulation API** with both async and synchronous interfaces
[](https://pypi.org/project/wokwi-client/)
[](https://pypi.org/project/wokwi-client/)
[](https://github.com/wokwi/wokwi-python-client/actions/workflows/ci.yaml)
[](LICENSE)
> **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](https://docs.wokwi.com/getting-started/supported-hardware), 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](https://wokwi.com/dashboard/ci).
Install the library with:
```bash
pip install wokwi-client
```
## Running the examples
### Async Example
The basic async example is in the [examples/hello_esp32/main.py](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:
```bash
pip install -e .[dev]
python -m examples.hello_esp32.main
```
### Sync Example
The synchronous example is in the [examples/hello_esp32_sync/main.py](examples/hello_esp32_sync/main.py) file. It demonstrates the same functionality using the blocking `WokwiClientSync`:
```bash
pip install -e .[dev]
python -m examples.hello_esp32_sync.main
```
For more examples, see the [examples](examples) directory.
## Documentation
The API documentation is available at [https://wokwi.github.io/wokwi-python-client/](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](https://wokwi.com/dashboard/ci)) and run the following command:
```bash
hatch run dev:pytest
```
To run the linter, run the following command:
```bash
hatch run ruff format --check .
hatch run ruff check .
```
To run the type checker, run the following command:
```bash
hatch run mypy .
```
### Creating a new release
To create a new release, run the following commands:
```bash
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](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "wokwi-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "api, arduino, asyncio, avr, esp32, python, rp2040, simulation, wokwi",
"author": null,
"author_email": "Uri Shaked <uri@wokwi.com>",
"download_url": "https://files.pythonhosted.org/packages/9e/d6/e018774a6afa63a9796909bbefb2fe7ac72512cd73ce8544f9277ad300cd/wokwi_client-0.2.0.tar.gz",
"platform": null,
"description": "# Wokwi Python Client \ud83d\ude80\n\nTyped Python SDK for the **Wokwi Simulation API** with both async and synchronous interfaces\n\n[](https://pypi.org/project/wokwi-client/)\n[](https://pypi.org/project/wokwi-client/)\n[](https://github.com/wokwi/wokwi-python-client/actions/workflows/ci.yaml)\n[](LICENSE)\n\n> **TL;DR:** Run and control your Wokwi simulations from Python with first-class type hints, zero boilerplate, and both async and synchronous APIs.\n\n---\n\nWokwi 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](https://docs.wokwi.com/getting-started/supported-hardware), including sensors, displays, motors, and debugging tools.\n\nWokwi Python Client is a Python SDK for the Wokwi Simulation API. It provides two client interfaces:\n\n- **`WokwiClient`**: Async client with full asyncio support for modern Python applications\n- **`WokwiClientSync`**: Synchronous client that mirrors the async API for traditional blocking code\n\nBoth 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.\n\n## Installation requirements\n\n- Python \u2265 3.9\n- An API token from [https://wokwi.com/dashboard/ci](https://wokwi.com/dashboard/ci).\n\nInstall the library with:\n```bash\npip install wokwi-client\n```\n\n## Running the examples\n\n### Async Example\n\nThe basic async example is in the [examples/hello_esp32/main.py](examples/hello_esp32/main.py) file. It shows how to:\n\n- Connect to the Wokwi Simulator\n- Upload a diagram and firmware files\n- Start a simulation\n- Monitor serial output asynchronously\n\nYou can run the async example with:\n\n```bash\npip install -e .[dev]\npython -m examples.hello_esp32.main\n```\n\n### Sync Example\n\nThe synchronous example is in the [examples/hello_esp32_sync/main.py](examples/hello_esp32_sync/main.py) file. It demonstrates the same functionality using the blocking `WokwiClientSync`:\n\n```bash\npip install -e .[dev]\npython -m examples.hello_esp32_sync.main\n```\n\nFor more examples, see the [examples](examples) directory.\n\n## Documentation\n\nThe API documentation is available at [https://wokwi.github.io/wokwi-python-client/](https://wokwi.github.io/wokwi-python-client/).\n\n## Development\n\nTo run the tests, set the `WOKWI_CLI_TOKEN` environment variable (you can get a token from [https://wokwi.com/dashboard/ci](https://wokwi.com/dashboard/ci)) and run the following command:\n\n```bash\nhatch run dev:pytest\n```\n\nTo run the linter, run the following command:\n\n```bash\nhatch run ruff format --check .\nhatch run ruff check .\n```\n\nTo run the type checker, run the following command:\n\n```bash\nhatch run mypy .\n```\n\n### Creating a new release\n\nTo create a new release, run the following commands:\n\n```bash\ngit tag -m \"v0.0.6\" v0.0.6\ngit push --follow-tags\n```\n\nReplace `0.0.6` with the new version number.\n\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "Typed Python SDK for the Wokwi Simulation API with both async and synchronous interfaces",
"version": "0.2.0",
"project_urls": {
"Documentation": "https://github.com/wokwi/wokwi-python-client#readme",
"Issues": "https://github.com/wokwi/wokwi-python-client/issues",
"Source": "https://github.com/wokwi/wokwi-python-client"
},
"split_keywords": [
"api",
" arduino",
" asyncio",
" avr",
" esp32",
" python",
" rp2040",
" simulation",
" wokwi"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "be92266511663775789a661068328953d5f5d2185a16238530196d59ee8234c6",
"md5": "54dae6460f77cc9265f5b6bda44d240d",
"sha256": "bf7869f73844fcdc6963a87b447381dfbc5e1b6931a8118b144a1258d45d9244"
},
"downloads": -1,
"filename": "wokwi_client-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "54dae6460f77cc9265f5b6bda44d240d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 24333,
"upload_time": "2025-09-07T10:57:14",
"upload_time_iso_8601": "2025-09-07T10:57:14.874459Z",
"url": "https://files.pythonhosted.org/packages/be/92/266511663775789a661068328953d5f5d2185a16238530196d59ee8234c6/wokwi_client-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9ed6e018774a6afa63a9796909bbefb2fe7ac72512cd73ce8544f9277ad300cd",
"md5": "b81fa4d69b087ae69c1e11e401298ee9",
"sha256": "150ad362540b7a08b08b2beda11d16c92224755b582104c8c337ea5ca704cd0e"
},
"downloads": -1,
"filename": "wokwi_client-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "b81fa4d69b087ae69c1e11e401298ee9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 20710,
"upload_time": "2025-09-07T10:57:15",
"upload_time_iso_8601": "2025-09-07T10:57:15.962990Z",
"url": "https://files.pythonhosted.org/packages/9e/d6/e018774a6afa63a9796909bbefb2fe7ac72512cd73ce8544f9277ad300cd/wokwi_client-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-07 10:57:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wokwi",
"github_project": "wokwi-python-client#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "wokwi-client"
}
JSON
