feat: add synchronous client wrapper and example usage for Wokwi simulation

Author: JakubAndrysek

README.md

@@ -1,6 +1,6 @@
 # Wokwi Python Client 🚀
 
-Typed, asyncio-friendly Python SDK for the **Wokwi Simulation API**
+Typed Python SDK for the **Wokwi Simulation API**, with async and sync APIs
 
 [![PyPI version](https://img.shields.io/pypi/v/wokwi-client?logo=pypi)](https://pypi.org/project/wokwi-client/)
 [![Python versions](https://img.shields.io/pypi/pyversions/wokwi-client)](https://pypi.org/project/wokwi-client/)

docs/index.md

@@ -1,6 +1,6 @@
 # Wokwi Python Client Library
 
-Typed, asyncio-friendly Python SDK for the **Wokwi Simulation API**.
+Typed Python SDK for the **Wokwi Simulation API**, with async and sync APIs.
 
 ## Features
 
@@ -10,6 +10,7 @@ Typed, asyncio-friendly Python SDK for the **Wokwi Simulation API**.
 - Monitor serial output asynchronously and write to them
 - Control peripherals and read GPIO pins
 - Fully type-annotated and easy to use with asyncio
+- Async and sync APIs
 
 ## Installation
 
@@ -25,37 +26,74 @@ Get your API token from [https://wokwi.com/dashboard/ci](https://wokwi.com/dashb
 
 ## Quickstart Example
 
-```python
-import asyncio
-import os
-from wokwi_client import WokwiClient, GET_TOKEN_URL
-
-
-async def main():
-    token = os.getenv("WOKWI_CLI_TOKEN")
-    if not token:
-        raise SystemExit(
-            f"Set WOKWI_CLI_TOKEN in your environment. You can get it from {GET_TOKEN_URL}."
-        )
-
-    client = WokwiClient(token)
-    await client.connect()
-    await client.upload_file("diagram.json")
-    await client.upload_file("firmware.bin")
-    await client.start_simulation(firmware="firmware.bin")
-    serial_task = asyncio.create_task(
-        client.serial_monitor_cat()
-    )  # Stream serial output
-    await client.wait_until_simulation_time(10)  # Run simulation for 10 seconds
-    serial_task.cancel()
-    await client.disconnect()
-
-
-if __name__ == "__main__":
-    asyncio.run(main())
-```
+=== "Async (recommended)"
+
+    ```python
+    import asyncio
+    import os
+    from wokwi_client import WokwiClient, GET_TOKEN_URL
+
+
+    async def main():
+        token = os.getenv("WOKWI_CLI_TOKEN")
+        if not token:
+            raise SystemExit(
+                f"Set WOKWI_CLI_TOKEN in your environment. You can get it from {GET_TOKEN_URL}."
+            )
+
+        client = WokwiClient(token)
+        await client.connect()
+        await client.upload_file("diagram.json")
+        await client.upload_file("firmware.bin")
+        await client.start_simulation(firmware="firmware.bin")
+
+        serial_task = asyncio.create_task(
+            client.serial_monitor_cat()
+        )  # Stream serial output
+        await client.wait_until_simulation_time(10)  # Run simulation for 10 seconds
+        serial_task.cancel()
+        await client.disconnect()
+
+
+    if __name__ == "__main__":
+        asyncio.run(main())
+    ```
+
+=== "Sync"
+
+    ```python
+    import os
+    from wokwi_client import WokwiClientSync, GET_TOKEN_URL
+
+
+    def main():
+        token = os.getenv("WOKWI_CLI_TOKEN")
+        if not token:
+            raise SystemExit(
+                f"Set WOKWI_CLI_TOKEN in your environment. You can get it from {GET_TOKEN_URL}."
+            )
+
+        client = WokwiClientSync(token)
+        client.connect()
+        client.upload_file("diagram.json")
+        client.upload_file("firmware.bin")
+        client.start_simulation(firmware="firmware.bin")
+
+        # Stream serial output concurrently for 10 seconds
+        client.monitor_serial(lambda line: print(line.decode("utf-8"), end="", flush=True))
+        client.wait_until_simulation_time(10)
+        client.disconnect()
+
+
+    if __name__ == "__main__":
+        main()
+    ```
+
+## Examples
 
-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.
+- [examples/hello_esp32/main.py](https://github.com/wokwi/wokwi-python-client/blob/main/examples/hello_esp32/main.py) full async example including serial monitoring
+- [examples/hello_esp32_sync/main.py](https://github.com/wokwi/wokwi-python-client/blob/main/examples/hello_esp32_sync/main.py) sync wrapper usage
+- [examples/micropython_esp32/main.py](https://github.com/wokwi/wokwi-python-client/blob/main/examples/micropython_esp32/main.py) example of running MicroPython on a simulated ESP32 board.
 
 ## API Reference
 

examples/hello_esp32_sync/.gitignore

@@ -0,0 +1,3 @@
+# Ignore the firmware files, as they are downloaded from the internet
+hello_world.bin
+hello_world.elf

examples/hello_esp32_sync/__init__.py

@@ -0,0 +1,22 @@
+{
+  "version": 1,
+  "author": "Uri Shaked",
+  "editor": "wokwi",
+  "parts": [
+    {
+      "type": "wokwi-esp32-devkit-v1",
+      "id": "esp",
+      "top": 0,
+      "left": 0,
+      "attrs": { "fullBoot": "1" }
+    }
+  ],
+  "connections": [
+    ["esp:TX0", "$serialMonitor:RX", "", []],
+    ["esp:RX0", "$serialMonitor:TX", "", []]
+  ],
+  "serialMonitor": {
+    "display": "terminal"
+  },
+  "dependencies": {}
+}

examples/hello_esp32_sync/diagram.json

@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: MIT
+# Copyright (C) 2025, CodeMagic LTD
+
+import os
+from pathlib import Path
+
+import requests
+
+from wokwi_client import GET_TOKEN_URL, WokwiClientSync
+
+EXAMPLE_DIR = Path(__file__).parent
+HELLO_WORLD_URL = "https://github.com/wokwi/esp-idf-hello-world/raw/refs/heads/main/bin"
+FIRMWARE_FILES = {
+    "hello_world.bin": f"{HELLO_WORLD_URL}/hello_world.bin",
+    "hello_world.elf": f"{HELLO_WORLD_URL}/hello_world.elf",
+}
+SLEEP_TIME = int(os.getenv("WOKWI_SLEEP_TIME", "10"))
+
+
+def main() -> None:
+    token = os.getenv("WOKWI_CLI_TOKEN")
+    if not token:
+        raise SystemExit(
+            f"Set WOKWI_CLI_TOKEN in your environment. You can get it from {GET_TOKEN_URL}."
+        )
+
+    for filename, url in FIRMWARE_FILES.items():
+        if (EXAMPLE_DIR / filename).exists():
+            continue
+        print(f"Downloading {filename} from {url}")
+        response = requests.get(url)
+        response.raise_for_status()
+        with open(EXAMPLE_DIR / filename, "wb") as f:
+            f.write(response.content)
+
+    client = WokwiClientSync(token)
+    print(f"Wokwi client library version: {client.version}")
+
+    hello = client.connect()
+    print("Connected to Wokwi Simulator, server version:", hello["version"])
+
+    # Upload the diagram and firmware files
+    client.upload_file("diagram.json", EXAMPLE_DIR / "diagram.json")
+    client.upload_file("hello_world.bin", EXAMPLE_DIR / "hello_world.bin")
+    client.upload_file("hello_world.elf", EXAMPLE_DIR / "hello_world.elf")
+
+    # Start the simulation
+    client.start_simulation(
+        firmware="hello_world.bin",
+        elf="hello_world.elf",
+    )
+
+    # Stream serial output for a few seconds (non-blocking)
+    client.monitor_serial(lambda line: print(line.decode("utf-8"), end="", flush=True))
+    print(f"Simulation started, waiting for {SLEEP_TIME} seconds…")
+    client.wait_until_simulation_time(SLEEP_TIME)
+
+    # Disconnect from the simulator
+    client.disconnect()
+
+
+if __name__ == "__main__":
+    main()

examples/hello_esp32_sync/main.py

@@ -42,6 +42,8 @@ markdown_extensions:
     - pymdownx.inlinehilite
     - pymdownx.superfences
     - pymdownx.tabbed
+    - pymdownx.tabbed:
+        alternate_style: true
     - toc:
           permalink: "¶"
 

mkdocs.yml

@@ -12,7 +12,8 @@
 
 from .__version__ import get_version
 from .client import WokwiClient
+from .client_sync import WokwiClientSync
 from .constants import GET_TOKEN_URL
 
 __version__ = get_version()
-__all__ = ["WokwiClient", "__version__", "GET_TOKEN_URL"]
+__all__ = ["WokwiClient", "WokwiClientSync", "__version__", "GET_TOKEN_URL"]