feat(simulator): add GUI runner, stubs, and workspace assets

Add host simulator scaffolding, examples, and docs so led-driver main can run end-to-end with MicroPython module stubs.

Co-authored-by: Cursor <cursoragent@cursor.com>

stubs/machine.py

@@ -0,0 +1,18 @@
+"""CPython stub for MicroPython `machine` (led-simulator)."""
+
+
+class Pin:
+    OUT = 1
+    IN = 0
+
+    def __init__(self, pin_id, mode=None, *, pull=None, value=None):
+        self.id = pin_id
+        self.mode = mode
+
+
+class WDT:
+    def __init__(self, timeout=10000):
+        self._timeout = timeout
+
+    def feed(self):
+        pass

stubs/neopixel.py

@@ -0,0 +1,37 @@
+"""Host NeoPixel: keeps RGB buffer and notifies the GUI on `write()`."""
+
+# Set by led-simulator main: callable(list[tuple[int,int,int]]) -> None
+PIXEL_SINK = None
+
+
+class NeoPixel:
+    def __init__(self, pin, n):
+        self.pin = pin
+        self.n = n
+        self._buf = [(0, 0, 0)] * n
+
+    def __setitem__(self, index, value):
+        if isinstance(value, (list, tuple)) and len(value) >= 3:
+            r, g, b = (int(value[0]), int(value[1]), int(value[2]))
+            self._buf[index] = (
+                max(0, min(255, r)),
+                max(0, min(255, g)),
+                max(0, min(255, b)),
+            )
+
+    def __getitem__(self, index):
+        return self._buf[index]
+
+    def fill(self, color):
+        c = (0, 0, 0)
+        if isinstance(color, (list, tuple)) and len(color) >= 3:
+            c = (
+                max(0, min(255, int(color[0]))),
+                max(0, min(255, int(color[1]))),
+                max(0, min(255, int(color[2]))),
+            )
+        self._buf = [c] * self.n
+
+    def write(self):
+        if PIXEL_SINK is not None:
+            PIXEL_SINK(list(self._buf))

stubs/network.py

@@ -0,0 +1,38 @@
+"""Minimal `network` stub so imports succeed (led-simulator)."""
+
+STA_IF = 0
+AP_IF = 1
+
+# Fixed “STA” identity for hello.py / discovery on the host.
+_SIM_MAC = b"\xaa\xbb\xcc\xdd\xee\xff"
+
+
+class WLAN:
+    PM_NONE = 0
+
+    def __init__(self, interface):
+        self._interface = interface
+        self._active = False
+
+    def active(self, is_active=None):
+        if is_active is None:
+            return self._active
+        self._active = bool(is_active)
+        return None
+
+    def config(self, param=None, **kwargs):
+        if param == "mac":
+            return _SIM_MAC
+        return None
+
+    def connect(self, *args, **kwargs):
+        return None
+
+    def isconnected(self):
+        return True
+
+    def ifconfig(self, config_tuple=None):
+        if config_tuple is None:
+            # ip, subnet, gateway, dns — enough for hello UDP targets
+            return ("192.168.1.100", "255.255.255.0", "192.168.1.1", "8.8.8.8")
+        return None

stubs/ubinascii.py

@@ -0,0 +1,6 @@
+"""Map MicroPython `ubinascii` to CPython `binascii`."""
+
+import binascii
+
+hexlify = binascii.hexlify
+unhexlify = binascii.unhexlify

stubs/utime.py

@@ -0,0 +1,22 @@
+"""CPython stub for MicroPython `utime` (led-simulator)."""
+
+import time
+
+_MS_MASK = (1 << 30) - 1
+
+
+def sleep_ms(ms):
+    time.sleep(max(0, ms) / 1000.0)
+
+
+def sleep(s):
+    time.sleep(s)
+
+
+def ticks_ms():
+    return int(time.monotonic() * 1000) & _MS_MASK
+
+
+def ticks_diff(t1, t0):
+    """Approximate MicroPython ticks_diff for host monotonic ms."""
+    return ((t1 - t0 + (1 << 29)) & _MS_MASK) - (1 << 29)