wsljoy 0.1.1__tar.gz

wsljoy-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python 3.10
+        run: uv python install 3.10
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish

wsljoy-0.1.1/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+*.egg-info/

wsljoy-0.1.1/.python-version

@@ -0,0 +1 @@
+3.10

wsljoy-0.1.1/.vscode/c_cpp_properties.json

@@ -0,0 +1,20 @@
+{
+  "configurations": [
+    {
+      "browse": {
+        "databaseFilename": "${workspaceFolder}/.vscode/browse.vc.db",
+        "limitSymbolsToIncludedHeaders": false
+      },
+      "includePath": [
+        "/opt/ros/humble/include/**",
+        "/usr/include/**"
+      ],
+      "name": "ros2",
+      "intelliSenseMode": "gcc-x64",
+      "compilerPath": "/usr/bin/gcc",
+      "cStandard": "gnu11",
+      "cppStandard": "c++17"
+    }
+  ],
+  "version": 4
+}

wsljoy-0.1.1/.vscode/settings.json

@@ -0,0 +1,13 @@
+{
+    "ROS2.distro": "humble",
+    "python.autoComplete.extraPaths": [
+        "/home/avula/workspaces/waywiser_ws/.venv/lib/python3.10/site-packages",
+        "/opt/ros/humble/lib/python3.10/site-packages",
+        "/opt/ros/humble/local/lib/python3.10/dist-packages"
+    ],
+    "python.analysis.extraPaths": [
+        "/home/avula/workspaces/waywiser_ws/.venv/lib/python3.10/site-packages",
+        "/opt/ros/humble/lib/python3.10/site-packages",
+        "/opt/ros/humble/local/lib/python3.10/dist-packages"
+    ]
+}

wsljoy-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ramana Avula
+
+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.

wsljoy-0.1.1/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: wsljoy
+Version: 0.1.1
+Summary: Mirror a Windows USB or Bluetooth game controller into WSL2 as a Linux joystick.
+Author: wsljoy contributors
+License: MIT
+License-File: LICENSE
+Requires-Python: <3.11,>=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: linux
+Provides-Extra: windows
+Requires-Dist: hidapi>=0.14; extra == 'windows'
+Requires-Dist: pygame>=2.5; extra == 'windows'
+Description-Content-Type: text/markdown
+
+# wsljoy
+
+`wsljoy` mirrors a controller connected to Windows over USB or Bluetooth into WSL2 as a normal Linux joystick device.
+
+## Python
+
+Use Python 3.10. The project is pinned to Python 3.10 because the Windows controller dependencies have the most reliable wheel support there.
+
+## Windows Host
+
+With `uv`:
+
+```cmd
+uv python install 3.10
+uv sync --extra windows
+uv run python -m wsljoy list
+uv run python -m wsljoy host
+```
+
+With standard `venv` and `pip`:
+
+```cmd
+py -3.10 -m venv .venv
+.venv\Scripts\activate.bat
+python -m pip install --upgrade pip
+python -m pip install -e ".[windows]"
+python -m wsljoy list
+python -m wsljoy host
+```
+
+## WSL2 Guest
+
+With `uv`:
+
+```bash
+uv sync --extra linux
+uv run python -m wsljoy setup-uinput
+uv run python -m wsljoy guest
+```
+
+With standard `venv` and `pip`:
+
+```bash
+python3.10 -m venv .venv
+. .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[linux]"
+python -m wsljoy setup-uinput
+python -m wsljoy guest
+```
+
+`setup-uinput` first checks whether `/dev/uinput` is already writable. It only asks for sudo when your user needs to be added to the `input` group; after that, start a new WSL shell or run `newgrp input`, then run the guest without sudo.
+
+It creates a virtual Linux input device through `/dev/uinput` using the Linux uinput API. The `/dev/input/event*` device appears after the guest receives the first packet from Windows. The `/dev/input/js*` device appears when the Linux `joydev` module is available and loaded.
+
+Check the guest side:
+
+```bash
+ls -l /dev/uinput
+groups
+python -m wsljoy guest
+```
+
+In a second WSL terminal, after the Windows host is running:
+
+```bash
+ls -l /dev/input/event* /dev/input/js*
+```
+
+If `event*` exists but `js*` does not, try:
+
+```bash
+sudo modprobe joydev
+```
+
+## Network Setup
+
+By default the Windows host targets WSL2. On Windows, `wsljoy` resolves the current WSL2 IP by running `wsl.exe hostname -I`.
+
+With `uv`:
+
+```cmd
+uv run python -m wsljoy host
+```
+
+```bash
+uv run python -m wsljoy guest --listen 0.0.0.0 --port 27414
+```
+
+With an activated venv:
+
+```cmd
+python -m wsljoy host
+```
+
+```bash
+python -m wsljoy guest --listen 0.0.0.0 --port 27414
+```
+
+If you have multiple WSL distros, name the one running the guest:
+
+```cmd
+python -m wsljoy host --wsl-distro Ubuntu-22.04
+```
+
+To bypass WSL auto-resolution, pass an explicit IP address:
+
+```cmd
+python -m wsljoy host --target 172.25.121.7
+```
+
+## Controller Support
+
+The Windows host has two reader backends:
+
+- `ds4-hid`: exact DualShock 4 HID parser for USB and Bluetooth, preferred automatically for DS4 devices.
+- `sdl`: generic SDL/pygame joystick reader, used for common Xbox, PlayStation, 8BitDo, Nintendo, Logitech, PowerA, Razer, and compatible controllers.
+
+If the same controller is visible through both APIs, `list` shows the exact backend and hides the duplicate SDL entry. `host --backend auto` prefers `ds4-hid`; use `host --backend sdl` to force SDL.
+
+Auto detection is the default:
+
+```cmd
+python -m wsljoy list
+python -m wsljoy host --backend auto
+```
+
+Force the generic backend:
+
+```cmd
+python -m wsljoy host --backend sdl
+```
+
+The exact DS4 path supports:
+
+- Sony vendor ID `054c`
+- Product IDs `05c4` and `09cc`
+- USB reports and Bluetooth reports
+
+The SDL path covers many usual-suspect controllers but depends on the mapping SDL exposes for that device. The WSL side creates a virtual Linux gamepad with the detected vendor/product IDs when available and Linux-style axes/buttons available through `/dev/input/event*` and `/dev/input/js*`.
+
+## Development
+
+With `uv`:
+
+```bash
+uv python install 3.10
+uv sync --all-extras --dev
+uv run pytest
+```
+
+With standard `venv` and `pip`:
+
+```bash
+python3.10 -m venv .venv
+. .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+python -m pytest
+```

