padsquire 0.1.0__py3-none-any.whl

padsquire/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Linux tools for GameSir controllers (Nova 2 Lite first)."""
+
+__version__ = "0.1.0"

padsquire/__main__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""`python -m padsquire`: the same as the padsquire command."""
+import sys
+
+from .cli import main
+
+sys.exit(main())

padsquire/ble.py

@@ -0,0 +1,125 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Bluetooth LE transport for the GCM protocol, via bleak (BlueZ on Linux).
+
+What the Android app does for a Nova 2 Lite (BluetoothLeService):
+  - finds the BLE config identity "GameSir-Nova 2 Lite_xxxx" (not "_DFU")
+  - service 0x8650; enables notifications on 0x865F and 0x8655
+  - writes each command to 0x865F (write with response)
+  - waits ~60 ms (bleWriteAfterReadIntervalTime) and reads the reply from 0x865F
+
+ASSUMPTION: replies are read from 0x865F rather than delivered by notification
+(the Nova 2 Lite config sets bleIsNotifyCallback = false). If hardware proves
+otherwise, NOTIFY_REPLIES switches to notification mode.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Callable
+
+SERVICE_UUID = "00008650-0000-1000-8000-00805f9b34fb"
+COMMAND_UUID = "0000865f-0000-1000-8000-00805f9b34fb"
+DATA_UUID = "00008655-0000-1000-8000-00805f9b34fb"
+NAME_PREFIX = "GameSir-Nova 2 Lite_"
+DFU_NAME = "GameSir-Nova 2 Lite_DFU"
+
+READ_DELAY = 0.06
+READ_ATTEMPTS = 4
+NOTIFY_REPLIES = False
+
+
+class BleError(RuntimeError):
+    pass
+
+
+def _bleak():
+    try:
+        import bleak
+    except ImportError:
+        raise BleError("Bluetooth support needs bleak: pip install 'padsquire[ble]'") from None
+    return bleak
+
+
+def is_config_name(name: str | None) -> bool:
+    return bool(name) and name.startswith(NAME_PREFIX) and name != DFU_NAME
+
+
+async def scan(timeout: float = 6.0) -> list[tuple[str, str]]:
+    """(address, name) of every Nova 2 Lite config channel in range."""
+    bleak = _bleak()
+    try:
+        found = await bleak.BleakScanner.discover(timeout=timeout)
+    except FileNotFoundError:
+        raise BleError("Bluetooth is unavailable: is bluetoothd running? "
+                       "(systemctl status bluetooth)") from None
+    except Exception as e:
+        raise BleError(f"Bluetooth scan failed: {e or type(e).__name__} "
+                       "(is the adapter powered on? bluetoothctl power on)") from e
+    return sorted((d.address, d.name) for d in found if is_config_name(d.name))
+
+
+class BleTransport:
+    """Wraps a connected bleak client (or anything with the same methods)."""
+
+    def __init__(self, client, read_delay: float = READ_DELAY, attempts: int = READ_ATTEMPTS):
+        self.client = client
+        self.read_delay = read_delay
+        self.attempts = attempts
+        self._notified: asyncio.Queue[bytes] = asyncio.Queue()
+        self._lock = asyncio.Lock()
+
+    async def start(self) -> None:
+        # The app subscribes to both characteristics; some firmware only answers
+        # once that has happened. Failures here are not fatal.
+        for uuid in (COMMAND_UUID, DATA_UUID):
+            try:
+                await self.client.start_notify(uuid, self._on_notify if uuid == COMMAND_UUID else _ignore)
+            except Exception:
+                pass
+
+    def _on_notify(self, _sender, data: bytearray) -> None:
+        if NOTIFY_REPLIES:
+            self._notified.put_nowait(bytes(data))
+
+    async def request(self, frame: bytes, accept: Callable[[bytes], bool] | None = None) -> bytes:
+        accept = accept or (lambda _r: True)
+        async with self._lock:
+            await self.client.write_gatt_char(COMMAND_UUID, frame, response=True)
+            last = b""
+            for _ in range(self.attempts):
+                await asyncio.sleep(self.read_delay)
+                if NOTIFY_REPLIES:
+                    last = await asyncio.wait_for(self._notified.get(), timeout=1.0)
+                else:
+                    last = bytes(await self.client.read_gatt_char(COMMAND_UUID))
+                if accept(last):
+                    return last
+            raise BleError(f"no valid reply to {frame.hex(' ')} (last read: {last.hex(' ') or 'nothing'})")
+
+
+def _ignore(_sender, _data) -> None:
+    pass
+
+
+class connect:
+    """async with connect(address) as transport: ..."""
+
+    def __init__(self, address: str, timeout: float = 15.0):
+        self.address, self.timeout = address, timeout
+
+    async def __aenter__(self) -> BleTransport:
+        bleak = _bleak()
+        self._client = bleak.BleakClient(self.address, timeout=self.timeout)
+        try:
+            await self._client.connect()
+        except FileNotFoundError:
+            raise BleError("Bluetooth is unavailable: is bluetoothd running? "
+                           "(systemctl status bluetooth)") from None
+        except Exception as e:
+            raise BleError(f"could not connect to {self.address}: {e or type(e).__name__}") from e
+        transport = BleTransport(self._client)
+        await transport.start()
+        return transport
+
+    async def __aexit__(self, *exc) -> None:
+        await self._client.disconnect()

