swbt-python 0.1.0__py3-none-any.whl

swbt/probe.py

@@ -0,0 +1,150 @@
+"""Command line probes for swbt hardware setup."""
+
+import argparse
+import asyncio
+import json
+import platform
+import sys
+from collections.abc import Sequence
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+from swbt import DiagnosticsConfig, SwitchGamepad
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the swbt-probe argument parser.
+
+    Returns:
+        argparse.ArgumentParser: Parser for the ``swbt-probe`` command.
+    """
+    parser = argparse.ArgumentParser(
+        prog="swbt-probe",
+        description="Probe helper for swbt-python development and hardware setup.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    adapters_parser = subparsers.add_parser(
+        "adapters",
+        description=(
+            "Show adapter discovery guidance. This command does not open a Bluetooth adapter."
+        ),
+        help="show adapter discovery guidance without opening hardware",
+    )
+    adapters_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="emit machine-readable adapter probe guidance",
+    )
+    adapters_parser.set_defaults(handler=_run_adapters)
+
+    pair_parser = subparsers.add_parser(
+        "pair",
+        description=(
+            "Pairing probe requires explicit approval before any Switch-facing Bluetooth action."
+        ),
+        help="show pairing probe options and approval requirements",
+    )
+    pair_parser.add_argument(
+        "--adapter",
+        default="usb:0",
+        help="adapter moniker to use after approval, for example usb:0",
+    )
+    pair_parser.add_argument(
+        "--key-store",
+        dest="key_store_path",
+        help="pairing key store path for the approved pairing run",
+    )
+    pair_parser.add_argument(
+        "--trace",
+        required=True,
+        type=Path,
+        metavar="PATH",
+        help="JSON Lines trace output path for the approved pairing run",
+    )
+    pair_parser.add_argument(
+        "--timeout",
+        default=30.0,
+        type=float,
+        help="seconds to wait for pairing during an approved run",
+    )
+    pair_parser.set_defaults(handler=_run_pair)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the swbt-probe command.
+
+    Args:
+        argv: Optional argument vector. ``None`` reads arguments from ``sys.argv``.
+
+    Returns:
+        int: Process exit code.
+    """
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    handler = args.handler
+    return int(handler(args))
+
+
+def _run_adapters(args: argparse.Namespace) -> int:
+    payload = {
+        "bumble_version": _package_version("bumble"),
+        "candidate_adapters": ["usb:0"],
+        "opens_adapter": False,
+        "platform": platform.platform(),
+        "python_version": platform.python_version(),
+        "status": "adapter listing does not open hardware",
+    }
+    if args.json:
+        sys.stdout.write(f"{json.dumps(payload, sort_keys=True)}\n")
+    else:
+        sys.stdout.write("This command does not open a Bluetooth adapter.\n")
+        sys.stdout.write(f"Platform: {payload['platform']}\n")
+        sys.stdout.write(f"Python: {payload['python_version']}\n")
+        sys.stdout.write(f"Bumble: {payload['bumble_version']}\n")
+        sys.stdout.write("Candidate adapters: usb:0\n")
+        sys.stdout.write("Opening an adapter requires an explicit hardware approval scope.\n")
+    return 0
+
+
+def _run_pair(_args: argparse.Namespace) -> int:
+    asyncio.run(
+        _run_pair_probe(
+            adapter=_args.adapter,
+            key_store_path=_args.key_store_path,
+            pair_timeout=_args.timeout,
+            trace_path=_args.trace,
+        )
+    )
+    return 0
+
+
+async def _run_pair_probe(
+    *,
+    adapter: str,
+    key_store_path: str | None,
+    pair_timeout: float,
+    trace_path: Path,
+) -> None:
+    trace_path.parent.mkdir(parents=True, exist_ok=True)
+    with trace_path.open("w", encoding="utf-8") as trace_writer:
+        diagnostics = DiagnosticsConfig(trace_writer=trace_writer)
+        async with SwitchGamepad(
+            adapter=adapter,
+            key_store_path=key_store_path,
+            diagnostics=diagnostics,
+        ) as pad:
+            await pad.pair(timeout=pair_timeout)
+
+
+def _package_version(package_name: str) -> str:
+    try:
+        return version(package_name)
+    except PackageNotFoundError:
+        return "unknown"
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

