swbt-python 0.1.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

swbt/__init__.py

@@ -1,7 +1,9 @@
 """Python API for virtual NX-compatible input devices."""
 
+from swbt.adapter_discovery import AdapterInfo, list_adapters
 from swbt.diagnostics import DiagnosticsConfig, GamepadStatus
 from swbt.errors import (
+    AdapterDiscoveryError,
     ClosedError,
     ConnectionFailedError,
     ConnectionTimeoutError,
@@ -9,29 +11,40 @@ from swbt.errors import (
     InvalidKeyStoreError,
     SwbtError,
     TransportOpenError,
+    UnsupportedInputError,
+)
+from swbt.gamepad import (
+    ConnectionResult,
+    JoyConL,
+    JoyConR,
+    ProController,
+    SwitchGamepad,
 )
-from swbt.gamepad import ConnectionResult, SwitchGamepad, SwitchGamepadConfig
 from swbt.input import Button, IMUFrame, InputState, Stick
-from swbt.transport.base import BondedPeer, DisconnectRequestResult, HidDeviceTransport
+from swbt.protocol.profiles.base import ControllerColors
 
 __all__ = (
-    "BondedPeer",
+    "AdapterDiscoveryError",
+    "AdapterInfo",
     "Button",
     "ClosedError",
     "ConnectionFailedError",
     "ConnectionResult",
     "ConnectionTimeoutError",
+    "ControllerColors",
     "DiagnosticsConfig",
-    "DisconnectRequestResult",
     "GamepadStatus",
-    "HidDeviceTransport",
     "IMUFrame",
     "InputState",
     "InvalidInputError",
     "InvalidKeyStoreError",
+    "JoyConL",
+    "JoyConR",
+    "ProController",
     "Stick",
     "SwbtError",
     "SwitchGamepad",
-    "SwitchGamepadConfig",
     "TransportOpenError",
+    "UnsupportedInputError",
+    "list_adapters",
 )

swbt/_testing/__init__.py

@@ -0,0 +1 @@
+"""Internal testing helpers for swbt's own test suite."""

swbt/_testing/gamepad.py

@@ -0,0 +1,74 @@
+"""Internal gamepad constructors for tests that inject fake transports."""
+
+from swbt import ControllerColors, DiagnosticsConfig, JoyConL, JoyConR, ProController
+from swbt.gamepad._config import _SwitchGamepadConfig
+from swbt.protocol.profiles.joycon import JoyConLeftProfile, JoyConRightProfile
+from swbt.transport.base import HidDeviceTransport
+
+
+def make_pro_controller(
+    *,
+    transport: HidDeviceTransport,
+    adapter: str | None = None,
+    key_store_path: str | None = None,
+    report_period_us: int | None = None,
+    controller_colors: ControllerColors | None = None,
+    diagnostics: DiagnosticsConfig | None = None,
+) -> ProController:
+    """Create a Pro Controller with an injected internal transport for tests."""
+    return ProController._from_config(
+        _SwitchGamepadConfig(
+            adapter=adapter,
+            key_store_path=key_store_path,
+            report_period_us=report_period_us,
+            controller_colors=controller_colors,
+        ),
+        diagnostics=diagnostics,
+        transport=transport,
+    )
+
+
+def make_joycon_l(
+    *,
+    transport: HidDeviceTransport,
+    adapter: str | None = None,
+    key_store_path: str | None = None,
+    report_period_us: int | None = None,
+    controller_colors: ControllerColors | None = None,
+    diagnostics: DiagnosticsConfig | None = None,
+) -> JoyConL:
+    """Create a Joy-Con L with an injected internal transport for tests."""
+    return JoyConL._from_config(
+        _SwitchGamepadConfig(
+            adapter=adapter,
+            key_store_path=key_store_path,
+            report_period_us=report_period_us,
+            controller_colors=controller_colors,
+            profile=JoyConLeftProfile(),
+        ),
+        diagnostics=diagnostics,
+        transport=transport,
+    )
+
+
+def make_joycon_r(
+    *,
+    transport: HidDeviceTransport,
+    adapter: str | None = None,
+    key_store_path: str | None = None,
+    report_period_us: int | None = None,
+    controller_colors: ControllerColors | None = None,
+    diagnostics: DiagnosticsConfig | None = None,
+) -> JoyConR:
+    """Create a Joy-Con R with an injected internal transport for tests."""
+    return JoyConR._from_config(
+        _SwitchGamepadConfig(
+            adapter=adapter,
+            key_store_path=key_store_path,
+            report_period_us=report_period_us,
+            controller_colors=controller_colors,
+            profile=JoyConRightProfile(),
+        ),
+        diagnostics=diagnostics,
+        transport=transport,
+    )

swbt/adapter_discovery.py

@@ -0,0 +1,231 @@
+"""No-open USB Bluetooth adapter discovery."""
+
+# ruff: noqa: N802
+
+import platform as platform_module
+from collections.abc import Callable, Iterable, Iterator
+from dataclasses import dataclass
+from importlib.metadata import PackageNotFoundError, version
+from typing import Protocol, cast
+
+from swbt.errors import AdapterDiscoveryError
+from swbt.transport import _bumble_usb_devices
+
+USB_DEVICE_CLASS_DEVICE = 0x00
+USB_DEVICE_CLASS_WIRELESS_CONTROLLER = 0xE0
+USB_DEVICE_SUBCLASS_RF_CONTROLLER = 0x01
+USB_DEVICE_PROTOCOL_BLUETOOTH_PRIMARY_CONTROLLER = 0x01
+
+USB_BT_HCI_CLASS_TUPLE = (
+    USB_DEVICE_CLASS_WIRELESS_CONTROLLER,
+    USB_DEVICE_SUBCLASS_RF_CONTROLLER,
+    USB_DEVICE_PROTOCOL_BLUETOOTH_PRIMARY_CONTROLLER,
+)
+
+
+class _UsbSetting(Protocol):
+    """USB interface setting shape used for HCI class detection."""
+
+    def getClass(self) -> int: ...
+    def getSubClass(self) -> int: ...
+    def getProtocol(self) -> int: ...
+
+
+class _UsbInterface(Protocol):
+    """USB interface shape used for HCI class detection."""
+
+    def __iter__(self) -> Iterator[_UsbSetting]: ...
+
+
+class _UsbConfiguration(Protocol):
+    """USB configuration shape used for HCI class detection."""
+
+    def __iter__(self) -> Iterator[_UsbInterface]: ...
+
+
+class _UsbDevice(Protocol):
+    """USB device shape consumed without opening the device handle."""
+
+    def getVendorID(self) -> int: ...
+    def getProductID(self) -> int: ...
+    def getDeviceClass(self) -> int: ...
+    def getDeviceSubClass(self) -> int: ...
+    def getDeviceProtocol(self) -> int: ...
+    def getSerialNumber(self) -> str | None: ...
+    def getManufacturer(self) -> str | None: ...
+    def getProduct(self) -> str | None: ...
+    def getBusNumber(self) -> int: ...
+    def getDeviceAddress(self) -> int: ...
+    def getPortNumberList(self) -> list[int]: ...
+    def __iter__(self) -> Iterator[_UsbConfiguration]: ...
+
+
+@dataclass(frozen=True, slots=True)
+class AdapterInfo:
+    """USB Bluetooth adapter candidate.
+
+    Args:
+        name: Primary adapter moniker passed to ``ProController(adapter=...)``.
+        aliases: Alternative adapter monikers for the same USB device.
+        vendor_id: USB vendor ID.
+        product_id: USB product ID.
+        manufacturer: USB manufacturer string when available.
+        product: USB product string when available.
+        serial_number: USB serial number when available.
+        bus_number: USB bus number when available.
+        device_address: USB device address when available.
+        port_numbers: USB port path numbers when available.
+        is_bluetooth_hci: Whether the USB device is classified as Bluetooth HCI.
+
+    Attributes:
+        name: Primary adapter moniker passed to ``ProController(adapter=...)``.
+        aliases: Alternative adapter monikers for the same USB device.
+        vendor_id: USB vendor ID.
+        product_id: USB product ID.
+        manufacturer: USB manufacturer string when available.
+        product: USB product string when available.
+        serial_number: USB serial number when available.
+        bus_number: USB bus number when available.
+        device_address: USB device address when available.
+        port_numbers: USB port path numbers when available.
+        is_bluetooth_hci: Whether the USB device is classified as Bluetooth HCI.
+    """
+
+    name: str
+    aliases: tuple[str, ...] = ()
+    vendor_id: int | None = None
+    product_id: int | None = None
+    manufacturer: str | None = None
+    product: str | None = None
+    serial_number: str | None = None
+    bus_number: int | None = None
+    device_address: int | None = None
+    port_numbers: tuple[int, ...] = ()
+    is_bluetooth_hci: bool = True
+
+
+def list_adapters() -> tuple[AdapterInfo, ...]:
+    """Return USB Bluetooth adapter candidates without opening them.
+
+    Returns:
+        Immutable snapshot of adapter candidates. An empty tuple means no
+        Bluetooth HCI candidates were found.
+
+    Raises:
+        AdapterDiscoveryError: USB device enumeration cannot be started.
+    """
+    try:
+        return tuple(_build_adapter_infos(_iter_usb_devices()))
+    except AdapterDiscoveryError:
+        raise
+    except Exception as error:
+        msg = "failed to discover USB Bluetooth adapters without opening them"
+        raise _discovery_error(msg) from error
+
+
+def _build_adapter_infos(devices: Iterable[_UsbDevice]) -> Iterator[AdapterInfo]:
+    seen_serials_by_id: dict[tuple[int, int], list[str | None]] = {}
+    hci_index = 0
+
+    for device in devices:
+        if not _is_bluetooth_hci(device):
+            continue
+
+        vendor_id = device.getVendorID()
+        product_id = device.getProductID()
+        device_id = (vendor_id, product_id)
+        serial_number = _optional_descriptor(device.getSerialNumber)
+        manufacturer = _optional_descriptor(device.getManufacturer)
+        product = _optional_descriptor(device.getProduct)
+        primary_name = f"usb:{hci_index}"
+        basic_name = f"usb:{vendor_id:04X}:{product_id:04X}"
+        transport_names = [primary_name]
+
+        if device_id not in seen_serials_by_id:
+            transport_names.append(basic_name)
+        else:
+            transport_names.append(f"{basic_name}#{len(seen_serials_by_id[device_id])}")
+
+        if serial_number is not None and (
+            device_id not in seen_serials_by_id
+            or serial_number not in seen_serials_by_id[device_id]
+        ):
+            transport_names.append(f"{basic_name}/{serial_number}")
+
+        seen_serials_by_id.setdefault(device_id, []).append(serial_number)
+        hci_index += 1
+
+        yield AdapterInfo(
+            name=primary_name,
+            aliases=tuple(name for name in transport_names if name != primary_name),
+            vendor_id=vendor_id,
+            product_id=product_id,
+            manufacturer=manufacturer,
+            product=product,
+            serial_number=serial_number,
+            bus_number=device.getBusNumber(),
+            device_address=device.getDeviceAddress(),
+            port_numbers=tuple(device.getPortNumberList()),
+            is_bluetooth_hci=True,
+        )
+
+
+def _iter_usb_devices() -> Iterator[_UsbDevice]:
+    yield from cast("Iterator[_UsbDevice]", _bumble_usb_devices.iter_usb_devices())
+
+
+def _is_bluetooth_hci(device: _UsbDevice) -> bool:
+    if (
+        device.getDeviceClass(),
+        device.getDeviceSubClass(),
+        device.getDeviceProtocol(),
+    ) == USB_BT_HCI_CLASS_TUPLE:
+        return True
+
+    if device.getDeviceClass() != USB_DEVICE_CLASS_DEVICE:
+        return False
+
+    for configuration in device:
+        for interface in configuration:
+            for setting in interface:
+                if (
+                    setting.getClass(),
+                    setting.getSubClass(),
+                    setting.getProtocol(),
+                ) == USB_BT_HCI_CLASS_TUPLE:
+                    return True
+
+    return False
+
+
+def _optional_descriptor(getter: Callable[[], str | None]) -> str | None:
+    try:
+        value = getter()
+    except Exception as error:  # descriptor access differs by OS and driver
+        if _is_usb_error(error):
+            return None
+        raise
+    if value is None:
+        return None
+    return str(value)
+
+
+def _is_usb_error(error: Exception) -> bool:
+    return _bumble_usb_devices.is_usb_error(error)
+
+
+def _discovery_error(message: str) -> AdapterDiscoveryError:
+    return AdapterDiscoveryError(
+        message,
+        platform=platform_module.platform(),
+        backend="bumble-usb",
+        libusb_available=None,
+        bumble_version=_package_version("bumble"),
+    )
+
+
+def _package_version(package_name: str) -> str:
+    try:
+        return version(package_name)
+    except PackageNotFoundError:
+        return "unknown"

swbt/diagnostics.py

@@ -9,7 +9,10 @@ from typing import TextIO
 
 @dataclass(frozen=True)
 class DiagnosticsConfig:
-    """Diagnostics configuration accepted by SwitchGamepad.
+    """Diagnostics configuration accepted by concrete gamepads.
+
+    Args:
+        trace_writer: Text stream that receives one JSON Lines diagnostics event per line.
 
     Attributes:
         trace_writer: Text stream that receives one JSON Lines diagnostics event per line.
@@ -39,7 +42,14 @@ class DiagnosticsEvent:
 
 @dataclass(frozen=True)
 class GamepadStatus:
-    """Snapshot of gamepad status exposed by SwitchGamepad.status().
+    """Snapshot of gamepad status exposed by ``SwitchGamepad.status()``.
+
+    Args:
+        connection_state: Current lifecycle state name.
+        report_counters: Sent report counts keyed by numeric report ID.
+        last_subcommand_id: Last observed subcommand ID, if any.
+        raw_rumble: Last raw rumble payload received from the host.
+        last_error: Latest diagnostics error event, if any.
 
     Attributes:
         connection_state: Current lifecycle state name.

swbt/errors.py

@@ -9,6 +9,48 @@ class TransportOpenError(SwbtError):
     """Raised when a transport cannot be opened."""
 
 
+class AdapterDiscoveryError(SwbtError):
+    """Raised when no-open adapter discovery cannot enumerate USB devices.
+
+    Args:
+        message: Human-readable failure message.
+        platform: Host platform string captured at discovery time.
+        backend: Discovery backend identifier.
+        libusb_available: Whether libusb availability is known at the failure point.
+        bumble_version: Installed Bumble package version when available.
+
+    Attributes:
+        platform: Host platform string captured at discovery time.
+        backend: Discovery backend identifier.
+        libusb_available: Whether libusb availability is known at the failure point.
+        bumble_version: Installed Bumble package version when available.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        platform: str,
+        backend: str = "bumble-usb",
+        libusb_available: bool | None = None,
+        bumble_version: str | None = None,
+    ) -> None:
+        """Initialize adapter discovery failure metadata.
+
+        Args:
+            message: Human-readable failure message.
+            platform: Host platform string captured at discovery time.
+            backend: Discovery backend identifier.
+            libusb_available: Whether libusb availability is known at the failure point.
+            bumble_version: Installed Bumble package version when available.
+        """
+        super().__init__(message)
+        self.platform = platform
+        self.backend = backend
+        self.libusb_available = libusb_available
+        self.bumble_version = bumble_version
+
+
 class ConnectionTimeoutError(SwbtError):
     """Raised when waiting for a connection times out."""
 
@@ -31,3 +73,28 @@ class ClosedError(SwbtError):
 
 class InvalidInputError(SwbtError):
     """Raised when user-provided input values are outside the supported range."""
+
+
+class UnsupportedInputError(InvalidInputError):
+    """Raised when a controller profile does not support a requested input."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        profile_kind: str,
+        buttons: tuple[str, ...] = (),
+        sticks: tuple[str, ...] = (),
+    ) -> None:
+        """Initialize unsupported input details.
+
+        Args:
+            message: Human-readable failure message.
+            profile_kind: Controller profile identity that rejected the input.
+            buttons: Unsupported button names.
+            sticks: Unsupported stick side names.
+        """
+        super().__init__(message)
+        self.profile_kind = profile_kind
+        self.buttons = buttons
+        self.sticks = sticks