wsljoy-0.1.1/README.md

@@ -0,0 +1,160 @@
+# wsljoy
+
+`wsljoy` mirrors a controller connected to Windows over USB or Bluetooth into WSL2 as a normal Linux joystick device.
+
+## Python
+
+Use Python 3.10. The project is pinned to Python 3.10 because the Windows controller dependencies have the most reliable wheel support there.
+
+## Windows Host
+
+With `uv`:
+
+```cmd
+uv python install 3.10
+uv sync --extra windows
+uv run python -m wsljoy list
+uv run python -m wsljoy host
+```
+
+With standard `venv` and `pip`:
+
+```cmd
+py -3.10 -m venv .venv
+.venv\Scripts\activate.bat
+python -m pip install --upgrade pip
+python -m pip install -e ".[windows]"
+python -m wsljoy list
+python -m wsljoy host
+```
+
+## WSL2 Guest
+
+With `uv`:
+
+```bash
+uv sync --extra linux
+uv run python -m wsljoy setup-uinput
+uv run python -m wsljoy guest
+```
+
+With standard `venv` and `pip`:
+
+```bash
+python3.10 -m venv .venv
+. .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[linux]"
+python -m wsljoy setup-uinput
+python -m wsljoy guest
+```
+
+`setup-uinput` first checks whether `/dev/uinput` is already writable. It only asks for sudo when your user needs to be added to the `input` group; after that, start a new WSL shell or run `newgrp input`, then run the guest without sudo.
+
+It creates a virtual Linux input device through `/dev/uinput` using the Linux uinput API. The `/dev/input/event*` device appears after the guest receives the first packet from Windows. The `/dev/input/js*` device appears when the Linux `joydev` module is available and loaded.
+
+Check the guest side:
+
+```bash
+ls -l /dev/uinput
+groups
+python -m wsljoy guest
+```
+
+In a second WSL terminal, after the Windows host is running:
+
+```bash
+ls -l /dev/input/event* /dev/input/js*
+```
+
+If `event*` exists but `js*` does not, try:
+
+```bash
+sudo modprobe joydev
+```
+
+## Network Setup
+
+By default the Windows host targets WSL2. On Windows, `wsljoy` resolves the current WSL2 IP by running `wsl.exe hostname -I`.
+
+With `uv`:
+
+```cmd
+uv run python -m wsljoy host
+```
+
+```bash
+uv run python -m wsljoy guest --listen 0.0.0.0 --port 27414
+```
+
+With an activated venv:
+
+```cmd
+python -m wsljoy host
+```
+
+```bash
+python -m wsljoy guest --listen 0.0.0.0 --port 27414
+```
+
+If you have multiple WSL distros, name the one running the guest:
+
+```cmd
+python -m wsljoy host --wsl-distro Ubuntu-22.04
+```
+
+To bypass WSL auto-resolution, pass an explicit IP address:
+
+```cmd
+python -m wsljoy host --target 172.25.121.7
+```
+
+## Controller Support
+
+The Windows host has two reader backends:
+
+- `ds4-hid`: exact DualShock 4 HID parser for USB and Bluetooth, preferred automatically for DS4 devices.
+- `sdl`: generic SDL/pygame joystick reader, used for common Xbox, PlayStation, 8BitDo, Nintendo, Logitech, PowerA, Razer, and compatible controllers.
+
+If the same controller is visible through both APIs, `list` shows the exact backend and hides the duplicate SDL entry. `host --backend auto` prefers `ds4-hid`; use `host --backend sdl` to force SDL.
+
+Auto detection is the default:
+
+```cmd
+python -m wsljoy list
+python -m wsljoy host --backend auto
+```
+
+Force the generic backend:
+
+```cmd
+python -m wsljoy host --backend sdl
+```
+
+The exact DS4 path supports:
+
+- Sony vendor ID `054c`
+- Product IDs `05c4` and `09cc`
+- USB reports and Bluetooth reports
+
+The SDL path covers many usual-suspect controllers but depends on the mapping SDL exposes for that device. The WSL side creates a virtual Linux gamepad with the detected vendor/product IDs when available and Linux-style axes/buttons available through `/dev/input/event*` and `/dev/input/js*`.
+
+## Development
+
+With `uv`:
+
+```bash
+uv python install 3.10
+uv sync --all-extras --dev
+uv run pytest
+```
+
+With standard `venv` and `pip`:
+
+```bash
+python3.10 -m venv .venv
+. .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+python -m pytest
+```