swbt/protocol/__init__.py

@@ -0,0 +1 @@
+"""Switch HID protocol helpers."""

swbt/protocol/input_report.py

@@ -0,0 +1,77 @@
+"""Input report builders."""
+
+from swbt.input import Button, InputState, Stick
+from swbt.protocol.profile import ProControllerProfile
+
+BUTTON_BITS = {
+    Button.Y: (3, 0x01),
+    Button.X: (3, 0x02),
+    Button.B: (3, 0x04),
+    Button.A: (3, 0x08),
+    Button.R: (3, 0x40),
+    Button.ZR: (3, 0x80),
+    Button.MINUS: (4, 0x01),
+    Button.PLUS: (4, 0x02),
+    Button.RIGHT_STICK: (4, 0x04),
+    Button.LEFT_STICK: (4, 0x08),
+    Button.HOME: (4, 0x10),
+    Button.CAPTURE: (4, 0x20),
+    Button.DPAD_DOWN: (5, 0x01),
+    Button.DPAD_UP: (5, 0x02),
+    Button.DPAD_RIGHT: (5, 0x04),
+    Button.DPAD_LEFT: (5, 0x08),
+    Button.L: (5, 0x40),
+    Button.ZL: (5, 0x80),
+}
+
+
+class InputReportBuilder:
+    """Build Switch HID input reports from immutable input state."""
+
+    def __init__(self, profile: ProControllerProfile | None = None) -> None:
+        """Create a report builder."""
+        self._profile = profile or ProControllerProfile()
+
+    def build_0x30(self, state: InputState, *, timer: int = 0) -> bytes:
+        """Build a 0x30 standard full input report."""
+        report = bytearray(49)
+        report[0] = 0x30
+        report[1] = timer & 0xFF
+        report[2] = self._profile.battery_connection
+        self._pack_buttons(report, state)
+        report[6:9] = self._pack_stick(state.left_stick)
+        report[9:12] = self._pack_stick(state.right_stick)
+        report[12] = self._profile.vibrator_input
+        self._pack_imu_frames(report, state)
+        return bytes(report)
+
+    @staticmethod
+    def _pack_buttons(report: bytearray, state: InputState) -> None:
+        for button in state.buttons:
+            offset, mask = BUTTON_BITS[button]
+            report[offset] |= mask
+
+    @staticmethod
+    def _pack_stick(stick: Stick) -> bytes:
+        return bytes(
+            (
+                stick.x & 0xFF,
+                ((stick.x >> 8) & 0x0F) | ((stick.y & 0x0F) << 4),
+                (stick.y >> 4) & 0xFF,
+            )
+        )
+
+    @staticmethod
+    def _pack_imu_frames(report: bytearray, state: InputState) -> None:
+        cursor = 13
+        for frame in state.imu_frames:
+            for value in (
+                frame.accel_x,
+                frame.accel_y,
+                frame.accel_z,
+                frame.gyro_x,
+                frame.gyro_y,
+                frame.gyro_z,
+            ):
+                report[cursor : cursor + 2] = int(value).to_bytes(2, "little", signed=True)
+                cursor += 2

swbt/protocol/output_report.py

