nwaves-leader 0.1.1__tar.gz

nwaves_leader-0.1.1/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: nwaves-leader
+Version: 0.1.1
+Summary: NWaves leader bridge: drive the NWaves SO-101 simulation with the leader arm plugged into your computer
+Author: NWaves
+Author-email: NWaves <support@nwaves.ai>
+License: Proprietary
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pyserial>=3.5
+Dynamic: author
+Dynamic: requires-python
+
+# NWaves leader bridge
+
+Drives the NWaves SO-101 simulation with the leader arm plugged into your own computer,
+for browsers that cannot open USB devices themselves (Firefox, Safari). Chrome and Edge
+connect over USB directly from the session page and do not need it.
+
+Install and run (the session page shows the same one-liners):
+
+    macOS / Linux:   curl -fsSL https://<academy host>/nwaves-leader.sh | sh
+    Windows:         irm https://<academy host>/nwaves-leader.ps1 | iex
+    any:             python3 -m pip install nwaves-leader   then   nwaves-leader
+
+Then press "Connect through the NWaves leader bridge" in the session page.
+
+The bridge listens on 127.0.0.1:8765 only, accepts connections from nwaves.ai pages only,
+and sends nothing but the six servo positions to the page in your browser. The page does
+the calibration and forwards the positions to your simulation.
+
+What the academy hosts and how to rebuild it (from the repo root): `sh tools/nwaves-leader/build.sh`
+
+- `nwaves-leader.pyz`: the self-contained app the installers download (pyserial is vendored, BSD licence
+  kept inside), runs with any Python 3.8+ as `python3 nwaves-leader.pyz`
+- `nwaves_leader-<version>-py3-none-any.whl`: for `pip install` and for PyPI
+- `nwaves-leader.py`: the single-file version (needs pyserial)
+
+Publishing to PyPI (name `nwaves-leader` was free on 2026-10-17): create the NWaves account on pypi.org with
+2FA, make an API token, then `python3 -m pip install build twine && python3 -m build && twine upload dist/*`
+with `TWINE_USERNAME=__token__ TWINE_PASSWORD=<token>`. Bump `version` in pyproject.toml and setup.py first.

nwaves_leader-0.1.1/README.md

@@ -0,0 +1,28 @@
+# NWaves leader bridge
+
+Drives the NWaves SO-101 simulation with the leader arm plugged into your own computer,
+for browsers that cannot open USB devices themselves (Firefox, Safari). Chrome and Edge
+connect over USB directly from the session page and do not need it.
+
+Install and run (the session page shows the same one-liners):
+
+    macOS / Linux:   curl -fsSL https://<academy host>/nwaves-leader.sh | sh
+    Windows:         irm https://<academy host>/nwaves-leader.ps1 | iex
+    any:             python3 -m pip install nwaves-leader   then   nwaves-leader
+
+Then press "Connect through the NWaves leader bridge" in the session page.
+
+The bridge listens on 127.0.0.1:8765 only, accepts connections from nwaves.ai pages only,
+and sends nothing but the six servo positions to the page in your browser. The page does
+the calibration and forwards the positions to your simulation.
+
+What the academy hosts and how to rebuild it (from the repo root): `sh tools/nwaves-leader/build.sh`
+
+- `nwaves-leader.pyz`: the self-contained app the installers download (pyserial is vendored, BSD licence
+  kept inside), runs with any Python 3.8+ as `python3 nwaves-leader.pyz`
+- `nwaves_leader-<version>-py3-none-any.whl`: for `pip install` and for PyPI
+- `nwaves-leader.py`: the single-file version (needs pyserial)
+
+Publishing to PyPI (name `nwaves-leader` was free on 2026-10-17): create the NWaves account on pypi.org with
+2FA, make an API token, then `python3 -m pip install build twine && python3 -m build && twine upload dist/*`
+with `TWINE_USERNAME=__token__ TWINE_PASSWORD=<token>`. Bump `version` in pyproject.toml and setup.py first.

nwaves_leader-0.1.1/nwaves_leader/__init__.py

@@ -0,0 +1,2 @@
+"""NWaves leader bridge: an SO-101 leader arm on your computer, driving the NWaves simulation."""
+from .bridge import VERSION as __version__  # noqa: F401

nwaves_leader-0.1.1/nwaves_leader/__main__.py

@@ -0,0 +1,4 @@
+from .bridge import main
+
+if __name__ == "__main__":
+    main()

nwaves_leader-0.1.1/nwaves_leader/bridge.py

