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

swbt/__init__.py

@@ -4,19 +4,27 @@ from swbt.adapter_discovery import AdapterInfo, list_adapters
 from swbt.diagnostics import DiagnosticsConfig, GamepadStatus
 from swbt.errors import (
     AdapterDiscoveryError,
+    AdapterIdentityRecoveryRequired,
     ClosedError,
     ConnectionFailedError,
     ConnectionTimeoutError,
     InvalidInputError,
     InvalidKeyStoreError,
+    InvalidProfileError,
+    ProfileControllerMismatchError,
     SwbtError,
     TransportOpenError,
     UnsupportedInputError,
 )
 from swbt.gamepad import (
     ConnectionResult,
+    DirectJoyConL,
+    DirectJoyConR,
+    DirectProController,
+    DirectSwitchGamepad,
     JoyConL,
     JoyConR,
+    PeriodicSwitchGamepad,
     ProController,
     SwitchGamepad,
 )
@@ -25,6 +33,7 @@ from swbt.protocol.profiles.base import ControllerColors
 
 __all__ = (
     "AdapterDiscoveryError",
+    "AdapterIdentityRecoveryRequired",
     "AdapterInfo",
     "Button",
     "ClosedError",
@@ -33,14 +42,21 @@ __all__ = (
     "ConnectionTimeoutError",
     "ControllerColors",
     "DiagnosticsConfig",
+    "DirectJoyConL",
+    "DirectJoyConR",
+    "DirectProController",
+    "DirectSwitchGamepad",
     "GamepadStatus",
     "IMUFrame",
     "InputState",
     "InvalidInputError",
     "InvalidKeyStoreError",
+    "InvalidProfileError",
     "JoyConL",
     "JoyConR",
+    "PeriodicSwitchGamepad",
     "ProController",
+    "ProfileControllerMismatchError",
     "Stick",
     "SwbtError",
     "SwitchGamepad",

swbt/_testing/gamepad.py

@@ -1,6 +1,15 @@
 """Internal gamepad constructors for tests that inject fake transports."""
 
-from swbt import ControllerColors, DiagnosticsConfig, JoyConL, JoyConR, ProController
+from swbt import (
+    ControllerColors,
+    DiagnosticsConfig,
+    DirectJoyConL,
+    DirectJoyConR,
+    DirectProController,
+    JoyConL,
+    JoyConR,
+    ProController,
+)
 from swbt.gamepad._config import _SwitchGamepadConfig
 from swbt.protocol.profiles.joycon import JoyConLeftProfile, JoyConRightProfile
 from swbt.transport.base import HidDeviceTransport
@@ -10,7 +19,7 @@ def make_pro_controller(
     *,
     transport: HidDeviceTransport,
     adapter: str | None = None,
-    key_store_path: str | None = None,
+    profile_path: str | None = None,
     report_period_us: int | None = None,
     controller_colors: ControllerColors | None = None,
     diagnostics: DiagnosticsConfig | None = None,
@@ -19,7 +28,7 @@ def make_pro_controller(
     return ProController._from_config(
         _SwitchGamepadConfig(
             adapter=adapter,
-            key_store_path=key_store_path,
+            profile_path=profile_path,
             report_period_us=report_period_us,
             controller_colors=controller_colors,
         ),
@@ -32,7 +41,7 @@ def make_joycon_l(
     *,
     transport: HidDeviceTransport,
     adapter: str | None = None,
-    key_store_path: str | None = None,
+    profile_path: str | None = None,
     report_period_us: int | None = None,
     controller_colors: ControllerColors | None = None,
     diagnostics: DiagnosticsConfig | None = None,
@@ -41,7 +50,7 @@ def make_joycon_l(
     return JoyConL._from_config(
         _SwitchGamepadConfig(
             adapter=adapter,
-            key_store_path=key_store_path,
+            profile_path=profile_path,
             report_period_us=report_period_us,
             controller_colors=controller_colors,
             profile=JoyConLeftProfile(),
@@ -55,7 +64,7 @@ def make_joycon_r(
     *,
     transport: HidDeviceTransport,
     adapter: str | None = None,
-    key_store_path: str | None = None,
+    profile_path: str | None = None,
     report_period_us: int | None = None,
     controller_colors: ControllerColors | None = None,
     diagnostics: DiagnosticsConfig | None = None,
@@ -64,7 +73,7 @@ def make_joycon_r(
     return JoyConR._from_config(
         _SwitchGamepadConfig(
             adapter=adapter,
-            key_store_path=key_store_path,
+            profile_path=profile_path,
             report_period_us=report_period_us,
             controller_colors=controller_colors,
             profile=JoyConRightProfile(),
@@ -72,3 +81,65 @@ def make_joycon_r(
         diagnostics=diagnostics,
         transport=transport,
     )
+
+
+def make_direct_pro_controller(
+    *,
+    transport: HidDeviceTransport,
+    adapter: str | None = None,
+    profile_path: str | None = None,
+    controller_colors: ControllerColors | None = None,
+    diagnostics: DiagnosticsConfig | None = None,
+) -> DirectProController:
+    """Create a Direct Pro Controller with an injected transport for tests."""
+    return DirectProController._from_config(
+        _SwitchGamepadConfig(
+            adapter=adapter,
+            profile_path=profile_path,
+            controller_colors=controller_colors,
+        ),
+        diagnostics=diagnostics,
+        transport=transport,
+    )
+
+
+def make_direct_joycon_l(
+    *,
+    transport: HidDeviceTransport,
+    adapter: str | None = None,
+    profile_path: str | None = None,
+    controller_colors: ControllerColors | None = None,
+    diagnostics: DiagnosticsConfig | None = None,
+) -> DirectJoyConL:
+    """Create a Direct Joy-Con L with an injected transport for tests."""
+    return DirectJoyConL._from_config(
+        _SwitchGamepadConfig(
+            adapter=adapter,
+            profile_path=profile_path,
+            controller_colors=controller_colors,
+            profile=JoyConLeftProfile(),
+        ),
+        diagnostics=diagnostics,
+        transport=transport,
+    )
+
+
+def make_direct_joycon_r(
+    *,
+    transport: HidDeviceTransport,
+    adapter: str | None = None,
+    profile_path: str | None = None,
+    controller_colors: ControllerColors | None = None,
+    diagnostics: DiagnosticsConfig | None = None,
+) -> DirectJoyConR:
+    """Create a Direct Joy-Con R with an injected transport for tests."""
+    return DirectJoyConR._from_config(
+        _SwitchGamepadConfig(
+            adapter=adapter,
+            profile_path=profile_path,
+            controller_colors=controller_colors,
+            profile=JoyConRightProfile(),
+        ),
+        diagnostics=diagnostics,
+        transport=transport,
+    )

swbt/diagnostics.py

@@ -112,7 +112,7 @@ class DiagnosticsRecorder:
         return diagnostics_event
 
     def record_report_tx(self, *, report_id: int, reason: str) -> DiagnosticsEvent:
-        """Record one sent report and increment its counter."""
+        """Record one transport-accepted report and increment its counter."""
         counter = self._report_counters.get(report_id, 0) + 1
         self._report_counters[report_id] = counter
         return self.record_event(
@@ -139,9 +139,7 @@ class DiagnosticsRecorder:
         self,
         *,
         adapter: str,
-        key_store_exists: bool | None = None,
-        key_store_path: str | None = None,
-        key_store_previous_exists: bool | None = None,
+        profile_path: str | None = None,
     ) -> DiagnosticsEvent:
         """Record environment metadata for one diagnostics run."""
         fields: dict[str, object] = {
@@ -150,12 +148,8 @@ class DiagnosticsRecorder:
             "package_version": self._package_version(),
             "python_version": platform.python_version(),
         }
-        if key_store_path is not None:
-            fields["key_store_path"] = key_store_path
-        if key_store_exists is not None:
-            fields["key_store_exists"] = key_store_exists
-        if key_store_previous_exists is not None:
-            fields["key_store_previous_exists"] = key_store_previous_exists
+        if profile_path is not None:
+            fields["profile_path"] = profile_path
         return self.record_event(
             "run_metadata",
             **fields,

swbt/errors.py

@@ -63,6 +63,43 @@ class InvalidKeyStoreError(SwbtError):
     """Raised when a key store has an unsupported or invalid shape."""
 
 
+class InvalidProfileError(SwbtError):
+    """Raised when a pairing profile is invalid or unsupported."""
+
+
+class ProfileControllerMismatchError(InvalidProfileError):
+    """Raised when a profile belongs to a different concrete controller kind."""
+
+    def __init__(
+        self,
+        *,
+        expected_controller_kind: str,
+        actual_controller_kind: str,
+    ) -> None:
+        """Initialize expected and actual profile controller kinds."""
+        message = (
+            "profile controller_kind mismatch: "
+            f"expected {expected_controller_kind!r}, got {actual_controller_kind!r}"
+        )
+        super().__init__(message)
+        self.expected_controller_kind = expected_controller_kind
+        self.actual_controller_kind = actual_controller_kind
+
+
+class AdapterIdentityRecoveryRequired(SwbtError):  # noqa: N818
+    """Raised when a volatile write may have changed the adapter identity."""
+
+    def __init__(self, *, target_address: str, stage: str) -> None:
+        """Initialize the target and failure stage requiring physical recovery."""
+        message = (
+            "adapter identity preparation became uncertain after write started; "
+            "unplug and reconnect the USB dongle before retrying"
+        )
+        super().__init__(message)
+        self.target_address = target_address
+        self.stage = stage
+
+
 class ProtocolError(SwbtError):
     """Raised when protocol bytes cannot be parsed or produced."""
 

swbt/gamepad/__init__.py

@@ -3,9 +3,16 @@
 from swbt.gamepad.connection import ConnectionResult, ConnectionStatus
 from swbt.gamepad.constants import DISCONNECT_REQUEST_TIMEOUT_SECONDS
 from swbt.gamepad.core import (
+    DirectJoyConL,
+    DirectJoyConR,
+    DirectProController,
     JoyConL,
     JoyConR,
     ProController,
+)
+from swbt.gamepad.interface import (
+    DirectSwitchGamepad,
+    PeriodicSwitchGamepad,
     SwitchGamepad,
 )
 
@@ -13,8 +20,13 @@ __all__ = (
     "DISCONNECT_REQUEST_TIMEOUT_SECONDS",
     "ConnectionResult",
     "ConnectionStatus",
+    "DirectJoyConL",
+    "DirectJoyConR",
+    "DirectProController",
+    "DirectSwitchGamepad",
     "JoyConL",
     "JoyConR",
+    "PeriodicSwitchGamepad",
     "ProController",
     "SwitchGamepad",
 )

swbt/gamepad/_config.py

@@ -13,7 +13,7 @@ class _SwitchGamepadConfig:
 
     Attributes:
         adapter: Bumble adapter moniker, such as ``"usb:0"``.
-        key_store_path: Path used by the default transport to persist pairing keys.
+        profile_path: Path to a swbt-owned pairing profile.
         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.
@@ -21,7 +21,7 @@ class _SwitchGamepadConfig:
     """
 
     adapter: str | None = None
-    key_store_path: str | None = None
+    profile_path: str | None = None
     profile: ControllerProfile = field(default_factory=default_controller_profile)
     report_period_us: int | None = None
     device_name: str | None = None
@@ -60,14 +60,14 @@ class _ControllerSpec:
         self,
         *,
         adapter: str | None,
-        key_store_path: str | None,
         report_period_us: int | None,
         controller_colors: ControllerColors | None,
+        profile_path: str | None = None,
     ) -> _SwitchGamepadConfig:
         """Create internal construction config from public constructor options."""
         return _SwitchGamepadConfig(
             adapter=adapter,
-            key_store_path=key_store_path,
+            profile_path=profile_path,
             profile=self.profile,
             report_period_us=report_period_us,
             controller_colors=controller_colors,
@@ -79,7 +79,7 @@ class _RuntimeConfig:
     """Normalized internal configuration for ControllerRuntime."""
 
     adapter: str | None
-    key_store_path: str | None
+    profile_path: str | None
     profile: ControllerProfile
     report_period_us: int
     device_name: str
@@ -93,7 +93,7 @@ class _RuntimeConfig:
             raise InvalidInputError(msg)
         return cls(
             adapter=config.adapter,
-            key_store_path=config.key_store_path,
+            profile_path=config.profile_path,
             profile=config.profile,
             report_period_us=config.report_period_us,
             device_name=config.device_name,

swbt/gamepad/connection.py

@@ -58,7 +58,7 @@ class ConnectionWorkflow:
     diagnostics: DiagnosticsRecorder
     ensure_open: EnsureOpen
     get_transport: TransportProvider
-    key_store_path: str | None
+    profile_path: str | None
     pair: PairWithTimeout
     set_connection_state: StateSetter
     transport_was_injected: bool
@@ -71,10 +71,10 @@ class ConnectionWorkflow:
         """Try active reconnect with exactly one bonded peer."""
         await self.ensure_open()
         transport = self._transport()
-        if self.key_store_path is None and not self.transport_was_injected:
+        if self.profile_path is None and not self.transport_was_injected:
             self.diagnostics.record_event(
-                "reconnect_key_store_unavailable",
-                reason="key_store_path_none",
+                "reconnect_profile_unavailable",
+                reason="profile_path_none",
                 route="active_reconnect",
             )
         peers = await transport.list_bonded_peers()