@@ -0,0 +1,58 @@
+"""Output report parser."""
+
+from dataclasses import dataclass
+
+from swbt.errors import ProtocolError
+
+
+@dataclass(frozen=True)
+class OutputReport:
+    """Parsed host-to-device output report."""
+
+    report_id: int
+    packet_id: int | None
+    rumble: bytes | None
+    subcommand_id: int | None
+    subcommand_payload: bytes
+
+
+class OutputReportParser:
+    """Parse Switch HID output reports."""
+
+    def parse(self, raw_report: bytes) -> OutputReport:
+        """Parse a raw output report."""
+        if not raw_report:
+            msg = "output report is empty"
+            raise ProtocolError(msg)
+        if raw_report[0] == 0x01:
+            return self._parse_0x01(raw_report)
+        if raw_report[0] == 0x10:
+            return self._parse_0x10(raw_report)
+        msg = f"unsupported output report id: 0x{raw_report[0]:02x}"
+        raise ProtocolError(msg)
+
+    @staticmethod
+    def _parse_0x01(raw_report: bytes) -> OutputReport:
+        if len(raw_report) < 11:
+            msg = "0x01 output report must include packet, rumble, and subcommand"
+            raise ProtocolError(msg)
+        return OutputReport(
+            report_id=0x01,
+            packet_id=raw_report[1],
+            rumble=raw_report[2:10],
+            subcommand_id=raw_report[10],
+            subcommand_payload=raw_report[11:],
+        )
+
+    @staticmethod
+    def _parse_0x10(raw_report: bytes) -> OutputReport:
+        if len(raw_report) < 10:
+            msg = "0x10 output report must include packet and rumble"
+            raise ProtocolError(msg)
+        return OutputReport(
+            report_id=0x10,
+            packet_id=raw_report[1],
+            rumble=raw_report[2:10],
+            subcommand_id=None,
+            subcommand_payload=b"",
+        )

swbt/protocol/profile.py

@@ -0,0 +1,221 @@
+"""Fixed protocol profile values for the controller shape."""
+
+from dataclasses import dataclass
+
+SWITCH_PRO_CONTROLLER_HID_REPORT_DESCRIPTOR = bytes(
+    (
+        0x05,
+        0x01,
+        0x15,
+        0x00,
+        0x09,
+        0x04,
+        0xA1,
+        0x01,
+        0x85,
+        0x30,
+        0x05,
+        0x01,
+        0x05,
+        0x09,
+        0x19,
+        0x01,
+        0x29,
+        0x0A,
+        0x15,
+        0x00,
+        0x25,
+        0x01,
+        0x75,
+        0x01,
+        0x95,
+        0x0A,
+        0x55,
+        0x00,
+        0x65,
+        0x00,
+        0x81,
+        0x02,
+        0x05,
+        0x09,
+        0x19,
+        0x0B,
+        0x29,
+        0x0E,
+        0x15,
+        0x00,
+        0x25,
+        0x01,
+        0x75,
+        0x01,
+        0x95,
+        0x04,
+        0x81,
+        0x02,
+        0x75,
+        0x01,
+        0x95,
+        0x02,
+        0x81,
+        0x03,
+        0x0B,
+        0x01,
+        0x00,
+        0x01,
+        0x00,
+        0xA1,
+        0x00,
+        0x0B,
+        0x30,
+        0x00,
+        0x01,
+        0x00,
+        0x0B,
+        0x31,
+        0x00,
+        0x01,
+        0x00,
+        0x0B,
+        0x32,
+        0x00,
+        0x01,
+        0x00,
+        0x0B,
+        0x35,
+        0x00,
+        0x01,
+        0x00,
+        0x15,
+        0x00,
+        0x27,
+        0xFF,
+        0xFF,
+        0x00,
+        0x00,
+        0x75,
+        0x10,
+        0x95,
+        0x04,
+        0x81,
+        0x02,
+        0xC0,
+        0x0B,
+        0x39,
+        0x00,
+        0x01,
+        0x00,
+        0x15,
+        0x00,
+        0x25,
+        0x07,
+        0x35,
+        0x00,
+        0x46,
+        0x3B,
+        0x01,
+        0x65,
+        0x14,
+        0x75,
+        0x04,
+        0x95,
+        0x01,
+        0x81,
+        0x02,
+        0x05,
+        0x09,
+        0x19,
+        0x0F,
+        0x29,
+        0x12,
+        0x15,
+        0x00,
+        0x25,
+        0x01,
+        0x75,
+        0x01,
+        0x95,
+        0x04,
+        0x81,
+        0x02,
+        0x75,
+        0x08,
+        0x95,
+        0x34,
+        0x81,
+        0x03,
+        0x06,
+        0x00,
+        0xFF,
+        0x85,
+        0x21,
+        0x09,
+        0x01,
+        0x75,
+        0x08,
+        0x95,
+        0x3F,
+        0x81,
+        0x03,
+        0x85,
+        0x81,
+        0x09,
+        0x02,
+        0x75,
+        0x08,
+        0x95,
+        0x3F,
+        0x81,
+        0x03,
+        0x85,
+        0x01,
+        0x09,
+        0x03,
+        0x75,
+        0x08,
+        0x95,
+        0x3F,
+        0x91,
+        0x83,
+        0x85,
+        0x10,
+        0x09,
+        0x04,
+        0x75,
+        0x08,
+        0x95,
+        0x3F,
+        0x91,
+        0x83,
+        0x85,
+        0x80,
+        0x09,
+        0x05,
+        0x75,
+        0x08,
+        0x95,
+        0x3F,
+        0x91,
+        0x83,
+        0x85,
+        0x82,
+        0x09,
+        0x06,
+        0x75,
+        0x08,
+        0x95,
+        0x3F,
+        0x91,
+        0x83,
+        0xC0,
+    )
+)
+
+
+@dataclass(frozen=True)
+class ProControllerProfile:
+    """Protocol defaults for a Pro Controller compatible report shape."""
+
+    battery_connection: int = 0x91
+    vibrator_input: int = 0x00
+    bluetooth_address: bytes = b"\x00\x00\x00\x00\x00\x00"
+    hid_report_descriptor: bytes = SWITCH_PRO_CONTROLLER_HID_REPORT_DESCRIPTOR