@@ -0,0 +1,267 @@
+#!/usr/bin/env python3
+"""NWaves leader bridge.
+
+Lets a browser without USB access (Firefox, Safari, ...) drive the NWaves SO-101
+simulation with the leader arm plugged into this computer. It reads the arm's six
+servos over its USB adapter and hands the positions to the NWaves session page over
+localhost; the page does the calibration and talks to your simulation.
+
+    python3 nwaves-leader.py            # finds the arm's port by itself
+    python3 nwaves-leader.py --port COM5   (or /dev/cu.usbserial-XXXX, /dev/ttyACM0)
+
+Needs Python 3.8+ and pyserial:  python3 -m pip install pyserial
+Then press "Connect through the NWaves leader bridge" in the session page.
+"""
+import argparse
+import base64
+import hashlib
+import json
+import socket
+import struct
+import sys
+import threading
+import time
+
+try:
+    import serial
+    from serial.tools import list_ports
+except ImportError:
+    print("pyserial is missing. Install it with:  python3 -m pip install pyserial")
+    sys.exit(1)
+
+VERSION = "0.1.1"
+IDS = [1, 2, 3, 4, 5, 6]
+BAUD = 1000000
+PRESENT_POSITION = 56
+RATE_HZ = 30
+HOST, PORT = "127.0.0.1", 8765
+ALLOWED_ORIGIN_SUFFIXES = (".nwaves.ai", "//localhost", "//127.0.0.1")
+KNOWN_ADAPTERS = {0x1A86, 0x10C4, 0x0403, 0x2341, 0x1D50}   # CH34x, CP210x, FTDI, Arduino, generic
+
+
+def checksum(data):
+    return (~sum(data)) & 0xFF
+
+
+def sync_read_packet(ids, addr, length):
+    params = [addr, length] + list(ids)
+    body = [0xFE, len(params) + 2, 0x82] + params
+    return bytes([0xFF, 0xFF] + body + [checksum(body)])
+
+
+class Arm:
+    def __init__(self, port):
+        self.ser = serial.Serial(port, BAUD, timeout=0.02)
+        self.pending = b""
+
+    def close(self):
+        try:
+            self.ser.close()
+        except Exception:
+            pass
+
+    def read_positions(self, timeout=0.04):
+        self.ser.reset_input_buffer()
+        self.ser.write(sync_read_packet(IDS, PRESENT_POSITION, 2))
+        want = set(IDS)
+        out = {}
+        deadline = time.monotonic() + timeout
+        buf = b""
+        while want and time.monotonic() < deadline:
+            chunk = self.ser.read(64)
+            if not chunk:
+                continue
+            buf += chunk
+            i = 0
+            while i + 5 < len(buf):
+                if buf[i] != 0xFF or buf[i + 1] != 0xFF:
+                    i += 1
+                    continue
+                sid, length = buf[i + 2], buf[i + 3]
+                end = i + 4 + length
+                if end > len(buf):
+                    break
+                body = buf[i + 2:end - 1]
+                if checksum(body) == buf[end - 1]:
+                    params = buf[i + 5:end - 1]
+                    if sid in want and len(params) >= 2:
+                        out[sid] = params[0] | (params[1] << 8)
+                        want.discard(sid)
+                    i = end
+                else:
+                    i += 2
+            buf = buf[i:]
+        return [out.get(i) for i in IDS]
+
+
+def find_port(explicit=None):
+    ports = list(list_ports.comports())
+    if explicit:
+        return explicit
+    known = [p for p in ports if (p.vid or 0) in KNOWN_ADAPTERS]
+    candidates = known or [p for p in ports if any(k in (p.device or "") for k in ("usbserial", "usbmodem", "ttyUSB", "ttyACM", "COM"))]
+    for p in candidates:
+        try:
+            arm = Arm(p.device)
+            if any(v is not None for v in arm.read_positions(0.2)):
+                arm.close()
+                return p.device
+            arm.close()
+        except Exception:
+            continue
+    return None
+
+
+# ------------------------------------------------------------------ a minimal WebSocket server
+def ws_accept(key):
+    return base64.b64encode(hashlib.sha1((key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11").encode()).digest()).decode()
+
+
+def ws_send_text(conn, text):
+    data = text.encode()
+    header = bytes([0x81])
+    n = len(data)
+    if n < 126:
+        header += bytes([n])
+    elif n < 65536:
+        header += bytes([126]) + struct.pack(">H", n)
+    else:
+        header += bytes([127]) + struct.pack(">Q", n)
+    conn.sendall(header + data)
+
+
+def serve(state):
+    srv = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    srv.bind((HOST, PORT))
+    srv.listen(2)
+    print(f"[nwaves-leader] ready: press 'Connect through the NWaves leader bridge' in the session page")
+    while True:
+        conn, _ = srv.accept()
+        threading.Thread(target=handle_client, args=(conn, state), daemon=True).start()
+
+
+def handle_client(conn, state):
+    try:
+        conn.settimeout(5)
+        req = b""
+        while b"\r\n\r\n" not in req:
+            chunk = conn.recv(4096)
+            if not chunk:
+                return
+            req += chunk
+        head = req.decode(errors="replace")
+        headers = {}
+        for line in head.split("\r\n")[1:]:
+            if ":" in line:
+                k, v = line.split(":", 1)
+                headers[k.strip().lower()] = v.strip()
+        origin = headers.get("origin", "")
+        if origin and not any(s in origin for s in ALLOWED_ORIGIN_SUFFIXES):
+            conn.sendall(b"HTTP/1.1 403 Forbidden\r\n\r\n")
+            return
+        key = headers.get("sec-websocket-key")
+        if not key:
+            conn.sendall(b"HTTP/1.1 400 Bad Request\r\n\r\nNWaves leader bridge: WebSocket clients only")
+            return
+        conn.sendall(("HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n"
+                      f"Sec-WebSocket-Accept: {ws_accept(key)}\r\n\r\n").encode())
+        conn.settimeout(None)
+        print("[nwaves-leader] session page connected")
+        ws_send_text(conn, json.dumps({"hello": "nwaves-leader", "port": state["port"], "rate_hz": RATE_HZ}))
+        # Drain anything the page sends (pings, close) in a side thread.
+        def drain():
+            try:
+                while conn.recv(4096):
+                    pass
+            except Exception:
+                pass
+            state["closed"].add(conn)
+        threading.Thread(target=drain, daemon=True).start()
+        last_sent = None
+        while conn not in state["closed"]:
+            raw = state["latest"]
+            if raw is not None and raw is not last_sent:
+                ws_send_text(conn, json.dumps({"raw": raw}))
+                last_sent = raw
+            if state["error"]:
+                ws_send_text(conn, json.dumps({"error": state["error"]}))
+                break
+            time.sleep(1.0 / RATE_HZ)
+    except Exception:
+        pass
+    finally:
+        try:
+            conn.close()
+        except Exception:
+            pass
+        print("[nwaves-leader] session page disconnected")
+
+
+def list_ports_cmd():
+    ports = list(list_ports.comports())
+    if not ports:
+        print("[nwaves-leader] no serial ports found; plug the leader arm's USB cable in")
+        return 1
+    print("[nwaves-leader] serial ports on this computer:")
+    for p in ports:
+        tag = " (likely the arm's USB adapter)" if (p.vid or 0) in KNOWN_ADAPTERS else ""
+        print(f"  {p.device}  {p.description or ''}{tag}")
+    return 0
+
+
+def main():
+    ap = argparse.ArgumentParser(prog="nwaves-leader",
+                                 description="NWaves leader bridge: your SO-101 leader arm -> the NWaves session page",
+                                 epilog="Commands: start (default), ports, version.")
+    ap.add_argument("command", nargs="?", default="start", choices=["start", "ports", "version"],
+                    help="start the bridge (default), list serial ports, or print the version")
+    ap.add_argument("--port", help="serial port of the leader arm (default: found automatically)")
+    ap.add_argument("--version", action="version", version=f"nwaves-leader {VERSION}")
+    args = ap.parse_args()
+    if args.command == "version":
+        print(f"nwaves-leader {VERSION}")
+        return
+    if args.command == "ports":
+        sys.exit(list_ports_cmd())
+    print(f"[nwaves-leader] NWaves leader bridge {VERSION}  (Ctrl-C stops it; 'nwaves-leader ports' lists the ports)")
+    port = find_port(args.port)
+    if not port:
+        names = [p.device for p in list_ports.comports()]
+        print("[nwaves-leader] no leader arm found." + (f" Ports seen: {', '.join(names)}" if names else " No serial ports at all:")
+              + "\n  - plug the arm's USB cable in and make sure the arm is powered\n"
+              "  - on Windows and macOS the USB adapter may need its driver installed\n"
+              "  - or pass the port yourself: python3 nwaves-leader.py --port <port>")
+        sys.exit(2)
+    print(f"[nwaves-leader] leader arm on {port}")
+    arm = Arm(port)
+    state = {"latest": None, "error": None, "port": port, "closed": set()}
+    threading.Thread(target=serve, args=(state,), daemon=True).start()
+    misses = 0
+    try:
+        while True:
+            t = time.monotonic()
+            try:
+                raw = arm.read_positions()
+            except Exception as e:
+                state["error"] = f"leader arm unplugged ({e})"
+                print(f"[nwaves-leader] {state['error']}")
+                break
+            if any(v is None for v in raw):
+                misses += 1
+                if misses % 60 == 1:
+                    silent = [i for i, v in zip(IDS, raw) if v is None]
+                    print(f"[nwaves-leader] no answer from servo {silent}; check the cable and power")
+            else:
+                misses = 0
+                state["latest"] = raw
+            time.sleep(max(0.0, 1.0 / RATE_HZ - (time.monotonic() - t)))
+    except KeyboardInterrupt:
+        pass
+    finally:
+        arm.close()
+        print("[nwaves-leader] stopped")
+
+
+if __name__ == "__main__":
+    main()

nwaves_leader-0.1.1/nwaves_leader.egg-info/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: nwaves-leader
+Version: 0.1.1
+Summary: NWaves leader bridge: drive the NWaves SO-101 simulation with the leader arm plugged into your computer
+Author: NWaves
+Author-email: NWaves <support@nwaves.ai>
+License: Proprietary
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pyserial>=3.5
+Dynamic: author
+Dynamic: requires-python
+
+# NWaves leader bridge
+
+Drives the NWaves SO-101 simulation with the leader arm plugged into your own computer,
+for browsers that cannot open USB devices themselves (Firefox, Safari). Chrome and Edge
+connect over USB directly from the session page and do not need it.
+
+Install and run (the session page shows the same one-liners):
+
+    macOS / Linux:   curl -fsSL https://<academy host>/nwaves-leader.sh | sh
+    Windows:         irm https://<academy host>/nwaves-leader.ps1 | iex
+    any:             python3 -m pip install nwaves-leader   then   nwaves-leader
+
+Then press "Connect through the NWaves leader bridge" in the session page.
+
+The bridge listens on 127.0.0.1:8765 only, accepts connections from nwaves.ai pages only,
+and sends nothing but the six servo positions to the page in your browser. The page does
+the calibration and forwards the positions to your simulation.
+
+What the academy hosts and how to rebuild it (from the repo root): `sh tools/nwaves-leader/build.sh`
+
+- `nwaves-leader.pyz`: the self-contained app the installers download (pyserial is vendored, BSD licence
+  kept inside), runs with any Python 3.8+ as `python3 nwaves-leader.pyz`
+- `nwaves_leader-<version>-py3-none-any.whl`: for `pip install` and for PyPI
+- `nwaves-leader.py`: the single-file version (needs pyserial)
+
+Publishing to PyPI (name `nwaves-leader` was free on 2026-10-17): create the NWaves account on pypi.org with
+2FA, make an API token, then `python3 -m pip install build twine && python3 -m build && twine upload dist/*`
+with `TWINE_USERNAME=__token__ TWINE_PASSWORD=<token>`. Bump `version` in pyproject.toml and setup.py first.

nwaves_leader-0.1.1/nwaves_leader.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+setup.py
+nwaves_leader/__init__.py
+nwaves_leader/__main__.py
+nwaves_leader/bridge.py
+nwaves_leader.egg-info/PKG-INFO
+nwaves_leader.egg-info/SOURCES.txt
+nwaves_leader.egg-info/dependency_links.txt
+nwaves_leader.egg-info/entry_points.txt
+nwaves_leader.egg-info/requires.txt
+nwaves_leader.egg-info/top_level.txt

nwaves_leader-0.1.1/nwaves_leader.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nwaves_leader-0.1.1/nwaves_leader.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nwaves-leader = nwaves_leader.bridge:main

nwaves_leader-0.1.1/nwaves_leader.egg-info/requires.txt

@@ -0,0 +1 @@
+pyserial>=3.5

nwaves_leader-0.1.1/nwaves_leader.egg-info/top_level.txt

@@ -0,0 +1 @@
+nwaves_leader

nwaves_leader-0.1.1/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nwaves-leader"
+version = "0.1.1"
+description = "NWaves leader bridge: drive the NWaves SO-101 simulation with the leader arm plugged into your computer"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "Proprietary"}
+authors = [{name = "NWaves", email = "support@nwaves.ai"}]
+dependencies = ["pyserial>=3.5"]
+
+[project.scripts]
+nwaves-leader = "nwaves_leader.bridge:main"
+
+[tool.setuptools]
+packages = ["nwaves_leader"]

nwaves_leader-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nwaves_leader-0.1.1/setup.py

@@ -0,0 +1,17 @@
+# Metadata lives in pyproject.toml; this file lets old setuptools (without PEP 621
+# support) build the same wheel.
+from setuptools import setup
+
+setup(
+    name="nwaves-leader",
+    version="0.1.1",
+    description="NWaves leader bridge: drive the NWaves SO-101 simulation with the leader arm plugged into your computer",
+    long_description=open("README.md").read(),
+    long_description_content_type="text/markdown",
+    author="NWaves",
+    author_email="support@nwaves.ai",
+    python_requires=">=3.8",
+    packages=["nwaves_leader"],
+    install_requires=["pyserial>=3.5"],
+    entry_points={"console_scripts": ["nwaves-leader=nwaves_leader.bridge:main"]},
+)