swbt-python 0.1.0__py3-none-any.whl

swbt/transport/_bumble_lifecycle.py

@@ -0,0 +1,311 @@
+"""Lifecycle and connection diagnostics helpers for Bumble HID transport."""
+
+from collections.abc import Callable
+from contextlib import suppress
+from typing import Any, Protocol, cast
+
+
+class EventRecorder(Protocol):
+    def __call__(self, event: str, **fields: object) -> None:
+        """Record one diagnostics event."""
+
+
+class ConnectionDiagnostics:
+    """Register diagnostics callbacks on a Bumble connection object."""
+
+    def __init__(
+        self,
+        *,
+        adapter: str,
+        handle_disconnection: Callable[[int | None], None],
+        record_event: EventRecorder,
+    ) -> None:
+        self._adapter = adapter
+        self._handle_disconnection = handle_disconnection
+        self._record_event = record_event
+
+    def register(self, connection: object) -> None:
+        """Register all connection diagnostics callbacks supported by the connection."""
+        on_event = getattr(connection, "on", None)
+        if not callable(on_event):
+            return
+        on_event(
+            getattr(connection, "EVENT_DISCONNECTION", "disconnection"),
+            self._handle_disconnection,
+        )
+        on_event(
+            getattr(connection, "EVENT_CLASSIC_PAIRING", "classic_pairing"),
+            lambda *_args: self._record_event("classic_pairing", adapter=self._adapter),
+        )
+        on_event(
+            getattr(connection, "EVENT_CLASSIC_PAIRING_FAILURE", "classic_pairing_failure"),
+            lambda reason=None, *_args: self._record_event(
+                "classic_pairing_failure",
+                adapter=self._adapter,
+                reason=reason,
+            ),
+        )
+        on_event(
+            getattr(connection, "EVENT_PAIRING_START", "pairing_start"),
+            lambda *_args: self._record_event("pairing_start", adapter=self._adapter),
+        )
+        on_event(
+            getattr(connection, "EVENT_PAIRING", "pairing"),
+            lambda keys=None, *_args: self._record_pairing_complete(connection, keys),
+        )
+        on_event(
+            getattr(connection, "EVENT_PAIRING_FAILURE", "pairing_failure"),
+            lambda reason=None, *_args: self._record_event(
+                "pairing_failure",
+                adapter=self._adapter,
+                reason=reason,
+            ),
+        )
+        on_event(
+            getattr(connection, "EVENT_CONNECTION_AUTHENTICATION", "connection_authentication"),
+            lambda *_args: self._record_connection_authentication(connection),
+        )
+        on_event(
+            getattr(
+                connection,
+                "EVENT_CONNECTION_AUTHENTICATION_FAILURE",
+                "connection_authentication_failure",
+            ),
+            lambda error=None, *_args: self._record_event(
+                "connection_authentication_failure",
+                adapter=self._adapter,
+                error=safe_event_value(error),
+            ),
+        )
+        on_event(
+            getattr(
+                connection,
+                "EVENT_CONNECTION_ENCRYPTION_CHANGE",
+                "connection_encryption_change",
+            ),
+            lambda *_args: self._record_connection_encryption_change(connection),
+        )
+        on_event(
+            getattr(
+                connection,
+                "EVENT_CONNECTION_ENCRYPTION_FAILURE",
+                "connection_encryption_failure",
+            ),
+            lambda error=None, *_args: self._record_event(
+                "connection_encryption_failure",
+                adapter=self._adapter,
+                error=safe_event_value(error),
+            ),
+        )
+        on_event(
+            getattr(
+                connection,
+                "EVENT_CONNECTION_ENCRYPTION_KEY_REFRESH",
+                "connection_encryption_key_refresh",
+            ),
+            lambda *_args: self._record_connection_encryption_refresh(connection),
+        )
+        on_event(
+            getattr(connection, "EVENT_LINK_KEY", "link_key"),
+            lambda *_args: self._record_event("link_key_available", adapter=self._adapter),
+        )
+        on_event(
+            getattr(connection, "EVENT_MODE_CHANGE", "mode_change"),
+            lambda *_args: self._record_classic_mode_change(connection),
+        )
+        on_event(
+            getattr(connection, "EVENT_MODE_CHANGE_FAILURE", "mode_change_failure"),
+            lambda status=None, *_args: self._record_event(
+                "classic_mode_change_failure",
+                adapter=self._adapter,
+                status=status,
+            ),
+        )
+
+    def _record_pairing_complete(self, connection: object, keys: object | None) -> None:
+        fields = connection_security_fields(connection)
+        fields["has_link_key"] = keys_include_link_key(keys)
+        self._record_event("pairing_complete", adapter=self._adapter, **fields)
+
+    def _record_connection_authentication(self, connection: object) -> None:
+        self._record_event(
+            "connection_authentication",
+            adapter=self._adapter,
+            authenticated=getattr(connection, "authenticated", None),
+        )
+
+    def _record_connection_encryption_change(self, connection: object) -> None:
+        self._record_event(
+            "connection_encryption_change",
+            adapter=self._adapter,
+            **connection_security_fields(connection),
+        )
+
+    def _record_connection_encryption_refresh(self, connection: object) -> None:
+        self._record_event(
+            "connection_encryption_key_refresh",
+            adapter=self._adapter,
+            **connection_security_fields(connection),
+        )
+
+    def _record_classic_mode_change(self, connection: object) -> None:
+        self._record_event(
+            "classic_mode_change",
+            adapter=self._adapter,
+            mode=getattr(connection, "classic_mode", None),
+            interval=getattr(connection, "classic_interval", None),
+        )
+
+
+def register_connection_diagnostics(
+    *,
+    adapter: str,
+    connection: object,
+    handle_disconnection: Callable[[int | None], None],
+    record_event: EventRecorder,
+) -> None:
+    """Register connection-level diagnostics callbacks."""
+    ConnectionDiagnostics(
+        adapter=adapter,
+        handle_disconnection=handle_disconnection,
+        record_event=record_event,
+    ).register(connection)
+
+
+def register_connection_request_bridge(
+    *,
+    adapter: str,
+    device: object,
+    record_event: EventRecorder,
+) -> None:
+    """Wrap Bumble's connection request callback while avoiding deprecated sync APIs."""
+    original_connection_request = cast("Any", device).on_connection_request
+
+    def on_connection_request(
+        bd_addr: object,
+        class_of_device: int,
+        link_type: int,
+    ) -> None:
+        record_event(
+            "connection_request",
+            adapter=adapter,
+            class_of_device=f"0x{class_of_device:06x}",
+            link_type=link_type,
+            peer_address=str(bd_addr),
+        )
+        call_connection_request_without_deprecated_sync_command(
+            device,
+            original_connection_request,
+            bd_addr,
+            class_of_device,
+            link_type,
+        )
+
+    device_with_attrs = cast("Any", device)
+    device_with_attrs.on_connection_request = on_connection_request
+    replace_host_connection_request_listener(
+        device,
+        original_connection_request,
+        on_connection_request,
+    )
+
+
+def register_l2cap_lifecycle_bridge(
+    *,
+    hid_device: object,
+    notify_connected_if_ready: Callable[[], None],
+    notify_disconnected_if_channels_closed: Callable[[], None],
+    record_l2cap_channel_event: Callable[[str, object], None],
+    set_l2cap_connected_emitted: Callable[[bool], None],
+) -> None:
+    """Wrap HID L2CAP lifecycle callbacks and emit transport diagnostics."""
+    hid_device_with_attrs = cast("Any", hid_device)
+    original_open = hid_device_with_attrs.on_l2cap_channel_open
+    original_close = hid_device_with_attrs.on_l2cap_channel_close
+
+    def on_l2cap_channel_open(l2cap_channel: object) -> None:
+        original_open(l2cap_channel)
+        record_l2cap_channel_event("l2cap_channel_open", l2cap_channel)
+        notify_connected_if_ready()
+
+    def on_l2cap_channel_close(l2cap_channel: object) -> None:
+        original_close(l2cap_channel)
+        record_l2cap_channel_event("l2cap_channel_close", l2cap_channel)
+        set_l2cap_connected_emitted(False)
+        notify_disconnected_if_channels_closed()
+
+    hid_device_with_attrs.on_l2cap_channel_open = on_l2cap_channel_open
+    hid_device_with_attrs.on_l2cap_channel_close = on_l2cap_channel_close
+
+
+def connection_security_fields(connection: object) -> dict[str, object]:
+    return {
+        "authenticated": getattr(connection, "authenticated", None),
+        "encryption": getattr(connection, "encryption", None),
+        "encryption_key_size": getattr(connection, "encryption_key_size", None),
+        "secure_connections": getattr(connection, "sc", None),
+    }
+
+
+def keys_include_link_key(keys: object | None) -> bool | None:
+    if keys is None:
+        return None
+    return getattr(keys, "link_key", None) is not None
+
+
+def safe_event_value(value: object) -> object:
+    if value is None or isinstance(value, int | str | bool | float):
+        return value
+    return str(value)
+
+
+def call_connection_request_without_deprecated_sync_command(
+    device: object,
+    connection_request: Callable[[object, int, int], None],
+    bd_addr: object,
+    class_of_device: int,
+    link_type: int,
+) -> None:
+    """Run Bumble's connection request handler without its deprecated sync helper."""
+    host = getattr(device, "host", None)
+    send_async_command = getattr(host, "send_async_command", None)
+    if host is None or not callable(send_async_command):
+        connection_request(bd_addr, class_of_device, link_type)
+        return
+
+    from bumble import utils  # noqa: PLC0415
+
+    missing = object()
+    host_dict = getattr(host, "__dict__", None)
+    previous_instance_attr = (
+        host_dict.get("send_command_sync", missing) if isinstance(host_dict, dict) else missing
+    )
+
+    def send_command_sync(command: object) -> None:
+        utils.AsyncRunner.spawn(send_async_command(command))
+
+    host_with_attrs = cast("Any", host)
+    host_with_attrs.send_command_sync = send_command_sync
+    try:
+        connection_request(bd_addr, class_of_device, link_type)
+    finally:
+        if previous_instance_attr is missing:
+            del host_with_attrs.send_command_sync
+        else:
+            host_with_attrs.send_command_sync = previous_instance_attr
+
+
+def replace_host_connection_request_listener(
+    device: object,
+    original_connection_request: Callable[[object, int, int], None],
+    replacement_connection_request: Callable[[object, int, int], None],
+) -> None:
+    host = getattr(device, "host", None)
+    remove_listener = getattr(host, "remove_listener", None)
+    on = getattr(host, "on", None)
+    if not callable(remove_listener) or not callable(on):
+        return
+
+    with suppress(KeyError, ValueError):
+        remove_listener("connection_request", original_connection_request)
+    on("connection_request", replacement_connection_request)

