feat: wait_until_simulation_time() method for better simulation control

Added a new method in WokwiClient to pause the simulation and wait for a specified duration.

Updated the hello_esp32 example to use this new method. This will make the simulation results predictable and repeatable.

Author: urish

examples/hello_esp32/main.py

@@ -54,7 +54,7 @@ async def main() -> None:
     # Stream serial output for a few seconds
     serial_task = asyncio.create_task(client.serial_monitor_cat())
     print(f"Simulation started, waiting for {SLEEP_TIME} seconds…")
-    await asyncio.sleep(SLEEP_TIME)
+    await client.wait_until_simulation_time(SLEEP_TIME)
     serial_task.cancel()
 
     # Disconnect from the simulator

src/wokwi_client/client.py

@@ -7,19 +7,24 @@
 
 from .__version__ import get_version
 from .constants import DEFAULT_WS_URL
+from .event_queue import EventQueue
 from .file_ops import upload, upload_file
-from .protocol_types import ResponseMessage
+from .protocol_types import EventMessage, ResponseMessage
 from .serial import monitor_lines
 from .simulation import pause, restart, resume, start
 from .transport import Transport
 
 
 class WokwiClient:
     version: str
+    last_pause_nanos: int
 
     def __init__(self, token: str, server: Optional[str] = None):
         self.version = get_version()
         self._transport = Transport(token, server or DEFAULT_WS_URL)
+        self.last_pause_nanos = 0
+        self._transport.add_event_listener("sim:pause", self._on_pause)
+        self._pause_queue = EventQueue(self._transport, "sim:pause")
 
     async def connect(self) -> dict[str, Any]:
         return await self._transport.connect()
@@ -44,9 +49,20 @@ async def pause_simulation(self) -> ResponseMessage:
     async def resume_simulation(self, pause_after: Optional[int] = None) -> ResponseMessage:
         return await resume(self._transport, pause_after)
 
+    async def wait_until_simulation_time(self, seconds: float) -> None:
+        await pause(self._transport)
+        remaining_nanos = seconds * 1e9 - self.last_pause_nanos
+        if remaining_nanos > 0:
+            self._pause_queue.flush()
+            await resume(self._transport, int(remaining_nanos))
+            await self._pause_queue.get()
+
     async def restart_simulation(self, pause: bool = False) -> ResponseMessage:
         return await restart(self._transport, pause)
 
     async def serial_monitor_cat(self) -> None:
         async for line in monitor_lines(self._transport):
             print(line.decode("utf-8"), end="", flush=True)
+
+    def _on_pause(self, event: EventMessage) -> None:
+        self.last_pause_nanos = int(event["nanos"])