swbt/protocol/rumble.py

@@ -0,0 +1,21 @@
+"""Raw rumble state."""
+
+from dataclasses import dataclass
+
+from swbt.errors import ProtocolError
+
+
+@dataclass(frozen=True)
+class RumbleState:
+    """Raw 8-byte rumble payload with receive timestamp."""
+
+    raw: bytes
+    updated_at_ns: int
+
+    @classmethod
+    def from_raw(cls, raw: bytes, *, updated_at_ns: int) -> "RumbleState":
+        """Create rumble state from an 8-byte payload."""
+        if len(raw) != 8:
+            msg = f"rumble payload must be 8 bytes: {len(raw)}"
+            raise ProtocolError(msg)
+        return cls(raw=bytes(raw), updated_at_ns=updated_at_ns)

swbt/protocol/spi.py

@@ -0,0 +1,37 @@
+"""Virtual SPI flash."""
+
+from swbt.errors import ProtocolError
+
+
+class VirtualSpiFlash:
+    """Read-only SPI flash data used by subcommand replies."""
+
+    ADDRESS_LIMIT = 0x80000
+    STORAGE_SIZE = 0x10000
+    MAX_READ_SIZE = 0x1D
+    ERASED_BYTE = 0xFF
+    DEVICE_TYPE_ADDRESS = 0x6012
+    PRO_CONTROLLER_DEVICE_TYPE = 0x03
+
+    def __init__(self) -> None:
+        """Create a virtual SPI flash image."""
+        self._data = bytearray([self.ERASED_BYTE] * self.STORAGE_SIZE)
+        self._data[self.DEVICE_TYPE_ADDRESS] = self.PRO_CONTROLLER_DEVICE_TYPE
+
+    def read(self, address: int, size: int) -> bytes:
+        """Read bytes from the virtual SPI address space."""
+        if size > self.MAX_READ_SIZE:
+            msg = f"SPI read size must be {self.MAX_READ_SIZE} bytes or less: {size}"
+            raise ProtocolError(msg)
+        if address < 0 or size < 0 or address + size > self.ADDRESS_LIMIT:
+            msg = f"SPI read is outside address space: address=0x{address:x}, size={size}"
+            raise ProtocolError(msg)
+
+        out = bytearray()
+        for offset in range(size):
+            absolute_address = address + offset
+            if absolute_address < self.STORAGE_SIZE:
+                out.append(self._data[absolute_address])
+            else:
+                out.append(self.ERASED_BYTE)
+        return bytes(out)

swbt/protocol/subcommand.py