swbt/transport/_bumble_sdp.py

@@ -0,0 +1,203 @@
+"""SDP service record builder for Bumble HID transport."""
+
+from swbt.transport._bumble_hidp import HID_CONTROL_PSM, HID_INTERRUPT_PSM
+
+_HID_SERVICE_RECORD_HANDLE = 0x00010001
+_HID_REPORT_DESCRIPTOR_TYPE = 0x22
+_DEFAULT_DEVICE_NAME = "Pro Controller"
+
+_SDP_HID_PARSER_VERSION_ATTRIBUTE_ID = 0x0201
+_SDP_HID_DEVICE_SUBCLASS_ATTRIBUTE_ID = 0x0202
+_SDP_HID_COUNTRY_CODE_ATTRIBUTE_ID = 0x0203
+_SDP_HID_VIRTUAL_CABLE_ATTRIBUTE_ID = 0x0204
+_SDP_HID_RECONNECT_INITIATE_ATTRIBUTE_ID = 0x0205
+_SDP_HID_DESCRIPTOR_LIST_ATTRIBUTE_ID = 0x0206
+_SDP_HID_LANG_ID_BASE_LIST_ATTRIBUTE_ID = 0x0207
+_SDP_HID_REMOTE_WAKE_ATTRIBUTE_ID = 0x020A
+_SDP_HID_PROFILE_VERSION_ATTRIBUTE_ID = 0x020B
+_SDP_HID_SUPERVISION_TIMEOUT_ATTRIBUTE_ID = 0x020C
+_SDP_HID_NORMALLY_CONNECTABLE_ATTRIBUTE_ID = 0x020D
+_SDP_HID_BOOT_DEVICE_ATTRIBUTE_ID = 0x020E
+_SDP_HIDSSR_HOST_MAX_LATENCY_ATTRIBUTE_ID = 0x020F
+_SDP_HIDSSR_HOST_MIN_TIMEOUT_ATTRIBUTE_ID = 0x0210
+_SDP_PRIMARY_LANGUAGE_SERVICE_NAME_ATTRIBUTE_ID = 0x0100
+
+_LANGUAGE_BASE_EN_US = 0x0100
+_SDP_LANGUAGE_CODE_ENGLISH = 0x656E
+_SDP_CHARACTER_ENCODING_UTF8 = 0x006A
+_LANGUAGE_ID_EN_US = 0x0409
+_REFERENCE_HID_COUNTRY_CODE = 0x21
+_REFERENCE_HID_SUPERVISION_TIMEOUT = 0x0C80
+_REFERENCE_HIDSSR_HOST_MAX_LATENCY = 0xFFFF
+_REFERENCE_HIDSSR_HOST_MIN_TIMEOUT = 0xFFFF
+
+
+def build_hid_service_records(
+    hid_descriptor: bytes,
+    *,
+    device_name: str = _DEFAULT_DEVICE_NAME,
+) -> dict[int, list[object]]:
+    """Build the Classic HID SDP service record used by the reference controller."""
+    from bumble import core  # noqa: PLC0415
+    from bumble.sdp import (  # noqa: PLC0415
+        SDP_ADDITIONAL_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+        SDP_BLUETOOTH_PROFILE_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+        SDP_BROWSE_GROUP_LIST_ATTRIBUTE_ID,
+        SDP_LANGUAGE_BASE_ATTRIBUTE_ID_LIST_ATTRIBUTE_ID,
+        SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+        SDP_PUBLIC_BROWSE_ROOT,
+        SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID,
+        SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID,
+        DataElement,
+        ServiceAttribute,
+    )
+
+    return {
+        _HID_SERVICE_RECORD_HANDLE: [
+            ServiceAttribute(
+                SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID,
+                DataElement.unsigned_integer_32(_HID_SERVICE_RECORD_HANDLE),
+            ),
+            ServiceAttribute(
+                SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID,
+                DataElement.sequence([DataElement.uuid(core.BT_HUMAN_INTERFACE_DEVICE_SERVICE)]),
+            ),
+            ServiceAttribute(
+                SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+                DataElement.sequence(
+                    [
+                        DataElement.sequence(
+                            [
+                                DataElement.uuid(core.BT_L2CAP_PROTOCOL_ID),
+                                DataElement.unsigned_integer_16(HID_CONTROL_PSM),
+                            ]
+                        ),
+                        DataElement.sequence([DataElement.uuid(core.BT_HIDP_PROTOCOL_ID)]),
+                    ]
+                ),
+            ),
+            ServiceAttribute(
+                SDP_BROWSE_GROUP_LIST_ATTRIBUTE_ID,
+                DataElement.sequence([DataElement.uuid(SDP_PUBLIC_BROWSE_ROOT)]),
+            ),
+            ServiceAttribute(
+                SDP_LANGUAGE_BASE_ATTRIBUTE_ID_LIST_ATTRIBUTE_ID,
+                DataElement.sequence(
+                    [
+                        DataElement.unsigned_integer_16(_SDP_LANGUAGE_CODE_ENGLISH),
+                        DataElement.unsigned_integer_16(_SDP_CHARACTER_ENCODING_UTF8),
+                        DataElement.unsigned_integer_16(_LANGUAGE_BASE_EN_US),
+                    ]
+                ),
+            ),
+            ServiceAttribute(
+                _SDP_PRIMARY_LANGUAGE_SERVICE_NAME_ATTRIBUTE_ID,
+                DataElement.text_string(device_name.encode("utf-8")),
+            ),
+            ServiceAttribute(
+                SDP_BLUETOOTH_PROFILE_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+                DataElement.sequence(
+                    [
+                        DataElement.sequence(
+                            [
+                                DataElement.uuid(core.BT_HUMAN_INTERFACE_DEVICE_SERVICE),
+                                DataElement.unsigned_integer_16(0x0101),
+                            ]
+                        )
+                    ]
+                ),
+            ),
+            ServiceAttribute(
+                SDP_ADDITIONAL_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+                DataElement.sequence(
+                    [
+                        DataElement.sequence(
+                            [
+                                DataElement.sequence(
+                                    [
+                                        DataElement.uuid(core.BT_L2CAP_PROTOCOL_ID),
+                                        DataElement.unsigned_integer_16(HID_INTERRUPT_PSM),
+                                    ]
+                                ),
+                                DataElement.sequence([DataElement.uuid(core.BT_HIDP_PROTOCOL_ID)]),
+                            ]
+                        )
+                    ]
+                ),
+            ),
+            ServiceAttribute(
+                _SDP_HID_PARSER_VERSION_ATTRIBUTE_ID,
+                DataElement.unsigned_integer_16(0x0111),
+            ),
+            ServiceAttribute(
+                _SDP_HID_DEVICE_SUBCLASS_ATTRIBUTE_ID,
+                DataElement.unsigned_integer_8(0x08),
+            ),
+            ServiceAttribute(
+                _SDP_HID_COUNTRY_CODE_ATTRIBUTE_ID,
+                DataElement.unsigned_integer_8(_REFERENCE_HID_COUNTRY_CODE),
+            ),
+            ServiceAttribute(
+                _SDP_HID_VIRTUAL_CABLE_ATTRIBUTE_ID,
+                DataElement.boolean(True),
+            ),
+            ServiceAttribute(
+                _SDP_HID_RECONNECT_INITIATE_ATTRIBUTE_ID,
+                DataElement.boolean(True),
+            ),
+            ServiceAttribute(
+                _SDP_HID_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+                DataElement.sequence(
+                    [
+                        DataElement.sequence(
+                            [
+                                DataElement.unsigned_integer_8(_HID_REPORT_DESCRIPTOR_TYPE),
+                                DataElement.text_string(hid_descriptor),
+                            ]
+                        )
+                    ]
+                ),
+            ),
+            ServiceAttribute(
+                _SDP_HID_LANG_ID_BASE_LIST_ATTRIBUTE_ID,
+                DataElement.sequence(
+                    [
+                        DataElement.sequence(
+                            [
+                                DataElement.unsigned_integer_16(_LANGUAGE_ID_EN_US),
+                                DataElement.unsigned_integer_16(_LANGUAGE_BASE_EN_US),
+                            ]
+                        )
+                    ]
+                ),
+            ),
+            ServiceAttribute(
+                _SDP_HID_REMOTE_WAKE_ATTRIBUTE_ID,
+                DataElement.boolean(True),
+            ),
+            ServiceAttribute(
+                _SDP_HID_PROFILE_VERSION_ATTRIBUTE_ID,
+                DataElement.unsigned_integer_16(0x0101),
+            ),
+            ServiceAttribute(
+                _SDP_HID_SUPERVISION_TIMEOUT_ATTRIBUTE_ID,
+                DataElement.unsigned_integer_16(_REFERENCE_HID_SUPERVISION_TIMEOUT),
+            ),
+            ServiceAttribute(
+                _SDP_HID_NORMALLY_CONNECTABLE_ATTRIBUTE_ID,
+                DataElement.boolean(True),
+            ),
+            ServiceAttribute(
+                _SDP_HID_BOOT_DEVICE_ATTRIBUTE_ID,
+                DataElement.boolean(False),
+            ),
+            ServiceAttribute(
+                _SDP_HIDSSR_HOST_MAX_LATENCY_ATTRIBUTE_ID,
+                DataElement.unsigned_integer_16(_REFERENCE_HIDSSR_HOST_MAX_LATENCY),
+            ),
+            ServiceAttribute(
+                _SDP_HIDSSR_HOST_MIN_TIMEOUT_ATTRIBUTE_ID,
+                DataElement.unsigned_integer_16(_REFERENCE_HIDSSR_HOST_MIN_TIMEOUT),
+            ),
+        ]
+    }

