pocketwand 0.1.1__tar.gz

pocketwand-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agasthyako
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pocketwand-0.1.1/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: pocketwand
+Version: 0.1.1
+Summary: Turn any phone into a motion controller, streamed through the browser.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/agasthyako/Pocket-Wand
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: pycloudflared>=0.2
+Requires-Dist: qrcode>=7.4
+Provides-Extra: demo
+Requires-Dist: pygame-ce>=2.4; extra == "demo"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# PocketWand
+
+Turn any phone into a motion controller for your Python program. The phone streams its rotation through its web browser, so there's no app to install, and it works on iPhone and Android, on any network (campus Wi-Fi included).
+
+## Try the demo
+
+```sh
+pip install "pocketwand[demo] @ git+https://github.com/agasthyako/Pocket-Wand"
+pocketwand demo
+```
+
+1. A window opens with a QR code (it takes a few seconds to get a public link).
+2. Scan it with your phone's camera and open the link.
+3. Tap **Enable motion** and allow access.
+4. Point your phone at the screen and move it. The phone on screen copies it.
+
+Press **R** (or the Recentre button on the phone) to make "pointing at the screen" count as straight ahead again.
+
+`pocketwand print` does the same without a window and prints the Controller state to the terminal.
+
+## Use it in your own Game
+
+```python
+import pocketwand
+
+room = pocketwand.Room()                  # starts the server and tunnel, prints a QR code
+room.on_join = lambda c: print("joined slot", c.slot)
+
+while True:
+    c = room.controller(0)             # never None; an empty Slot reads as disconnected
+    if c.connected:
+        c.orientation                  # Quaternion(w, x, y, z)
+        c.orientation.matrix()         # 3x3 rotation matrix
+        yaw, pitch, roll = c.euler     # degrees
+        c.button                       # True while the on-screen button is held
+    # c.recenter() makes the current facing count as straight ahead
+```
+
+**Frames.** Orientation rotates the phone's frame (+X right edge, +Y top of the phone, +Z out of the screen) into the world frame (+X right, +Y towards your screen, +Z up). Recentring only changes heading, so tilt always matches gravity.
+
+**Several phones.** Every phone that opens the link gets its own Slot (`room.controller(1)`, …). A phone that reconnects gets its old Slot back. `room.controllers` lists the connected ones.
+
+State is updated on a background thread; reading it from your game loop every frame is safe and cheap.
+
+## How it works
+
+`Room()` runs a small web server on your computer and opens a free [Cloudflare quick tunnel](https://try.cloudflare.com) to it (the `cloudflared` program is downloaded automatically on first run). The phone opens the page over HTTPS, which iOS requires before a page can read motion sensors, and streams its orientation back over a WebSocket. Both sides only make outgoing connections, so firewalls and campus client isolation don't get in the way.
+
+Needs Python 3.10+ and an internet connection.

pocketwand-0.1.1/README.md

@@ -0,0 +1,49 @@
+# PocketWand
+
+Turn any phone into a motion controller for your Python program. The phone streams its rotation through its web browser, so there's no app to install, and it works on iPhone and Android, on any network (campus Wi-Fi included).
+
+## Try the demo
+
+```sh
+pip install "pocketwand[demo] @ git+https://github.com/agasthyako/Pocket-Wand"
+pocketwand demo
+```
+
+1. A window opens with a QR code (it takes a few seconds to get a public link).
+2. Scan it with your phone's camera and open the link.
+3. Tap **Enable motion** and allow access.
+4. Point your phone at the screen and move it. The phone on screen copies it.
+
+Press **R** (or the Recentre button on the phone) to make "pointing at the screen" count as straight ahead again.
+
+`pocketwand print` does the same without a window and prints the Controller state to the terminal.
+
+## Use it in your own Game
+
+```python
+import pocketwand
+
+room = pocketwand.Room()                  # starts the server and tunnel, prints a QR code
+room.on_join = lambda c: print("joined slot", c.slot)
+
+while True:
+    c = room.controller(0)             # never None; an empty Slot reads as disconnected
+    if c.connected:
+        c.orientation                  # Quaternion(w, x, y, z)
+        c.orientation.matrix()         # 3x3 rotation matrix
+        yaw, pitch, roll = c.euler     # degrees
+        c.button                       # True while the on-screen button is held
+    # c.recenter() makes the current facing count as straight ahead
+```
+
+**Frames.** Orientation rotates the phone's frame (+X right edge, +Y top of the phone, +Z out of the screen) into the world frame (+X right, +Y towards your screen, +Z up). Recentring only changes heading, so tilt always matches gravity.
+
+**Several phones.** Every phone that opens the link gets its own Slot (`room.controller(1)`, …). A phone that reconnects gets its old Slot back. `room.controllers` lists the connected ones.
+
+State is updated on a background thread; reading it from your game loop every frame is safe and cheap.
+
+## How it works
+
+`Room()` runs a small web server on your computer and opens a free [Cloudflare quick tunnel](https://try.cloudflare.com) to it (the `cloudflared` program is downloaded automatically on first run). The phone opens the page over HTTPS, which iOS requires before a page can read motion sensors, and streams its orientation back over a WebSocket. Both sides only make outgoing connections, so firewalls and campus client isolation don't get in the way.
+
+Needs Python 3.10+ and an internet connection.

pocketwand-0.1.1/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pocketwand"
+version = "0.1.1"
+description = "Turn any phone into a motion controller, streamed through the browser."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = [
+    "aiohttp>=3.9",
+    "pycloudflared>=0.2",
+    "qrcode>=7.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/agasthyako/Pocket-Wand"
+
+[project.optional-dependencies]
+demo = ["pygame-ce>=2.4"]
+dev = ["pytest>=8"]
+
+[project.scripts]
+pocketwand = "pocketwand.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pocketwand = ["static/*"]

pocketwand-0.1.1/setup.cfg

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

pocketwand-0.1.1/src/pocketwand/__init__.py

@@ -0,0 +1,7 @@
+"""PocketWand: turn any phone into a motion controller, streamed through the browser."""
+
+from .orientation import Quaternion
+from .room import Controller, Room
+
+__all__ = ["Controller", "Quaternion", "Room"]
+__version__ = "0.1.0"

pocketwand-0.1.1/src/pocketwand/cli.py

@@ -0,0 +1,34 @@
+import argparse
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="pocketwand", description="Turn your phone into a motion controller.")
+    sub = parser.add_subparsers(dest="command", required=True)
+    for name, help in (("demo", "open a window with a 3D phone that copies your phone's rotation"),
+                       ("print", "print Controller state to the terminal")):
+        p = sub.add_parser(name, help=help)
+        p.add_argument("--local", action="store_true",
+                       help="skip the public tunnel and serve plain http on your network (phones won't send motion data without HTTPS)")
+    args = parser.parse_args()
+
+    if args.command == "demo":
+        from .demo import run
+        run(tunnel=not args.local)
+    else:
+        _print(tunnel=not args.local)
+
+
+def _print(tunnel: bool) -> None:
+    import time
+
+    from . import Room
+
+    room = Room(tunnel=tunnel)
+    room.on_join = lambda c: print(f"\njoined: slot {c.slot}")
+    room.on_leave = lambda c: print(f"\nleft: slot {c.slot}")
+    try:
+        while True:
+            print(f"\r{room.controller(0)!r}    ", end="", flush=True)
+            time.sleep(1 / 20)
+    except KeyboardInterrupt:
+        room.close()

pocketwand-0.1.1/src/pocketwand/demo.py

@@ -0,0 +1,168 @@
+"""Tech demo: a 3D phone on screen that copies the real phone's rotation 1:1."""
+
+from __future__ import annotations
+
+import math
+
+import pygame
+import qrcode
+
+from . import Room
+
+W, H = 960, 720
+BG = (14, 17, 22)
+FG = (232, 237, 243)
+DIM = (138, 150, 166)
+BODY = (120, 130, 145)
+SCREEN = (40, 110, 160)
+SCREEN_HOT = (247, 37, 133)
+LIGHT = (0.3, -0.5, 0.8)
+
+# Phone half-sizes in phone frame: X across the screen, Y along the phone, Z out of the screen.
+HX, HY, HZ = 0.38, 0.78, 0.05
+CAMERA = (0.0, -3.2, 1.9)
+FOCAL = 760
+
+
+def run(tunnel: bool = True) -> None:
+    room = Room(tunnel=tunnel)
+    pygame.init()
+    pygame.display.set_caption("PocketWand demo")
+    screen = pygame.display.set_mode((W, H))
+    font = pygame.font.SysFont("menlo,consolas,monospace", 18)
+    big = pygame.font.SysFont("helvetica,arial,sans", 28)
+    qr = _qr_surface(room.join_url, 10)
+    clock = pygame.time.Clock()
+    view = _camera_basis(CAMERA, (0.0, 0.0, 0.0))
+
+    running = True
+    while running:
+        for event in pygame.event.get():
+            if event.type == pygame.QUIT or (event.type == pygame.KEYDOWN and event.key in (pygame.K_ESCAPE, pygame.K_q)):
+                running = False
+            elif event.type == pygame.KEYDOWN and event.key == pygame.K_r:
+                room.controller(0).recenter()
+
+        c = room.controller(0)
+        screen.fill(BG)
+        if c.connected:
+            _draw_phone(screen, view, c.orientation.matrix(), c.button)
+            yaw, pitch, roll = c.euler
+            lines = [
+                f"slot {c.slot}   button {'DOWN' if c.button else 'up'}",
+                f"yaw {yaw:7.1f}   pitch {pitch:7.1f}   roll {roll:7.1f}",
+                f"{clock.get_fps():.0f} fps   R: recentre   Q: quit",
+            ]
+            for i, text in enumerate(lines):
+                screen.blit(font.render(text, True, DIM), (20, 20 + i * 24))
+        else:
+            title = big.render("Scan with your phone camera", True, FG)
+            screen.blit(title, title.get_rect(center=(W // 2, 70)))
+            screen.blit(qr, qr.get_rect(center=(W // 2, H // 2)))
+            url = font.render(room.join_url, True, DIM)
+            screen.blit(url, url.get_rect(center=(W // 2, H - 60)))
+
+        pygame.display.flip()
+        clock.tick(120)
+
+    pygame.quit()
+    room.close()
+
+
+def _draw_phone(screen, view, rot, hot: bool) -> None:
+    corners = [(sx * HX, sy * HY, sz * HZ) for sx in (-1, 1) for sy in (-1, 1) for sz in (-1, 1)]
+    world = [_mat_vec(rot, p) for p in corners]
+    cam = [_to_camera(view, p) for p in world]
+
+    def idx(sx, sy, sz):
+        return ((sx > 0) << 2) | ((sy > 0) << 1) | (sz > 0)
+
+    # Each face: (corner indices wound counter-clockwise from outside, phone-frame normal)
+    faces = [
+        ([idx(-1, -1, 1), idx(1, -1, 1), idx(1, 1, 1), idx(-1, 1, 1)], (0, 0, 1)),
+        ([idx(-1, 1, -1), idx(1, 1, -1), idx(1, -1, -1), idx(-1, -1, -1)], (0, 0, -1)),
+        ([idx(1, -1, -1), idx(1, 1, -1), idx(1, 1, 1), idx(1, -1, 1)], (1, 0, 0)),
+        ([idx(-1, -1, 1), idx(-1, 1, 1), idx(-1, 1, -1), idx(-1, -1, -1)], (-1, 0, 0)),
+        ([idx(-1, 1, 1), idx(1, 1, 1), idx(1, 1, -1), idx(-1, 1, -1)], (0, 1, 0)),
+        ([idx(-1, -1, -1), idx(1, -1, -1), idx(1, -1, 1), idx(-1, -1, 1)], (0, -1, 0)),
+    ]
+
+    drawn = []
+    for quad, normal in faces:
+        n = _mat_vec(rot, normal)
+        centre = [sum(world[i][k] for i in quad) / 4 for k in range(3)]
+        to_cam = [CAMERA[k] - centre[k] for k in range(3)]
+        if _dot(n, to_cam) <= 0:
+            continue  # facing away
+        depth = sum(cam[i][2] for i in quad) / 4
+        drawn.append((depth, quad, n, normal))
+
+    for depth, quad, n, normal in sorted(drawn, reverse=True):
+        shade = 0.35 + 0.65 * max(0.0, _dot(n, _normalise(LIGHT)))
+        pts = [_project(cam[i]) for i in quad]
+        pygame.draw.polygon(screen, _scale(BODY, shade), pts)
+        if normal == (0, 0, 1):
+            _draw_display(screen, view, rot, SCREEN_HOT if hot else SCREEN, shade)
+
+
+def _draw_display(screen, view, rot, colour, shade) -> None:
+    """The glass on the front, plus a notch so you can tell the top from the bottom."""
+    z = HZ + 0.001
+    glass = [(-HX * 0.88, -HY * 0.92, z), (HX * 0.88, -HY * 0.92, z), (HX * 0.88, HY * 0.86, z), (-HX * 0.88, HY * 0.86, z)]
+    pygame.draw.polygon(screen, _scale(colour, shade), [_project(_to_camera(view, _mat_vec(rot, p))) for p in glass])
+    notch = [(-0.1, HY * 0.9, z), (0.1, HY * 0.9, z), (0.1, HY * 0.95, z), (-0.1, HY * 0.95, z)]
+    pygame.draw.polygon(screen, (20, 20, 20), [_project(_to_camera(view, _mat_vec(rot, p))) for p in notch])
+
+
+def _qr_surface(data: str, cell: int) -> pygame.Surface:
+    qr = qrcode.QRCode(border=4)  # the full 4-module quiet zone; iOS Camera ignores codes with less
+    qr.add_data(data)
+    matrix = qr.get_matrix()
+    size = len(matrix) * cell
+    surf = pygame.Surface((size, size))
+    surf.fill((255, 255, 255))
+    for y, row in enumerate(matrix):
+        for x, on in enumerate(row):
+            if on:
+                surf.fill((0, 0, 0), (x * cell, y * cell, cell, cell))
+    return surf
+
+
+def _camera_basis(eye, target):
+    forward = _normalise([target[k] - eye[k] for k in range(3)])
+    right = _normalise(_cross(forward, (0.0, 0.0, 1.0)))
+    up = _cross(right, forward)
+    return right, up, forward
+
+
+def _to_camera(view, p):
+    right, up, forward = view
+    rel = [p[k] - CAMERA[k] for k in range(3)]
+    return (_dot(rel, right), _dot(rel, up), _dot(rel, forward))
+
+
+def _project(p):
+    x, y, z = p
+    z = max(z, 0.01)
+    return (W / 2 + FOCAL * x / z, H / 2 - FOCAL * y / z)
+
+
+def _mat_vec(m, v):
+    return tuple(m[r][0] * v[0] + m[r][1] * v[1] + m[r][2] * v[2] for r in range(3))
+
+
+def _dot(a, b):
+    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
+
+
+def _cross(a, b):
+    return (a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0])
+
+
+def _normalise(v):
+    length = math.sqrt(_dot(v, v))
+    return tuple(x / length for x in v)
+
+
+def _scale(colour, k):
+    return tuple(min(255, int(c * k)) for c in colour)

pocketwand-0.1.1/src/pocketwand/orientation.py

@@ -0,0 +1,100 @@
+"""Orientation maths.
+
+World frame (after Recentre): +X right, +Y forward (towards the screen), +Z up.
+Phone frame: +X right edge of the screen, +Y top of the phone, +Z out of the screen.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Quaternion:
+    w: float
+    x: float
+    y: float
+    z: float
+
+    @staticmethod
+    def identity() -> Quaternion:
+        return Quaternion(1.0, 0.0, 0.0, 0.0)
+
+    @staticmethod
+    def from_axis_angle(axis: tuple[float, float, float], degrees: float) -> Quaternion:
+        half = math.radians(degrees) / 2
+        s = math.sin(half)
+        return Quaternion(math.cos(half), axis[0] * s, axis[1] * s, axis[2] * s)
+
+    def __iter__(self):
+        return iter((self.w, self.x, self.y, self.z))
+
+    def __neg__(self) -> Quaternion:
+        return Quaternion(-self.w, -self.x, -self.y, -self.z)
+
+    def __mul__(self, o: Quaternion) -> Quaternion:
+        return Quaternion(
+            self.w * o.w - self.x * o.x - self.y * o.y - self.z * o.z,
+            self.w * o.x + self.x * o.w + self.y * o.z - self.z * o.y,
+            self.w * o.y - self.x * o.z + self.y * o.w + self.z * o.x,
+            self.w * o.z + self.x * o.y - self.y * o.x + self.z * o.w,
+        )
+
+    def conjugate(self) -> Quaternion:
+        return Quaternion(self.w, -self.x, -self.y, -self.z)
+
+    def rotate(self, v: tuple[float, float, float]) -> tuple[float, float, float]:
+        """Rotate a phone-frame vector into the world frame."""
+        p = self * Quaternion(0.0, *v) * self.conjugate()
+        return (p.x, p.y, p.z)
+
+    def matrix(self) -> tuple[tuple[float, float, float], ...]:
+        w, x, y, z = self
+        return (
+            (1 - 2 * (y * y + z * z), 2 * (x * y - w * z), 2 * (x * z + w * y)),
+            (2 * (x * y + w * z), 1 - 2 * (x * x + z * z), 2 * (y * z - w * x)),
+            (2 * (x * z - w * y), 2 * (y * z + w * x), 1 - 2 * (x * x + y * y)),
+        )
+
+    def euler(self) -> tuple[float, float, float]:
+        """(yaw, pitch, roll) in degrees, applied yaw about Z, then pitch about X, then roll about Y.
+
+        Yaw is heading (positive turns left), pitch tips the top of the phone up,
+        roll twists the phone around its long edge.
+        """
+        r = self.matrix()
+        pitch = math.asin(max(-1.0, min(1.0, r[2][1])))
+        yaw = math.atan2(-r[0][1], r[1][1])
+        roll = math.atan2(-r[2][0], r[2][2])
+        return (math.degrees(yaw), math.degrees(pitch), math.degrees(roll))
+
+
+_Z = (0.0, 0.0, 1.0)
+_X = (1.0, 0.0, 0.0)
+_Y = (0.0, 1.0, 0.0)
+
+
+def from_device_angles(alpha: float, beta: float, gamma: float) -> Quaternion:
+    """Convert browser DeviceOrientationEvent angles (degrees) to a quaternion.
+
+    Per the W3C spec the rotation is Z(alpha) then X(beta) then Y(gamma), intrinsic.
+    """
+    return (
+        Quaternion.from_axis_angle(_Z, alpha)
+        * Quaternion.from_axis_angle(_X, beta)
+        * Quaternion.from_axis_angle(_Y, gamma)
+    )
+
+
+def recentre_offset(raw: Quaternion) -> Quaternion:
+    """The heading-only correction that makes the phone's current facing count as forward.
+
+    Facing is the direction the top of the phone points; when the phone stands
+    upright that direction is vertical, so the back of the phone is used instead.
+    """
+    top = raw.rotate((0.0, 1.0, 0.0))
+    back = raw.rotate((0.0, 0.0, -1.0))
+    fx, fy, _ = top if math.hypot(top[0], top[1]) > 0.5 else back
+    heading = math.degrees(math.atan2(-fx, fy))
+    return Quaternion.from_axis_angle(_Z, -heading)

pocketwand-0.1.1/src/pocketwand/room.py

@@ -0,0 +1,180 @@
+"""The Game-facing API: a Room that Controllers join, polled for their state."""
+
+from __future__ import annotations
+
+import asyncio
+import secrets
+import socket
+import threading
+from typing import Callable
+
+from .orientation import Quaternion, recentre_offset
+from .server import Server
+from .tunnel import Tunnel
+
+
+class Controller:
+    """The live state of one Slot. Safe to read from any thread, every frame."""
+
+    def __init__(self, slot: int):
+        self.slot = slot
+        self._lock = threading.Lock()
+        self._raw = Quaternion.identity()
+        self._offset = Quaternion.identity()
+        self._button = False
+        self._connected = False
+        self._has_data = False
+
+    @property
+    def orientation(self) -> Quaternion:
+        """Rotation from phone frame to world frame (+X right, +Y towards the screen, +Z up)."""
+        with self._lock:
+            return self._offset * self._raw
+
+    @property
+    def euler(self) -> tuple[float, float, float]:
+        """(yaw, pitch, roll) in degrees. See Quaternion.euler."""
+        return self.orientation.euler()
+
+    @property
+    def button(self) -> bool:
+        with self._lock:
+            return self._button
+
+    @property
+    def connected(self) -> bool:
+        with self._lock:
+            return self._connected
+
+    def recenter(self) -> None:
+        """Make the direction the phone currently faces count as straight ahead."""
+        with self._lock:
+            self._offset = recentre_offset(self._raw)
+
+    def __repr__(self) -> str:
+        yaw, pitch, roll = self.euler
+        return (
+            f"Controller(slot={self.slot}, connected={self.connected}, button={self.button}, "
+            f"yaw={yaw:.0f}, pitch={pitch:.0f}, roll={roll:.0f})"
+        )
+
+    # Called by the server thread.
+
+    def _update(self, raw: Quaternion, button: bool) -> None:
+        with self._lock:
+            first = not self._has_data
+            self._raw = raw
+            self._button = button
+            self._has_data = True
+        if first:
+            self.recenter()
+
+    def _set_connected(self, connected: bool) -> None:
+        with self._lock:
+            self._connected = connected
+
+
+class Slots:
+    """Hands out Slots, giving a returning Controller its old one back."""
+
+    def __init__(self):
+        self._by_id: dict[str, int] = {}
+
+    def claim(self, controller_id: str) -> int:
+        if controller_id not in self._by_id:
+            self._by_id[controller_id] = len(self._by_id)
+        return self._by_id[controller_id]
+
+
+class Room:
+    """One Game's session. Creating it starts the server and the public tunnel.
+
+    >>> room = pocketwand.Room()
+    >>> room.controller(0).euler
+    """
+
+    def __init__(self, *, tunnel: bool = True, port: int = 0, show_qr: bool = True):
+        self.code = secrets.token_urlsafe(6)
+        self.on_join: Callable[[Controller], None] | None = None
+        self.on_leave: Callable[[Controller], None] | None = None
+
+        self._controllers: dict[int, Controller] = {}
+        self._controllers_lock = threading.Lock()
+        self._slots = Slots()
+
+        self.port = port or _free_port()
+        self._loop = asyncio.new_event_loop()
+        self._server = Server(self, self._loop, host="127.0.0.1" if tunnel else "0.0.0.0", port=self.port)
+        ready = threading.Event()
+        self._thread = threading.Thread(target=self._run, args=(ready,), daemon=True, name="pocketwand-server")
+        self._thread.start()
+        ready.wait()
+
+        if tunnel:
+            self._tunnel: Tunnel | None = Tunnel(self.port)
+            base = self._tunnel.url
+        else:
+            self._tunnel = None
+            base = f"http://{_lan_ip()}:{self.port}"
+        self.join_url = f"{base}/?room={self.code}"
+
+        if show_qr:
+            self.print_qr()
+
+    def controller(self, slot: int = 0) -> Controller:
+        """The Controller in `slot`. Never None: an empty Slot reads as disconnected."""
+        with self._controllers_lock:
+            if slot not in self._controllers:
+                self._controllers[slot] = Controller(slot)
+            return self._controllers[slot]
+
+    @property
+    def controllers(self) -> list[Controller]:
+        """Every Controller that is currently connected, ordered by Slot."""
+        with self._controllers_lock:
+            return [c for _, c in sorted(self._controllers.items()) if c.connected]
+
+    def print_qr(self) -> None:
+        import qrcode
+
+        qr = qrcode.QRCode(border=1)
+        qr.add_data(self.join_url)
+        qr.print_ascii(invert=True)
+        print(f"Scan with your phone, or open: {self.join_url}")
+
+    def close(self) -> None:
+        if self._tunnel:
+            self._tunnel.close()
+        if self._loop.is_running():
+            try:
+                asyncio.run_coroutine_threadsafe(self._server.stop(), self._loop).result(timeout=3)
+            except Exception:
+                pass
+            self._loop.call_soon_threadsafe(self._loop.stop)
+
+    def __enter__(self) -> Room:
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    def _run(self, ready: threading.Event) -> None:
+        asyncio.set_event_loop(self._loop)
+        self._loop.run_until_complete(self._server.start())
+        ready.set()
+        self._loop.run_forever()
+
+
+def _free_port() -> int:
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+def _lan_ip() -> str:
+    with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:
+        try:
+            s.connect(("10.255.255.255", 1))
+            return s.getsockname()[0]
+        except OSError:
+            return "127.0.0.1"

pocketwand-0.1.1/src/pocketwand/server.py

@@ -0,0 +1,98 @@
+"""Serves the Controller page and receives Controller messages over a WebSocket."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from importlib.resources import files
+from typing import TYPE_CHECKING
+
+from aiohttp import WSMsgType, web
+
+from .orientation import from_device_angles
+
+if TYPE_CHECKING:
+    from .room import Room
+
+PAGE = files("pocketwand").joinpath("static/controller.html")
+
+
+class Server:
+    def __init__(self, room: Room, loop: asyncio.AbstractEventLoop, host: str, port: int):
+        self.room = room
+        self.loop = loop
+        self.host = host
+        self.port = port
+        self._sockets: dict[int, web.WebSocketResponse] = {}
+
+    async def start(self) -> None:
+        app = web.Application()
+        app.router.add_get("/", self._page)
+        app.router.add_get("/ws", self._ws)
+        self._runner = web.AppRunner(app, access_log=None)
+        await self._runner.setup()
+        await web.TCPSite(self._runner, self.host, self.port).start()
+
+    async def stop(self) -> None:
+        for ws in list(self._sockets.values()):
+            await ws.close()
+        await self._runner.cleanup()
+
+    async def _page(self, request: web.Request) -> web.Response:
+        return web.Response(
+            text=PAGE.read_text(encoding="utf-8"),
+            content_type="text/html",
+            headers={"Cache-Control": "no-store"},
+        )
+
+    async def _ws(self, request: web.Request) -> web.StreamResponse:
+        if request.query.get("room") != self.room.code:
+            raise web.HTTPForbidden(text="Wrong or missing Room code")
+        controller_id = request.query.get("id", "")
+        if not controller_id:
+            raise web.HTTPBadRequest(text="Missing controller id")
+
+        ws = web.WebSocketResponse(heartbeat=5)
+        await ws.prepare(request)
+
+        slot = self.room._slots.claim(controller_id)
+        controller = self.room.controller(slot)
+
+        # The same phone reconnecting (e.g. a reloaded tab) replaces its old connection.
+        old = self._sockets.get(slot)
+        self._sockets[slot] = ws
+        if old is not None:
+            await old.close()
+
+        controller._set_connected(True)
+        await ws.send_json({"t": "slot", "slot": slot})
+        _call(self.room.on_join, controller)
+
+        try:
+            async for msg in ws:
+                if msg.type != WSMsgType.TEXT:
+                    continue
+                try:
+                    data = json.loads(msg.data)
+                    if data.get("t") == "recentre":
+                        controller.recenter()
+                    elif "a" in data:
+                        raw = from_device_angles(float(data["a"] or 0), float(data["b"] or 0), float(data["g"] or 0))
+                        controller._update(raw, bool(data.get("p")))
+                except (ValueError, TypeError, KeyError, AttributeError):
+                    continue  # ignore malformed messages
+        finally:
+            if self._sockets.get(slot) is ws:
+                del self._sockets[slot]
+                controller._set_connected(False)
+                _call(self.room.on_leave, controller)
+        return ws
+
+
+def _call(callback, controller) -> None:
+    if callback is None:
+        return
+    try:
+        callback(controller)
+    except Exception as e:  # a buggy Game callback must not kill the server
+        print(f"pocketwand: callback raised {e!r}")

pocketwand-0.1.1/src/pocketwand/static/controller.html

@@ -0,0 +1,130 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
+<meta name="apple-mobile-web-app-capable" content="yes">
+<title>PocketWand Controller</title>
+<style>
+  :root { --bg: #0e1116; --fg: #e8edf3; --dim: #8a96a6; --accent: #4cc9f0; --hot: #f72585; }
+  * { box-sizing: border-box; -webkit-user-select: none; user-select: none; -webkit-touch-callout: none; }
+  html, body { margin: 0; height: 100%; background: var(--bg); color: var(--fg);
+    font: 16px/1.4 -apple-system, system-ui, sans-serif; touch-action: none; overflow: hidden; }
+  body { display: flex; flex-direction: column; padding: 16px; gap: 12px; }
+  #status { font-size: 14px; color: var(--dim); display: flex; justify-content: space-between; }
+  #status b { color: var(--fg); }
+  .screen { flex: 1; display: none; flex-direction: column; gap: 12px; }
+  .screen.on { display: flex; }
+  button { font: inherit; border: 0; border-radius: 16px; color: var(--bg); background: var(--accent); padding: 18px; }
+  #start button { margin: auto 0; font-size: 22px; padding: 28px; }
+  #trigger { flex: 1; background: #1c2230; color: var(--fg); font-size: 22px; }
+  #trigger.down { background: var(--hot); }
+  #recentre { background: #2b3446; color: var(--fg); }
+  #angles { font: 13px ui-monospace, monospace; color: var(--dim); text-align: center; }
+  #msg { color: var(--dim); text-align: center; margin: auto 0; }
+</style>
+</head>
+<body>
+<div id="status"><span id="conn">Not connected</span><span id="slot"></span></div>
+
+<div id="start" class="screen on">
+  <p id="msg">Tap below, then allow motion access.</p>
+  <button id="enable">Enable motion</button>
+</div>
+
+<div id="pad" class="screen">
+  <button id="trigger">Hold</button>
+  <div id="angles"></div>
+  <button id="recentre">Recentre (point at your screen)</button>
+</div>
+
+<script>
+const $ = (id) => document.getElementById(id);
+const room = new URLSearchParams(location.search).get("room");
+
+// A stable random id lets this phone reclaim its Slot after reconnecting.
+let id;
+try { id = localStorage.getItem("pocketwand-id"); } catch {}
+if (!id) {
+  id = Math.random().toString(36).slice(2) + Date.now().toString(36);
+  try { localStorage.setItem("pocketwand-id", id); } catch {}
+}
+
+const state = { a: null, b: null, g: null, p: 0 };
+let ws = null, failures = 0, lastSent = "", lastSentAt = 0;
+
+if (!room) {
+  $("msg").textContent = "Open this page by scanning the QR code shown by the game.";
+  $("enable").style.display = "none";
+}
+
+$("enable").onclick = async () => {
+  // iOS only hands out sensor data after this permission call, made directly from a tap.
+  if (typeof DeviceOrientationEvent !== "undefined" && typeof DeviceOrientationEvent.requestPermission === "function") {
+    try {
+      if (await DeviceOrientationEvent.requestPermission() !== "granted") {
+        $("msg").textContent = "Motion access was denied. Close this tab, reopen the link and tap Allow.";
+        return;
+      }
+    } catch (e) {
+      $("msg").textContent = "Couldn't ask for motion access: " + e.message;
+      return;
+    }
+  }
+  window.addEventListener("deviceorientation", (e) => { state.a = e.alpha; state.b = e.beta; state.g = e.gamma; });
+  $("start").classList.remove("on");
+  $("pad").classList.add("on");
+  keepAwake();
+  connect();
+  requestAnimationFrame(send);
+  setTimeout(() => {
+    if (state.b === null) $("angles").textContent = "No motion data. This browser or device may not have motion sensors.";
+  }, 2000);
+};
+
+function connect() {
+  const proto = location.protocol === "https:" ? "wss" : "ws";
+  ws = new WebSocket(`${proto}://${location.host}/ws?room=${encodeURIComponent(room)}&id=${encodeURIComponent(id)}`);
+  $("conn").textContent = "Connecting…";
+  ws.onopen = () => { failures = 0; $("conn").innerHTML = "<b>Connected</b>"; };
+  ws.onmessage = (e) => {
+    const m = JSON.parse(e.data);
+    if (m.t === "slot") $("slot").textContent = "Slot " + m.slot;
+  };
+  ws.onclose = () => {
+    failures++;
+    $("conn").textContent = failures > 5 ? "Can't reach the game. The link may be old; scan the new QR code." : "Reconnecting…";
+    setTimeout(connect, Math.min(1000 * failures, 5000));
+  };
+}
+
+function send() {
+  requestAnimationFrame(send);
+  if (!ws || ws.readyState !== WebSocket.OPEN || state.b === null) return;
+  // Drop frames rather than queue them: stale orientation is worse than missing orientation.
+  if (ws.bufferedAmount > 1024) return;
+  const msg = JSON.stringify(state);
+  const now = performance.now();
+  if (msg === lastSent && now - lastSentAt < 250) return;
+  ws.send(msg);
+  lastSent = msg; lastSentAt = now;
+  $("angles").textContent = `α ${state.a?.toFixed(0)}  β ${state.b?.toFixed(0)}  γ ${state.g?.toFixed(0)}`;
+}
+
+const trigger = $("trigger");
+const press = (down) => (e) => { e.preventDefault(); state.p = down ? 1 : 0; trigger.classList.toggle("down", down); };
+trigger.addEventListener("pointerdown", press(true));
+trigger.addEventListener("pointerup", press(false));
+trigger.addEventListener("pointercancel", press(false));
+trigger.addEventListener("pointerleave", press(false));
+
+$("recentre").onclick = () => { if (ws && ws.readyState === WebSocket.OPEN) ws.send('{"t":"recentre"}'); };
+
+let wakeLock = null;
+async function keepAwake() {
+  try { wakeLock = await navigator.wakeLock?.request("screen"); } catch {}
+}
+document.addEventListener("visibilitychange", () => { if (document.visibilityState === "visible") keepAwake(); });
+</script>
+</body>
+</html>

pocketwand-0.1.1/src/pocketwand/tunnel.py

@@ -0,0 +1,86 @@
+"""Gives the local server a public HTTPS address with a Cloudflare quick tunnel.
+
+A tunnel rather than a hosted relay or a LAN-only server: iOS needs HTTPS for motion
+sensors, campus Wi-Fi blocks device-to-device traffic, and nobody has to host anything.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import re
+import shutil
+import subprocess
+import threading
+import time
+import urllib.request
+from pathlib import Path
+
+URL_PATTERN = re.compile(r"https://[a-z0-9-]+\.trycloudflare\.com")
+
+
+class Tunnel:
+    def __init__(self, port: int, timeout: float = 30.0):
+        exe = _cloudflared()
+        print("pocketwand: opening a public tunnel (a few seconds)...")
+        self._process = subprocess.Popen(
+            [exe, "tunnel", "--no-autoupdate", "--url", f"http://127.0.0.1:{port}"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
+            text=True,
+        )
+        atexit.register(self.close)
+
+        found = threading.Event()
+        self.url = ""
+
+        def read_log():
+            # Keep draining stderr for the tunnel's whole life, or cloudflared blocks once the pipe fills.
+            for line in self._process.stderr:
+                if not self.url and (m := URL_PATTERN.search(line)):
+                    self.url = m.group(0)
+                    found.set()
+
+        threading.Thread(target=read_log, daemon=True, name="pocketwand-tunnel-log").start()
+        if not found.wait(timeout):
+            self.close()
+            raise RuntimeError("cloudflared did not report a tunnel URL; check your internet connection")
+        _wait_until_reachable(self.url, timeout)
+
+    def close(self) -> None:
+        if self._process.poll() is None:
+            self._process.terminate()
+
+
+def _cloudflared() -> str:
+    """A cloudflared already on PATH, otherwise one downloaded by pycloudflared on first use."""
+    if exe := shutil.which("cloudflared"):
+        return exe
+    from pycloudflared.util import download, get_info
+
+    info = get_info()
+    if not Path(info.executable).exists():
+        download(info)
+    return info.executable
+
+
+def _wait_until_reachable(url: str, timeout: float) -> None:
+    """New quick-tunnel hostnames take a few seconds to exist; don't hand out a dead link.
+
+    Only ask Cloudflare's own DNS. Looking the name up through the local resolver
+    before it exists makes that resolver cache "no such host" for 30 minutes (the
+    trycloudflare.com negative TTL), breaking the link for every device on the network.
+    """
+    host = url.removeprefix("https://")
+    query = f"https://1.1.1.1/dns-query?name={host}&type=A"
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            req = urllib.request.Request(query, headers={"accept": "application/dns-json"})
+            with urllib.request.urlopen(req, timeout=3) as resp:
+                if json.load(resp).get("Answer"):
+                    return
+        except Exception:
+            pass
+        time.sleep(1)
+    print("pocketwand: tunnel is slow to come up; the link may take a moment to work")

pocketwand-0.1.1/src/pocketwand.egg-info/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: pocketwand
+Version: 0.1.1
+Summary: Turn any phone into a motion controller, streamed through the browser.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/agasthyako/Pocket-Wand
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: pycloudflared>=0.2
+Requires-Dist: qrcode>=7.4
+Provides-Extra: demo
+Requires-Dist: pygame-ce>=2.4; extra == "demo"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# PocketWand
+
+Turn any phone into a motion controller for your Python program. The phone streams its rotation through its web browser, so there's no app to install, and it works on iPhone and Android, on any network (campus Wi-Fi included).
+
+## Try the demo
+
+```sh
+pip install "pocketwand[demo] @ git+https://github.com/agasthyako/Pocket-Wand"
+pocketwand demo
+```
+
+1. A window opens with a QR code (it takes a few seconds to get a public link).
+2. Scan it with your phone's camera and open the link.
+3. Tap **Enable motion** and allow access.
+4. Point your phone at the screen and move it. The phone on screen copies it.
+
+Press **R** (or the Recentre button on the phone) to make "pointing at the screen" count as straight ahead again.
+
+`pocketwand print` does the same without a window and prints the Controller state to the terminal.
+
+## Use it in your own Game
+
+```python
+import pocketwand
+
+room = pocketwand.Room()                  # starts the server and tunnel, prints a QR code
+room.on_join = lambda c: print("joined slot", c.slot)
+
+while True:
+    c = room.controller(0)             # never None; an empty Slot reads as disconnected
+    if c.connected:
+        c.orientation                  # Quaternion(w, x, y, z)
+        c.orientation.matrix()         # 3x3 rotation matrix
+        yaw, pitch, roll = c.euler     # degrees
+        c.button                       # True while the on-screen button is held
+    # c.recenter() makes the current facing count as straight ahead
+```
+
+**Frames.** Orientation rotates the phone's frame (+X right edge, +Y top of the phone, +Z out of the screen) into the world frame (+X right, +Y towards your screen, +Z up). Recentring only changes heading, so tilt always matches gravity.
+
+**Several phones.** Every phone that opens the link gets its own Slot (`room.controller(1)`, …). A phone that reconnects gets its old Slot back. `room.controllers` lists the connected ones.
+
+State is updated on a background thread; reading it from your game loop every frame is safe and cheap.
+
+## How it works
+
+`Room()` runs a small web server on your computer and opens a free [Cloudflare quick tunnel](https://try.cloudflare.com) to it (the `cloudflared` program is downloaded automatically on first run). The phone opens the page over HTTPS, which iOS requires before a page can read motion sensors, and streams its orientation back over a WebSocket. Both sides only make outgoing connections, so firewalls and campus client isolation don't get in the way.
+
+Needs Python 3.10+ and an internet connection.

pocketwand-0.1.1/src/pocketwand.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+pyproject.toml
+src/pocketwand/__init__.py
+src/pocketwand/cli.py
+src/pocketwand/demo.py
+src/pocketwand/orientation.py
+src/pocketwand/room.py
+src/pocketwand/server.py
+src/pocketwand/tunnel.py
+src/pocketwand.egg-info/PKG-INFO
+src/pocketwand.egg-info/SOURCES.txt
+src/pocketwand.egg-info/dependency_links.txt
+src/pocketwand.egg-info/entry_points.txt
+src/pocketwand.egg-info/requires.txt
+src/pocketwand.egg-info/top_level.txt
+src/pocketwand/static/controller.html
+tests/test_orientation.py
+tests/test_room.py

pocketwand-0.1.1/src/pocketwand.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pocketwand-0.1.1/src/pocketwand.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pocketwand = pocketwand.cli:main

pocketwand-0.1.1/src/pocketwand.egg-info/requires.txt

@@ -0,0 +1,9 @@
+aiohttp>=3.9
+pycloudflared>=0.2
+qrcode>=7.4
+
+[demo]
+pygame-ce>=2.4
+
+[dev]
+pytest>=8

pocketwand-0.1.1/src/pocketwand.egg-info/top_level.txt

@@ -0,0 +1 @@
+pocketwand

pocketwand-0.1.1/tests/test_orientation.py

@@ -0,0 +1,52 @@
+import math
+
+import pytest
+
+from pocketwand.orientation import Quaternion, from_device_angles, recentre_offset
+
+
+def close(a, b, tol=1e-6):
+    return all(abs(x - y) < tol for x, y in zip(a, b))
+
+
+def same_rotation(q1, q2, tol=1e-6):
+    # q and -q are the same rotation
+    return close(tuple(q1), tuple(q2), tol) or close(tuple(q1), tuple(-q2), tol)
+
+
+def test_identity_when_phone_flat_facing_north():
+    assert same_rotation(from_device_angles(0, 0, 0), Quaternion.identity())
+
+
+@pytest.mark.parametrize(
+    "alpha,beta,gamma",
+    [(30, 0, 0), (0, 45, 0), (0, 0, -60), (120, 30, -20), (350, -70, 85)],
+)
+def test_euler_round_trips_device_angles(alpha, beta, gamma):
+    yaw, pitch, roll = from_device_angles(alpha, beta, gamma).euler()
+    assert yaw == pytest.approx(alpha if alpha <= 180 else alpha - 360)
+    assert pitch == pytest.approx(beta)
+    assert roll == pytest.approx(gamma)
+
+
+def test_rotating_vector_matches_right_hand_rule():
+    # 90 degrees about Z (alpha) turns the phone's top (+Y) to point west (-X)
+    q = from_device_angles(90, 0, 0)
+    assert close(q.rotate((0, 1, 0)), (-1, 0, 0))
+
+
+def test_recentre_makes_current_heading_forward():
+    raw = from_device_angles(73, 20, 10)
+    offset = recentre_offset(raw)
+    yaw, pitch, roll = (offset * raw).euler()
+    assert yaw == pytest.approx(0, abs=1e-6)
+    # recentring only removes heading; tilt stays true to gravity
+    assert pitch == pytest.approx(20)
+    assert roll == pytest.approx(10)
+
+
+def test_recentre_with_phone_upright_uses_back_of_phone():
+    # phone standing up (top pointing at the sky), screen facing the user, turned 40 degrees
+    raw = from_device_angles(40, 90, 0)
+    forward = (recentre_offset(raw) * raw).rotate((0, 0, -1))
+    assert close(forward, (0, 1, 0), 1e-6)

pocketwand-0.1.1/tests/test_room.py

@@ -0,0 +1,90 @@
+import asyncio
+import json
+
+import aiohttp
+import pytest
+
+from pocketwand import Room
+from pocketwand.room import Slots
+
+
+def test_returning_controller_reclaims_its_slot():
+    slots = Slots()
+    assert slots.claim("phone-a") == 0
+    assert slots.claim("phone-b") == 1
+    assert slots.claim("phone-a") == 0
+    assert slots.claim("phone-c") == 2
+
+
+def test_empty_slot_reads_as_disconnected():
+    room = Room(tunnel=False, show_qr=False)
+    try:
+        c = room.controller(3)
+        assert not c.connected
+        assert c.euler == pytest.approx((0, 0, 0))
+    finally:
+        room.close()
+
+
+@pytest.fixture
+def room():
+    r = Room(tunnel=False, show_qr=False)
+    yield r
+    r.close()
+
+
+def ws_url(room, code, controller_id="phone-a"):
+    return f"ws://127.0.0.1:{room.port}/ws?room={code}&id={controller_id}"
+
+
+def run(coro):
+    return asyncio.run(coro)
+
+
+def test_wrong_room_code_is_refused(room):
+    async def go():
+        async with aiohttp.ClientSession() as s:
+            with pytest.raises(aiohttp.WSServerHandshakeError):
+                await s.ws_connect(ws_url(room, "wrong"))
+
+    run(go())
+
+
+def test_controller_streams_orientation_and_button(room):
+    joined = []
+    room.on_join = joined.append
+
+    async def go():
+        async with aiohttp.ClientSession() as s:
+            async with s.ws_connect(ws_url(room, room.code)) as ws:
+                assert json.loads((await ws.receive()).data) == {"t": "slot", "slot": 0}
+                await ws.send_json({"a": 10, "b": 30, "g": -15, "p": 0})  # first reading recentres
+                await ws.send_json({"a": 40, "b": 30, "g": -15, "p": 1})
+                await asyncio.sleep(0.2)
+                c = room.controller(0)
+                assert c.connected and c.button
+                yaw, pitch, roll = c.euler
+                assert yaw == pytest.approx(30, abs=1e-6)
+                assert pitch == pytest.approx(30, abs=1e-6)
+                assert roll == pytest.approx(-15, abs=1e-6)
+            await asyncio.sleep(0.2)
+
+    run(go())
+    assert joined == [room.controller(0)]
+    assert not room.controller(0).connected
+
+
+def test_reloaded_tab_replaces_old_connection_in_same_slot(room):
+    async def go():
+        async with aiohttp.ClientSession() as s:
+            old = await s.ws_connect(ws_url(room, room.code))
+            await old.receive()
+            new = await s.ws_connect(ws_url(room, room.code))
+            assert json.loads((await new.receive()).data)["slot"] == 0
+            await asyncio.sleep(0.2)
+            assert room.controller(0).connected
+            assert len(room.controllers) == 1
+            await new.close()
+            await old.close()
+
+    run(go())