wsljoy-0.1.1/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "wsljoy"
+version = "0.1.1"
+description = "Mirror a Windows USB or Bluetooth game controller into WSL2 as a Linux joystick."
+readme = "README.md"
+requires-python = ">=3.10,<3.11"
+license = { text = "MIT" }
+authors = [{ name = "wsljoy contributors" }]
+dependencies = []
+
+[project.optional-dependencies]
+windows = ["hidapi>=0.14", "pygame>=2.5"]
+linux = []
+dev = ["pytest>=8"]
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[project.scripts]
+wsljoy-host = "wsljoy.cli:host_main"
+wsljoy-guest = "wsljoy.cli:guest_main"
+wsljoy-list = "wsljoy.cli:list_main"
+wsljoy-setup-uinput = "wsljoy.setup_uinput:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/wsljoy"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

wsljoy-0.1.1/src/wsljoy/__init__.py

@@ -0,0 +1,4 @@
+"""Mirror Windows game controller input into WSL2."""
+
+__all__ = ["__version__"]
+__version__ = "0.1.0"

wsljoy-0.1.1/src/wsljoy/__main__.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Callable
+
+
+COMMANDS = {
+    "list": "List supported Windows controllers.",
+    "host": "Send Windows controller state to WSL2.",
+    "guest": "Create a virtual gamepad in Linux/WSL2.",
+    "setup-uinput": "Configure /dev/uinput permissions.",
+}
+
+
+def _load_handler(command: str) -> Callable[[list[str] | None], None]:
+    if command == "list":
+        from .cli import list_main
+
+        return list_main
+    if command == "host":
+        from .cli import host_main
+
+        return host_main
+    if command == "guest":
+        from .cli import guest_main
+
+        return guest_main
+    if command == "setup-uinput":
+        from .setup_uinput import main as setup_uinput_main
+
+        return setup_uinput_main
+    choices = ", ".join(COMMANDS)
+    raise SystemExit(f"unknown command: {command}\nchoose one of: {choices}")
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = list(sys.argv[1:] if argv is None else argv)
+    if not args or args[0] in {"-h", "--help"}:
+        parser = argparse.ArgumentParser(prog="python -m wsljoy")
+        subcommands = parser.add_subparsers(dest="command")
+        for name, help_text in COMMANDS.items():
+            subcommands.add_parser(name, help=help_text)
+        parser.print_help()
+        return
+
+    command = args.pop(0)
+    handler = _load_handler(command)
+    try:
+        handler(args)
+    except KeyboardInterrupt:
+        print("\nStopped.")
+
+
+if __name__ == "__main__":
+    main()

