You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
> **TL;DR:** Run and control your Wokwi simulations from Python with first-class type hints and zero boilerplate.
10
+
> **TL;DR:** Run and control your Wokwi simulations from Python with first-class type hints, zero boilerplate, and both async and synchronous APIs.
11
11
12
12
---
13
13
14
14
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.
15
15
16
-
Wokwi Python Client is a Python SDK for the Wokwi Simulation API. It allows you to run and control your Wokwi simulations from Python in a typed, asyncio-friendly way. You can use it to automate your embedded testing and development workflows.
16
+
Wokwi Python Client is a Python SDK for the Wokwi Simulation API. It provides two client interfaces:
17
+
18
+
-**`WokwiClient`**: Async client with full asyncio support for modern Python applications
19
+
-**`WokwiClientSync`**: Synchronous client that mirrors the async API for traditional blocking code
20
+
21
+
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.
17
22
18
23
## Installation requirements
19
24
@@ -27,20 +32,31 @@ pip install wokwi-client
27
32
28
33
## Running the examples
29
34
30
-
The basic example is in the [examples/hello_esp32/main.py](examples/hello_esp32/main.py) file. It shows how to:
35
+
### Async Example
36
+
37
+
The basic async example is in the [examples/hello_esp32/main.py](examples/hello_esp32/main.py) file. It shows how to:
31
38
32
39
- Connect to the Wokwi Simulator
33
40
- Upload a diagram and firmware files
34
41
- Start a simulation
35
42
- Monitor serial output asynchronously
36
43
37
-
You can run the example with:
44
+
You can run the async example with:
38
45
39
46
```bash
40
47
pip install -e .[dev]
41
48
python -m examples.hello_esp32.main
42
49
```
43
50
51
+
### Sync Example
52
+
53
+
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`:
54
+
55
+
```bash
56
+
pip install -e .[dev]
57
+
python -m examples.hello_esp32_sync.main
58
+
```
59
+
44
60
For more examples, see the [examples](examples) directory.
Copy file name to clipboardExpand all lines: docs/index.md
+41-4Lines changed: 41 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Wokwi Python Client Library
2
2
3
-
Typed, asyncio-friendly Python SDK for the **Wokwi Simulation API**.
3
+
TypedPython SDK for the **Wokwi Simulation API** with both async and synchronous interfaces.
4
4
5
5
## Features
6
6
@@ -9,7 +9,8 @@ Typed, asyncio-friendly Python SDK for the **Wokwi Simulation API**.
9
9
- Start, pause, resume, and restart simulations
10
10
- Monitor serial output asynchronously and write to them
11
11
- Control peripherals and read GPIO pins
12
-
- Fully type-annotated and easy to use with asyncio
12
+
- Fully type-annotated
13
+
- Two client interfaces: `WokwiClient` (async) and `WokwiClientSync` (sync)
13
14
14
15
## Installation
15
16
@@ -23,7 +24,9 @@ pip install wokwi-client
23
24
24
25
Get your API token from [https://wokwi.com/dashboard/ci](https://wokwi.com/dashboard/ci).
25
26
26
-
## Quickstart Example
27
+
## Quickstart Examples
28
+
29
+
### Async Client (WokwiClient)
27
30
28
31
```python
29
32
import asyncio
@@ -55,7 +58,41 @@ if __name__ == "__main__":
55
58
asyncio.run(main())
56
59
```
57
60
58
-
See the [examples/hello_esp32/main.py](https://github.com/wokwi/wokwi-python-client/blob/main/examples/hello_esp32/main.py) for a full example including serial monitoring, and [examples/micropython_esp32/main.py](https://github.com/wokwi/wokwi-python-client/blob/main/examples/micropython_esp32/main.py) for an example of running MicroPython on a simulated ESP32 board.
61
+
For a complete example, see [examples/hello_esp32/main.py](https://github.com/wokwi/wokwi-python-client/blob/main/examples/hello_esp32/main.py).
62
+
63
+
### Sync Client (WokwiClientSync)
64
+
65
+
```python
66
+
import os
67
+
from wokwi_client import WokwiClientSync, GET_TOKEN_URL
68
+
69
+
70
+
defmain():
71
+
token = os.getenv("WOKWI_CLI_TOKEN")
72
+
ifnot token:
73
+
raiseSystemExit(
74
+
f"Set WOKWI_CLI_TOKEN in your environment. You can get it from {GET_TOKEN_URL}."
75
+
)
76
+
77
+
client = WokwiClientSync(token)
78
+
client.connect()
79
+
client.upload_file("diagram.json")
80
+
client.upload_file("firmware.bin")
81
+
client.start_simulation(firmware="firmware.bin")
82
+
client.serial_monitor_cat() # Stream serial output
83
+
client.wait_until_simulation_time(10) # Run simulation for 10 seconds
84
+
client.disconnect()
85
+
86
+
87
+
if__name__=="__main__":
88
+
main()
89
+
```
90
+
91
+
For a complete example, see [examples/hello_esp32_sync/main.py](https://github.com/wokwi/wokwi-python-client/blob/main/examples/hello_esp32_sync/main.py).
92
+
93
+
### MicroPython Example
94
+
95
+
See [examples/micropython_esp32/main.py](https://github.com/wokwi/wokwi-python-client/blob/main/examples/micropython_esp32/main.py) for an example of running MicroPython on a simulated ESP32 board.
0 commit comments