swbt/gamepad/__init__.py

@@ -1,14 +1,20 @@
 """Public gamepad facade."""
 
 from swbt.gamepad.connection import ConnectionResult, ConnectionStatus
-from swbt.gamepad.core import SwitchGamepad, SwitchGamepadConfig
-
-DISCONNECT_REQUEST_TIMEOUT_SECONDS = 0.25
+from swbt.gamepad.constants import DISCONNECT_REQUEST_TIMEOUT_SECONDS
+from swbt.gamepad.core import (
+    JoyConL,
+    JoyConR,
+    ProController,
+    SwitchGamepad,
+)
 
 __all__ = (
     "DISCONNECT_REQUEST_TIMEOUT_SECONDS",
     "ConnectionResult",
     "ConnectionStatus",
+    "JoyConL",
+    "JoyConR",
+    "ProController",
     "SwitchGamepad",
-    "SwitchGamepadConfig",
 )

swbt/gamepad/_config.py

@@ -0,0 +1,101 @@
+"""Configuration models for gamepad construction and runtime setup."""
+
+from dataclasses import dataclass, field
+
+from swbt.errors import InvalidInputError
+from swbt.protocol.profiles.base import ControllerColors, ControllerProfile
+from swbt.protocol.profiles.pro_controller import default_controller_profile
+
+
+@dataclass(frozen=True)
+class _SwitchGamepadConfig:
+    """Configuration used to construct a concrete gamepad.
+
+    Attributes:
+        adapter: Bumble adapter moniker, such as ``"usb:0"``.
+        key_store_path: Path used by the default transport to persist pairing keys.
+        profile: Fixed controller identity and protocol profile.
+        report_period_us: Periodic input report interval in microseconds.
+        device_name: HID device name advertised to the host.
+        controller_colors: Fixed controller body, button, and grip colors for SPI profile data.
+    """
+
+    adapter: str | None = None
+    key_store_path: str | None = None
+    profile: ControllerProfile = field(default_factory=default_controller_profile)
+    report_period_us: int | None = None
+    device_name: str | None = None
+    controller_colors: ControllerColors | None = None
+
+    def __post_init__(self) -> None:
+        """Validate resource configuration."""
+        if not isinstance(self.profile, ControllerProfile):
+            msg = "profile must be a ControllerProfile"
+            raise InvalidInputError(msg)
+        if self.report_period_us is None:
+            object.__setattr__(
+                self,
+                "report_period_us",
+                self.profile.default_report_period_us,
+            )
+        elif self.report_period_us <= 0:
+            msg = "report_period_us must be positive"
+            raise InvalidInputError(msg)
+        if self.device_name is None:
+            object.__setattr__(self, "device_name", self.profile.device_name)
+        if self.controller_colors is not None and not isinstance(
+            self.controller_colors, ControllerColors
+        ):
+            msg = "controller_colors must be a ControllerColors"
+            raise InvalidInputError(msg)
+
+
+@dataclass(frozen=True)
+class _ControllerSpec:
+    """Internal controller identity selected by a concrete controller class."""
+
+    profile: ControllerProfile
+
+    def build_config(
+        self,
+        *,
+        adapter: str | None,
+        key_store_path: str | None,
+        report_period_us: int | None,
+        controller_colors: ControllerColors | None,
+    ) -> _SwitchGamepadConfig:
+        """Create internal construction config from public constructor options."""
+        return _SwitchGamepadConfig(
+            adapter=adapter,
+            key_store_path=key_store_path,
+            profile=self.profile,
+            report_period_us=report_period_us,
+            controller_colors=controller_colors,
+        )
+
+
+@dataclass(frozen=True)
+class _RuntimeConfig:
+    """Normalized internal configuration for ControllerRuntime."""
+
+    adapter: str | None
+    key_store_path: str | None
+    profile: ControllerProfile
+    report_period_us: int
+    device_name: str
+    controller_colors: ControllerColors | None
+
+    @classmethod
+    def from_public_config(cls, config: _SwitchGamepadConfig) -> "_RuntimeConfig":
+        """Create normalized runtime configuration from public construction config."""
+        if config.report_period_us is None or config.device_name is None:
+            msg = "_SwitchGamepadConfig was not normalized"
+            raise InvalidInputError(msg)
+        return cls(
+            adapter=config.adapter,
+            key_store_path=config.key_store_path,
+            profile=config.profile,
+            report_period_us=config.report_period_us,
+            device_name=config.device_name,
+            controller_colors=config.controller_colors,
+        )

swbt/gamepad/connection.py

@@ -30,6 +30,12 @@ PairWithTimeout = Callable[[float | None], Awaitable[None]]
 class ConnectionResult:
     """Result of an explicit connection strategy.
 
+    Args:
+        route: Connection path that produced the result.
+        status: Outcome of the connection attempt.
+        peer_address: Address of the bonded peer used for reconnect, when one was selected.
+        peer_count: Number of bonded peers observed while selecting a reconnect target.
+
     Attributes:
         route: Connection path that produced the result.
         status: Outcome of the connection attempt.

swbt/gamepad/constants.py

@@ -0,0 +1,3 @@
+"""Constants for the gamepad package."""
+
+DISCONNECT_REQUEST_TIMEOUT_SECONDS = 0.25