wsljoy-0.1.1/src/wsljoy/cli.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import argparse
+
+
+def list_main(argv: list[str] | None = None) -> None:
+    from .controllers.common import decode_hid_path
+    from .windows import list_controllers
+
+    devices = list_controllers()
+    if not devices:
+        print("No supported game controllers found.")
+        return
+    for index, device in enumerate(devices):
+        product = device.get("product_string") or "Wireless Controller"
+        path = decode_hid_path(device.get("path"))
+        vendor_id = int(device.get("vendor_id") or 0)
+        product_id = int(device.get("product_id") or 0)
+        print(
+            f"{index}: [{device.get('backend', 'unknown')}] {product} "
+            f"vid={vendor_id:04x} pid={product_id:04x} "
+            f"path={path}"
+        )
+
+
+def host_main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(description="Send Windows controller state to WSL2.")
+    parser.add_argument("--target", default="wsl", help="WSL/Linux UDP target address. Defaults to `wsl`, resolved via wsl.exe; explicit IPs are also allowed.")
+    parser.add_argument("--wsl-distro", help="WSL distro name to use when --target is wsl/wsl2.")
+    parser.add_argument("--port", type=int, default=27414, help="UDP target port.")
+    parser.add_argument("--path", help="Controller path from wsljoy-list.")
+    parser.add_argument(
+        "--backend",
+        choices=("auto", "ds4-hid", "sdl"),
+        default="auto",
+        help="Controller reader backend.",
+    )
+    parser.add_argument("--rate", type=float, default=250.0, help="Maximum send rate in Hz.")
+    args = parser.parse_args(argv)
+
+    from .windows import run_host
+
+    try:
+        run_host(
+            target=args.target,
+            port=args.port,
+            path=args.path,
+            backend=args.backend,
+            rate_limit_hz=args.rate,
+            wsl_distro=args.wsl_distro,
+        )
+    except KeyboardInterrupt:
+        print("\nStopped.")
+
+
+def guest_main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(description="Create a virtual gamepad in Linux/WSL2.")
+    parser.add_argument("--listen", default="0.0.0.0", help="UDP listen address.")
+    parser.add_argument("--port", type=int, default=27414, help="UDP listen port.")
+    parser.add_argument("--stale-after", type=float, default=1.0, help="Neutralize after silence.")
+    args = parser.parse_args(argv)
+
+    from .linux import run_guest
+
+    try:
+        run_guest(listen=args.listen, port=args.port, stale_after=args.stale_after)
+    except KeyboardInterrupt:
+        print("\nStopped.")

wsljoy-0.1.1/src/wsljoy/controllers/__init__.py

@@ -0,0 +1,2 @@
+"""Controller backends used by the Windows host."""
+

wsljoy-0.1.1/src/wsljoy/controllers/common.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+
+KNOWN_GAMEPAD_VENDORS = {
+    0x044F: "Thrustmaster",
+    0x045E: "Microsoft",
+    0x046D: "Logitech",
+    0x054C: "Sony",
+    0x057E: "Nintendo",
+    0x0738: "Mad Catz",
+    0x0E6F: "PDP",
+    0x1532: "Razer",
+    0x20D6: "PowerA",
+    0x24C6: "PowerA",
+    0x2DC8: "8BitDo",
+}
+
+
+def is_known_gamepad(device: dict) -> bool:
+    vendor_id = int(device.get("vendor_id") or 0)
+    usage_page = int(device.get("usage_page") or 0)
+    usage = int(device.get("usage") or 0)
+    product = str(device.get("product_string") or "").lower()
+    manufacturer = str(device.get("manufacturer_string") or "").lower()
+
+    if vendor_id in KNOWN_GAMEPAD_VENDORS:
+        return True
+    if usage_page == 0x01 and usage in {0x04, 0x05}:
+        return True
+    return any(
+        token in f"{manufacturer} {product}"
+        for token in (
+            "xbox",
+            "dualshock",
+            "dualsense",
+            "wireless controller",
+            "8bitdo",
+            "gamepad",
+            "controller",
+        )
+    )
+
+
+def decode_hid_path(path: object) -> str:
+    if isinstance(path, bytes):
+        return path.decode(errors="replace")
+    return str(path or "")
+
+
+def hid_connection(device: dict) -> str:
+    bus_type = int(device.get("bus_type") or 0)
+    if bus_type == 1:
+        return "usb"
+    if bus_type == 2:
+        return "bluetooth"
+
+    path = decode_hid_path(device.get("path")).lower()
+    if "bth" in path or "bluetooth" in path:
+        return "bluetooth"
+    if "usb" in path or "vid_" in path:
+        return "usb"
+    return "unknown"