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

swbt/__init__.py

@@ -4,11 +4,14 @@ 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,
@@ -30,6 +33,7 @@ from swbt.protocol.profiles.base import ControllerColors
 
 __all__ = (
     "AdapterDiscoveryError",
+    "AdapterIdentityRecoveryRequired",
     "AdapterInfo",
     "Button",
     "ClosedError",
@@ -47,10 +51,12 @@ __all__ = (
     "InputState",
     "InvalidInputError",
     "InvalidKeyStoreError",
+    "InvalidProfileError",
     "JoyConL",
     "JoyConR",
     "PeriodicSwitchGamepad",
     "ProController",
+    "ProfileControllerMismatchError",
     "Stick",
     "SwbtError",
     "SwitchGamepad",

swbt/_testing/gamepad.py

@@ -19,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,
@@ -28,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,
         ),
@@ -41,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,
@@ -50,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(),
@@ -64,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,
@@ -73,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(),
@@ -87,7 +87,7 @@ def make_direct_pro_controller(
     *,
     transport: HidDeviceTransport,
     adapter: str | None = None,
-    key_store_path: str | None = None,
+    profile_path: str | None = None,
     controller_colors: ControllerColors | None = None,
     diagnostics: DiagnosticsConfig | None = None,
 ) -> DirectProController:
@@ -95,7 +95,7 @@ def make_direct_pro_controller(
     return DirectProController._from_config(
         _SwitchGamepadConfig(
             adapter=adapter,
-            key_store_path=key_store_path,
+            profile_path=profile_path,
             controller_colors=controller_colors,
         ),
         diagnostics=diagnostics,
@@ -107,7 +107,7 @@ def make_direct_joycon_l(
     *,
     transport: HidDeviceTransport,
     adapter: str | None = None,
-    key_store_path: str | None = None,
+    profile_path: str | None = None,
     controller_colors: ControllerColors | None = None,
     diagnostics: DiagnosticsConfig | None = None,
 ) -> DirectJoyConL:
@@ -115,7 +115,7 @@ def make_direct_joycon_l(
     return DirectJoyConL._from_config(
         _SwitchGamepadConfig(
             adapter=adapter,
-            key_store_path=key_store_path,
+            profile_path=profile_path,
             controller_colors=controller_colors,
             profile=JoyConLeftProfile(),
         ),
@@ -128,7 +128,7 @@ def make_direct_joycon_r(
     *,
     transport: HidDeviceTransport,
     adapter: str | None = None,
-    key_store_path: str | None = None,
+    profile_path: str | None = None,
     controller_colors: ControllerColors | None = None,
     diagnostics: DiagnosticsConfig | None = None,
 ) -> DirectJoyConR:
@@ -136,7 +136,7 @@ def make_direct_joycon_r(
     return DirectJoyConR._from_config(
         _SwitchGamepadConfig(
             adapter=adapter,
-            key_store_path=key_store_path,
+            profile_path=profile_path,
             controller_colors=controller_colors,
             profile=JoyConRightProfile(),
         ),

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/_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()

swbt/gamepad/core.py

@@ -17,6 +17,10 @@ from swbt.protocol.profiles.base import ControllerColors
 from swbt.protocol.profiles.joycon import JoyConLeftProfile, JoyConRightProfile
 from swbt.protocol.profiles.pro_controller import default_controller_profile
 from swbt.state_store import InputStateStore
+from swbt.transport._pairing_profile import (
+    LocalAddress,
+    PairingProfile,
+)
 from swbt.transport.base import HidDeviceTransport
 
 
@@ -34,7 +38,6 @@ class _RuntimeBackedGamepad:
         self,
         *,
         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,
@@ -43,7 +46,6 @@ class _RuntimeBackedGamepad:
 
         Args:
             adapter: Bumble adapter moniker used for the Bluetooth backend.
-            key_store_path: Optional path used by the Bluetooth backend to persist keys.
             report_period_us: Optional periodic input report interval in microseconds.
             controller_colors: Optional fixed controller body, button, and grip colors.
             diagnostics: Optional diagnostics configuration for trace output.
@@ -53,7 +55,6 @@ class _RuntimeBackedGamepad:
         """
         config = self._controller_spec.build_config(
             adapter=adapter,
-            key_store_path=key_store_path,
             report_period_us=report_period_us,
             controller_colors=controller_colors,
         )
@@ -350,6 +351,39 @@ class _PeriodicRuntimeBackedGamepad(_RuntimeBackedGamepad, PeriodicSwitchGamepad
         """
         await self._runtime.apply(state)
 
+    @classmethod
+    async def _create_pairing_profile(
+        cls,
+        *,
+        adapter: str,
+        profile_path: str,
+        local_address: str | None,
+        pair_timeout: float | None,
+        report_period_us: int | None,
+        controller_colors: ControllerColors | None,
+        diagnostics: DiagnosticsConfig | None,
+    ) -> Self:
+        """Create, pair, and clean up a concrete periodic controller profile."""
+        target = None if local_address is None else LocalAddress.parse(local_address)
+        PairingProfile.create_new(
+            profile_path,
+            target,
+            controller_kind=cls._controller_spec.profile.kind,
+        )
+        gamepad = cls(
+            adapter=adapter,
+            profile_path=profile_path,  # ty: ignore[unknown-argument]
+            report_period_us=report_period_us,
+            controller_colors=controller_colors,
+            diagnostics=diagnostics,
+        )
+        try:
+            await gamepad.pair(timeout=pair_timeout)
+        except BaseException:
+            await gamepad.close(neutral=False)
+            raise
+        return gamepad
+
 
 class _DirectRuntimeBackedGamepad(_RuntimeBackedGamepad, DirectSwitchGamepad):
     """Runtime-backed gamepad with caller-owned input transmission."""
@@ -360,7 +394,7 @@ class _DirectRuntimeBackedGamepad(_RuntimeBackedGamepad, DirectSwitchGamepad):
         self,
         *,
         adapter: str | None = None,
-        key_store_path: str | None = None,
+        profile_path: str | None = None,
         controller_colors: ControllerColors | None = None,
         diagnostics: DiagnosticsConfig | None = None,
     ) -> None:
@@ -368,7 +402,7 @@ class _DirectRuntimeBackedGamepad(_RuntimeBackedGamepad, DirectSwitchGamepad):
 
         Args:
             adapter: Bumble adapter moniker used for the Bluetooth backend.
-            key_store_path: Optional path used by the Bluetooth backend to persist keys.
+            profile_path: Optional swbt-owned pairing profile path.
             controller_colors: Optional fixed controller body, button, and grip colors.
             diagnostics: Optional diagnostics configuration for trace output.
 
@@ -377,12 +411,63 @@ class _DirectRuntimeBackedGamepad(_RuntimeBackedGamepad, DirectSwitchGamepad):
         """
         config = self._controller_spec.build_config(
             adapter=adapter,
-            key_store_path=key_store_path,
+            profile_path=profile_path,
             report_period_us=None,
             controller_colors=controller_colors,
         )
         self._init_from_config(config, diagnostics=diagnostics, transport=None)
 
+    @classmethod
+    async def create_profile(
+        cls,
+        *,
+        adapter: str,
+        profile_path: str,
+        local_address: str | None = None,
+        pair_timeout: float | None = None,
+        controller_colors: ControllerColors | None = None,
+        diagnostics: DiagnosticsConfig | None = None,
+    ) -> Self:
+        """Create a new direct pairing profile and pair it.
+
+        Args:
+            adapter: Bumble adapter moniker. An explicit local address may prepare
+                volatile adapter identity state.
+            profile_path: New path for the swbt-owned profile JSON.
+            local_address: Optional individual locally administered Bluetooth address.
+                ``None`` uses the adapter's current default address without rewriting it.
+            pair_timeout: Maximum seconds to wait for the initial pairing connection.
+            controller_colors: Optional fixed controller body, button, and grip colors.
+            diagnostics: Optional diagnostics configuration for trace output.
+
+        Returns:
+            The paired direct controller. The caller owns its lifetime.
+
+        Raises:
+            ValueError: ``local_address`` is invalid.
+            FileExistsError: ``profile_path`` already exists.
+            Exception: Profile preparation or pairing failed. The created profile remains
+                available for a later retry.
+        """
+        target = None if local_address is None else LocalAddress.parse(local_address)
+        PairingProfile.create_new(
+            profile_path,
+            target,
+            controller_kind=cls._controller_spec.profile.kind,
+        )
+        gamepad = cls(
+            adapter=adapter,
+            profile_path=profile_path,
+            controller_colors=controller_colors,
+            diagnostics=diagnostics,
+        )
+        try:
+            await gamepad.pair(timeout=pair_timeout)
+        except BaseException:
+            await gamepad.close(neutral=False)
+            raise
+        return gamepad
+
     async def send(self, state: InputState) -> None:
         """Send one complete input state and commit it after transmission.
 
@@ -397,6 +482,79 @@ class ProController(_PeriodicRuntimeBackedGamepad):
 
     _controller_spec = _ControllerSpec(profile=default_controller_profile())
 
+    def __init__(
+        self,
+        *,
+        adapter: str | None = None,
+        profile_path: str | None = None,
+        report_period_us: int | None = None,
+        controller_colors: ControllerColors | None = None,
+        diagnostics: DiagnosticsConfig | None = None,
+    ) -> None:
+        """Create a Pro Controller-compatible gamepad.
+
+        Args:
+            adapter: Bumble adapter moniker used for the Bluetooth backend.
+            profile_path: Optional swbt-owned pairing profile path.
+            report_period_us: Optional periodic input report interval in microseconds.
+            controller_colors: Optional fixed controller body, button, and grip colors.
+            diagnostics: Optional diagnostics configuration for trace output.
+
+        Raises:
+            InvalidInputError: adapter is omitted or report_period_us is not positive.
+        """
+        config = self._controller_spec.build_config(
+            adapter=adapter,
+            profile_path=profile_path,
+            report_period_us=report_period_us,
+            controller_colors=controller_colors,
+        )
+        self._init_from_config(config, diagnostics=diagnostics, transport=None)
+
+    @classmethod
+    async def create_profile(
+        cls,
+        *,
+        adapter: str,
+        profile_path: str,
+        local_address: str | None = None,
+        pair_timeout: float | None = None,
+        report_period_us: int | None = None,
+        controller_colors: ControllerColors | None = None,
+        diagnostics: DiagnosticsConfig | None = None,
+    ) -> Self:
+        """Create a new pairing profile and pair it.
+
+        Args:
+            adapter: Bumble adapter moniker. An explicit local address may prepare
+                volatile adapter identity state.
+            profile_path: New path for the swbt-owned profile JSON.
+            local_address: Optional individual locally administered Bluetooth address.
+                ``None`` uses the adapter's current default address without rewriting it.
+            pair_timeout: Maximum seconds to wait for the initial pairing connection.
+            report_period_us: Optional periodic input report interval in microseconds.
+            controller_colors: Optional fixed controller body, button, and grip colors.
+            diagnostics: Optional diagnostics configuration for trace output.
+
+        Returns:
+            ProController: The paired controller. The caller owns its lifetime.
+
+        Raises:
+            ValueError: ``local_address`` is invalid.
+            FileExistsError: ``profile_path`` already exists.
+            Exception: Profile preparation or pairing failed. The created profile remains
+                available for a later retry.
+        """
+        return await cls._create_pairing_profile(
+            adapter=adapter,
+            profile_path=profile_path,
+            local_address=local_address,
+            pair_timeout=pair_timeout,
+            report_period_us=report_period_us,
+            controller_colors=controller_colors,
+            diagnostics=diagnostics,
+        )
+
 
 class JoyConL(_PeriodicRuntimeBackedGamepad):
     """Runtime-backed Joy-Con L-compatible gamepad."""
@@ -407,7 +565,7 @@ class JoyConL(_PeriodicRuntimeBackedGamepad):
         self,
         *,
         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,
@@ -416,7 +574,7 @@ class JoyConL(_PeriodicRuntimeBackedGamepad):
 
         Args:
             adapter: Bumble adapter moniker used for the Bluetooth backend.
-            key_store_path: Optional path used by the Bluetooth backend to persist keys.
+            profile_path: Optional swbt-owned pairing profile path.
             report_period_us: Optional periodic input report interval in microseconds.
             controller_colors: Optional fixed controller body, button, and grip colors.
             diagnostics: Optional diagnostics configuration for trace output.
@@ -426,12 +584,56 @@ class JoyConL(_PeriodicRuntimeBackedGamepad):
         """
         config = self._controller_spec.build_config(
             adapter=adapter,
-            key_store_path=key_store_path,
+            profile_path=profile_path,
             report_period_us=report_period_us,
             controller_colors=controller_colors,
         )
         self._init_from_config(config, diagnostics=diagnostics, transport=None)
 
+    @classmethod
+    async def create_profile(
+        cls,
+        *,
+        adapter: str,
+        profile_path: str,
+        local_address: str | None = None,
+        pair_timeout: float | None = None,
+        report_period_us: int | None = None,
+        controller_colors: ControllerColors | None = None,
+        diagnostics: DiagnosticsConfig | None = None,
+    ) -> Self:
+        """Create a new Joy-Con L pairing profile and pair it.
+
+        Args:
+            adapter: Bumble adapter moniker. An explicit local address may prepare
+                volatile adapter identity state.
+            profile_path: New path for the swbt-owned profile JSON.
+            local_address: Optional individual locally administered Bluetooth address.
+                ``None`` uses the adapter's current default address without rewriting it.
+            pair_timeout: Maximum seconds to wait for the initial pairing connection.
+            report_period_us: Optional periodic input report interval in microseconds.
+            controller_colors: Optional fixed controller body, button, and grip colors.
+            diagnostics: Optional diagnostics configuration for trace output.
+
+        Returns:
+            JoyConL: The paired controller. The caller owns its lifetime.
+
+        Raises:
+            ValueError: ``local_address`` is invalid.
+            FileExistsError: ``profile_path`` already exists.
+            Exception: Profile preparation or pairing failed. The created profile remains
+                available for a later retry.
+        """
+        return await cls._create_pairing_profile(
+            adapter=adapter,
+            profile_path=profile_path,
+            local_address=local_address,
+            pair_timeout=pair_timeout,
+            report_period_us=report_period_us,
+            controller_colors=controller_colors,
+            diagnostics=diagnostics,
+        )
+
 
 class JoyConR(_PeriodicRuntimeBackedGamepad):
     """Runtime-backed Joy-Con R-compatible gamepad."""
@@ -442,7 +644,7 @@ class JoyConR(_PeriodicRuntimeBackedGamepad):
         self,
         *,
         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,
@@ -451,7 +653,7 @@ class JoyConR(_PeriodicRuntimeBackedGamepad):
 
         Args:
             adapter: Bumble adapter moniker used for the Bluetooth backend.
-            key_store_path: Optional path used by the Bluetooth backend to persist keys.
+            profile_path: Optional swbt-owned pairing profile path.
             report_period_us: Optional periodic input report interval in microseconds.
             controller_colors: Optional fixed controller body, button, and grip colors.
             diagnostics: Optional diagnostics configuration for trace output.
@@ -461,12 +663,56 @@ class JoyConR(_PeriodicRuntimeBackedGamepad):
         """
         config = self._controller_spec.build_config(
             adapter=adapter,
-            key_store_path=key_store_path,
+            profile_path=profile_path,
             report_period_us=report_period_us,
             controller_colors=controller_colors,
         )
         self._init_from_config(config, diagnostics=diagnostics, transport=None)
 
+    @classmethod
+    async def create_profile(
+        cls,
+        *,
+        adapter: str,
+        profile_path: str,
+        local_address: str | None = None,
+        pair_timeout: float | None = None,
+        report_period_us: int | None = None,
+        controller_colors: ControllerColors | None = None,
+        diagnostics: DiagnosticsConfig | None = None,
+    ) -> Self:
+        """Create a new Joy-Con R pairing profile and pair it.
+
+        Args:
+            adapter: Bumble adapter moniker. An explicit local address may prepare
+                volatile adapter identity state.
+            profile_path: New path for the swbt-owned profile JSON.
+            local_address: Optional individual locally administered Bluetooth address.
+                ``None`` uses the adapter's current default address without rewriting it.
+            pair_timeout: Maximum seconds to wait for the initial pairing connection.
+            report_period_us: Optional periodic input report interval in microseconds.
+            controller_colors: Optional fixed controller body, button, and grip colors.
+            diagnostics: Optional diagnostics configuration for trace output.
+
+        Returns:
+            JoyConR: The paired controller. The caller owns its lifetime.
+
+        Raises:
+            ValueError: ``local_address`` is invalid.
+            FileExistsError: ``profile_path`` already exists.
+            Exception: Profile preparation or pairing failed. The created profile remains
+                available for a later retry.
+        """
+        return await cls._create_pairing_profile(
+            adapter=adapter,
+            profile_path=profile_path,
+            local_address=local_address,
+            pair_timeout=pair_timeout,
+            report_period_us=report_period_us,
+            controller_colors=controller_colors,
+            diagnostics=diagnostics,
+        )
+
 
 class DirectProController(_DirectRuntimeBackedGamepad):
     """Direct-reporting Pro Controller-compatible gamepad."""