padsquire/cli.py

@@ -0,0 +1,233 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""PadSquire command line."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from . import __version__, installer, jlflash, paths, safety, ufw
+
+DEFAULT_FW_DIR = paths.FIRMWARE_DIR
+
+
+def cmd_extract(args) -> int:
+    try:
+        manifest = installer.extract(args.installer, args.output, model=args.model)
+    except (installer.ExtractError, OSError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    print(f"GameSir Connect {manifest['gamesir_connect_version']}: "
+          f"extracted {len(manifest['firmware'])} firmware files to {args.output}")
+    for fw in manifest["firmware"]:
+        region = f", {fw['region']}" if fw["region"] else ""
+        print(f"  {fw['target']:10} v{fw['version']}{region:15} {fw['file']}")
+    return 0
+
+
+def cmd_update(args) -> int:
+    from . import updater
+
+    shown = []
+
+    def progress(done, total):
+        if sys.stderr.isatty():
+            pct = f"{done * 100 // total}%" if total else f"{done >> 20} MB"
+            print(f"\rdownloading GameSir Connect... {pct}", end="", file=sys.stderr, flush=True)
+            shown.append(True)
+
+    try:
+        r = updater.update(args.firmware_dir, feed_url=args.feed, check_only=args.check,
+                           force=args.force, keep_installer=args.keep_installer, progress=progress)
+    except (updater.UpdateError, installer.ExtractError, OSError) as e:
+        print(("\n" if shown else "") + f"error: {e}", file=sys.stderr)
+        return 1
+    if shown:
+        print(file=sys.stderr)
+    have = r.current or "none"
+    if r.updated:
+        print(f"updated firmware from GameSir Connect {have} to {r.latest}")
+        for fw in r.manifest["firmware"]:
+            region = f", {fw['region']}" if fw["region"] else ""
+            print(f"  {fw['target']:10} v{fw['version']}{region:15} {fw['file']}")
+    elif updater.version_key(r.latest) > updater.version_key(r.current):
+        print(f"GameSir Connect {r.latest} is available (you have {have}); "
+              "run `padsquire update` to fetch it")
+    else:
+        print(f"up to date (GameSir Connect {have})")
+    return 0
+
+
+def cmd_gui(args) -> int:
+    try:
+        from .web.server import serve
+    except ImportError:
+        print("the GUI needs aiohttp: pip install --user 'padsquire[gui]'", file=sys.stderr)
+        return 1
+    serve(args.firmware_dir, port=args.port, simulate=args.simulate, open_browser=not args.no_browser,
+          tab=args.tab, keep_running=args.keep_running or args.no_browser)
+    return 0
+
+
+def cmd_menu(args) -> int:
+    from . import desktop
+    if args.remove:
+        gone = desktop.remove_entry()
+        print("Removed " + ", ".join(map(str, gone)) if gone else "PadSquire wasn't in the app menu.")
+        return 0
+    for f in desktop.install_entry():
+        print(f"Wrote {f}")
+    print("PadSquire is in your app menu. To take it out again: padsquire menu --remove")
+    return 0
+
+
+def cmd_udev_rules(args) -> int:
+    from . import desktop
+    if args.path:
+        print(desktop.rules_path())
+    else:
+        sys.stdout.write(desktop.rules_text())
+    return 0
+
+
+def cmd_ufw(args) -> int:
+    try:
+        f = ufw.load(args.file)
+    except (ufw.UfwError, OSError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    problems = f.problems()
+    if args.json:
+        print(json.dumps({
+            "chip": f.chip, "jl_pid": f.jl_pid, "jl_vid": f.jl_vid,
+            "tool_version": f.tool_version, "size": len(f.data), "ok": not problems,
+            "problems": problems,
+            "entries": [{"name": e.name, "type": e.type, "offset": e.offset,
+                         "length": e.length, "crc_ok": e.crc_ok} for e in f.entries],
+        }, indent=2))
+    else:
+        print(f"chip      {f.chip}")
+        print(f"identity  PID={f.jl_pid}  VID={f.jl_vid}")
+        print(f"built by  {f.tool_version}")
+        print(f"size      {len(f.data)} bytes, {len(f.entries)} partitions")
+        for e in f.entries:
+            mark = "ok " if e.crc_ok else "BAD"
+            print(f"  [{mark}] {e.name:16} offset {e.offset:#09x}  {e.length:>8} bytes")
+        print("verdict   " + ("intact" if not problems else "DAMAGED: " + "; ".join(problems)))
+    return 0 if not problems else 1
+
+
+def cmd_plan(args) -> int:
+    try:
+        bundled = installer.load_manifest(args.firmware_dir)
+    except (OSError, KeyError, ValueError) as e:
+        print(f"error: cannot read manifest in {args.firmware_dir}: {e}", file=sys.stderr)
+        return 1
+    device = safety.DeviceState(args.target, args.pid, args.vid, args.version)
+    if not (args.pid and args.vid):
+        print("BLOCKED    device identity unknown (--pid/--vid); refusing to guess")
+        return 2
+    fw = safety.choose_firmware(device, bundled)
+    if fw is None:
+        print("no matching firmware in this release for that device")
+        return 1
+    plan = safety.plan_update(
+        device, fw, Path(args.firmware_dir) / fw.file,
+        dongle_version=args.dongle_version, bundled=bundled, reinstall=args.reinstall,
+    )
+    print(f"candidate  {fw.file} (v{fw.version})")
+    errors = list(plan.errors)
+    if args.backup is None:
+        errors.append("no flash backup of this controller (--backup, from `padsquire uboot backup`)")
+    else:
+        image = safety.choose_flash_image(Path(args.firmware_dir) / fw.file, args.backup)
+        errors += image.errors
+        if image.partition:
+            print(f"image      {image.partition} -> {image.start:#x}-{image.end - 1:#x}; keeps "
+                  + ", ".join(jlflash.RESERVED))
+    for w in plan.warnings:
+        print(f"warning    {w}")
+    for e in errors:
+        print(f"BLOCKED    {e}")
+    print("verdict    " + ("would flash" if not errors else "will not flash"))
+    return 0 if not errors else 2
+
+
+def main(argv=None) -> int:
+    if os.environ.get("PADSQUIRE_DEBUG"):
+        import logging
+        logging.basicConfig(level=logging.DEBUG, format="%(asctime)s.%(msecs)03d %(name)s %(message)s",
+                            datefmt="%H:%M:%S")
+    for line in paths.migrate():          # the folders of the old name, gamesir-linux, once
+        print(f"PadSquire: {line}", file=sys.stderr)
+    p = argparse.ArgumentParser(prog="padsquire", description="PadSquire: Linux tools for GameSir controllers")
+    p.add_argument("--version", action="version", version=__version__)
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    e = sub.add_parser("extract", help="pull firmware out of a GameSir Connect installer")
+    e.add_argument("installer", help="GameSir Connect Setup .exe")
+    e.add_argument("-o", "--output", type=Path, default=DEFAULT_FW_DIR)
+    e.add_argument("--model", default="T4N2", help="GameSir model code (T4N2 = Nova 2 Lite)")
+    e.set_defaults(func=cmd_extract)
+
+    from .updater import FEED_URL
+    up = sub.add_parser("update", help="check for new official firmware and download it")
+    up.add_argument("--check", action="store_true", help="only report whether a newer release exists")
+    up.add_argument("--force", action="store_true", help="re-download even if already current")
+    up.add_argument("--firmware-dir", type=Path, default=DEFAULT_FW_DIR)
+    up.add_argument("--keep-installer", type=Path, metavar="PATH", help="also save the installer here")
+    up.add_argument("--feed", default=FEED_URL, help=argparse.SUPPRESS)
+    up.set_defaults(func=cmd_update)
+
+    u = sub.add_parser("ufw", help="inspect and verify a .ufw firmware file")
+    u.add_argument("file")
+    u.add_argument("--json", action="store_true")
+    u.set_defaults(func=cmd_ufw)
+
+    pl = sub.add_parser(
+        "plan", help="dry run: would this device be updated, and with what?",
+        description="Until device detection exists, describe the device by hand.",
+    )
+    pl.add_argument("--firmware-dir", type=Path, default=DEFAULT_FW_DIR)
+    pl.add_argument("--target", choices=["controller", "dongle"], required=True)
+    pl.add_argument("--pid", help="JieLi PID string, e.g. AC695X_TRANS")
+    pl.add_argument("--vid", help="JieLi VID string, e.g. N2LT")
+    pl.add_argument("--version", type=int, help="installed firmware version, e.g. 8101")
+    pl.add_argument("--dongle-version", type=int)
+    pl.add_argument("--reinstall", action="store_true")
+    pl.add_argument("--backup", type=Path, help="this controller's flash backup (.bin with its .json)")
+    pl.set_defaults(func=cmd_plan)
+
+    from . import cli_ble, cli_probe, cli_uboot
+    cli_ble.register(sub)
+    cli_probe.register(sub)
+    cli_uboot.register(sub)
+
+    g = sub.add_parser("gui", help="open the graphical settings app in your browser")
+    g.add_argument("--simulate", action="store_true", help="start connected to a simulated controller")
+    g.add_argument("--port", type=int, default=0, help="port on 127.0.0.1 (default: any free port)")
+    g.add_argument("--no-browser", action="store_true",
+                   help="print the address instead of opening it (keeps running until Ctrl+C)")
+    g.add_argument("--tab", action="store_true", help="open in a browser tab instead of its own window")
+    g.add_argument("--keep-running", action="store_true",
+                   help="don't stop when the app's window is closed")
+    g.add_argument("--firmware-dir", type=Path, default=DEFAULT_FW_DIR)
+    g.set_defaults(func=cmd_gui)
+
+    m = sub.add_parser("menu", help="add PadSquire to your app menu (no root needed)")
+    m.add_argument("--remove", action="store_true", help="take it out of the app menu again")
+    m.set_defaults(func=cmd_menu)
+
+    r = sub.add_parser("udev-rules", help="print the udev rules that let you use the controller without sudo")
+    r.add_argument("--path", action="store_true", help="print where the rules file is instead")
+    r.set_defaults(func=cmd_udev_rules)
+
+    args = p.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

padsquire/cli_ble.py

@@ -0,0 +1,218 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""`padsquire ble ...` and `padsquire usb ...`: configure a Nova 2 Lite over
+Bluetooth LE or the USB cable. Both speak GCM, so they share every action."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import contextlib
+import sys
+
+from . import ble, hid
+from .client import NotApplied, NovaClient
+from .gcm import DeadZone, Feature, ProtocolError, Vibration
+from .simulator import SimulatedNova
+
+
+def _names(enum) -> dict[str, object]:
+    return {m.name.lower().replace("_", "-"): m for m in enum}
+
+
+ZONES = _names(DeadZone)
+FEATURES = _names(Feature)
+ON_OFF = {"on": True, "off": False, "true": True, "false": False, "1": True, "0": False}
+
+
+def _byte(text: str) -> int:
+    v = int(text)
+    if not 0 <= v <= 255:
+        raise argparse.ArgumentTypeError("must be 0-255")
+    return v
+
+
+@contextlib.asynccontextmanager
+async def _open(args):
+    if args.simulate:
+        yield NovaClient(SimulatedNova())
+        return
+    if args.link == "usb":
+        async with hid.connect(_usb_path(args)) as transport:
+            yield NovaClient(transport)
+        return
+    address = args.address
+    if not address:
+        found = await ble.scan()
+        if not found:
+            raise ble.BleError(
+                "no Nova 2 Lite found. Put it in Bluetooth mode and pair it, or pass --address")
+        if len(found) > 1:
+            raise ble.BleError("several found, pick one with --address: "
+                               + ", ".join(f"{a} ({n})" for a, n in found))
+        address = found[0][0]
+    async with ble.connect(address) as transport:
+        yield NovaClient(transport)
+
+
+def _usb_path(args) -> str:
+    if args.device:
+        return args.device
+    found = hid.find()
+    if not found:
+        raise hid.HidError("no Nova 2 Lite found on USB. Connect the cable and switch to PC/Xbox "
+                           "mode (hold Menu + View until the LED is green), or pass --device")
+    if len(found) > 1:
+        raise hid.HidError("several found, pick one with --device: "
+                           + ", ".join(f"{d.path} ({d.link})" for d in found))
+    return found[0].path
+
+
+# -- actions -------------------------------------------------------------------
+
+async def a_scan(args) -> int:
+    if args.link == "usb" and not args.simulate:
+        found = hid.find()
+        for d in found:
+            print(f"{d.path}  GameSir Nova 2 Lite  ({d.link})")
+        if not found:
+            print("nothing found (is the cable in, and the LED green?)", file=sys.stderr)
+        return 0 if found else 1
+    if args.simulate:
+        print("00:00:00:00:00:00  GameSir-Nova 2 Lite_SIM  (simulated)")
+        return 0
+    found = await ble.scan(args.timeout)
+    for address, name in found:
+        print(f"{address}  {name}")
+    if not found:
+        print("nothing found (is the controller in Bluetooth mode?)", file=sys.stderr)
+    return 0 if found else 1
+
+
+async def a_info(args) -> int:
+    async with _open(args) as nova:
+        info = await nova.info()
+        bat = await nova.battery()
+    print(f"firmware      {info.firmware_version}")
+    print(f"hardware      {info.hardware_version}")
+    print(f"MAC           {info.mac}")
+    print(f"made          {info.production_date}")
+    print(f"protocol      GCM {info.gcm_version}")
+    print(f"battery       {bat.level}%{' (charging)' if bat.charging else ''}  [raw {bat.raw:#04x}]")
+    return 0
+
+
+async def a_deadzone(args) -> int:
+    async with _open(args) as nova:
+        if args.zone is None:
+            for name, zone in ZONES.items():
+                print(f"{name:22} {await nova.dead_zone(zone)}")
+        elif args.value is None:
+            print(await nova.dead_zone(ZONES[args.zone]))
+        else:
+            await nova.set_dead_zone(ZONES[args.zone], args.value)
+            print(f"{args.zone} = {args.value}")
+    return 0
+
+
+async def a_feature(args) -> int:
+    async with _open(args) as nova:
+        if args.name is None:
+            for name, feat in FEATURES.items():
+                print(f"{name:22} {'on' if await nova.feature(feat) else 'off'}")
+        elif args.state is None:
+            print("on" if await nova.feature(FEATURES[args.name]) else "off")
+        else:
+            await nova.set_feature(FEATURES[args.name], ON_OFF[args.state])
+            print(f"{args.name} = {args.state}")
+    return 0
+
+
+VIB_FIELDS = ["left_grip", "left_trigger", "right_grip", "right_trigger"]
+
+
+async def a_vibration(args) -> int:
+    async with _open(args) as nova:
+        v = await nova.vibration()
+        changes = {f: getattr(args, f) for f in VIB_FIELDS if getattr(args, f) is not None}
+        if changes:
+            v = Vibration(**{**v.__dict__, **changes})
+            await nova.set_vibration(v)
+    for f in VIB_FIELDS:
+        print(f"{f.replace('_', '-'):15} {getattr(v, f)}")
+    return 0
+
+
+async def a_sleep(args) -> int:
+    async with _open(args) as nova:
+        if args.minutes is not None:
+            await nova.set_auto_sleep(args.minutes)
+        print(f"auto sleep: {await nova.auto_sleep()}")
+    return 0
+
+
+async def a_restore(args) -> int:
+    if not args.yes:
+        print("this resets every setting on the controller; add --yes to confirm", file=sys.stderr)
+        return 2
+    async with _open(args) as nova:
+        await nova.restore_defaults()
+    print("restored factory defaults")
+    return 0
+
+
+# -- wiring --------------------------------------------------------------------
+
+def register(sub) -> None:
+    p = sub.add_parser("ble", help="configure the controller over Bluetooth LE")
+    p.add_argument("--address", help="Bluetooth address (default: scan for one)")
+    _add_actions(p, "ble")
+
+    p = sub.add_parser("usb", help="configure the controller over the USB cable (green LED mode)")
+    p.add_argument("--device", help="hidraw node, e.g. /dev/hidraw11 (default: find it)")
+    _add_actions(p, "usb")
+
+
+def _add_actions(p, link: str) -> None:
+    p.add_argument("--simulate", action="store_true", help="talk to a simulated controller")
+    p.set_defaults(link=link, address=None, device=None)
+    acts = p.add_subparsers(dest="action", required=True)
+
+    s = acts.add_parser("scan", help="list connected Nova 2 Lite controllers"
+                        if link == "usb" else "list Nova 2 Lite controllers in range")
+    s.add_argument("--timeout", type=float, default=6.0)
+    s.set_defaults(run=a_scan)
+
+    acts.add_parser("info", help="firmware version, battery, MAC").set_defaults(run=a_info)
+
+    d = acts.add_parser("deadzone", help="show or set dead zones")
+    d.add_argument("zone", nargs="?", choices=list(ZONES))
+    d.add_argument("value", nargs="?", type=_byte, help="raw value (units unconfirmed)")
+    d.set_defaults(run=a_deadzone)
+
+    f = acts.add_parser("feature", help="show or toggle features (stick swap, D-pad lock, ...)")
+    f.add_argument("name", nargs="?", choices=list(FEATURES))
+    f.add_argument("state", nargs="?", choices=list(ON_OFF))
+    f.set_defaults(run=a_feature)
+
+    v = acts.add_parser("vibration", help="show or set rumble strength")
+    for field in VIB_FIELDS:
+        v.add_argument("--" + field.replace("_", "-"), dest=field, type=_byte)
+    v.set_defaults(run=a_vibration)
+
+    z = acts.add_parser("sleep", help="show or set the auto-sleep time")
+    z.add_argument("minutes", nargs="?", type=_byte)
+    z.set_defaults(run=a_sleep)
+
+    r = acts.add_parser("restore", help="reset all settings to factory defaults")
+    r.add_argument("--yes", action="store_true")
+    r.set_defaults(run=a_restore)
+
+    p.set_defaults(func=run)
+
+
+def run(args) -> int:
+    try:
+        return asyncio.run(args.run(args))
+    except (ble.BleError, hid.HidError, ProtocolError, NotApplied, ValueError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1

padsquire/cli_probe.py

@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""`padsquire probe`: read-only first contact with a controller."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from . import probe
+
+GUIDE = [
+    ("wired-xinput",
+     "Connect the controller with the USB cable. Hold Home + X for 3 s (LED blue: XInput)."),
+    ("wired-dinput", "Still on the cable: hold Home + Y for 3 s (LED green: DInput)."),
+    ("wired-switch", "Still on the cable: hold Home + B for 3 s (LED red: Switch mode)."),
+    ("dongle", "Unplug the cable. Plug in the 2.4 GHz dongle and turn the controller on "
+               "so it connects to the dongle."),
+    ("controller-update-mode", "Unplug everything. Hold M + X + B while plugging in the USB cable "
+                               "(update mode). Nothing will be flashed."),
+    ("dongle-update-mode", "Unplug the controller. Hold the dongle's pairing button while plugging "
+                           "the dongle in (update mode). Nothing will be flashed."),
+    ("bluetooth", "Unplug everything. Turn the controller on in Bluetooth mode; the phone app uses "
+                  "Android mode, so try that first (Home + A for 3 s, LED yellow)."),
+]
+
+
+def _ask(prompt: str) -> str:
+    try:
+        return input(prompt).strip().lower()
+    except EOFError:
+        return "q"
+
+
+def _usb_id(text: str) -> tuple[str, str]:
+    vid, sep, pid = text.lower().partition(":")
+    if not sep or not all(len(x) == 4 and all(c in "0123456789abcdef" for c in x) for x in (vid, pid)):
+        raise argparse.ArgumentTypeError(f"expected VID:PID in hex, like 054c:09cc, not {text!r}")
+    return vid, pid
+
+
+def cmd_probe(args) -> int:
+    out = args.output or Path(f"gamesir-probe-{datetime.now():%Y%m%d-%H%M%S}.json")
+    report = probe.new_report()
+
+    if args.guided:
+        print("Read-only probe: nothing on the controller is changed.\n"
+              "For each step: set the controller up as described, then press Enter.\n"
+              "Type s to skip a step, q to stop and save.\n")
+        for label, text in GUIDE:
+            print(f"--- {label}\n{text}")
+            answer = _ask("[Enter] probe / [s]kip / [q]uit: ")
+            if answer == "q":
+                break
+            if answer == "s":
+                continue
+            snap = probe.snapshot(label, usb=label != "bluetooth", bluetooth=label == "bluetooth",
+                                  address=args.address, extra_ids=args.device)
+            report["snapshots"].append(snap)
+            probe.save(report, out)
+            print("\n".join(probe.summarize(snap)) + "\n")
+    else:
+        bluetooth = args.bluetooth or args.bluetooth_only or args.address is not None
+        snap = probe.snapshot(args.label, usb=not args.bluetooth_only, bluetooth=bluetooth,
+                              address=args.address, extra_ids=args.device)
+        report["snapshots"].append(snap)
+        print("\n".join(probe.summarize(snap)))
+
+    probe.save(report, out)
+    print(f"\nreport saved to {out}; please share this file")
+    return 0
+
+
+def register(sub) -> None:
+    p = sub.add_parser("probe", help="read-only: collect details about a connected controller",
+                       description="Collects USB, input and Bluetooth details into a JSON report. "
+                                   "Never changes controller settings or flashes anything.")
+    p.add_argument("--guided", action="store_true", help="walk through every connection mode")
+    p.add_argument("--bluetooth", action="store_true", help="also probe Bluetooth")
+    p.add_argument("--bluetooth-only", action="store_true", help="skip USB, probe only Bluetooth")
+    p.add_argument("--address", help="Bluetooth address to connect to (default: auto)")
+    p.add_argument("--label", default="manual", help="name for this snapshot")
+    p.add_argument("-o", "--output", type=Path)
+    p.add_argument("--device", type=_usb_id, action="append", default=[], metavar="VID:PID",
+                   help="also include this USB device, e.g. 054c:09cc when the dongle "
+                        "presents as a DualShock 4 (repeatable)")
+    p.set_defaults(func=cmd_probe)