feat: add pin control and reading functionalities

Author: JakubAndrysek

src/wokwi_client/client.py

@@ -7,8 +7,10 @@
 
 from .__version__ import get_version
 from .constants import DEFAULT_WS_URL
+from .control import set_control
 from .event_queue import EventQueue
 from .file_ops import upload, upload_file
+from .pins import pin_listen, pin_read
 from .protocol_types import EventMessage, ResponseMessage
 from .serial import monitor_lines
 from .simulation import pause, restart, resume, start
@@ -181,3 +183,35 @@ async def serial_monitor_cat(self) -> None:
 
     def _on_pause(self, event: EventMessage) -> None:
         self.last_pause_nanos = int(event["nanos"])
+
+    async def read_pin(self, part: str, pin: str) -> ResponseMessage:
+        """Read the current state of a pin.
+
+        Args:
+            part: The part id (e.g. "uno").
+            pin: The pin name (e.g. "A2").
+        """
+        return await pin_read(self._transport, part=part, pin=pin)
+
+    async def listen_pin(self, part: str, pin: str, listen: bool = True) -> ResponseMessage:
+        """Start or stop listening for changes on a pin.
+
+        When enabled, "pin:change" events will be delivered via the transport's
+        event mechanism.
+
+        Args:
+            part: The part id.
+            pin: The pin name.
+            listen: True to start listening, False to stop.
+        """
+        return await pin_listen(self._transport, part=part, pin=pin, listen=listen)
+
+    async def set_control(self, part: str, control: str, value: int | bool | float) -> ResponseMessage:
+        """Set a control value (e.g. simulate button press).
+
+        Args:
+            part: Part id (e.g. "btn1").
+            control: Control name (e.g. "pressed").
+            value: Control value to set (float).
+        """
+        return await set_control(self._transport, part=part, control=control, value=value)

src/wokwi_client/control.py

@@ -0,0 +1,31 @@
+"""Control command helpers for virtual parts.
+
+Provides `set_control` to manipulate part controls (e.g. press a button).
+
+Assumptions:
+* Underlying websocket command name: "control:set".
+* Parameter names expected by server: part, control, value.
+"""
+
+# SPDX-FileCopyrightText: 2025-present CodeMagic LTD
+#
+# SPDX-License-Identifier: MIT
+
+from .protocol_types import ResponseMessage
+from .transport import Transport
+
+
+async def set_control(
+    transport: Transport, *, part: str, control: str, value: int | bool | float
+) -> ResponseMessage:
+    """Set a control value on a part (e.g. simulate button press/release).
+
+    Args:
+        transport: Active Transport.
+        part: Part identifier (e.g. "btn1").
+        control: Control name (e.g. "pressed").
+        value: Control value to set (float).
+    """
+    return await transport.request(
+        "control:set", {"part": part, "control": control, "value": float(value)}
+    )

src/wokwi_client/pins.py

@@ -0,0 +1,49 @@
+"""Pin command helpers for the Wokwi Simulation API.
+
+This module exposes helper coroutines for issuing pin-related commands:
+
+* pin:read   - Read the current state of a pin.
+* pin:listen - Start/stop listening for changes on a pin (emits pin:change
+    events).
+"""
+
+# SPDX-FileCopyrightText: 2025-present CodeMagic LTD
+#
+# SPDX-License-Identifier: MIT
+
+from .protocol_types import ResponseMessage
+from .transport import Transport
+
+
+async def pin_read(
+    transport: Transport, *, part: str, pin: str
+) -> ResponseMessage:
+    """Read the state of a pin.
+
+    Args:
+        transport: The active Transport instance.
+        part: Part identifier (e.g. "uno").
+        pin: Pin name (e.g. "A2", "13").
+    """
+
+    return await transport.request("pin:read", {"part": part, "pin": pin})
+
+
+async def pin_listen(
+    transport: Transport, *, part: str, pin: str, listen: bool = True
+) -> ResponseMessage:
+    """Enable or disable listening for changes on a pin.
+
+    When listening is enabled, "pin:change" events will be emitted with the
+    pin state.
+
+    Args:
+        transport: The active Transport instance.
+        part: Part identifier.
+        pin: Pin name.
+        listen: True to start listening, False to stop.
+    """
+
+    return await transport.request(
+        "pin:listen", {"part": part, "pin": pin, "listen": listen}
+    )