@@ -0,0 +1,102 @@
+"""Subcommand reply generation."""
+
+from swbt.errors import ProtocolError
+from swbt.input import InputState
+from swbt.protocol.input_report import InputReportBuilder
+from swbt.protocol.output_report import OutputReport
+from swbt.protocol.profile import ProControllerProfile
+from swbt.protocol.spi import VirtualSpiFlash
+
+SIMPLE_ACK_SUBCOMMANDS = {0x03, 0x08, 0x30, 0x40, 0x48}
+DEVICE_INFO_DATA = bytes.fromhex("04 00 03 02 00 00 00 00 00 00 01 01")
+TRIGGER_BUTTONS_ELAPSED_DATA = bytes.fromhex("2c 01 2c 01 00 00 00 00 00 00 00 00 00 00")
+MCU_CONFIG_DATA = bytes.fromhex(
+    "01 00 ff 00 08 00 1b 01 00 00 00 00 00 00 00 00 00 00 00 00 "
+    "00 00 00 00 00 00 00 00 00 00 00 00 00 c8"
+)
+
+
+class UnsupportedSubcommandError(ProtocolError):
+    """Raised when a subcommand is not supported by the responder."""
+
+    def __init__(self, subcommand_id: int, payload: bytes) -> None:
+        """Create an error with fields diagnostics can record."""
+        self.subcommand_id = subcommand_id
+        self.payload = bytes(payload)
+        super().__init__(f"unsupported subcommand: 0x{subcommand_id:02x}")
+
+
+class SubcommandResponder:
+    """Build 0x21 replies for supported subcommands."""
+
+    def __init__(
+        self,
+        *,
+        spi_flash: VirtualSpiFlash | None = None,
+        profile: ProControllerProfile | None = None,
+    ) -> None:
+        """Create a responder."""
+        self._spi_flash = spi_flash or VirtualSpiFlash()
+        self._profile = profile or ProControllerProfile()
+
+    def respond(self, output_report: OutputReport, *, state: InputState, timer: int = 0) -> bytes:
+        """Return a 0x21 reply for an output report with a subcommand."""
+        if output_report.subcommand_id is None:
+            msg = "output report does not include a subcommand"
+            raise ProtocolError(msg)
+
+        ack, data = self._reply_data(output_report)
+        return self._build_0x21_reply(
+            subcommand_id=output_report.subcommand_id,
+            ack=ack,
+            data=data,
+            state=state,
+            timer=timer,
+        )
+
+    def _reply_data(self, output_report: OutputReport) -> tuple[int, bytes]:
+        subcommand_id = output_report.subcommand_id
+        if subcommand_id is None:
+            msg = "output report does not include a subcommand"
+            raise ProtocolError(msg)
+        if subcommand_id in SIMPLE_ACK_SUBCOMMANDS:
+            return 0x80, b""
+        if subcommand_id == 0x02:
+            return 0x82, DEVICE_INFO_DATA
+        if subcommand_id == 0x04:
+            return 0x83, TRIGGER_BUTTONS_ELAPSED_DATA
+        if subcommand_id == 0x10:
+            return 0x90, self._spi_read_reply_data(output_report.subcommand_payload)
+        if subcommand_id == 0x21:
+            return 0xA0, MCU_CONFIG_DATA
+        raise UnsupportedSubcommandError(subcommand_id, output_report.subcommand_payload)
+
+    def _spi_read_reply_data(self, payload: bytes) -> bytes:
+        if len(payload) < 5:
+            msg = "SPI read subcommand must include address and size"
+            raise ProtocolError(msg)
+        address = int.from_bytes(payload[0:4], "little")
+        size = payload[4]
+        return payload[:5] + self._spi_flash.read(address, size)
+
+    def _build_0x21_reply(
+        self,
+        *,
+        subcommand_id: int,
+        ack: int,
+        data: bytes,
+        state: InputState,
+        timer: int,
+    ) -> bytes:
+        if len(data) > 35:
+            msg = f"subcommand reply data is too large: {len(data)}"
+            raise ProtocolError(msg)
+
+        prefix = InputReportBuilder(self._profile).build_0x30(state, timer=timer)[:13]
+        reply = bytearray(50)
+        reply[:13] = prefix
+        reply[0] = 0x21
+        reply[13] = ack
+        reply[14] = subcommand_id
+        reply[15 : 15 + len(data)] = data
+        return bytes(reply)

swbt/py.typed

@@ -0,0 +1 @@
+