swbt/transport/base.py

@@ -0,0 +1,81 @@
+"""Transport protocol shared by gamepad and transport implementations."""
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Literal, Protocol
+
+InterruptDataCallback = Callable[[bytes], Awaitable[None]]
+ControlDataCallback = Callable[[bytes], Awaitable[None]]
+ConnectedCallback = Callable[[], Awaitable[None]]
+DisconnectedCallback = Callable[[int | None], Awaitable[None]]
+DisconnectRequestStatus = Literal["requested", "unavailable", "failed"]
+
+
+@dataclass(frozen=True)
+class DisconnectRequestResult:
+    """Result of a best-effort remote HID disconnect request."""
+
+    status: DisconnectRequestStatus
+    channels: tuple[str, ...] = ()
+    reason: str | None = None
+    error_type: str | None = None
+    message: str | None = None
+
+
+@dataclass(frozen=True)
+class BondedPeer:
+    """Peer address discovered from a transport key store."""
+
+    address: str
+
+
+class HidDeviceTransport(Protocol):
+    """Abstract HID device transport used by SwitchGamepad."""
+
+    async def open(self) -> None:
+        """Open transport resources without waiting for a host connection."""
+
+    async def start_advertising(self) -> None:
+        """Enter the host-discoverable state."""
+
+    async def close(self) -> None:
+        """Close transport resources."""
+
+    async def request_disconnect(self) -> DisconnectRequestResult:
+        """Request a remote HID/L2CAP disconnect when the transport supports it."""
+
+    async def list_bonded_peers(self) -> tuple[BondedPeer, ...]:
+        """Return current reconnect candidates.
+
+        Implementations must return zero or one peer. A transport that stores
+        multiple historical peers must expose only the current reconnect target
+        here. Multiple current peers are an invalid transport or key-store state
+        and should raise InvalidKeyStoreError rather than returning multiple
+        BondedPeer values.
+        """
+
+    async def connect_bonded_peer(
+        self,
+        peer_address: str,
+        *,
+        connect_timeout: float | None,
+    ) -> None:
+        """Start an active reconnect attempt to a bonded peer."""
+
+    async def send_interrupt(self, payload: bytes) -> None:
+        """Send one HID interrupt report."""
+
+    async def send_control(self, payload: bytes) -> None:
+        """Send one HID control report."""
+
+    def on_interrupt_data(self, callback: InterruptDataCallback) -> None:
+        """Register a callback for interrupt-channel host data."""
+
+    def on_control_data(self, callback: ControlDataCallback) -> None:
+        """Register a callback for control-channel host data."""
+
+    def on_connected(self, callback: ConnectedCallback) -> None:
+        """Register a callback for transport connection completion."""
+
+    def on_disconnected(self, callback: DisconnectedCallback) -> None:
+        """Register a callback for transport disconnection."""